.akr archive format

Technical specification for the Akron archive format, including manifests, payloads, and import safety rules.

Akron uses .akr files to store and share setup sections, overlay themes, HUD labels, and control-display presets. An .akr file is a ZIP archive containing one manifest and one main payload. StartPos and Whole setup packs with saved slots also contain one shared snapshot bundle. The reader accepts only manifest.json, the main payload required by the archive kind, and StartPos attachments declared by setup.json.

Archive shape

Exports write compact manifest and setup JSON and use maximum DEFLATE compression for JSON entries. StartPos slots share one startpos/snapshots.bin.br entry stored without further ZIP compression. A bounded dictionary shares repeated byte chunks; a reversible base64 transform removes text overhead before Brotli quality 11, window 24. Every original snapshot JSON byte survives unchanged.

snapshotBundleSha256 covers the compressed bundle. Each slot’s snapshotSha256 covers its raw JSON document. Local StartPos saves continue to use gzip; export does not rewrite them. Imports validate each document and save it through the normal local snapshot writer. The byte-level contract is documented in docs/reference/snapshot-bundle.md.

Pack creation runs in the background because maximum compression can take minutes on large maps. The completed archive replaces its destination atomically. Uploads and downloads transfer those compressed bytes directly. A downloaded pack with the catalog’s exact size and SHA-256 is reused on subsequent imports. Existing cloud objects do not shrink until replaced with new exports.

Most archives contain two entries. StartPos and Whole setup archives with saved slots add one shared entry:

The reader rejects undeclared entries, rooted paths, backslashes, empty path segments, and . or .. path segments, as well as archives that do not match the expected payload name and kind.

Manifest

The manifest.json file uses the following structure:

{
  "format": "akron-archive",
  "formatVersion": 1,
  "kind": "setup",
  "kindVersion": 1,
  "createdBy": "Akron",
  "createdAt": "2026-05-14T00:00:00.0000000Z",
  "target": {
    "game": "Celeste",
    "mapSid": ""
  }
}

Field	Meaning
format	Must be akron-archive.
formatVersion	Must be 1.
kind	Payload kind. See the current kinds below. The value is limited to 64 characters.
kindVersion	Must be 1.
createdBy	Must be Akron.
createdAt	Required UTC creation timestamp ending in Z.
target.game	Must be Celeste.
target.mapSid	Required string for the target map SID. Use an empty string for payloads that are not map-scoped. The value is limited to 256 characters.

The manifest must contain exactly these fields, including both fields in target. Missing, extra, differently cased, or null fields are rejected. The manifest size limit is 16 KiB.

Current archive kinds

Kind	Payload entry	Payload format	Payload limit	Default directory
setup	setup.json	akron-setup-v10	2 MiB, plus declared StartPos attachments	Saves/AkronSetups
theme	theme.json	akron-overlay-theme-v2	64 KiB	Saves/AkronThemes
hud-labels	hud-labels.json	akron-hud-labels-v1	256 KiB	Saves/AkronHudLabels
control-display	control-display.json	akron-control-display-v1	256 KiB	Saves/AkronControlDisplay

Every current kind uses manifest kindVersion 1. The payload format has its own version and is validated before Akron applies imported state.

Payload contract versions

The archive container (akron-archive, formatVersion 1, kindVersion 1) describes the ZIP shape and the manifest. It is independent of what a payload means, and it does not change when a payload contract changes.

The current portable and local contracts are:

Setup payload	StartPos snapshot document	StartPos attachment name	Snapshot file on disk
akron-setup-v10	akron-reconstruction-v12	startpos/snapshots.bin.br	Saves/AkronStartPos/v12-<digest>.json.gz

A StartPos snapshot records an object graph with map identities, ownership edges, live-resource identities, and structural paths into a clean room reload. Reconstruction checks those relationships before applying saved state. A change to required captured state or baseline assumptions requires a new snapshot version; the filename carries that version too. The setup payload version changes independently when the pack’s own contract changes.

The contracts also move when a snapshot has to carry something it did not carry before. A snapshot records, next to each saved object, whether the name it was saved under is one any install can look up again and whether the map laid that entity out. A snapshot written without those cannot be checked against them, so it is refused rather than read with a weaker guarantee under the same version number.

Akron does not convert older payloads. A pack whose payload format is not the current one is refused when it is read, before any attachment is opened, and the message names both contract versions. A snapshot whose document format is not the current one is refused by the reader, before the reconstruction path sees it.

