ravenous_roll20/docs/craft-json-v1.md

107 lines
3.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.