UnofficialWIKI
Builder
Edit / Suggest changeSuggest deletion

Premade Characters

premadeCharacters

Pre-built character templates a player can select at session start instead of building one from scratch.

Editor location
Files → World → Premade Characters
Editor type
Edit in Studio + View JSON
API endpoint
/sections/premadeCharacters.json/sections/premadeCharacters.md
Size limits
  • premadeCharacters (entry count) — 100 entries
  • premadeCharacters.* (each, compact JSON) — 20,000
  • premadeCharacters.*.traits (count) — 40 traits
Related

Schema

json
{
  "premadeCharacters": [
    {
      "name": "string",
      "gender": "string",
      "description": "string",
      "attributes": {
        "<key>": "number"
      },
      "traits": [
        "string"
      ],
      "backstory": "string",
      "portraitUrl": "string",
      "portraitFocusX": "number",
      "portraitFocusY": "number",
      "portraitZoom": "number",
      "replacesNpc": "string",
      "generatedBackground": "string",
      "generatedAppearance": "string",
      "voiceTag": "string",
      "worldVoiceId": "string"
    }
  ]
}

Example

json
{
  "premadeCharacters": [
    {
      "name": "Edra Vane",
      "gender": "female",
      "description": "A former city archivist who left the guild under unclear circumstances. She knows where the bodies are buried - metaphorically and otherwise - and has the patience to find out what she is missing. Edra spent a decade cataloguing documents others assumed were unimportant. When she found records contradicting the official history of a land dispute, her supervisor reassigned her before she could finish the analysis. She kept copies. She does not know yet what they prove.",
      "traits": ["Human", "Scholar", "Investigator", "Neutral Good"],
      "portraitUrl": "https://world-assets.example/premade/edra-vane.webp",
      "voiceTag": "female harsh commanding"
    }
  ]
}

Premade-only mode. World creators can disable custom character creation by setting characterCreationSettings.customizationEnabled to false, so players can only choose from these creator-authored premade characters instead of building one from scratch.

Fields

description

description serves two roles simultaneously: it's what the player reads at character selection, and it's the Background: field sent to the story AI every turn. Lead with a hook that sells the character, then expand into history, motivation, and voice.

traits

traits is how the premade gets its attributes, skills, resources, abilities, and starting items — via the normal trait pipeline.

replacesNpc

replacesNpc — when this premade is selected, the named NPC is fully removed from game state. Nothing from the original NPC is inherited (description, location, faction, abilities, equipment all come from the premade). Use only when the premade canonically IS that NPC.

Warning (replacesNpc and dependencies): Because the named NPC is fully removed from game state, do not target an NPC that a quest or trigger depends on. Anything referencing that NPC — quest objectives, trigger conditions, dialogue gates — is left pointing at an entity that no longer exists, which can break the quest or trigger when the premade is chosen. Reserve replacesNpc for NPCs nothing else relies on.

name

The character's name, copied directly to the player.

gender

Normalized to "male", "female", or "non-binary".

attributes

Attribute values keyed by attribute name; unset attributes fall back to defaults, unknown keys are ignored. Prefer carrying attributes through traits instead: setting them directly on a premade drifts from trait-driven balancing and is hard to narrow down when attribute balance needs adjusting.

backstory

Hand-written backstory that becomes the character's Background: line on every story turn, overriding description when both are set. Prefer a single strong description and omit backstory (see "Do not include" below).

portraitUrl

Portrait image URL, used as-is; skips portrait generation.

portraitFocusX

Positions the visible window over the source image along the horizontal axis, as a percentage: 0 holds the left edge, 50 centres it, 100 holds the right edge. Saved by the crop control rather than typed by hand, and applied wherever Voyage shows the image.

portraitFocusY

Positions the visible window over the source image along the vertical axis, as a percentage: 0 holds the top edge, 50 centres it, 100 holds the bottom edge. Saved by the crop control rather than typed by hand, and applied wherever Voyage shows the image.

portraitZoom

Scales the image inside its frame, as a percentage of the unzoomed fit: 100 fills the frame with no magnification, 150 shows it at one and a half times, cropping to the area picked by the focus fields. Saved by the crop control rather than typed by hand, and applied wherever Voyage shows the image.

voiceTag

The TTS voice this character speaks with. See the Voice Catalog for the voices available to name. A character left without one is given a voice during play, matched from its gender and traits, so set it to pin a specific voice rather than take whichever fits.

worldVoiceId

Points at a worldVoices entry by its key, giving this character that voice. Use it in place of voiceTag when the voice is one the world defines and more than one character may share.

generatedBackground

Sets the generated background used by this premade character.

generatedAppearance

Sets the generated appearance used by this premade character.

Do not include

Do not include: backstory (redundant with description — if both are set, backstory overrides description in the Background: slot); attributes (use traits instead).

Selection lifecycle

Selection lifecycle. Each entry becomes a selectable card in the character-creation UI (use [] to skip this feature). When a player selects a premade the engine:

  1. Copies name and gender directly.
  2. Resolves traits through the normal pipeline (modifiers, starting items, abilities). Unknown trait names are silently skipped. excludedBy mutual-exclusion is bypassed — premades can combine traits that would normally conflict.
  3. Uses portraitUrl as-is, skipping portrait generation.
  4. If replacesNpc is set, removes the matching NPC from game state at session start and any mid-game join.
  5. If the player customizes the premade in character creation, both description and backstory are replaced by an AI-generated profile seeded from the player's edits.

Note: Character portraits are portrait-orientation: Voyage's own generator produces 896×1200, and the minimum is 600×600. In the editor you can upload your own or generate one from a prompt; portraitUrl is used as-is, skipping generation.