Change	Effect on existing data
akron-reconstruction-v11 -> akron-reconstruction-v12	Set StartPos slots again, then export their packs again. Snapshots now record whether Akron owned the saved global timescale and the clock value it replaced. Older snapshots lack that ownership and cannot safely restore timing under map restrictions. The akron-setup-v10 container is unchanged.
akron-reconstruction-v10 -> akron-reconstruction-v11	Set StartPos slots again, then export their packs again. Snapshots now include the active area’s room-owned dust style in the same graph as its controllers. Older snapshots lack that state and cannot be restored exactly. The akron-setup-v10 container is unchanged.
akron-setup-v9 -> akron-setup-v10	Export packs again to use the shared Brotli bundle. This container change alone did not invalidate local snapshots; snapshot format changes are separate.
akron-setup-v8 -> akron-setup-v9	Every .akr setup pack made by an earlier build must be exported again. Auto Kill and Auto Deafen areas now name the map they were drawn on, and the Core Mode override’s enabled flag left the setup state.
akron-setup-v7 -> akron-setup-v8	Every .akr setup pack made by an earlier build must be exported again. The overlay animation duration, floating button, and Deload Spinners flag left the setup state.
akron-overlay-theme-v1 -> akron-overlay-theme-v2	Every .akr theme pack made by an earlier build must be exported again. The animation duration left the theme.
akron-setup-v6 -> akron-setup-v9	Every .akr setup pack made by an earlier build must be exported again.
akron-reconstruction-v9 -> akron-reconstruction-v10	Every StartPos slot set by an earlier build must be set again. The saved state carries the same content in less than half the bytes: type names live in a per-document table, property names are short, and empty values are omitted. Slot positions, spawn settings and keybinds are unaffected; only the saved room state behind each slot is.
akron-setup-v4 -> akron-setup-v9	Every .akr setup pack made by an earlier build must be exported again.
akron-reconstruction-v7 -> akron-reconstruction-v10	Every StartPos slot set by an earlier build must be set again. Slot positions, spawn settings and keybinds are unaffected; only the saved room state behind each slot is.

Setup payload

Setup packs use the setup archive contract:

kind: setup
Payload entry: setup.json
Payload format: akron-setup-v10
Directory: Saves/AkronSetups

The following abbreviated example shows the top-level shape of a Whole setup. It is not an importable payload because state omits its required fields:

{
  "format": "akron-setup-v10",
  "name": "Whole Setup",
  "createdUtc": "2026-05-14T00:00:00.0000000Z",
  "section": "Whole",
  "state": {},
  "buttonBindings": {},
  "menuActionBindings": {},
  "startPositions": {},
  "snapshotBundleSha256": ""
}

The reader requires the exact state fields owned by the declared section. It rejects missing fields, extra fields, unknown enum values, and incorrectly cased property names. buttonBindings and menuActionBindings are present only for Keybinds and Whole. startPositions and snapshotBundleSha256 are present only for StartPos and Whole. The bundle hash is empty when there are no slots. The payload createdUtc value must exactly match the manifest createdAt value.

The setup payload size limit is 2 MiB.

The compressed bundle is limited to 509 MiB, leaving room under the 512 MiB community-download limit. Each expanded v12 snapshot is limited to 384 MiB, and all expanded snapshot documents together are limited to 1 GiB. Export accepts local gzip sources up to 128 MiB each and 509 MiB in total. A StartPos or Whole archive can contain at most 99 StartPos entries. Each slot key must be in the range 1-99.

The public upload service has narrower resource limits: 32 MiB per archive and 384 MiB of expanded snapshot JSON across the whole pack. Split larger packs before uploading. Catalog previews use the existing JPEG conversion with a 2 MiB cap. Published private upload sources become eligible for cleanup after 24 hours; the approved public pack and images remain stored.

Portable setup validation limits

Akron applies these limits when it writes or reads a setup pack. Values outside the ranges are rejected rather than clamped during pack validation.

Data	Limit
StartPos entries	99
Auto Kill areas	128
Auto Deafen areas	128
Custom HUD labels	64
Control Display elements	48
HUD row-order keys	128
Everest button bindings	128
Inputs in one Everest button binding	16 total across keyboard, controller, and mouse inputs
Akron menu action bindings	256
Sound volume entries	64
Sound override entries	64

Value	Accepted range
StartPos coordinates	Finite values from -16,777,216 through 16,777,216 on each axis
StartPos dashes	-1 for native, or 0-5
StartPos stamina	-1 for native, or 0-100 percent
Auto Kill and Auto Deafen rectangles	Width and height must be zero or greater, and each area must name the map it belongs to
Recorder resolution	Width 1-15,360, height 1-8,640, and at most 132,710,400 total pixels
Recorder framerate	1-360 FPS
Recorder bitrate	1-1,000 Mbps
Replay buffer	0-600 seconds
Clip pre-roll	0-120 seconds
Clip post-roll	0-120 seconds
Keyframe interval	0-20 seconds
Endscreen duration	Finite value from 0-30 seconds
Recorder audio levels	0-200 percent per track
Audio speed multiplier	Finite value from 0.1x-4.0x
Pitch multiplier	Finite value from 0.1x-4.0x
Per-sound volume	0-200 percent
Control Display element bindings	Up to 16 action bindings and up to 16 keyboard bindings per element

