Relationship Stages

relationshipStages

Optional labels for the relationship-score bands the engine tracks on every NPC. Rename the stages and set their score ranges; players see these labels and the AI uses them as context. Define none and Voyage falls back to its default stages.

In the editor

"Relationship Stages"

Editor location
Files → Mechanics → Relationship Stages
Editor type
Edit in Studio + View JSON
Size limits

No character-length caps for this section.

Schema

json
{
  "relationshipStages": [
    {
      "name": "string",
      "minScore": "number",
      "maxScore": "number"
    }
  ]
}

Example: the default relationship stages (used when a world defines none)

json
{
  "relationshipStages": [
    {
      "name": "Nemesis",
      "minScore": -100,
      "maxScore": -81
    },
    {
      "name": "Antagonist",
      "minScore": -80,
      "maxScore": -61
    },
    {
      "name": "Hostile",
      "minScore": -60,
      "maxScore": -41
    },
    {
      "name": "Unfriendly",
      "minScore": -40,
      "maxScore": -21
    },
    {
      "name": "Cold",
      "minScore": -20,
      "maxScore": -1
    },
    {
      "name": "Neutral",
      "minScore": 0,
      "maxScore": 0
    },
    {
      "name": "Warm",
      "minScore": 1,
      "maxScore": 20
    },
    {
      "name": "Friendly",
      "minScore": 21,
      "maxScore": 40
    },
    {
      "name": "Confidant",
      "minScore": 41,
      "maxScore": 60
    },
    {
      "name": "Ally",
      "minScore": 61,
      "maxScore": 80
    },
    {
      "name": "Devoted",
      "minScore": 81,
      "maxScore": 100
    }
  ]
}

How it works

Every NPC carries a relationship score from -100 to 100 that reflects how they feel about the player. Negative scores mean dislike, distrust, or opposition; positive scores mean warmth, trust, or attachment. relationshipStages maps score ranges to the labels shown to players and handed to the AI as context, so NPC behavior can reflect your world's own terminology (a romance world's Fond or Soulbound, a rivalry world's Threatened or Sworn Nemesis).

  • Each stage is a { name, minScore, maxScore } object with a unique name and whole-number scores. If you define this section, the stages must cover every score from -100 to 100 with no gaps and no overlaps, so any score resolves to exactly one stage.
  • Omit the section entirely to use the default set shown above; a present-but-empty [] is rejected, so cover the full range or leave the section out.
  • This section only names the bands. How fast scores move is plain-language pacing you write in the relationship_change_updates block of NPC Updates, not a field here.
  • Triggers read a score with the npc-relationship condition and a stage name with npc-relationship-stage, and change a score with the npc-relationship effect (see Triggers). A changed score stays clamped to -100..100.

Fields

name

The label shown for this score band, in the player-facing UI and in AI context. Rename it to your world's terminology.

minScore

Lowest score this stage covers, inclusive. Keep it within -100 to 100 and at or below maxScore.

maxScore

Highest score this stage covers, inclusive. Keep it within -100 to 100 and at or above minScore.