# Open Character Format (OCF)

> One character format for every tabletop RPG. Packs hold a game's rules as data (fields,
> formulas, content); a reference engine computes characters from them; every app that speaks
> OCF reads the same character files.

- The engine knows the rules; the app owns the experience. Apps never write a game's math: they
  load packs into a ruleset, call the engine, and render what it returns.
- A character file holds only base state (inputs, owned items, picks). Every value is computed by
  `computeSheet`, with a breakdown of where it came from.
- Engine calls: `loadRuleset`, `computeSheet`, `listOptions`, `applyChanges`, `startAction`,
  `continueAction`, `upgrade`. The engine returns keys and codes, never display text.
- npm: `@opencharacter/engine` (the TypeScript reference engine, no runtime dependencies),
  `@opencharacter/spec` (docs, JSON Schemas, conformance suite), `@opencharacter/text`
  (wording helper), `@opencharacter/packs` (every official pack), and one package per pack.
- Spec version 0.1.0. Source: https://github.com/pixelqueue/opencharacter. Code and spec are Apache-2.0; each pack keeps its own license.
- Every page below is Markdown; the website has each one as HTML at the same path without `.md`.
  [llms-full.txt](https://opencharacterformat.org/llms-full.txt) holds every guide and spec chapter in one file.

## Guides

- [Building an app with OCF](https://opencharacterformat.org/guides.md): These guides are for people building apps that use OCF characters: a VTT, a character builder, a campaign manager, a Discord bot, a game server. They explain…
- [Quick start](https://opencharacterformat.org/guides/quick-start.md): This page loads the 5E SRD pack, computes a character's sheet, changes the character and rolls an attack. The other guides explain each step in depth.
- [Implementing OCF](https://opencharacterformat.org/guides/implementing.md): This page is the view from above: how much of OCF your app needs, and where the engine should run. The other guides cover each part in depth; this one says…
- [Apps not written in JavaScript](https://opencharacterformat.org/guides/other-languages.md): The reference engine is TypeScript. If your app is in C#, Swift, Kotlin, Python, Rust, Go or GDScript, you have three options: run the reference engine from…
- [Packs and rulesets](https://opencharacterformat.org/guides/packs-and-rulesets.md): A pack is a versioned bundle of game data: an edition's rules, a sourcebook's content, a homebrew collection. A ruleset is what the engine makes from one or…
- [Storing characters](https://opencharacterformat.org/guides/storing-characters.md): The character file is the one standard format for a character. Apps must be able to import and export it, and it's what the engine reads. How you store…
- [Showing a sheet](https://opencharacterformat.org/guides/showing-a-sheet.md): Everything your app shows about a character comes from computeSheet. This page explains its output, how to lay out a sheet from a pack's display hints, and…
- [Text and translation](https://opencharacterformat.org/guides/text-and-translation.md): Each pack has one message file per language: a flat map from key to an ICU MessageFormat message.
- [Showing text](https://opencharacterformat.org/guides/showing-text.md): Text and translation explains where text lives and how each key is built. This page shows the shortcut: @opencharacter/text, a small helper that builds the…
- [Changing characters](https://opencharacterformat.org/guides/changing-characters.md): Your app never edits a character file directly. Every change, from typing a new Strength score to taking damage to levelling up, goes through applyChanges.
- [Building characters](https://opencharacterformat.org/guides/building-characters.md): Character creation and levelling up are mostly choices: a class, a playbook, skills, a fighting style, cantrips, a subclass at level 3. The packs declare…
- [Upgrading characters](https://opencharacterformat.org/guides/upgrading-characters.md): A character pins the exact versions of its packs. When a pack publishes a new version, nothing happens to existing characters until your app decides to…
- [Rolling dice](https://opencharacterformat.org/guides/rolling-dice.md): Attacks, saving throws, FitD action rolls, Mothership panic checks, rests: anything that rolls dice or makes an in-play decision is an action. The engine…
- [Other characters](https://opencharacterformat.org/guides/other-characters.md): Every engine call works on one character. Combat, spells cast on allies and monsters all involve several, so your app does the routing: it reads one…

## Specification

- [Open Character Format: specification](https://opencharacterformat.org/spec.md): OCF is an open format for tabletop RPG character data. The spec covers three layers.
- [Packs](https://opencharacterformat.org/spec/packs.md): A pack is a versioned bundle of rules and/or content: a game edition, a sourcebook, a homebrew collection. Packs are plain files. Nothing in a pack is code.
- [Rules and fields](https://opencharacterformat.org/spec/rules-and-fields.md): The rules layer is a set of rules documents (rules.schema.json) per pack, merged by the build. This chapter covers fields, settings, constraints, result bands…
- [Content](https://opencharacterformat.org/spec/content.md): Each game defines its own content types in data (content-type.schema.json), declared under contentTypes in a rules document. Mothership does not inherit 5E's…
- [Effects](https://opencharacterformat.org/spec/effects.md): An effect (effect.schema.json) is how active content changes the character. It applies while the content carrying it is active (content.md) and its when…
- [Formulas](https://opencharacterformat.org/spec/formulas.md): The formula language computes field values, conditions, effect values, query filters and rolls. It is OCF's own language. Its syntax, edge-case rules and type…
- [Dice and actions](https://opencharacterformat.org/spec/dice-and-actions.md): Dice notation is the familiar VTT notation, written inside formulas.
- [Characters](https://opencharacterformat.org/spec/characters.md): A character file (character.schema.json) is the one strict, standard file for exchanging a character between apps. Apps MUST be able to import and export it…
- [Engine interface](https://opencharacterformat.org/spec/engine-interface.md): Every engine, the TypeScript reference engine and community ports alike, exposes the same calls. Ports may follow their own language's style (naming…
- [Engine core](https://opencharacterformat.org/spec/engine-core.md): How loadRuleset, computeSheet, listOptions and applyChanges behave. The calls' inputs and outputs are in engine-interface.md and ../schemas/engine/. This…
- [Actions at run time](https://opencharacterformat.org/spec/engine-actions.md): How startAction and continueAction run an action: building and rolling each roll, choices, branches, proposed changes and outcomes, pausing at checkpoints…
- [Display hints](https://opencharacterformat.org/spec/display-hints.md): Display hints (display.schema.json) are optional presentation data under display in a rules document. They never affect calculations or saved state. Apps may…
- [Translation](https://opencharacterformat.org/spec/i18n.md): Every player-facing string (names, labels, short labels, descriptions, group labels, choice prompts) is looked up by key. None is written inline next to the…
- [Upgrades](https://opencharacterformat.org/spec/upgrades.md): Characters pin exact pack versions, and the app decides when, or whether, to upgrade a character. Most new versions need no upgrade work: only base state is…
- [Versioning](https://opencharacterformat.org/spec/versioning.md): There are three separate version numbers.

## Official packs

- [5E System Reference Document 5.1](https://github.com/pixelqueue/opencharacter/tree/main/packs/5e/srd-5.1): `5e-srd-5.1` 0.1.0, CC-BY-4.0, npm `@opencharacter/5e-srd-5.1`
- [Fate Core](https://github.com/pixelqueue/opencharacter/tree/main/packs/fate/core): `fate-core` 0.1.0, CC-BY-3.0, npm `@opencharacter/fate-core`
- [Forged in the Dark crew](https://github.com/pixelqueue/opencharacter/tree/main/packs/fitd/crew): `fitd-crew` 0.1.0, mechanics-only, npm `@opencharacter/fitd-crew`
- [Forged in the Dark scoundrel](https://github.com/pixelqueue/opencharacter/tree/main/packs/fitd/scoundrel): `fitd-scoundrel` 0.1.0, mechanics-only, npm `@opencharacter/fitd-scoundrel`
- [MÖRK BORG](https://github.com/pixelqueue/opencharacter/tree/main/packs/mork-borg/core): `mork-borg-core` 0.1.0, mechanics-only, npm `@opencharacter/mork-borg-core`
- [Mothership 1e](https://github.com/pixelqueue/opencharacter/tree/main/packs/mothership/1e): `mothership-1e` 0.1.0, mechanics-only, npm `@opencharacter/mothership-1e`
- [Second Edition fantasy rules (ORC)](https://github.com/pixelqueue/opencharacter/tree/main/packs/orc/2e): `orc-2e` 0.1.0, ORC, npm `@opencharacter/orc-2e`

## Machine-readable

- [packs.json](https://opencharacterformat.org/packs.json): the official packs as JSON (ID, name, version, license, npm package, source, dependencies)
- [action.schema.json](https://opencharacterformat.org/schemas/0.1/action.schema.json): JSON Schema (draft 2020-12)
- [change.schema.json](https://opencharacterformat.org/schemas/0.1/change.schema.json): JSON Schema (draft 2020-12)
- [character.schema.json](https://opencharacterformat.org/schemas/0.1/character.schema.json): JSON Schema (draft 2020-12)
- [choice.schema.json](https://opencharacterformat.org/schemas/0.1/choice.schema.json): JSON Schema (draft 2020-12)
- [common.schema.json](https://opencharacterformat.org/schemas/0.1/common.schema.json): JSON Schema (draft 2020-12)
- [content-item.schema.json](https://opencharacterformat.org/schemas/0.1/content-item.schema.json): JSON Schema (draft 2020-12)
- [content-type.schema.json](https://opencharacterformat.org/schemas/0.1/content-type.schema.json): JSON Schema (draft 2020-12)
- [display.schema.json](https://opencharacterformat.org/schemas/0.1/display.schema.json): JSON Schema (draft 2020-12)
- [effect.schema.json](https://opencharacterformat.org/schemas/0.1/effect.schema.json): JSON Schema (draft 2020-12)
- [engine/action-run.schema.json](https://opencharacterformat.org/schemas/0.1/engine/action-run.schema.json): JSON Schema (draft 2020-12)
- [engine/apply-changes.schema.json](https://opencharacterformat.org/schemas/0.1/engine/apply-changes.schema.json): JSON Schema (draft 2020-12)
- [engine/check-release.schema.json](https://opencharacterformat.org/schemas/0.1/engine/check-release.schema.json): JSON Schema (draft 2020-12)
- [engine/compute-sheet.schema.json](https://opencharacterformat.org/schemas/0.1/engine/compute-sheet.schema.json): JSON Schema (draft 2020-12)
- [engine/continue-action.schema.json](https://opencharacterformat.org/schemas/0.1/engine/continue-action.schema.json): JSON Schema (draft 2020-12)
- [engine/error.schema.json](https://opencharacterformat.org/schemas/0.1/engine/error.schema.json): JSON Schema (draft 2020-12)
- [engine/list-options.schema.json](https://opencharacterformat.org/schemas/0.1/engine/list-options.schema.json): JSON Schema (draft 2020-12)
- [engine/load-ruleset.schema.json](https://opencharacterformat.org/schemas/0.1/engine/load-ruleset.schema.json): JSON Schema (draft 2020-12)
- [engine/rules-issue.schema.json](https://opencharacterformat.org/schemas/0.1/engine/rules-issue.schema.json): JSON Schema (draft 2020-12)
- [engine/ruleset.schema.json](https://opencharacterformat.org/schemas/0.1/engine/ruleset.schema.json): JSON Schema (draft 2020-12)
- [engine/start-action.schema.json](https://opencharacterformat.org/schemas/0.1/engine/start-action.schema.json): JSON Schema (draft 2020-12)
- [engine/upgrade.schema.json](https://opencharacterformat.org/schemas/0.1/engine/upgrade.schema.json): JSON Schema (draft 2020-12)
- [field.schema.json](https://opencharacterformat.org/schemas/0.1/field.schema.json): JSON Schema (draft 2020-12)
- [follow-up.schema.json](https://opencharacterformat.org/schemas/0.1/follow-up.schema.json): JSON Schema (draft 2020-12)
- [formula.schema.json](https://opencharacterformat.org/schemas/0.1/formula.schema.json): JSON Schema (draft 2020-12)
- [homebrew.schema.json](https://opencharacterformat.org/schemas/0.1/homebrew.schema.json): JSON Schema (draft 2020-12)
- [i18n.schema.json](https://opencharacterformat.org/schemas/0.1/i18n.schema.json): JSON Schema (draft 2020-12)
- [pack-release.schema.json](https://opencharacterformat.org/schemas/0.1/pack-release.schema.json): JSON Schema (draft 2020-12)
- [pack.schema.json](https://opencharacterformat.org/schemas/0.1/pack.schema.json): JSON Schema (draft 2020-12)
- [query.schema.json](https://opencharacterformat.org/schemas/0.1/query.schema.json): JSON Schema (draft 2020-12)
- [roll-item.schema.json](https://opencharacterformat.org/schemas/0.1/roll-item.schema.json): JSON Schema (draft 2020-12)
- [rules.schema.json](https://opencharacterformat.org/schemas/0.1/rules.schema.json): JSON Schema (draft 2020-12)
- [situational.schema.json](https://opencharacterformat.org/schemas/0.1/situational.schema.json): JSON Schema (draft 2020-12)
- [upgrade.schema.json](https://opencharacterformat.org/schemas/0.1/upgrade.schema.json): JSON Schema (draft 2020-12)

## Optional

- [Glossary](https://opencharacterformat.org/project/glossary.md): One-line definitions of OCF terms, consistent with the specification.
- [Packages](https://opencharacterformat.org/project/packages.md): Every package this repository publishes to npm, under the @opencharacter scope.
- [Contributing to the Open Character Format](https://opencharacterformat.org/project/contributing.md): Thanks for helping. Start with AGENTS.md: it lists where things live, the commands, and the rules. This file covers what every contribution needs.