rsek / dataforged Goto Github PK

i'm in the midst of expanding asset ability annotations. it's not live yet, but the WIP (in YAML) is here: https://github.com/rsek/dataforged/blob/main/_master-data/Starforged/Assets.yaml

couple notes:

• currently, these are more structured than may be advisable in the long term, but i decided the best way to get a feel for what's really important in asset abilities was to start annotating and see what the pain points were.
• my focus isn't on exposing the numeric values for calculation, but instead the content/triggers of the asset ability. i reckon stuff like "moves A, B, and C are altered with X on outcome Y" or "move A offers a reroll of die B on outcome C" are the most useful information when deciding what shortcuts to present to the user.
  • that said... there's an awful lot of things that are really close to being numbers already, particularly where "Add +X" and "Take X momentum" strings are concerned 🤔

Alternatives

a more sustainable/extensible (and less structured) approach might be some kind of tag system. each asset ability could include an array of keywords describing rules elements it references. for example, an ability with the following text:

When you Set a Course, choose one.

• Follow the fastest path: Take +2 momentum on a strong hit.
• Follow the safest path: Add +1

On a strong hit with a match, you charted a new path during the journey; mark 1 tick on your discoveries legacy track.

... might have the following keyword array:

["take +X momentum", "add +X", "mark discoveries legacy"]

these keywords would all have documented meanings, and then developers could decide what to do with them. for example, "take +X momentum" might mean including a shortcut for the user to increment momentum.

annotating this by hand wouldn't be any faster than what i'm currently doing... but short, uncomplicated phrases like these are pretty easy to regex for, so i could conceivably just extract them from asset text when i build dataforged's JSON.

couple things that occur to me about this approach

• i'm not sure to what degree this would overlap with trigger data; programmatically extracting nice self-contained trigger phrases is tricky
• the best way to test whether it would work would be for me to code something to do it, so i'm not sure it'll save me any labour in the short term ;) long term it could pay off, though
• is there hybrid approaches that might be fruitful?
• if i build a dataforged-compatible asset builder, would it be possible to build these keywords/structures into that?

It's really hard to deserilalize the moves.json right now with out adding a custom deserialization rule for typed languages due to the Highest Of type stats using the same keyword "Stat" as the other stats. Consider changing it to be a separate property, adding a move type, or making all the stat fields arrays.

Another option would be to make the trigger "Highest of" for those fields so it follows the same layout as the rest of the moves.

