3.8 KiB
Ravenous craft JSON interface, version 1
The machine-readable contract is
ravenous-craft-v1.schema.json; this page
documents its intended use.
The crafting website exports finalized sheet values. The Roll20 importer does not reproduce or verify crafting rules: it validates the envelope, then creates one repeating sheet row per item. This separation lets the website evolve its recipe UI without coupling it to Roll20 attribute names.
Envelope
{
"format": "ravenous-roll20-craft",
"version": 1,
"craft": {
"name": "Lame de braise",
"discipline": "forge",
"element": "Feu",
"recipe": "Acier; Affilage",
"level": 3,
"difficulty": 2
},
"items": []
}
items is required and contains 1–100 entries. craft is optional metadata
for producers and archives; the importer validates but does not put it on the
sheet. Put any metadata that players must see in the item's notes, effects,
or description field. Text values are limited to 10,000 characters (names to
150). Numbers must be finite. Unknown fields are rejected so producer mistakes
do not silently disappear.
Item types
Each item requires type and a non-empty name. Omitted fields keep the
sheet's normal default. JSON numbers and strings are accepted for sheet fields.
For attacks, dice is an optional default for the Nombre de dés prompt; the
player chooses the actual pool whenever the attack is rolled.
type |
Destination | Allowed fields besides type |
|---|---|---|
attack |
Combat → Attaques | name, dice, threshold, temp, auto_successes, roll_dice, base_damage, damage_per_success, break_damage, rmax, notes, dodge_threshold, parry_threshold, reposition_threshold |
protection |
Combat → Protections | name, protection, integrity, integrity_max, parry, dodge, effects |
consumable |
Potions & nourriture | name, kind, quantity, duration, description |
modifier |
Effets temporaires | name, duration, description |
For a consumable, kind is exactly Nourriture, Potion, or Autre.
Protection imports intentionally omit active: imported armor must be selected
manually for the struck location. The importer never spends ingredients,
changes HP, equips an item, or applies its effects.
Example containing two outputs from one craft:
{
"format": "ravenous-roll20-craft",
"version": 1,
"craft": { "name": "Expédition ardente", "discipline": "forge", "element": "Feu" },
"items": [
{
"type": "attack",
"name": "Lame de braise",
"dice": 5,
"threshold": 6,
"base_damage": 8,
"damage_per_success": 2,
"break_damage": 1,
"rmax": 3,
"notes": "Feu — Acier; Affilage"
},
{
"type": "consumable",
"name": "Huile de braise",
"kind": "Autre",
"quantity": 2,
"duration": "1 combat",
"description": "Enduit une arme; effet déterminé par la recette."
}
]
}
Roll20 commands
Install roll20_mod/ravenous_craft_import.js as a Mod script. A player may
target a character they control and read a shared/controlled handout; a GM may
target any character and handout. With one destination token selected:
!ravenous-import-craft {"format":"ravenous-roll20-craft","version":1,"items":[{"type":"consumable","name":"Potion rouge","kind":"Potion","quantity":1}]}
!ravenous-import-craft --handout HANDOUT_ID
Without a token, or to target a character directly:
!ravenous-import-craft --id CHARACTER_ID {JSON}
!ravenous-import-craft --id CHARACTER_ID --handout HANDOUT_ID
For large JSON, a GM can paste it into a private handout's GM Notes. A player must use the visible Notes of a shared or controlled handout. Then use the handout form and open the destination sheet so its workers refresh derived protection summaries.