---
title: 'WarpEngine — Reference'
url: 'https://wiki.teletypegames.org/engines/warp-engine/reference'
markdown: 'https://wiki.teletypegames.org/engines/warp-engine/reference.md'
lang: en
date: '2026-11-16'
description: 'The full reference of WarpEngine: every feature, endpoint and setting, in detail. New to the engine? Start with Getting started; the API of every class is in the RDoc. Features in detail Catalog domain — Software, Release, ReleaseAsset, ExternalLink, PlatformLink, SoftwareImage, Download. All so…'
taxonomy:
  tag:
    - reference
    - warp-engine
    - ruby
---

# WarpEngine — Reference

> The full reference of [WarpEngine](https://wiki.teletypegames.org/engines/warp-engine): every feature, endpoint and setting, in detail. New to the engine? Start with [Getting started](https://wiki.teletypegames.org/engines/warp-engine/getting-started); the API of every class is in the [RDoc](https://wiki.teletypegames.org/rdoc/warp_engine/latest/).

# Features in detail

- **Catalog domain** — `Software`, `Release`, `ReleaseAsset`, `ExternalLink`, `PlatformLink`, `SoftwareImage`, `Download`. All soft-deleted — since 2.0 every delete path (Admin API, admin screens, a nested `_destroy`) is a soft delete —, with download tracking.
- **CI pipeline server** — a Woodpecker [configuration extension](https://woodpecker-ci.org/docs/usage/extensions/configuration-extension). Game repos hold only a platform marker. Builder images are server-side, so bumping an image reaches every repo at once.
- **Pluggable CI** — from 0.7 every CI feature goes through one adapter. Woodpecker ships with the engine as `WarpEngine::CI::Woodpecker` and is the default; `:none` turns CI off, and another server is a host-supplied object.
- **Build endpoints** — `POST /build/upload` and `POST /build/publish`, authenticated by a shared secret or by database application tokens.
- **Public JSON API** — catalog, highlighted title, per-platform build matrix, download tracking, static file server for web builds.
- **Host-owned image library** — from 0.6 the `Image` model, its files, its `/api/image/:id` endpoint and its admin page live in the host; the engine links a software to an image and publishes the URL through an adapter. The same table can then serve avatars or anything else the site has.
- **Pluggable access** — the host supplies a policy and the catalog gains prices, entitlements and gated downloads, and says so in the API, so a client can show a paid title as paid instead of failing at download time. Default: the open catalog.
- **Client sign-in** — RFC 8628 device authorization grant over the host's user model, for clients with no browser. Off unless configured.
- **Optional admin** — ActiveAdmin resources (catalog editor, file manager, download stats, app tokens). Without ActiveAdmin the engine runs headless.
- **CI management** — with an API token the admin drives the CI server: repo sync, pipeline history with manual triggers, application tokens provisioned as CI secrets.
- **Asset checklist** — from 0.8, `rake warp_engine:builds:check` prints per software and release which assets exist and which the platform's pipeline could still deliver. See *Which assets are missing*.
- **Shelves** — from 1.2, a platform's latest builds as a flat folder under fixed, versionless names with an `INDEX.TXT`, for clients that cannot read the JSON API (the [WARP64U](https://wiki.teletypegames.org/stores/warp64u) C64 store reads the C64 shelf over plain HTTP). From 1.7 a shelf can also be one folder per title, the layout [DOSINST](https://wiki.teletypegames.org/dos/dosinst) reads, so the DOS store is built from the catalog too. See *Shelves*.
- **Platforms of your own** — from 1.5, a host registers a platform with its kinds and pipeline template; the built-in ones are no longer the only ones. See *Platforms of your own*.
- **One definition per platform** — from 1.12 a platform is declared in one place: the kinds it accepts, requires and builds, its metadata source and one CI-neutral pipeline template that every CI adapter renders. The upload and publish steps are generated from the kinds, a publish runs the engine's own steps (`WarpEngine::Publish`), and every error the engine raises on purpose is a `WarpEngine::Error`.
- **Shared version and release steps** — from 1.7 the engine adds the `version` step to every generated pipeline and, where the host asks for it, a forge `release` step at the end, on any platform. See *Steps every pipeline shares*.
- **Configuration DSL** — from 1.8 the initializer is a block of named settings (`shelf`, `admin_api`, `additional_resource`, `ci … do platform … end`) instead of hashes; the old `|c|` form still works. See *Installing into a host*.
- **Outlets and Assembly64** — from 1.11 the JSON API, the shelves and an Assembly64 server are outlets of one catalog, over one shared rule of what is on offer; a host may add types of its own. The Assembly64 outlet lets a C64 Ultimate browse and run the catalog from its menu. See *Outlets* and *Assembly64*.
- **Releases from tags the pipeline makes** — from 1.9 a push builds, and a new version in the source gets its `v<version>` tag from the pipeline itself; the tag's pipeline publishes it. A dev build moves its branch's `dev-<branch>` tag, so the branch's newest build is always the published one. See *Versions and releases*.
- **Release channels** — from 4.0 every release has a channel, read from its version: `stable` (`1.2.0`), `beta` (`1.3.0-beta.1`, listed but the latest only for those who ask) and `dev` (`dev-…` builds off the default branch, never listed). See *Release channels*.
- **Developer tools** — from 3.5 the engine describes itself to editors and scripts: the platforms with their templates and metadata schemas (`GET /build/platforms`), a publish preflight (`POST /build/check`), a tool sign-in that an administrator approves, a new game's repo and pipeline in one call (Admin API `softwares/scaffold`) and a local build played in the real runtime (`/play-preview`). The [WarpEngine Toolbox](https://wiki.teletypegames.org/development/warpengine-toolbox) VS Code extension is built on them.

## Supported platforms

Two lists per platform, and the difference matters. **Assets accepted** is what the updater ingests when a release is published (`WarpEngine::Platform#expected_kinds`). **The pipeline builds** is what the platform's pipeline actually produces (`WarpEngine::Platform#built_kinds`; since 1.12 both lists come from the same platform definition). Where they differ, the rest is a manual upload.

Since 1.5 each accepted kind is also **required**, **expected** or **optional**. A publish without a required kind answers `422` with the missing kinds and records nothing. An expected kind may be missing from a release, and the checklist below reports it. An optional kind may be absent for good and is not counted as missing. `GET /api/builds` lists all three per platform.

| Platform | Label | Assets accepted | Required | The pipeline builds |
|---|---|---|---|---|
| `godot` | Godot | html, win\_x86, win\_x64, linux\_x64, mac\_universal | html | all of them |
| `tic80` | TIC-80 | cartridge, source, html, docs, win\_x64, linux\_x64, mac\_x64 | cartridge | all of them |
| `bevy` | Bevy | html, win\_x64, linux\_x64, linux\_arm64 | html | all of them |
| `love` | LÖVE | html, win\_x64, linux\_x64, mac\_universal | html | all of them |
| `ebitengine` | Ebitengine | html, win\_x86, win\_x64, linux\_x64, linux\_arm64, mac\_x64, mac\_arm64 | html | html, win\_x86, win\_x64, linux\_x64, linux\_arm64 |
| `phaser` | Phaser | html | html | all of them |
| `c64` | C64 | cartridge, html, win\_x64, linux\_x64, mac\_arm64 | cartridge | all of them |
| `plus4` | Plus/4 | cartridge, html, win\_x64, linux\_x64, mac\_arm64 | cartridge | all of them |
| `dos` | DOS | cartridge (the installable folder as a zip), win\_x86 (optional: the Win32 build some programs have) | cartridge | all of them |

Ebitengine is the one gap: a macOS binary needs osxcross, which the linux builder image does not carry, so `mac_x64` and `mac_arm64` only ever arrive by hand.

## Which assets are missing

A release is complete when it carries every asset kind its platform's pipeline can produce — and nothing enforces that. A build step fails, a platform gains a target, a title gets published from a laptop, and the catalog serves a release with three of its seven assets. The engine ships a checklist for it:

```
$ bin/rails warp_engine:builds:check

WarpEngine release asset coverage — latest release per software
expected: the kinds a platform's updater registers · [ ] the CI builds it · [-] the CI does not, upload it by hand

rabbitroller  ebitengine  v1.1.1  3/7
  [x] html
  [x] win_x64
  [x] linux_x64
  [ ] win_x86
  [ ] linux_arm64
  [-] mac_x64
  [-] mac_arm64

The CI can build these and the release does not have them:
  rabbitroller v1.1.1 (ebitengine): win_x86, linux_arm64

12 softwares, 12 releases, 61/78 assets present, 11 missing from CI-built kinds
4 softwares are missing an asset the CI builds
2 assets are expected but this CI does not build them
```

| Marker | Meaning |
|---|---|
| `[x]` | the release has this asset |
| `[ ]` | the platform expects it **and** the pipeline builds it — a real gap, and the line worth acting on |
| `[-]` | expected, but this CI cannot build it (see the table above) — a manual upload, or nothing |
| `[~]` | optional on this platform (DOS's `win_x86`): absent, and not counted as missing |
| `[+]` | the release carries an asset the platform does not expect |

Options are environment variables, so it composes in a shell:

| Variable | Effect |
|---|---|
| `NAME=rabbitroller` | one software |
| `PLATFORM=ebitengine` | one platform |
| `RELEASES=all` | every release, not just the newest per software |
| `ONLY=missing` | only the releases short of a CI-built asset |
| `STRICT=1` | exit non-zero when anything is missing, for a scheduled check |

"Newest" is the newest `stable` release (before 4.0: the newest non-`dev-` version) — the same rule the catalog API uses when it names a title's latest release. The numbers are objects too: `WarpEngine::AssetCoverageService` (before 2.0 `AssetCoverage`) answers `#rows`, `#missing_rows` and `#totals`, and `WarpEngine::AssetCoverageChecklist` renders them.

Available in the host app, the [public site](https://wiki.teletypegames.org/services/public-site).

# Endpoints

## Public API

This is the read side of the API — the **WECP, WarpEngine Catalog Protocol**. Every endpoint's request and response shape is on the [WECP page](https://wiki.teletypegames.org/engines/warp-engine/wecp); this table is the map.

| Endpoint | Purpose |
|---|---|
| `GET /api/service` | What this deployment is: version, whether the catalog gates, how to sign in, and its outlets — the shelves with their addresses among them (a separate `shelves` field from 1.7 to 1.13). |
| `GET /api/software` | The catalog with releases, assets, links, download counts, an optional `category` and an `access` block — whole, or one page at a time (`?page=`, `?per_page=`), filtered by `status`, `platform`, `category`, `q`, `owner_id`. |
| `GET /api/software/facets` | How many softwares each status, platform and category would show under the other filters. |
| `GET /api/software/vocabulary` | The statuses and categories this catalog uses, with labels and display order. |
| `GET /api/software/highlighted` | The highlighted title. |
| `GET /api/builds` | Expected asset kinds per platform. |
| `GET /api/softwares/:name/builds` | Actual vs. missing build assets per release. |
| `GET /api/image/:id` | Images. **The host's endpoint** since 0.6 — the engine publishes the address, the host serves it. |
| `GET /api/download?path=` | Serves an artifact and logs a download. |
| `GET /file/*path` | Static build output (web-playable games, docs). |
| `POST /api/auth/device` | Starts a device sign-in, returns the code pair. 404 when no client identity is configured. |
| `POST /api/auth/device/token` | Polls a device sign-in for its token. |
| `DELETE /api/auth/token` | Revokes the bearer token on the request — sign out. |
| `GET /play-preview/:platform?payload=message` | The platform's runtime page waiting for a build by `postMessage` — a local build played in the real runtime (4.0: only `payload=message`). |

Every read endpoint accepts an optional `Authorization: Bearer …`; none requires one. The token only changes what the access policy is asked. An anonymous caller is a supported caller.

Every response carries a `WarpEngine-Version` header, set before the action runs — so error responses have it too, and a client can branch on the engine version without an extra request.

```sh
$ curl -sI https://teletypegames.org/api/software | grep -i warpengine
WarpEngine-Version: 0.13.1
```

The host app's own endpoints (the store registry, for example) do not carry it — they are not part of the engine.

## Build / CI

| Endpoint | Purpose |
|---|---|
| `POST /build/upload` | One artifact (multipart `file`, optional `sha256`). Needs `X-Update-Secret`. |
| `POST /build/publish` | Register uploaded artifacts as a release. Needs `X-Update-Secret`. Since 1.9 a version older than the newest published answers `409`. |
| `POST /build/config` | Woodpecker configuration extension; serves the pipeline YAML. Signature-verified (RFC 9421, ed25519). |
| `GET /build/config?platform=` | Public preview of the generated YAML. |
| `GET /build/platforms[/:name[/metadata-schema]]` | The platforms for developer tools: kinds, marker, template and demo repos, the `metadata.json` JSON Schema. Public. |
| `POST /build/check` | Publish preflight: would this `metadata.json` (and version) publish, and what is missing. Public, nothing is written. |

# Access and identity

Two seams added in **0.5.0**, both shaped like the storage adapter: a documented contract, a default identical to the old behaviour, and one config key to replace it. Set neither and nothing changes.

## Who may see and download what

```ruby
c.access_policy = MyStore::AccessPolicy.new   # :open (default) = the catalog as it was
```

The policy answers three questions:

| Method | Question |
|---|---|
| `visible_software_scope` | which titles `GET /api/software` lists |
| `access_for` | what a client is told about each title |
| `authorize_download` | may this artifact be handed over |

`authorize_download` is asked by `/api/download` **and** `/file/*` before anything is served, so a host no longer has to shadow those routes.

Every catalog entry carries an `access` block, **also under the open policy** — a client never has to guess whether the catalog is silent or the title is simply not gated:

```json
"access": { "gated": true, "entitled": false,
            "price": { "amountCents": 1490, "currency": "EUR" },
            "purchaseUrl": "https://shop.example/games/slug",
            "webUrl": "https://shop.example/play/slug" }
```

The field names are deliberately generic, because one client reads several catalogs.

**A policy that raises counts as a refusal**: empty catalog, denied download, logged. An artifact must never be served because the gatekeeper crashed.

## Signing a client in

A desktop client has no cookie jar and no browser session, so the engine uses the device authorization grant (RFC 8628) instead of a login form.

```ruby
c.access_token_owner_class  = "User"      # nil (default): no sign-in anywhere
c.identity_verification_url = "/devices"  # your page, where a person types the code
c.subject_resolver = ->(request) { request.env["warden"]&.user }   # recognise a browser
```

1. the client `POST`s `/api/auth/device` and shows the `userCode`;
2. the person opens the verification page and types that code;
3. **the host's page** calls `WarpEngine::DeviceGrantService#approve(user_code:, subject:)` — approving needs a session and HTML, which are not the engine's business;
4. the client's next poll takes the token. It is handed over exactly once.

The token is a `WarpEngine::ApplicationToken` with the `catalog` scope, so publishing and client credentials stay separable in one table. `subject_resolver` covers the other case: a browser has a session, not a bearer token, and without it a gated store would refuse its own signed-in visitors.

With `access_token_owner_class` unset, `/api/auth/*` answers 404 and `/api/service` reports `auth: null`, so the client offers no sign-in.

# The image library

An image is not a catalog concept — the same picture library serves covers, screenshots and avatars — so from **0.6.0** the engine owns only the link (`SoftwareImage`: ordered, one default), while the model, the files, the endpoint and the admin page belong to the host. `rails g warp_engine:install`writes a working set (`app/models/image.rb`, `app/controllers/api/images_controller.rb`, a `create_images` migration), and the engine reaches it through an adapter:

```ruby
c.image_class_name = "Image"          # default
c.image_adapter    = MyLibrary.new    # or replace the adapter entirely
```

| Method | Used for |
|---|---|
| `model_name` / `model` | the class `SoftwareImage#image` belongs to |
| `url_for(image_id)` | `imageUrl` and `images[].url` in the catalog JSON, and the admin previews |
| `select_options` | the image picker on the software form |
| `build_from_upload(upload)` | "upload a new image" on that form |
| `label_for(record)`, `available?(record)` | the admin's label and "is the file there" check |

The default adapter publishes `/api/image/<id>` — the address clients have always used — which is why the generated route serves exactly that. **The `images` table did not move**: the engine simply stopped creating it, and `software_images.image_id` still points at the same rows.

# Using Woodpecker with WarpEngine

A game repo has no pipeline of its own. On every pipeline start Woodpecker POSTs the one-line marker to `/build/config` and gets the full YAML back.

1. Woodpecker is configured with WarpEngine as a configuration extension.
2. The repo's `.woodpecker.yaml` holds only `platform:` (and `name:` when the software name differs from the repo name).
3. A push sends the marker to `POST /build/config`.
4. The CI adapter renders the platform's template, `lib/warp_engine/ci/platforms/<template>.yaml.erb`, with the configured builder image. Since 1.12 the template is CI-neutral — one per platform, `commodore` for both `c64` and `plus4` — and the adapter's renderer writes it in its own YAML dialect (Woodpecker steps or GitLab jobs). From 1.1 the helper steps (version, lint, minify, docs, upload, publish) run in the platform's `tools` image when it has one, and install nothing; without it they run in `alpine` and `apk add` (or `luarocks install`) what they need on every run.
5. The pipeline runs. Since 1.9, after a push: version → build → tag; on the tag that step made: version → build → upload → publish (→ release, where the host turns it on). See *Versions and releases*.

A repo opts out by committing a real pipeline YAML: a non-marker config gets `204 No Content` and runs unchanged.

## Setting up a game repo

```yaml
# .woodpecker.yaml
platform: godot
name: mygame     # optional, defaults to the repo name
```

```json
// metadata.json — same for every platform except TIC-80
{
  "name": "mygame",
  "version": "1.0.0",
  "title": "My Godot Game",
  "author": "You",
  "desc": "A cool game",
  "license": "MIT",
  "category": "puzzle"
}
```

`category` is optional free text a client may group titles by — *puzzle*, *action*, *demo*. Since 0.12 it lands on the `Software` record and in `GET /api/software`; the WarpEngine Client draws a category axis in its filter as soon as a catalog publishes one. `site` and `repo` are optional too and become external links.

| Platform | Source expectations | What the pipeline builds |
|---|---|---|
| `godot` | export presets: Web, Windows x86, Windows x64, Linux x64, Mac universal | `godot --headless --export-release` per preset |
| `bevy` | standard Cargo project; `assets/` is packaged next to native binaries | WASM, linux-x64, win-x64 (mingw) |
| `love` | standard LÖVE project | love.js web, Windows exe, Linux AppImage, universal macOS `.app` |
| `ebitengine` | standard Go project | WASM, win x86/x64, linux x64, mac x64/arm64 |
| `phaser` | JS files in `src/` | syntax check, Phaser runtime download, web zip |
| `c64` | `main.asm`, or a Makefile with `build: make` | ACME assembly into a `.prg` cartridge (or `make <name>.prg`, cc65 is in the builder image), then `commodore-pack` in the `exporter` image: an EmulatorJS web build with the `vice_x64sc` core and yapeSDL bundles for linux-x64, win-x64 and mac-arm64 |
| `plus4` | the same as `c64` | the same as `c64` with the `vice_xplus4` core and yapeSDL in Plus/4 mode |
| `dos` | `SOURCE/build.sh`, its tests, and the `dos` block of `metadata.json` (see [DOS](https://wiki.teletypegames.org/platforms/dos)) | the commands of the `dos-builder` image ([dos-tools](https://wiki.teletypegames.org/platforms/dos)): the build and the tests on every event; on a tag the installable folder zip (and the Win32 one) and the forge release; the FTP store is the DOS shelf, built from the catalog |
| `tic80` | `<name>.inc` listing fragments from `inc/` | concat, luacheck, minify, LDoc, HTML + cartridge + native binaries |

TIC-80 needs no `metadata.json` — the metadata is the Lua header:

```lua
-- title: My TIC Game
-- name: mygame
-- author: You
-- desc: A TIC-80 game
-- category: puzzle
-- version: 1.0.0
function TIC() end
```

## Marker options

| Key | Required | Description |
|---|---|---|
| `platform` | yes | `godot`, `tic80`, `bevy`, `love`, `ebitengine`, `phaser`, `c64`, `plus4`, `dos`, or a platform the host registered |
| `name` | no | Software name; defaults to the repo name |
| `release` | no | `tag` (default since 1.9): the build runs on every event, a push ends with the `tag` step, and the release steps (package, upload, publish, release) run on tags only. `push`: the way before 1.9, every push publishes and nothing is tagged. A platform can require tags (`release_rule "tag"` in its service), and then the marker cannot choose `push`: DOS is such a platform |
| `build` | no | `make` on `c64` and `plus4`: `make <name>.prg` instead of ACME on `main.asm`, for a program in C (WARP64U is built this way) |

Any other key is an option a platform's template may read: letters, digits and `_ . -` only, the rest is dropped. The repo's other `.woodpecker/*.yaml` files are passed back unchanged, so a repo can keep a workflow of its own (its tests, a deploy) next to the generated one.

## Preview a pipeline

```sh
curl "https://your-host/build/config?platform=godot"
```

## Paging and vocabulary (0.13)

`GET /api/software` answers in an envelope — `api` (the JSON shape's own version, 2), `page`, `perPage`, `total`, `totalPages`, `nextPage`, and `softwares`. **Without `page` the whole catalog comes back** in that envelope, which is what every reader before API version 2 finds under `softwares`; with `page` it is one page of `per_page` entries (`catalog_page_size` when unsaid, at most `catalog_max_page_size`). Filters narrow the catalog before it is paged; the access policy decides visibility before either.

Statuses and categories are a **vocabulary in the database** — `WarpEngine::SoftwareStatus` and `WarpEngine::SoftwareCategory`, editable in the admin — not a list in the code. A software's `status` must be a known key: the migration seeds the four, and since 0.13.1 the model puts them back into an empty table the first time anything asks — a database built with `db:schema:load` rather than the migration, which is every test database, has no rows otherwise. A category a publish brings that nobody has named yet is added to the vocabulary with its key as its label and `needs_review` set. `GET /api/software/vocabulary` publishes both, and the site's catalog page and the WarpEngine Client take their labels from it.

## Secrets and versions

Every generated pipeline expects one Woodpecker secret, `application_token`, sent as the `X-Update-Secret` header to `/build/upload` and `/build/publish`.

The `tag` step (1.9) writes tags with the `gitea_token` secret, a Forgejo token with repository write access (on GitLab a `TAG_TOKEN` CI/CD variable, an access token with the `api` scope). On teletypegames.org it is a global Woodpecker secret, so a new repo needs nothing for it.

Versioning is the same everywhere, because since 1.7 the engine adds the `version` step itself (see below).

## Steps every pipeline shares

Since 1.7 no template carries these steps; the engine adds them to every pipeline it renders. Since 1.12 their shell scripts are plain `sh` files in the engine (`lib/warp_engine/ci/scripts/`, plus each adapter's forge and release script), linted by shellcheck:

- **`version`**, first. The version comes from `metadata.json` (or the `-- version:` line of the Lua header on TIC-80). On a tag a version tag (`v1.2.3` or `1.2.3`) has to match it, and is the version when the source names none; a tag that does not match fails the pipeline. Off the repo's default branch it becomes `dev-<version>-<branch>`, e.g. `dev-1.0.0-my-feature`, and so on a `dev-<branch>` tag; with no version at all the build is `dev-<commit>`, which is never the latest. Since 1.9 the default branch is the repo's own (`CI_REPO_DEFAULT_BRANCH`), so a repo whose default is `develop` releases from `develop`; before, it was `main` or `master`.
- **`upload`** and **`publish`** (generated since 1.12), after the platform's steps. The upload sends `<name>-<version>` plus the suffix of every kind the pipeline always builds (a required kind, or one declared `always`) and the metadata, failing when one is missing, and every other kind the platform accepts when the build made it; `publish` calls `/build/publish`.
- **`tag`** (1.9), after a push build, unless the marker says `release: push`: tags a new version, or moves the branch's dev tag. See *Versions and releases*.
- **`release`**, last, on a version tag (a `dev-` tag makes none), when the host sets `forge_release: true` in the platform's entry (any platform can have it): the Gitea/Forgejo release of the tag (a GitLab release on GitLab), named after the title and the tag, with `RELEASE_NOTES.md` as its text, made with the `gitea_token` secret. It attaches the files the build listed in `.release-assets`, or else the files the upload step uploaded. On teletypegames.org only `dos` has it.

Since 1.9.1 a generated Woodpecker pipeline starts on every event but `release` (a workflow `when`, left out where a template has its own): moving a dev tag makes Forgejo send a release event besides the tag one, and that built the same commit a second time.

The step that sends the files to `/build/upload` is `upload` (c64, plus4, ebitengine and dos called it `artifact` before 1.7), the one that calls `/build/publish` is `publish`; a template names its packaging step `package`. On `c64` and `plus4` only the players that were built are uploaded; LÖVE no longer uploads a `.love.zip`.

## Versions and releases

Since 1.9 nobody tags by hand and nobody publishes by hand: the version in the source decides everything.

1. **The version lives in the source** — `version` in `metadata.json`, the `-- version:` line on TIC-80. Raising it is the release.
2. **A push to the default branch with a new version** builds, and the `tag` step tags the pushed commit `v<version>` (through the forge API). That tag starts a pipeline of its own, which uploads and publishes. A forge release is made too where the platform has `forge_release`.
3. **A push with a version that is tagged already** only builds. Committing without raising the version publishes nothing.
4. **A tag made by hand** works as before: it has to match the version in the source, or the `version` step fails the pipeline, and the `tag` step leaves an existing tag alone.
5. **Versions only grow.** `/build/publish` answers `409` to a version older than the newest one published (by `Gem::Version`): it would become the latest release and bring back its old metadata. Publishing the same version again, a newer one, or any `dev-` version goes through.
6. **Dev builds always follow the branch.** Off the default branch the version is `dev-<version>-<branch>`; with no version in the source, `dev-<commit>`. For such a build the `tag` step **moves** the branch's `dev-<branch>` tag onto the pushed commit (creating it the first time), and the tag's pipeline publishes the dev build, overwriting the previous one of the same name. A dev version is never a title's latest release, is not listed in the catalog, and makes no forge release.
7. **Opting out:** `release: push` in the marker publishes on every push, with no tags, as before 1.9. DOS cannot opt out.

## Release channels

Since 4.0 a release's channel comes from its version (`releases.channel`, filled on every save):

| Channel | Versions | Who sees it |
|---|---|---|
| `stable` | `1.2.0` | everyone: the latest release, the outlets (shelves, Assembly64) |
| `beta` | `1.3.0-beta.1`, `2.0.0-rc.2` | listed; the latest only for a client asking `GET /api/software?channel=beta` |
| `dev` | `dev-1.3.0-feature-x`, `dev-3fb3ed8` | never listed nor the latest; its own `/play/` and `/file/` links and the Admin API |

A pre-release goes out like any release: put `1.3.0-beta.1` in the source and push. Every release in the catalog and the Admin API carries its `channel`.

**Pruning.** `WarpEngine::DevReleasePruneJob` (4.1) removes the development builds superseded on their branch and the ones not updated for `dev_release_ttl_days` (30), assets and folder included. The newest build of a branch in `dev_release_keep_branches` stays whatever its age. The engine does not schedule it: on teletypegames.org Solid Queue runs it every day at 04:00 inside the API's Puma, and `develop` is kept. `rake warp_engine:releases:prune_dev DRY_RUN=1` lists what it would remove.

**Pull request previews.** With a forge configured, the publish of a development build comments on the open pull request of its branch: the version, the commit, the play link and the downloads; the next build changes the same comment. The forge token needs `write:issue`.

The earlier versions of every engine-built teletypegames.org repo were tagged in one go on 2026-10-27 (`script/backfill_version_tags.rb` in the monorepo: each version's tag on the first default-branch commit that carried it), so the tags list a repo's whole history.

## Values a template takes from the host

Since 1.5 the templates hold no host's addresses. A platform's entry in the CI adapter's `platforms:` carries what differs from host to host:

- `web_shell:` — the page a bevy, ebitengine or phaser browser build is wrapped in. With a URL the pipeline downloads it; without one it takes the repo's own `web/index.html`.
- `bundle_id_prefix:` — the LÖVE macOS app's bundle id is `<prefix>.<name>` (default `org.warpengine`).
- `exporter:` — on `c64` and `plus4`, the image with `commodore-pack <c64|plus4> <name> <version>`, which writes the browser player and the three native players next to the PRG.

Our hosts set the Teletype Games values, so their pipelines render as before.

## Platforms of your own

A host adds a platform in its initializer, with the same DSL the built-in platforms are declared with (`WarpEngine::Platform::Builder`, 1.12):

```ruby
register_platform "amiga" do
  label "Amiga"
  kind :cartridge, ext: ".adf", required: true   # a publish fails without it
  kind :html                                      # built when the pipeline can
  kind :mac_arm64, built: false                   # accepted, uploaded by hand
  metadata :json                                  # or :lua, or a callable
  version_source "cat VERSION"                    # default: metadata.json's version
  ci template: Rails.root.join("ci/amiga.yaml.erb")
end
```

A kind is one of the `WarpEngine::AssetKinds` (`cartridge`, `source`, `html`, `docs`, `win_x64`, …), which knows its upload name and whether the engine unpacks it, so the platform only says which kinds it has. The template is CI-neutral (see *Steps every pipeline shares*), so one template serves Woodpecker and GitLab alike. From then on it is a platform like the others: a software may be on it, a publish runs the engine's publish steps, the admin lists it, every CI adapter renders its pipeline and a shelf may serve it. Everything that used to read the fixed list reads `WarpEngine::Platform.names`.

The 1.5 form — `register_platform "amiga", service: "AmigaPlatform", built_kinds: [...], templates: { woodpecker: ... }`, with a service including `WarpEngine::Platforms::Updatable` — still works and is deprecated.

## Outlets

From 1.11 the formats the catalog leaves the engine in are *outlets*, side by side over one shared decision of what is on offer (`WarpEngine::Catalog::Offer`: the kept, ungated titles of a platform with a listed status, each with the latest release that has the asset):

| Outlet | Kind | What it is |
|---|---|---|
| `wecp` | always on | the JSON catalog API ([WECP](https://wiki.teletypegames.org/engines/warp-engine/wecp)); the only outlet that knows a caller, sign-in and gated titles |
| `shelf` | materialized | a folder with an `INDEX.TXT` (below); rewritten whenever the catalog changes |
| `assembly64` | served | the Assembly64 search API under `/leet/search` (below) |

`shelf :c64, …` is an outlet of type `shelf`; any other is `outlet :key, type: :assembly64, …`. A host can register a type of its own (`register_outlet_type :feed, "Acme::FeedOutlet"`, a subclass of `WarpEngine::Outlets::Base`). `GET /api/service` lists every outlet under `outlets`; `rake warp_engine:outlets:check` and `warp_engine:outlets:sync` check them and rewrite the materialized ones, from a background job (`WarpEngine::OutletRefreshJob`, since 2.0) after every change that can alter them. The design: `docs/warp-engine/CATALOG_OUTLETS.md` in the TTG workspace.

Since 2.0 every type has one shape: `lib/warp_engine/outlets/TYPE.rb` reads and checks the options, describes the outlet and draws its routes (served) or syncs (materialized); the objects that do the work sit in the folder beside it (`Shelf::Builder`, `Shelf::IndexFile`, `Shelf::Layouts`, `Shelf::Preview`; `Assembly64::Catalog`, `Assembly64::Query`). The catalog API draws its own routes too (`Outlets::Wecp.draw_routes`); it is the one outlet without an offer, since it decides per caller. Shelves are kept with the other outlets in `config.outlets`, keyed by platform; an unknown option of any outlet stops the boot.

## Assembly64

From 1.11 an `assembly64` outlet answers the [Assembly64](https://assembly64.hackerswithstyle.se) search API as `hackerswithstyle.se` does, so the Assembly64 browser of an Ultimate (C64 Ultimate, Ultimate 64, 1541 Ultimate) finds the catalog's titles and runs them from its menu:

| Endpoint | Answers |
|---|---|
| `GET /leet/search/aql/presets` | the search form: repo, category, type, date, latest, sort, order |
| `GET /leet/search/aql?query=` and `/aql/START/COUNT?query=` | a search (AQL: `(name:"ra") & (category:games)`); unpaged it stays under the stock firmware's 16 KiB |
| `GET /leet/search/entries/ID/CATEGORY` | the title's files |
| `GET /leet/search/bin/ID/CATEGORY/FILE` | the file, through the download service (counted, access-checked) |

Options: `platforms` (default `c64`), `kinds` (default `cartridge`), `statuses`, `hosts`, `repo` and `repo_name`, `categories` (catalog category to Assembly64 category), `client_ids`, `max_results` (100), `name_length` (16). A file is named as on a shelf (`ARIADNE.PRG`).

teletypegames.org serves its C64 titles at **`http://a64.teletypegames.org`** (plain HTTP on port 80, the only thing the Ultimate speaks). The stock firmware asks only Assembly64 or CommoServe; a C64 Ultimate with the Spiffy patch takes more servers in `/flash/config/server.json`:

```json
{
    "assembly64": [
        { "name": "Assembly64", "client-id": "Spiffy" },
        { "name": "Teletype Games", "host": "a64.teletypegames.org" }
    ]
}
```

## Shelves

A shelf (since 1.2) is a folder the engine keeps in step with the catalog: for one platform, the latest release of every public title under a fixed, versionless name, plus an `INDEX.TXT` (`#SHELF 2`: `file|version|size|crc32|title|author|description|category|preview`, ASCII, at most 255 bytes a line; version 1, before 1.10, ended after the description). It is for clients that cannot read the JSON API over HTTPS. `shelf :c64, kind: "cartridge", path: "shelves/C64", extension: ".PRG"` names the platform, kind, path, extension and name length — an outlet of type `shelf`, keyed by its platform (`key:` names another); it needs the `:local` storage adapter. The software's `shelf_name` (from `metadata.json`, the admin or the Admin API) names the file. A shelf is rebuilt on every publish and every change to its titles, the index replaced last; `rake warp_engine:outlets:check` and `warp_engine:outlets:sync` check and rebuild it by hand (the `warp_engine:shelves:*` tasks were dropped in 2.0).

Since 1.7 a shelf can have `layout: "folders"`: one folder per title, the layout [DOSINST](https://wiki.teletypegames.org/dos/dosinst) reads. The engine unpacks the release zip's top folder, leaves out the `settings` files of the metadata's `dos` block (so an update keeps an installed program's configuration), and writes two files into each folder: `INFO.INI` (`[program]` with `name`, `description`, `version` and `platform` `DOS` or `WIN32`, CRLF) and `FILES.LST` (`crc32 size path`, CRLF). `kind` may be a list: the DOS shelf holds `cartridge` and `win_x86`, so DOSINST, for example, has a `DOSINST` and a `DOSINSTW` folder. Only folders the shelf's `INDEX.TXT` listed are ever removed, so a folder put there by hand (a test program, say) stays.

Since 1.10 a flat shelf can have `preview: "c64"`: beside `NAME.PRG` it then holds `NAME.PVW`, a C64 bitmap of the title's default gallery image (hires or multicolor, whichever is closer to the image; 3 header bytes, the screen matrix, the color RAM in multicolor, the bitmap), and the line names it in its `preview` field. A 384x272 VICE screenshot is read without its border. [WARP64U](https://wiki.teletypegames.org/stores/warp64u) shows it full screen. The C64 shelf of teletypegames.org has it on.

A shelf also has `urls`, where the host serves it, and `GET /api/service` lists the shelves under `shelves` (platform, kinds, layout, index, urls). Serving stays the host's job: the engine writes the folder and runs no FTP or HTTP server of its own.

teletypegames.org keeps three shelves, served by the FTP server over FTP and plain HTTP:

| Shelf | Folder | Layout | Served at |
|---|---|---|---|
| C64 | `shelves/C64` | flat | `ftp://ftp.teletypegames.org/C64`, `http://archive.teletypegames.org/C64` |
| Plus/4 | `shelves/PLUS4` | flat | `ftp://ftp.teletypegames.org/PLUS4`, `http://archive.teletypegames.org/PLUS4` |
| DOS | `shelves/APPS` | folders | `ftp://ftp.teletypegames.org/APPS`, `http://archive.teletypegames.org/APPS` |

# CI management (Woodpecker API)

Active only where the adapter has a `url` and an `api_token` (`WarpEngine.ci.configured?`). Until then the admin pages hide themselves.

- **Repo sync** — *Admin → Pipelines → Sync from Woodpecker* (the button carries the adapter's name). Mirrors the repo list into `Pipeline` records, matching each repo to a `Software` by name and inheriting its platform. Repos gone from Woodpecker are deactivated. Links stay editable by hand.
- **Pipelines** — each entry lists its recent runs (status, branch, message, time) with a manual **Trigger**. The newest run refreshes the cached status on the index. A software's admin page links to its pipelines.
- **Secret provisioning** — creating a token provisions the `application_token` secret to the owner's repos (unrestricted tokens: every active repo); deleting removes it; **Rotate** creates a replacement, provisions it everywhere and revokes the old one in one step.

The PAT must belong to a Woodpecker **instance admin** — listing repos is an admin-only endpoint, anything else returns `403 User not authorized`. Add the user to `WOODPECKER_ADMIN`, then **log out and back in**: the admin flag is written at login, a server restart is not enough.

# Build authentication

`X-Update-Secret` carries one of two credential types, chosen by `application_token_source`. The modes are exclusive.

| Mode | Credential |
|---|---|
| `:env` (default) | the shared secret in `update_secret`; unset means every request is rejected |
| `:database` | `WarpEngine::ApplicationToken` records: an owner (e.g. `AdminUser`), scopes (`update` to publish, `upload` to upload), optional expiry. Created in the admin; the plain token is shown once, only its SHA256 digest is stored. `last_used_at` tracks use. |

> **Cutover warning:** switching to `:database` invalidates the shared secret immediately. Create the tokens first.

# Installing into a host

```ruby
# Gemfile — from git:
gem "warp_engine", git: "https://git.teletypegames.org/engines/warp_engine.git"

# ...or from the Forgejo rubygems registry (tagged releases):
source "https://git.teletypegames.org/api/packages/engines/rubygems" do
  gem "warp_engine"
end
```

```sh
bundle install
rails g warp_engine:install   # initializer, image library, migrations
rails db:migrate
```

```ruby
# config/routes.rb
namespace :api do
  get "image/:id", to: "images#show"   # the image library is yours (see below)
end

# keep the mount last so the host's own routes win
mount WarpEngine::Engine => "/"
```

The generator writes `config/initializers/warp_engine.rb`. Since 1.8 it is a block without a parameter, one line per setting:

```ruby
Rails.application.config.to_prepare do
  WarpEngine.configure do
    file_container_path ENV.fetch("FILE_CONTAINER_PATH", "/softwares")

    # The image library is the host's; "Image" is the adapter's default.
    # image_class "Media::Picture"
    # image_adapter MyImageLibrary.new

    update_secret ENV["UPDATE_SECRET"]

    # application_tokens from: :database, owner: "AdminUser"

    # One adapter carries the whole CI side: server, recipes, signing key.
    ci :woodpecker do
      url            ENV["WOODPECKER_URL"]
      api_token      ENV["WOODPECKER_API_TOKEN"]
      repo_owner     ENV["WOODPECKER_REPO_OWNER"]
      public_key_url "https://ci.example.org/api/signature/public-key"
      update_server  "https://catalog.example.org"
      tools          "registry.example/ci-tools:1.0"   # every platform's, unless it names its own (1.1)

      platform :godot,      builder: "registry.example/godot-builder:4.6"
      platform :tic80,      builder: "registry.example/tic80-builder:1.0"
      platform :bevy,       builder: "registry.example/bevy-builder:1.0"
      platform :love,       builder: "registry.example/love-builder:1.0"
      platform :ebitengine, builder: "registry.example/ebitengine-builder:1.0"
      platform :phaser,     builder: "registry.example/phaser-builder:1.0"
      platform :c64,        builder: "registry.example/c64-builder:1.0", exporter: "registry.example/commodore-player:1.0"
      platform :plus4,      builder: "registry.example/plus4-builder:1.0", exporter: "registry.example/commodore-player:1.0"
    end

    # max_upload_size 500 * 1024 * 1024
    # enforce_software_ownership true
  end
end
```

The block also takes `shelf …`, `admin_api do … end` and `additional_resource … do … end` (permitted attributes, the admin form, and an `api_schema` built from `string`/`integer`/… lines in camelCase). An unknown setting or key stops the boot. The settings carry the names of the table below, except `image_class` (`image_class_name`), `application_tokens from:, owner:` (the two `application_token_*` keys) and `ci` (`ci_adapter`). The `WarpEngine.configure do |c| c.site_url = … end` form of the versions before 1.8 still works; both write the same configuration.

| Key | Default | Description |
|---|---|---|
| `file_container_path` | `ENV["FILE_CONTAINER_PATH"]` or `/softwares` | Where build artifacts are stored |
| `update_secret` | `ENV["UPDATE_SECRET"]` | Shared secret for `/build/*` |
| `application_token_source` | `:env` | `:env` or `:database`, exclusive |
| `application_token_owner_class` | `nil` | Owner model for `:database` mode |
| `max_upload_size` | 500MB | Cap for `/build/upload` |
| `enforce_software_ownership` | `false` | DB token owner isolation |
| `ci_adapter` | `:woodpecker` | Which CI server builds the games; `:none` turns CI off, or a host object |
| `image_class_name` | `"Image"` | The host model behind the image library |
| `image_adapter` | `nil` | Replaces the default host-model adapter |
| `access_policy` | `:open` | Access policy object |
| `access_token_owner_class` | `nil` | User model for device sign-in; nil = no sign-in |
| `admin_api.*` | `enabled = false` | The [Admin API](https://wiki.teletypegames.org/engines/warp-engine/admin-api) and its MCP server (1.0) |

A platform spec takes three images. `builder` runs the build steps. `exporter` is a second image a template may run a step in — the c64 and plus4 pipelines package the `.prg` into the browser player and the native players there. `tools` (1.1, optional) runs the helper steps: version, lint, minify, docs, upload, publish. Without it they run in `alpine` and install git, jq, curl, zip and lua5.4 with `apk add`, plus luacheck and ldoc with `luarocks install` for tic80, on every run; with it they install nothing, so the image must already carry those, with Lua 5.4 as `lua`. In the DSL, `tools` in the `ci` block is every platform's default. The upload and publish steps get the `application_token` secret, so reference the tools image by digest. teletypegames.org gives every platform its `build/ci-tools` image this way.

# Admin integration

The host owns the ActiveAdmin instance (auth, theme, routes); WarpEngine appends its resources to `ActiveAdmin.application.load_paths`. A new host needs two things:

- the file-picker JS for release-asset path inputs (iframe → `/admin/files?picker=1&field=<dom_id>`) in its `active_admin.js`;
- with apipie docs, `"#{WarpEngine::Engine.root}/app/controllers/**/*.rb"` in `api_controllers_matcher`.

The same resources are a JSON API too since 1.0 — see [WarpEngine Admin API](https://wiki.teletypegames.org/engines/warp-engine/admin-api). The admin pages and the API call the same services (`ApplicationTokenService`, `DownloadStatsService`, `FileManagerService`), so the two cannot drift apart.

Since 1.13 the *WarpEngine → ℹ️ SysInfo* page describes the running configuration in words: engine and file container, publishing credentials, storage/image/access adapters, client sign-in, the CI server and its platforms, every platform's kinds, the outlets and shelves (or why their configuration is invalid), the Admin API and the additional resources. It is computed on every request from the live configuration (`WarpEngine::SysInfo`); secrets show only as *set* or *not set*.

# Behaviour notes

- Every model is soft-deleted: a `deleted_at` column and the `kept` / `discarded` scopes. Since 0.10 there is no `default_scope`, so a query does not filter by itself — a host asks for `WarpEngine::Software.kept`, and one upgrading from 0.9 or earlier adds `.kept` where it relied on the default scope.
- The JSON shape is stable and bug-compatible with the former Go backend: Go zero-time timestamps, camelCase keys, legacy flat path fields.
- Model extension points: `ActiveSupport.on_load(:warp_engine_<model>)`.
- Every error the engine raises on purpose is a `WarpEngine::Error` (1.12); a misconfigured shelf, outlet, platform or Admin API raises `WarpEngine::ConfigurationError` at boot.
- An uploaded zip (web build, docs) is unpacked only inside its own directory: an entry with `../` makes the publish fail (1.12).

# Testing

```sh
bundle install
bundle exec rake app:db:prepare RAILS_ENV=test
bundle exec rspec
```

 [reference](https://wiki.teletypegames.org/tags?tag=reference)[warp-engine](https://wiki.teletypegames.org/tags?tag=warp-engine)[ruby](https://wiki.teletypegames.org/tags?tag=ruby) 

## Related pages

- [WarpEngine Admin API](https://wiki.teletypegames.org/engines/warp-engine/admin-api) WarpEngineSince WarpEngine 1.0: what the admin does, as a JSON API under /api/admin/v1, with a live OpenAPI 3.1 document and an MCP server.
- [WECP](https://wiki.teletypegames.org/engines/warp-engine/wecp) WarpEngineWarpEngine Catalog Protocol: the endpoints a WarpEngine server offers to catalog readers, each with its response shape.
- [RDoc](https://wiki.teletypegames.org/development/rdoc) DevelopmentThe API reference of our Ruby gems, built from the source with RDoc on every release tag and published here at /rdoc/.
- [WarpEngine](https://wiki.teletypegames.org/engines/warp-engine) EnginesTurn any Rails app into a retro game catalog: push a game, the CI builds it, the catalog publishes it, and every store client can install it.
- [Technologies](https://wiki.teletypegames.org/technologies)The full register of every language, piece of software and library this wiki mentions, grouped by category — with the libraries listed under the language they belong to.

'; var prevLevel = 2; for (var i = 0; i < headings.length; i++) { var h = headings\[i\]; var text = h.textContent.trim(); var slug = text.toLowerCase() .replace(/\[áàâä\]/g,'a').replace(/\[éèêë\]/g,'e').replace(/\[íìîï\]/g,'i') .replace(/\[óòôöő\]/g,'o').replace(/\[úùûüű\]/g,'u') .replace(/\[^a-z0-9\]+/g, '-').replace(/^-|-$/g, ''); if (!slug) slug = 'heading-' + i; if (used\[slug\]) { slug += '-' + i; } used\[slug\] = true; h.id = slug; var level = parseInt(h.tagName.charAt(1)); var cls = level > 2 ? ' class="toc-child"' : ''; html += '- [' + text + '](#'%20+%20slug%20+%20')
'; } html += '
'; toc.innerHTML = html; // Scroll-spy: highlight current heading var links = toc.querySelectorAll('a'); var ids = \[\]; for (var j = 0; j < links.length; j++) ids.push(links\[j\].getAttribute('href').slice(1)); function updateActive() { var current = ''; for (var k = 0; k < ids.length; k++) { var el = document.getElementById(ids\[k\]); if (el && el.getBoundingClientRect().top <= 80) current = ids\[k\]; } for (var m = 0; m < links.length; m++) { links\[m\].parentNode.classList.toggle('active', links\[m\].getAttribute('href') === '#' + current); } } window.addEventListener('scroll', updateActive, { passive: true }); updateActive(); })();

---

## Navigation

- Parent: [WarpEngine](https://wiki.teletypegames.org/engines/warp-engine.md)
- Previous: [WarpEngine Admin API](https://wiki.teletypegames.org/engines/warp-engine/admin-api.md)
- Next: [WarpEngine Starter Kit](https://wiki.teletypegames.org/engines/warp-engine/starter-kit.md)