locally, the data entry in the YAML masters is complete. release pending a build script rewrite (#39)

• assets
• oracles
• encounters
• moves
• setting truths

best handled as part of the build scripts.

• assets
• moves
• tables
• encounters

• cripes, the oracle file sure is big
• not everyone wants or needs every planet oracle, for instance

I might just have missed it but I can't find the default descriptions for the different planet types in the Planets oracles. I.e; for Desert: "A pitiless planet of searing heat, blowing sand, and sunbaked rock." and so on.

• a working schema is now being generated at build time for dataforged, though it's currently only made explicit in the dataforged.json file. the assets.json and co should include correct refs too - probably applied at the level of category object.
• datasworn's mostly works, but needs some additional cleanup in this department

• Character
• Planet
• Settlement
• Starship
• Creature

maybe include whether the roll is suggested to be deferred or not?

At

Typo with double "may" in "...you may may spend 3 experience..."

this came up at one point as something that might be good for TheOracle, so i might as well add it here too

couple of options:

• jsonpath-plus is an order of magnitude faster than jsonpath, apparently
• json-query uses its own DSL, and it's not clear to me if it can handle the sorts of queries i'm using here. however, it's very fast. like, multiple orders of magnitude faster than even jsonpath-plus. fast enough it's feasible to use in user-facing stuff!

ultimately, not especially urgent, but if nothing else it'll get me in the habit of using the

I've been writing an importer to translate dataforged oracle data into Foundry's roll tables, and I've been running into complications around the different ways tables are represented in dataforged.

Currently an oracle's table(s) are represented in three ways:

{"Table":  {table}
 "Tables": [{table}]
 "Tables": {"key" {table}}}

Ideally I'd like to pull out each table, and give it a unique name. This isn't insurmountable, but it is made a little trickier by the differences in how tables are stored. It would be nice if all oracles stored tables in the same format, and all tables had a unique name that could be used to identify them if being stored as separate files or tables.

If you think there's merit to the idea, I could submit a PR.

evidently i introduced something which broke table construction and templating for certain tables. i have to rewrite my legacy format converters anyways to work with my new build scripts; this should resolve the problem.

the reference guide uses some colour coding for things other than asset categories, including moves. it might make sense to fold this into the Display class, since it's information about rendering.

• Vehicles should have the 'Battered' condition checkbox to represent Vehicle Troubles
• Command Vehicle (Starship) should also have the 'Cursed' condition.
• Companions should have the 'Out of Action' condition.
• Modules might need the 'Broken' condition, but it is not listed on the Assets cards. It feels like a different thing and might not be relevant here nor need the same treatment.

I don't know how they should be formatted in the json (so no pull request), a boolean seems wrong, but could represent a 'checkbox'?

basically moving from a format like:

"Region": "Terminus",

to

"Requires": {
  "Property": "Region",
  "Value": "Terminus"
}

The following Move Oracle data appears to be missing, i.e referenced in the Move data but without a corresponding entry in oracles/moves.json:

Begin a Session
Ask the Oracle

e.g. minimum number of rolls for oracles that are templated, default state for asset meters, etc.

should be handled in build script.

content changes are relatively minor in this update. the biggest speedbump is probably going to be finishing my build scripts for legacy output.

i'm already writing ES6 classes to build/transform/typecheck the data; jsdoc annotation means i can do it inline. i can probably start generating schema from it too.

• assets
• oracles
• encounters
• moves

In moves.json, markdown links use dashes to separate words, e.g. #Secure-an-Advantage, while in assets.json, links use underscores, e.g. #Secure_an_Advantage. Is it possible to normalize these to use either underscores or dashes?

(I can submit a PR, but I'm not sure which format you'd prefer.)

idk what else should go in there yet, but i'm sure someone out there has some ideas

probably me destroyed once again by the string and array prototypes sharing some method names 😢

also, i've been thinking on adding a key for references to oracle categories - one separate from the key for oracle rolls. basically, i reckon there's a different sort of operation implied by ">Stellar Object" (which i'd infer to mean "turn to the stellar object oracle and roll on it, 'cause it's just one table") vs ">Furnace World" (which i'd infer to mean "turn to the furnace world category and consider whether you want to roll more oracles") ... but the text itself doesn't make a distinction between the two, because in the context of the book, the little arrows are really just a marker for "this is a jump link".

might be reasonable to include references to any oracle or oracle category here. it's arguably a little redundant w/ oracle roll, but for those who only care about the references, it means they only have to check one key.

I think the planet name tables need to follow the same format as the other table entries at the same level to properly deserialize.

Current:

Possible solution:

Mostly for easy of deseralization the location property of Requires should be a string, or a string array, not both. It is possible to handle, but is a lot of extra code, and makes it hard to define a schema for the json class (see derelict exterior.json for a sample).

Moves

• Pay the Price - Some edits for brevity
  • Changed “Ask the Oracle for inspiration. Interpret the answer as a hardship or complication appropriate to the current situation” to “Ask the Oracle for inspiration. Interpret the answer as a hardship or complication appropriate to the situation”
  • Changed “Roll on the table below. If you have difficulty interpreting the result to fit the current situation, roll again.“ to “Roll on the table below. If the result doesn’t fit the situation, roll again.”

Assets

• Module / Stealth Tech
  • Ability 1 - Minor edits
  • Ability 2 - Changed benefit to an action die reroll on any result
• Module / Sensor Array: Ability 1 - Updated to allow for a challenge die reroll on any result
• Module / Vehicle Bay: Ability 1 - Changed the cost to 1 experience (instead of 2)
• Support Vehicle / Shuttle - Updated ability 2 (added “or evade an attack”)
• Path / Commander - Renamed “Leader”
• Path / Fugitive - Ability 1: Minor updates to replace counter with a 4-segment clock
• Companion / Voidglider
  • Ability 1 - Changed benefit to “add +1” instead of “take +1 momentum”
  • Ability 3 - Minor edits
• Deed / Marked
  • Ability 1 - Minor updates for space
  • Ability 2 - Updated to include a 6-segment clock

Oracles

• Planets / Planetside Peril: Fixed “Impassible” spelling error in entry 28-30/4-7
• Characters / Names: Changed entry 99 from Zephyr to Zev
• Settlement / First Look: Made adjustments and renumbered entries for alphabetical order.

Rulebook

• Minor updates and fixes

Reference Guide

• Minor updates and fixes
• Updated digital files to include hyperlinks and bookmarks

Other Resources

• Added Pay the Price card and Position Card to Reference Card Set (single and sheet/duplex versions)

oracle data entry in YAML is basically complete. most of the additional work involved is making will be making sure next can accomodate all ironsworn content gracefully.

And thanks for all the work!

Cheers, Mario

as of 033122, Fugitive and Marked now have embedded clocks where they previously had Counters

sketch of typing IClockYaml interface for internal data:

"Clock type": ClockType // string enum: "campaign" | "tension"
Segments: ClockSegments // number enum: 4 | 6 | 8 | 10

sketch of typing for the complete Clock object in JSON output:

$id: string; // auto-generated from parent ID when building JSON
"Clock type": ClockType;
Segments: ClockSegments;
Filled: number; // 0 by default. mainly to make it dead simple for ppl to use as-is

they're pretty gross atm! i'm working on a rewrite that dumps the YAML data into ES6 classes for transformation + error checking. i'm doing jsdoc annotations while i'm at it so i can generate some documentation of the JSON keys, but i may defer completing it so that i can release the next content update in a timely fashion.

• assets
  • standalone buildAssets() function
    • legacyFormat param
  • es6 classes
• encounters
  • standalone buildEncounters() function
    • legacyFormat param (unnecessary because encounter structure is already pretty clean)
  • es6 classes
• moves
  • standalone buildMoves() function
    • legacyFormat param
  • es6 classes
• oracles
  • standalone buildAssets() function
    • legacyFormat param
  • es6 classes (Row, Table, Oracle, OracleCategory)

jsdoc annotation is on the todo list, too, but that's a separate issue.

• zone_access.json
• zone_community.json
• zone_engineering.json
• zone_living.json
• zone_medical.json
• zone_operations.json
• zone_production.json
• zone_research.json

• Assets
• Encounters
• Moves
• Setting Truths
• Oracles

At https://github.com/rsek/dataforged/blob/main/_data-master/oracles/planet/planet.yaml#L134 I think it should be Select table by: Life not ...by: Region

The context is:

    - Name: Opportunity
      Display name: Planetside Opportunity
      Content tags: [opportunity]
      Repeatable: true
      Description: |-
        Choose or roll on this table when you want inspiration for a beneficial encounter or event on a planetside journey, such as when you roll a strong hit with a match as you Undertake an Expedition, or if you Explore a Waypoint and find an opportunity.
      Part of speech: [fragment]
      Select table by: Region
      Tables:
        - Display name: Planetside Opportunity - Lifebearing
          Name: Lifebearing
          Requires:
            Location: [Planetside]
            Life: [Lifebearing, Simple, Sparse, Diverse, Bountiful, Overrun]
          Table:
           ...

The sub-tables have Requires of Location and Life. As Location is somewhat of a given, then it seems like it should be Life is selector? This would also match with the formatting of the table on page 317 of the 122421 version of the backer preview pdf.

I would make a pull request to fix it, but I'm not quite sure of which files are canonical and which are built by tools.

Thanks for the amazing work on Dataforged in general!

The structure of the individual move/ objects will remain the same. however, the IDs will change to reflect their place in the category hierarchy. the upshot is that it'll let me include category metadata.

• migrate moves
• migrate assets

couldn't hurt to drop all of that in a google drive folder, either; not everyone making tools wants/needs to deal with JSON. i should probably find a way to automate all of this.