Resources

resourceSettings

Resources are the tracked bars in your game: health, mana, stamina, corruption, and so on. Exactly one resource carries isHealth: true and is the health bar. Each resource defines a starting and maximum value, UI bar color, recharge rate, and usage instructions for the narrator.

In the editor

"Character resources like health, mana, etc."

Editor location: Files → Mechanics → Resources
Editor type: Edit in Studio + View JSON
API endpoint: /sections/resourceSettings.json/sections/resourceSettings.md
Size limits: No character-length caps for this section.

Schema

json

{
  "resourceSettings": {
    "<key>": {
      "name": "string",
      "initialValue": "number",
      "maxValue": "number",
      "rechargeRate": "number",
      "restRechargeMultiplier": "number",
      "color": "string",
      "gainPerLevel": "number",
      "usageInstructions": "string",
      "isHealth": "boolean"
    }
  }
}

Example

json

{
  "resourceSettings": {
    "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,
      "restRechargeMultiplier": 1,
      "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"
    }
  }
}

Fields

name

string. Display name, shown to players. Required, and the outer key must match it exactly: Voyage rejects a world whose key and name differ.

initialValue

number. The current value a new character starts with.

maxValue

number. The maximum a new character starts with, not a ceiling the resource can never pass: traits, attributes and level gains all modify it from here. For the health resource this is the level-1 maximum (see the formula below).

rechargeRate

integer. Amount restored each tick. Must be a whole number; Voyage rejects a fraction.

restRechargeMultiplier

number. Fraction restored on rest: 1=full, 0.5=half, 0=none.

color

string. Hex color for UI bar.

gainPerLevel

number. The amount added to the resource's maximum on each level-up. Required on every resource; use 0 for one that doesn't scale.

isHealth

boolean. Optional. true marks the health bar: the resource combat damages, and the one whose reaching 0 means death. Set it on exactly one resource.

usageInstructions

string. Optional. Markdown given to the AI explaining the resource's behaviour. Include what raises or lowers it and what happens at thresholds.

Any additional resources (like mana) are added as sibling entries inside resourceSettings.

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 the whole party by default; set target to satisfyingPlayers to affect only the players who met the trigger's conditions.
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. 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, or a deterministic per-turn drain — 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:

Scope sentence — what actions consume this resource. "Mana is consumed when actively channeling magical energy." "Stamina is spent on physically demanding actions."
Cost tiers — a bulleted list mapping action types to numeric ranges. Minor / Moderate / Major / Extreme is a standard set; use whatever fits the resource.
"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), and overflow (gaining more than max and banking the excess). Write these rules as plain prose in usageInstructions; the narrator applies them. 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 doesn't enforce prose rules; use triggers for anything that must be exact.

Thematic tracker resources

Thematic tracker resources (Influence, Reputation, Luck, Favour) use a specific pattern: rechargeRate: 0, restRechargeMultiplier: 0, 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. A level change from a player-level trigger effect re-derives the maximum the same way and fills the current value to it. 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.

Resources

#Schema

#Example

#Fields

#name

#initialValue

#maxValue

#rechargeRate

#restRechargeMultiplier

#color

#gainPerLevel

#isHealth

#usageInstructions

#Authoring tips

#Driving resources mechanically (triggers and scripts)

#Writing usageInstructions

#Recovery mechanics not natively supported

#Thematic tracker resources

#Player HP formula