Skip to content

Namespace presets

Some things a game needs are a list of records, not a bespoke admin page: announcements, news, rotating offers, a ban list. This page is the preset for the first of those — a ready-made schema, table layout and example document for announcements — and the shape to copy if you build another.

A list of records is a Config namespace, and the namespace editor already edits an array of records as a table (Edit tables of game data): add and delete rows, a typed cell per column, validation against the schema. Everything a namespace has then applies: a draft separate from what is live, versions, publish, promote to live, roll back, and an audit row for each. Publishing an announcement is a release, so it rolls back with the release it shipped in, and it cannot be edited in place while players are reading it.

The admin website's Announcements page (under Content) is a friendlier way to write the same rows. It edits this namespace's draft and nothing else, so everything above still applies: it saves the draft, cuts a version and hands you to the release composer. It adds a preview of what a player would see at a time you pick, and shows the time zone you typed alongside the UTC time that is saved. The namespace and its schema below are what it needs to exist; you can still edit the same rows in the namespace editor.

You need admin to create the namespace and set its schema and presentation, and live_ops to write announcements and publish.

What you end up with

  • a namespace named announcements, whose document is { "announcements": [ … ] };
  • a table with one row per announcement per language, so the same news can exist in en and ja;
  • a published flag and an optional start and end, so a row can sit in the document and out of the feed until its time comes, and stop being shown when it is over;
  • an order column, so the feed has a deliberate order rather than the order rows were typed.

Step 1: Create the namespace

Namespaces → New namespace, name it announcements, audience client (players' games read it).

A deployment that ran config seed already has it, with this schema and an empty list (seeding skips a namespace that exists, so nothing here overwrites your work). Config also refuses a save or a version whose rows break a rule a schema cannot express: an ends_at that is not after its starts_at, or two rows with the same id and locale. That is 422 validation_failed, with each broken row listed under error.details.errors.

Step 2: Paste the schema

Open the namespace's Schema page, choose Edit, and paste this. It is the same JSON as announcementsSchema in services/adminui/src/config/presets/announcements.ts, which is the copy the console's tests validate; keep the two in step if you change either.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Announcements",
  "type": "object",
  "additionalProperties": false,
  "required": ["announcements"],
  "properties": {
    "announcements": {
      "type": "array",
      "title": "Announcements",
      "description": "One record per language. Two rows that share an id are the same announcement in two languages, so a player reads it in theirs.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "locale", "title", "body", "published", "order"],
        "properties": {
          "id": {
            "type": "string",
            "title": "Id",
            "pattern": "^[a-z0-9][a-z0-9-]{0,47}$",
            "description": "Groups the translations of one announcement. Lower case letters, digits and dashes, and never changed once players have seen it."
          },
          "locale": {
            "type": "string",
            "title": "Locale",
            "pattern": "^[a-z]{2,3}(-[A-Za-z0-9]{1,8})*$",
            "description": "A BCP-47 language tag, lower case: en, ja, pt-BR."
          },
          "title": { "type": "string", "title": "Title", "minLength": 1, "maxLength": 120 },
          "body": { "type": "string", "title": "Body", "minLength": 1, "maxLength": 2000 },
          "published": {
            "type": "boolean",
            "title": "Published",
            "default": false,
            "description": "A published row is one a player may be shown. Leaving it false keeps the row in the document and out of the feed."
          },
          "starts_at": {
            "type": ["string", "null"],
            "title": "Starts",
            "format": "date-time",
            "default": null,
            "description": "When it may first be shown, RFC 3339. Null means it has no start."
          },
          "ends_at": {
            "type": ["string", "null"],
            "title": "Ends",
            "format": "date-time",
            "default": null,
            "description": "When it stops being shown, RFC 3339. Null means it never expires."
          },
          "order": {
            "type": "integer",
            "title": "Order",
            "minimum": 0,
            "maximum": 9999,
            "default": 100,
            "description": "Lower sorts first. Two rows with the same order keep document order."
          }
        }
      }
    }
  }
}

additionalProperties: false at both levels is deliberate: a typo in a column name is refused when you save, rather than being stored and quietly ignored by whatever reads the feed.

Step 3: Say how the table looks

The editor works without this step, in schema property order with property names as labels. To get the columns you want, in the order you want, add an entry to the reserved ui.presentation namespace's document, keyed by the namespace name:

{
  "announcements": {
    "title": "Announcements",
    "tables": {
      "/announcements": {
        "label": "title",
        "columns": ["id", "locale", "title", "published", "starts_at", "ends_at", "order"],
        "search": ["id", "title", "body"],
        "newRow": { "published": false, "order": 100 }
      }
    }
  }
}

/announcements is the JSON Pointer of the array. A column this names that the schema does not define is ignored, and a property it does not name stays reachable from the column chooser, so this can never hide a field for good. Publish ui.presentation the same way as any other namespace.

Step 4: Write the first announcements

Open the namespace. Each row is one language of one announcement. To start from a working document, paste the example from announcementsExample in the same TypeScript file:

{
  "announcements": [
    {
      "id": "season-rollover",
      "locale": "en",
      "title": "A new season starts on Friday",
      "body": "Progress is kept, the ladder is reset, and the new maps are in the rotation.",
      "published": true,
      "starts_at": "2026-11-06T10:00:00Z",
      "ends_at": null,
      "order": 10
    },
    {
      "id": "season-rollover",
      "locale": "ja",
      "title": "金曜日から新しいシーズンが始まります",
      "body": "進行状況は引き継がれ、ランキングはリセットされます。",
      "published": true,
      "starts_at": "2026-11-06T10:00:00Z",
      "ends_at": null,
      "order": 10
    },
    {
      "id": "store-page-refresh",
      "locale": "en",
      "title": "Our store page looks different",
      "body": "Same game, easier to find. Nothing to download.",
      "published": false,
      "starts_at": null,
      "ends_at": null,
      "order": 20
    }
  ]
}

The two season-rollover rows are the same announcement in two languages: they share an id and an order, and a game that reads the namespace picks the row for the player's locale. The third row is a draft — it is in the document, and a game that filters on published will not show it.

Step 5: Publish

Save draft, then Create version, then publish it as a release — Releases → Compose release, choose the channel and the announcements version, publish. That is the same path as every other namespace, which is the point: the announcement and the content it belongs with ship together and roll back together.

Editing an announcement later is a new draft and a new version. A release that has already gone out is never rewritten.

What your game does with it

The game reads the namespace from the channel's bundle (see Content and patching) and keeps the rows where:

  • published is true;
  • starts_at is null or in the past;
  • ends_at is null or in the future;
  • locale matches the player's, falling back to one you choose;

sorted by order, then by starts_at.

Making another preset

Any list works the same way: name the namespace, put the array under a property, describe the rows in the schema, add a tables entry keyed by the array's pointer, and publish. Keep the schema in a module under services/adminui/src/config/presets/ with a spec next to it, so a preset that stops validating its own example fails a test rather than a person's afternoon.