UnofficialWIKI
Builder
Edit / Suggest changeSuggest deletion

Success Levels

successLevelSettings

The outcome bands an action's skill check can land in. Each tier is a score range with a player-facing name, narration instructions and an optional image, and one tier marks where success begins. Voyage rejects a world that leaves the section out.

Editor location
Files → Mechanics → Success Levels
Editor type
Edit in Studio + View JSON
API endpoint
/sections/successLevelSettings.json/sections/successLevelSettings.md
Size limits

No character-length caps for this section.

Related

Schema

json
{
  "successLevelSettings": {
    "firstSuccessfulTierId": "string",
    "tiers": [
      {
        "id": "string",
        "name": "string",
        "minScore": "number",
        "maxScore": "number",
        "prompt": "string",
        "imageUrl": "string"
      }
    ]
  }
}

Example: Voyage's default success tiers, which every new world starts from

json
{
  "successLevelSettings": {
    "firstSuccessfulTierId": "mixed-results",
    "tiers": [
      {
        "id": "critical-failure",
        "name": "Critical Failure",
        "minScore": null,
        "maxScore": -66,
        "imageUrl": "",
        "prompt": "[Note: {{characterName}} tries to do the action, but it fails in a dramatic, catastrophic way - if enemies are present, consider framing the failure as partly the result of an enemy's cleverness, tactics, or intervention that thwarts the attempt, rather than the player merely being inept.]"
      },
      {
        "id": "failure",
        "name": "Failure",
        "minScore": -65,
        "maxScore": -51,
        "imageUrl": "",
        "prompt": "[Note: {{characterName}} tries to do the action, but it fails - if enemies are present, consider framing the failure as partly the result of an enemy's cleverness, tactics, or intervention that thwarts the attempt, rather than the player merely being inept.]"
      },
      {
        "id": "mixed-results",
        "name": "Mixed Results",
        "minScore": -50,
        "maxScore": -26,
        "imageUrl": "",
        "prompt": "[Note: {{characterName}} does the action, but it is only partially successful with mixed results.]"
      },
      {
        "id": "basic-success",
        "name": "Basic Success",
        "minScore": -25,
        "maxScore": -1,
        "imageUrl": "",
        "prompt": "[Note: {{characterName}}'s action is successful.]"
      },
      {
        "id": "success",
        "name": "Success",
        "minScore": 0,
        "maxScore": 24,
        "imageUrl": "",
        "prompt": "[Note: {{characterName}}'s action is quite successful.]"
      },
      {
        "id": "great-success",
        "name": "Great Success",
        "minScore": 25,
        "maxScore": 49,
        "imageUrl": "",
        "prompt": "[Note: {{characterName}}'s action is very successful.]"
      },
      {
        "id": "critical-success",
        "name": "Critical Success",
        "minScore": 50,
        "maxScore": null,
        "imageUrl": "",
        "prompt": "[Note: {{characterName}}'s action is amazingly successful in an awesome way.]"
      }
    ]
  }
}

How it works

An action the engine resolves with a skill check produces a score, and successLevelSettings decides which outcome band that score falls in. The band it lands on names the outcome for the player and hands the narrator that band's prompt as guidance for describing it.

  • A tier is { id, name, minScore, maxScore, prompt } with an optional imageUrl. A world defines between 2 and 20 of them.
  • The bands are read in score order rather than file order, so rearranging the list changes nothing. They must tile the range exactly: each band begins one point above the previous band's maxScore, leaving no gaps and no overlaps.
  • The two ends are open: the lowest band sets minScore to null and the highest sets maxScore to null. Exactly one band may do each, and it must be the band at that end of the ladder.
  • firstSuccessfulTierId names the id of the lowest tier that counts as a success. That tier and every band above it succeed, everything below it fails. How far above the threshold a tier sits is what makes its success read as a stronger one, so a ladder with a single successful tier treats that tier as the strongest.
  • id must be unique and non-empty. name must be unique as well, compared ignoring case and surrounding spaces, so Great Success and great success collide.
  • Voyage rejects a world that leaves this section out, so unlike an optional settings section it cannot simply be omitted. The defaults above are the starting point.
  • Triggers read the outcome with the action-success-level condition, which matches a tier's name rather than its id, again ignoring case and surrounding spaces. The values are an ordered ladder, so the comparison operators rank them. A value matching no tier name leaves the condition permanently false. The engine also refuses to judge action-success-level in the same trigger as a story or story-text condition; put the story check on its own trigger (see Triggers).

Fields

firstSuccessfulTierId

The id of the lowest tier that counts as a success. That tier and every higher band succeed; the bands below it fail. It must name a tier in tiers.

tiers

The outcome bands, between 2 and 20 of them. They are read in score order and must tile the range with no gaps or overlaps, so the list's own order carries no meaning.

id

A stable identifier for this tier, unique within tiers and non-empty. firstSuccessfulTierId points at one of these.

name

The player-facing name for this outcome, and the value an action-success-level trigger condition matches against. It must be unique, compared ignoring case and surrounding spaces.

minScore

The lowest score this band covers, inclusive, as a whole number. Set it to null on the lowest band to leave that end open; on every other band it must be one point above the band below's maxScore.

maxScore

The highest score this band covers, inclusive, as a whole number. Set it to null on the highest band to leave that end open. It must be at or above this band's minScore.

prompt

The instruction handed to the narrator when an action lands in this band. {{characterName}} is replaced with the acting character's name.

imageUrl

An optional image shown with the outcome. Voyage limits which hosts it will load, so use the https URL Voyage gives you when the image is uploaded, or leave it blank for no image.