Factions

factions

Factions are the named organizations in your world - governing bodies, guilds, cults, criminal networks, or any group with shared goals. Each pairs a public face with a hidden agenda.

In the editor

"Organizations and groups that exist in the world, each with their own goals and influence"

Editor location: Files → World → Factions
Editor type: Edit in Studio + View JSON
API endpoint: /sections/factions.json/sections/factions.md
Size limits: factions.*.basicInfo — 4,000
factions.*.hiddenInfo — 4,000
factions (entire section) — 100,000

Schema

json

{
  "factions": {
    "<key>": {
      "name": "string",
      "basicInfo": "string",
      "factionType": "minor | major",
      "hiddenInfo": "string",
      "initialKnown": "boolean"
    }
  }
}

Example

json

{
  "factions": {
    "The Merchant Council": {
      "name": "The Merchant Council",
      "factionType": "major",
      "basicInfo": "The Merchant Council is the city's formal governing body, holding authority over trade licensing, taxation, city watch funding, and judicial appointments within the Capital. In practice its decisions are made through committee deals and tightly managed consensus — the public sessions are theater for motions already decided in private. Members are appointed by hereditary merchant houses, making the body self-perpetuating; no councillor has ever been removed by election. To the city's general population they represent stability, predictable law, and moderate taxation — an institution too useful to overthrow and too boring to threaten. To those who understand the city's actual power structures, they represent something different: a set of negotiable positions held by people with expensive tastes and finite leverage.",
      "hiddenInfo": "The council chair has been in a directed arrangement with a criminal syndicate for three years — not merely ignoring illegal operations but actively redirecting city watch patrols away from specific warehouse districts on scheduled nights. She believes the arrangement is a controlled exposure she can end at any time. The syndicate knows this is not true and has prepared documentation sufficient to destroy her position. A junior colleague entered the same arrangement two years later and does not know the full scope of what the chair committed to at the outset; he believes the arrangement is smaller than it is and has recently begun showing visible anxiety. The syndicate is preparing to expand its demands, using both councillors' exposure as leverage for permanent allocation of dockside authority. Neither councillor knows this is coming. A copy of the incriminating documents, believed destroyed, sits in the Old Customs Vault.",
      "initialKnown": true
    }
  }
}

Fields

name

Display name of the faction, shown to players. Required, and the outer key must match it exactly: Voyage rejects a world whose key and name differ. The full name is also what reveals a hidden faction when the story mentions it (see initialKnown).

factionType

Required, and one of "major" or "minor": Voyage rejects a world whose faction omits it. A major faction is labelled World in the journal and is also given to the AI whenever it generates a new region, so new regions can reference it. A minor faction is labelled Local and reaches the AI only through the regions, locations, and NPCs it is attached to. Factions are author-written: the engine does not create faction records, though it feeds the authored ones to the AI and tracks whether each is known.

initialKnown

Boolean (optional). Whether the faction starts known to the party. Set to false for secret organisations the player must discover through play; an unknown faction is hidden from the party's faction list until it becomes known.

Full-name discovery (initialKnown: false): after each turn the engine scans that turn's story text for the faction's full name as a whole word, ignoring case and extra spacing, and reveals the faction when it appears. Partial references and paraphrases don't count. A known-entity trigger effect reveals or hides the faction directly, so use one for an authored discovery moment. Give hidden factions distinctive names: a faction called "The Watch" would be revealed by any mention of a watch.

basicInfo

The faction's public face. A useful faction basicInfo covers what the faction is and its reach, how it operates, how outsiders perceive it, and any visible contradiction between stated purpose and actual behaviour. A few sentences usually isn't enough for a major faction.

Template: What + How + Perception + Contradiction (if any).

hiddenInfo

Strong faction hiddenInfo covers four things: the truth that contradicts basicInfo, the internal schism or pressure that secret creates, what different ranks of the faction actually know, and something actively happening right now that the player can discover and engage with. The last element is what turns backstory into a live situation — without it, the AI has history but no current hook to surface through play.

Authoring tips

The basicInfo/hiddenInfo split

The basicInfo/hiddenInfo split is where factions get interesting. basicInfo is the public face — what you'd read in a political pamphlet. hiddenInfo is what's actually driving the faction's decisions. Make them contradict each other specifically: not just "they're secretly evil" but "they genuinely believe they're doing the right thing while doing something that would horrify their public supporters."

Faction + World Lore sync rule

Pair each faction with a worldLore entry under the same key, with text identical to the faction's basicInfo. It gives the same information two retrieval pathways: semantic search (worldLore) and the faction itself. Nothing enforces the pairing; if the two diverge the narrator may surface inconsistent descriptions.

For a worked example of tracking faction standing through triggers see Faction Reputation Tracker in the Authoring Guide.

Factions

#Schema

#Example

#Fields

#name

#factionType

#initialKnown

#basicInfo

#hiddenInfo

#Authoring tips

#The basicInfo/hiddenInfo split

#Faction + World Lore sync rule