Datasworn v0.0.9

What is this?

This is a pre-release of the successor to the original Datasworn repository and Dataforged package, which provided game rules from the Ironsworn and Ironsworn: Starforged in JSON.

Until it reaches v1.0, it may receive breaking changes on any version change.

If you're looking for the original Datasworn JSON files, they are available on the legacy branch.

Why a new version?

Some of the design goals for the new standard:

• provide a format that accomodates both classic Ironsworn and Ironsworn: Starforged
• language-agnostic JSON schema as the "source of truth", rather than a JSON schema generated from Typescript typings
• provide type information for languages other than Typescript
• provide an interchange format that better accomodates homebrew/3rd party content, so it can be imported to any project that relies on the format
• provide a format friendlier to localization
• a format and codebase that are less messy, more consistent, and easier to maintain

Usage

Javascript and Typescript

Datasworn spans several NodeJS packages available via npm.

• @datasworn/core: Contains the Typescript typings and the JSON schema, on which all other Datasworn packages depend.
• @datasworn/ironsworn-classic: Contains JSON data from the original Ironsworn rulebook.
• @datasworn/ironsworn-classic-delve: Contains JSON data from Ironsworn: Delve, an expansion to the Ironsworn rulebook.
• @datasworn/starforged: Contains JSON data from Ironsworn: Starforged, and a number of SVG icons and WEBP planet images.

Other languages

Typings for C# (System.Text), Go, Java (Jackson), Python, Ruby, and Rust are available in the json-typedef directory.

These are automatically generated from a JSON TypeDef schema. For the data itself, see below.

JSON

The JSON schema and JSON data are available in the datasworn directory.

Licensing

Core package content (the typings and JSON schema) and internal tooling use the MIT license.

Textual and image content (in other words, the actual content from the rulebooks as described in JSON, Markdown, and other files) is CC-BY-4.0 or CC-BY-NC-4.0.

Additionally, the JSON files embed licensing information in the source property that appears on many objects throughout Datasworn.

Contributors

The previous versions of Datasworn and Dataforged began as unofficial personal projects of rsek, who now maintains Datasworn in an official capacity.

Special thanks to XenotropicDev for allowing me to use data from TheOracle (a Discord bot for use with Ironsworn and Starforged) as the nucleus of the original.

Version 0.0.5

• get version const from tools package

Changes from Dataforged Legacy

Breaking changes

General

• object properties are now snake_case (lower cased separated by underscores) rather than inconsistently applied title case with spaces
  • important: this is very serious breaking change. in fact it will break pretty much everything!
  • also note: ID maps (e.g. hash objects) and/or functions will be provided to make the conversion easier
  • 1.5.0 will remain available, of course, so you can make the migration in your own time (or never, if you decide it's not worth it)
  • but why do this at all?
    • prose labels were nice for readability, but at this point it's more useful if it fits more neatly with one of the de facto standards for JSON schema (the other option being camelCase). in other words - many languages expect JSON data in this shape anyways, so they're generally equipped to handle snake_case keys (or someone has written a handy library to do so)
    • snake_case also has the advantage of lining up with the changes to IDs, below
    • coinciding with other breaking changes means folks only have to make the migration once. so while it'll be something of a chore now, i reckon this is the least crappy time to do it
• significant changes to composition of $ids
  • IDs are now lower case with underscores, to make them friendly to as many environments as possible
  • asset abilities follow he same principle as e.g. oracle tables, and don't bother to note their most important child element's prop name (abilities for assets, table rows for oracle tables)
    • example: starforged/assets/companion/sidekick/abilities/1 has become starforged/assets/companion/sidekick/1
• a new constant, LEGACY_ID_MAP, is now exported for use with Dataforged. it's a plain object, where the keys are the current ID and the values are the corresponding legacy ID.
  • currently, this is a quick-and-dirty implementation, but my plan is to include most or all IDs at release to make conversion as painless as possible
• major restructuring of internal and external interface/class names and their organization
  • public interfaces (the bulk of dataforged's API) are no longer prefixed with "I". example: IEncounter is now Encounter
  • internal builder classes are now suffixed with "Builder"
  • internal interfaces for generating YAML schemas are now prefixed with Yaml
• many arrays of named objects (including oracles, moves, assets, etc) are now instead represented with keyed objects
• Name key removed (as it was trying to do too many jobs). in its place is title, an object which provides the proeprties canonical, standard, and short version of the item's title. items which can't rightly be said to have a title of their own, like asset inputs, receive label (a string) instead.

Assets and Moves

• "Health" on companion assets is now labelled "companion health"
• "Integrity" on vehicle cards is now labelled "vehicle integrity"
• internal references to stats (as opposed to localizable user-facing labels) and the like are now snake_case rather than title case. all of these are reflected in the relevant enums, so if you're already using those, the changeover should be relatively painless
  • examples:
    • Shadow is now shadow (enum: Stat)
    • Health is now health (enum: PlayerConditionMeter)
    • Journey Progress is now journey_progress
• names are now provided for Ironsworn ritual moves (so their IDs may have changed)
• the URLs provided by image and icons are now relative to the root directory rather than pretending that the relative url is somehow useful ;) they're also lower cased, both to match with the new $ids and to be a little more predictable for use on the web
  • old: ../../img/vector/Oracles/Creature/Environment/Space.svg
  • new: icon/oracles/creature/environment/space.svg

Oracles

• complete overhaul of oracle table display data -- see OracleSet.display.columns and OracleTable.display.columns
• roll templates (type RowTemplate) now demarcate strings to be replaced with {{oracle_id}} rather than ${{Oracle_Id}}. Admittedly, this is a bit arbitrary, and is mainly so that internal JSON template replacement when Dataforged builds from YAML uses a replacement demarcation distinct from roll templates. example:
  • old: "${{Starforged/Oracles/Factions/Affiliation}} of the ${{Starforged/Oracles/Factions/Legacy}} ${{Starforged/Oracles/Factions/Identity}}"
  • new: "{{starforged/oracles/factions/affiliation}} of the {{starforged/oracles/factions/legacy}} {{starforged/oracles/factions/identity}}"
• restructure of IOracle + IOracleCategory into OracleTable and OracleSet
  • "leaf" nodes (ones with a table property) key are now always OracleTable
  • "branch" nodes (ones that previously had Oracles or Categories) are now OracleSet
    • OracleSet.sets is a keyed object of any OracleSet children belonging to that set.
    • OracleSet.tables is a keyed object of any OracleTable children belonging to that oracle set.
  • to make this new scheme consistent, some oracle objects have been re-organized, and may have new IDs
• for OracleSet and OracleTable, Category and Member of are now replaced by a single array called ancestors, which contains the string IDs of every OracleSet from which the item descends

Other API changes

• Source now includes a license property, containing a URL pointing to the relevant license.
• everything that has a localizable string descendent (direct or otherwise) now has an $id, putting us one step closer to extracting complete localization data
• OracleBase (and its descendants, OracleSet and OracleTable) may now have summary in addition to description, consistent with some other objects in dataforgeds. summary is for providing a brief summary of the article (a couple sentences tops), while description includes more detailed information (often multiple paragraphs).

Fixes

• Fixed incorrect data in many MoveOutcomes (and asset AlterMoveOutcomes) due to a janky build script

New content

Starforged

• Sundered Isles preview of the Kraken asset

  Ironsworn preview content

• Ironlands region entries (with a lot of link annotation)
• Ironlands encounter entries (ditto)
• Ironlands setting truths
• Delve site themes and domains