Required strings cannot be empty or whitespace. Optional strings can be empty, but cannot exceed their listed length.

String	Requirement
Setup pack name	Required, at most 256 characters
StartPos room and map SID	Required, at most 256 characters each
Everest binding name	Required, at most 128 characters, and must name a supported ButtonBinding property exactly
Keyboard, controller, or mouse binding input	Required, at most 64 characters, and must use the exact enum name
Akron menu action name	Required, at most 128 characters
Akron menu action binding	Required, at most 256 characters
Audio channel name	Required, at most 128 characters
Custom HUD label ID	Required, at most 128 characters
Custom HUD label name	Optional, at most 128 characters
Custom HUD label text	Optional, at most 4,096 characters
Control Display element ID	Required, at most 128 characters
Control Display element label	Optional, at most 128 characters
HUD row-order key	Required, at most 128 characters

Every enum field must contain a defined named string value. Each StartPos entry must use the archive name startpos/snapshots.bin.br and a 64-character lowercase hexadecimal SHA-256 digest of its original JSON bytes.

Setup sections

Section	Included data
Whole	All portable setup state, button bindings, menu action bindings, and StartPos slots for the target map.
StartPos	StartPos settings and saved StartPos slots.
Keybinds	Everest ButtonBinding properties plus Akron menu action bindings.
AutoKill	Auto Kill toggles, timer, area settings, rectangles, speed ranges, movement direction filters, dash-count conditions, grounded/airborne state, player state, and condition inversion.
AutoDeafen	Auto Deafen toggle, area settings, and rectangles. The local hotkey is not included.
Recorder	Portable replay-buffer, trigger, audio-capture, codec, quality, and preset settings.
Audio	Audio speed, pitch shift, and per-sound volumes and overrides.
Hud	HUD widgets, labels, input displays, resource bars, counters, and HUD presentation state.

Setup packs preserve machine-local values: the screenshot export path; recording output folder, filename template, replay auto-start mode, and colorspace arguments; audio-splitter state and device selections; and the Auto Deafen hotkey. Whole exports omit these values too.

Scoped imports replace the selected portable settings without resetting unrelated settings. A StartPos import also replaces every StartPos slot for the archive’s target map. Slots for other maps remain unchanged.

Import safety rules

Imports follow a “fail closed” policy:

Akron rejects archives with unsupported formats or versions, incorrect kinds, missing or extra entries, oversized payloads, invalid JSON, or unsupported payload formats. Setup packs created before akron-setup-v10 cannot be imported. Older StartPos snapshots, including v11, must be captured again, then their packs re-exported with the current build.

Akron verifies the compressed bundle hash and each document’s checksum, map, and room before applying the setup. It then binds the snapshot to the recipient’s active save-file slot. The exported attachment contains the captured active map’s berry progress, but import replaces that field with the recipient’s current active-map berry progress before binding the snapshot. Akron does not import the author’s progress or module save data.

If an import fails, current settings remain unchanged. Akron shows a short toast and writes the detailed error to its logs.

Maintenance requirements

Settings included in .akr setup packs must meet these requirements:

• Must be defined as a field in AkronSetupState.
• Must support capture from AkronModuleSettings.
• Must support application back to AkronModuleSettings.
• Must implement scoped-section copy behavior when the setting belongs to StartPos, AutoKill, AutoDeafen, Recorder, Audio, or Hud.
• Must have automated tests proving whole import/export and scoped import/export preserve the intended state.

Avoid adding compatibility shims for old local packs unless explicitly required. Akron maintains a single canonical contract to ensure clear import errors.

New archive kinds are reserved for payloads that are not setup packs or setup sections.

New archive kinds require:

• A unique manifest kind, payload entry name, payload format string, and payload size limit.
• Dedicated single-payload archive helper methods.
• Simple payload entry names (e.g., labels.json).
• Unsupported payload-format rejection before state is applied.
• Tests for round-trip behavior, wrong kinds, extra entries, oversized payloads, and missing manifests.
• An update to this page that documents the complete contract.

Do not include multiple unrelated main payloads in a single .akr archive. The current contract requires exactly one kind, one manifest, and one main payload. Only StartPos snapshot attachments declared by setup.json are allowed.

Archive tests live in tests/archive-tests.cs.

dotnet test tests/akron-tests.csproj --nologo --filter ArchiveTests