ravenous_roll20/docs/craft-json-v1.md

3.8 KiB
Raw Permalink Blame History

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.