Skip to content

Instance policy seeds

Three seeded Config namespaces are policy a game owns rather than a platform default: chat.rules, what a message may carry and how often it may be sent, ext.session.player, what a player's ext column may hold, and session.loadout, the versioned schemas a player's loadout is checked against. All three ship with a working document, so a fresh instance has an answer before anyone has an opinion, and both are meant to be edited.

A seed is written once, by otomo-config seed on first run, and never over one that already exists: a namespace that is present is skipped whatever its document says. Editing one is therefore safe — your document is the one that survives a redeploy.

Editing is a config release, not a deploy

These documents live in the database, not in the image. To change a permitted attachment or a word:

  1. Namespaces → the namespace → Edit the draft, then Save draft.
  2. Create version.
  3. Releases → Compose release, choose that namespace's version, publish.

No rebuild, no restart, no new image: the live document is what a service reads. The release is also the rollback unit — publishing the previous version restores the previous rules — and every change carries an audit row naming who made it. admin sets a schema; live_ops writes a document and publishes. The editor is the same one every namespace uses (Edit tables of game data).

Allowing an attachment

chat.rules → attachments.items. An attachment is an economy item id, written the way the existing entries are. Ownership and permission are separate checks — a player must hold the item and the item must be named here, so this list is what a game curates, not what a player owns. Removing an id refuses it in chat without taking it out of anyone's inventory; the message is refused as attachment_unknown, before Economy is asked.

attachments.without_text decides whether an attachment may be the whole message. The seed ships no attachments, which is not an omission: the platform does not know which items a game draws, so it permits none until that game names its own, and a message carrying one is refused.

Nothing here is a game's noun. A "sticker", a "stamp" or a "flair" is an item a player owns and may attach, and it reaches chat as an item id in this list — the namespace carries no word for one game's version of it (design/29-game-boundary.md).

Adding an NG word

chat.rules → ng_words: a list of literal words, compared case-insensitively. Add a word as its own entry. The seed ships the list empty, which means no filtering is configured — not that every message is refused. Filtering is opt-in because a platform has no opinion on a game's language, and shipping words would be it having one.

The rest of the document is the same kind of policy: max_length (at most 140 characters), retention_messages (100 to 500), rate (a per-player, per-channel token bucket) and expiry (how long a party's or a match's channel outlives its last message). The chat service reads the namespace with a strict decoder, so a member it does not know is refused at load and the last good document stays in force — which is why the shape above is the service's, not a convenient one.

Declaring ext fields

ext.session.player seeds a declaration that names no fields, so the platform refuses every non-empty ext write. That is deliberate: a column nobody has designed should reject rather than accept anything, and a game that has designed it publishes its own declaration. Replace the draft with one whose schema accepts {} and then the fields you want, plus any indexes a query needs. The seed's schema document carries an examples entry with one shaped declaration to copy; it is documentation, not the seed, and nothing in the repo publishes it for you.

Declaring loadout schemas

session.loadout is the document Session reads to know what a player's loadout may contain. Its members are active_version (the schema version new loadouts are written in), versions (a map from a version number, written as a whole number from 1 without leading zeros, to a JSON Schema for a whole loadout document of that version), and two optional ones: lifetime_seconds (how long an unsaved loadout lasts, 0 or absent meaning it is kept until the player changes it, at most one year) and ready_policy (free, the default, lets a ready player keep saving; lock refuses a save until they un-ready). Session reads it with a strict decoder, so an unknown member, an active_version that is not a key of versions, or a version schema that does not compile refuses the whole document and the last good one stays in force. The document is capped at 1 MiB.

Whether loadouts are on is decided by the release, not by the document: a release that does not include session.loadout leaves them off, and a published document must define at least one version. The seeded draft is therefore the smallest document that parses: version 1 is {"type": "object"}, so a loadout is constrained only to being an object, it never expires, and Ready does not lock saving. It is inert until a release includes it. Replace version 1 with the schema your loadouts need before you publish, and add a version rather than editing one that players have already saved against. The schema's examples entry shows a two-version document to copy.