Resources

{
  "health": {
    "name": "health",
    "initialValue": 80,
    "maxValue": 80,
    "rechargeRate": 1,
    "restRechargeMultiplier": 1,
    "color": "#ef4444",
    "gainPerLevel": 10,
    "isHealth": true,
    "usageInstructions": "### Health\nHealth is lost when the character takes a direct physical strike or injury — not for environmental atmosphere or narrative lingering.\n\n### Deduct when\n- Minor wound: 5-15\n- Serious wound: 15-35\n- Near-fatal injury: 35-60\n\n### Do not deduct when\n- The scene describes wounds aching or lingering from a prior turn without a new strike\n- The environment is dangerous but no specific hit connects\n- The character is unconscious, being carried, or stabilized\n- An NPC is describing past damage\n\n### Recovery\n- Rest in a safe location: 50-80% restored\n- Medical treatment: additional 10-30 on top of rest"
  },
  "mana": {
    "name": "mana",
    "initialValue": 40,
    "maxValue": 100,
    "rechargeRate": 0,
    "replenishOnLongRest": true,
    "restRechargeMultiplier": 1,
    "canCost": true,
    "color": "#8b5cf6",
    "gainPerLevel": 5,
    "isHealth": false,
    "usageInstructions": "### Mana\nMana is spent when actively channeling or casting — not when magic is mentioned, discussed, or witnessed.\n\n### Cost by scale\n- Minor cantrip or passive effect: 0\n- Standard spell or ability: 5-10\n- Powerful multi-target or sustained effect: 15-25\n- Legendary or world-altering: 30+\n\n### Do not deduct when\n- The character perceives, identifies, or describes magic in the environment\n- An NPC casts a spell at the character\n- Magic is discussed in conversation without active use\n\n### Recovery\n- Full recovery on long rest\n- Half recovery on short rest for primary magic class only\n- Overdrawing (below 0): the character takes 2d6 damage and cannot cast until they rest"
  }
}

replenishOnLongRest

boolean. Mechanically refills the resource to its max when a Long Rest action is completed. Extra-codec - accepted but not validated.

📋 Note (replenishOnLongRest): Extra-codec - not in the formal schema but accepted by the engine. The codec-validated equivalent is restRechargeMultiplier (a number): 1.0 = full refill, 0.5 = half, 0 = no rest recovery. Use restRechargeMultiplier as the primary mechanism. State the same rule in usageInstructions ("Refills to maximum on Long Rest.") for prose-level clarity.

canCost

boolean. false = engine and UI prevent this resource from being selected as a cost for abilities. Use for trackers that accumulate rather than get spent. Extra-codec - accepted but not validated.

📋 Note (canCost): Extra-codec - not in the formal schema but accepted by the engine. Set false to mark a resource as accumulation-only (cannot be spent by ability costs). Reinforce the rule in usageInstructions for prose clarity ("This resource only ever increases - it cannot be spent or reduced by ability costs.").

Authoring tips

Driving resources mechanically (triggers and scripts)

usageInstructions is the soft path — the narrator reads the prose and decides when and how much to change a resource. For exact, deterministic changes that do not depend on the AI's judgement, drive the resource from triggers:

• A player-resource effect changes a resource by an exact amount — operators add, subtract, multiply, divide, set. It applies to all party characters at once.
• A player-resource condition gates a trigger on a resource value (fires if any party member matches), so something can happen the moment a resource crosses a threshold.
• Inside a trigger script, check({ type: "player-resource", resource: "<key>" }) reads the live per-character value, and you can push further player-resource effects for derived or conditional math (counters, costs that scale, spending one resource to refill another).

Reference the resource by its key (heed the name bug above). This is how you build hard mechanics — an ability or evolution that unlocks at a resource milestone, a tracker that ticks up on specific events, a deterministic per-turn drain (also achievable with a negative rechargeRate) — instead of leaving it to the narrator.

Writing usageInstructions

On usageInstructions: This is the most important field in a resource definition — it's the prose that actually reaches the AI. A well-structured entry follows a consistent three-part pattern:

1. Scope sentence — what actions consume this resource. "Mana is consumed when actively channeling magical energy." "Stamina is spent on physically demanding actions."
2. Cost tiers — a bulleted list mapping action types to numeric ranges. Minor / Moderate / Major / Extreme is a standard set; use whatever fits the resource.
3. "Do not deduct when" list — explicit guard rails. Without this, the AI may subtract health for passive atmosphere ("the wound aches as you walk"), subtract mana for mentioning magic, or drain stamina for a light conversation. List the specific non-triggering conditions: "when unconscious or carried," "when environment is generally dangerous but no specific strike occurs," "during dialogue with no physical exertion."

Recovery rules belong in usageInstructions prose for anything beyond the simple schema fields — partial rest recovery, conditional recovery zones, overdraw penalties.

Recovery mechanics not natively supported

Recovery mechanics the schema does not support natively: short rest recovery (partial, class-specific), conditional recovery (only if the player meditates / only in a safe zone), overflow (gaining more than max and banking the excess), and spending one resource to restore another. All of these are achievable via usageInstructions - write the rule as plain prose and the narrator applies it. Example: "Recovers fully on Long Rest. Recovers 50% on Short Rest for the primary magic class only. Cannot recover inside the Scar Zone." The engine won't enforce it mechanically, but the narrator reads and follows it.

Thematic tracker resources

Thematic tracker resources (Influence, Reputation, Luck, Favour) use a specific pattern: rechargeRate: 0, restRechargeMultiplier: 0, canCost: false, and usageInstructions describing what narrative events increase or decrease the value. These are not "bars" in the traditional sense — they are narrative state trackers that the AI manages through events rather than spending. Define how they increase, what they represent at different values, and what happens when they hit floor or ceiling.

Player HP formula

Player HP formula: When a resource has isHealth: true, the engine derives player HP from its codec fields plus an engine-constant milestone bonus:

Player HP at level L = maxValue + gainPerLevel * (L - 1) + milestoneHealthBonus
milestoneHealthBonus = floor(L / 5) * 5    // engine constant; not configurable

maxValue is the level-1 maximum, not an absolute cap; per-level growth comes from gainPerLevel, and every 5 character levels grants an additional +5 HP milestone. Players also receive +2 damage on the same milestone schedule (engine constant; lives in combat math, not a resource field).

Example: with maxValue: 80, gainPerLevel: 10, level 20 → 80 + 10*19 + floor(20/5)*5 = 80 + 190 + 20 = 290 HP.