Community pack catalog

The Community Packs browser reads a public JSON index, filters entries by the current map, and imports selected .akr packs.

Catalog URL

Catalog URLs are HTTPS JSON endpoints. Command examples use this placeholder:

<catalog-url>

Replace this placeholder with a full catalog URL. Custom URLs enable local testing, self-hosted packs, or recovery if the primary catalog is unavailable. The official Akron catalog is served at:

https://akron.micr.dev/catalog/index.json

The Akron website handles the public akron.micr.dev catalog routes and rewrites reserved asset paths to Cloudflare R2:

Public path	R2 object path
`/catalog/index.json`	`catalog/index.json`
`/maps/<map>/<pack>.akr`	`packs/<map>/<pack>.akr`
`/maps/<map>/<pack>/captures/<room>.jpg`	`captures/<map>/<pack>/<room>.jpg`
`/submissions/<path>`	`submissions/<path>`
`/r2-assets/<path>`	`<path>`

Players and catalog entries should use the Akron-branded URLs. Raw R2 URLs are a storage fallback, not the public catalog contract.

JSON shape

The catalog is a JSON document with the following structure. Replace angle-bracket placeholders with valid HTTPS URLs:

{
  "format": "akron-community-pack-index-v3",
  "version": 3,
  "packs": [
    {
      "id": "spring-collab-beginner-startpos-v1",
      "title": "Beginner Lobby StartPos Set",
      "description": "StartPos slots for common Beginner lobby rooms.",
      "section": "StartPos",
      "mapSid": "SpringCollab2020/1-Beginner",
      "mapUrl": "https://gamebanana.com/mods/150453",
      "discordUrl": "https://discord.com/channels/123456789012345678/234567890123456789",
      "downloadUrl": "<direct .akr HTTPS URL>",
      "authorName": "Display Name",
      "authorAvatarUrl": "",
      "images": [
        {
          "url": "<room preview HTTPS URL>",
          "roomName": "a-00"
        }
      ],
      "downloadCount": 42,
      "updatedUtc": "2026-05-20T00:00:00Z",
      "tags": ["startpos", "beginner", "lobby"],
      "sha256": "<64 lowercase hexadecimal characters>",
      "sizeBytes": 1234
    }
  ]
}

Pack fields

Field	Meaning
`id`	Stable catalog identifier for this pack entry.
`title`	Reader-facing pack name.
`description`	Short description shown in the browser and matched by search.
`section`	`.akr` import scope. Must match one of the supported section values.
`mapSid`	Celeste map SID used for map filtering.
`mapUrl`	Public page for the target map when available.
`discordUrl`	Optional source Discord thread shown as See in Discord. Official entries use `https://discord.com/channels/<server>/<thread>`.
`downloadUrl`	Direct HTTPS URL for the `.akr` archive.
`authorName`	Display name for the pack author.
`authorAvatarUrl`	Optional avatar URL. Use an empty string when unavailable.
`images`	Optional preview images. Each item has a `url` and optional `roomName`. Akron shows these as a carousel.
`imageUrls`	Optional URL-only preview image list. Use `images` when room names are known.
`imageUrl`	Legacy single preview image URL. Prefer `images` for new catalog entries.
`downloadCount`	Display count from the catalog maintainer.
`updatedUtc`	UTC timestamp for the latest catalog update.
`tags`	Search tags used for filtering.
`sha256`	Lowercase SHA-256 digest of the exact `.akr` bytes.
`sizeBytes`	Exact `.akr` byte length.

The section field must be one of the following values:

Whole
StartPos
Keybinds
AutoKill
AutoDeafen
Recorder
Audio
Hud

In-game category buttons primarily focus on map-specific sharing cases: All, StartPos, Auto Kill, and Auto Deafen.

Publishing guidelines

Each catalog entry must point to a .akr file for a specific map and sharing scope. Before adding archives to the catalog, ensure that:

The mapSid matches the Celeste map SID.
The downloadUrl is a stable HTTPS URL for the .akr file.
Catalog metadata is updated whenever the pack changes.
The .akr is no larger than 4 MiB.
Optional catalog image sources are no larger than 100 MiB before optimization.
Optimized catalog images stored in R2 are no larger than 4 MiB.

The official in-game upload flow accepts StartPos, Auto Kill, and Auto Deafen packs. Auto Kill and Auto Deafen areas are coordinate-based setup state, so catalog maintainers should reject area packs when the submitted map SID does not match the map those areas were created for.

Catalog validation

Before publishing, verify the catalog-facing pack contract:

Verify that the archive contains exactly manifest.json and setup.json.
Verify that the manifest Kind is setup.
Ensure that setup.json uses the akron-setup-v2 format.
Verify that the entry section matches the setup section, unless a different scope is intended.
Confirm that the download URL returns the expected .akr archive.
Reject Whole setup packs from the public Discord catalog.

The official Discord bot also enforces implementation-level safety checks before publishing:

Open archives in memory and never extract uploaded archives to the filesystem.
Reject absolute paths, .. traversal, nested archives, unexpected files, suspicious compression ratios, oversized JSON payloads, and suspicious command-like or credential-like text.

See Akron .akr archives for the full archive contract and import safety rules.

Storage and publication architecture

The official catalog separates unreviewed upload storage from public catalog storage. In-game uploads go to the Upload Worker first. The Worker stores source .akr files and marked-room captures in a private quarantine bucket, records batch, submission, and object state in its database, and exposes signed bot-only endpoints for moderation. Nothing from quarantine is public. The Discord bot polls the Worker for queued jobs, posts moderation messages, handles attribution confirmation, and sends approve, reject, or request-changes actions back to the Worker. Moderation messages should attach every marked-room capture and expose next/previous controls when Discord-side pagination is needed. Approval is the only path that copies a pack into public catalog storage. When a submission is approved, the Worker writes the .akr archive to the public pack path, transforms each marked-room capture into an optimized catalog preview image, stores those previews at the public capture path, and rebuilds catalog/index.json with an images array. The public website serves branded Akron URLs and routes the reserved catalog and map asset paths to the public storage objects. Operational capacity depends on the number and size of approved public packs, optimized preview images, retained quarantine objects, catalog refreshes, pack downloads, and image transformations. Keep provider quotas in deployment configuration and monitoring, not in the player-facing catalog contract.

Runtime logic

Akron filters catalog entries using the following criteria:

Current map SID.
Selected category.
Search terms against title, description, author, map URL, section label, and tags.

When a player imports a pack, Akron downloads it to Saves/AkronSetups/community-*.akr and imports the declared scope.

Automation commands

Debug and live verification can drive the same browser flow:

akron_community_packs url <catalog-url>
akron_community_packs refresh
akron_community_packs category StartPos
akron_community_packs search beginner lobby
akron_community_packs list
akron_community_packs import 0

list prints the currently filtered zero-based entries. import uses the same download and scoped import path as the in-game button.

Start

Concepts

Player guide

Feature guide

.akr Packs

Reference

Troubleshooting

Contributing

Project

Community pack catalog

Catalog URL

JSON shape

Pack fields

Publishing guidelines

Catalog validation

Storage and publication architecture

Runtime logic

Automation commands

​Catalog URL

​JSON shape

​Pack fields

​Publishing guidelines

​Catalog validation

​Storage and publication architecture

​Runtime logic

​Automation commands

Catalog URL

JSON shape

Pack fields

Publishing guidelines

Catalog validation

Storage and publication architecture

Runtime logic

Automation commands