107 lines
3.6 KiB
Markdown
107 lines
3.6 KiB
Markdown
# Ravenous craft JSON interface, version 1
|
||
|
||
The machine-readable contract is
|
||
[`ravenous-craft-v1.schema.json`](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
|
||
|
||
```json
|
||
{
|
||
"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`, `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:
|
||
|
||
```json
|
||
{
|
||
"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. Commands are
|
||
GM-only. With one destination token selected:
|
||
|
||
```text
|
||
!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:
|
||
|
||
```text
|
||
!ravenous-import-craft --id CHARACTER_ID {JSON}
|
||
!ravenous-import-craft --id CHARACTER_ID --handout HANDOUT_ID
|
||
```
|
||
|
||
For large JSON, paste it into a private handout's **GM Notes** and use the
|
||
handout form. Open the destination sheet after import so its workers refresh
|
||
derived protection summaries.
|