Community pack catalog

Reference for the public JSON catalog consumed by Akron’s Community Packs browser.

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

Catalog URL

Remote catalog URLs are HTTPS JSON endpoints. Local testing can use an explicit file:/// index path. 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 URL for the .akr archive. Public catalogs use same-origin HTTPS URLs. Local file catalogs use file:/// URLs inside the catalog directory.
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 three community-supported values:

StartPos
AutoKill
AutoDeafen

The in-game categories are All, StartPos, Auto Kill, and Auto Deafen. All is a browser filter, not a pack section.

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 512 MiB.
• Optional catalog image sources submitted through Akron are no larger than 24 MiB before optimization.
• The images list and legacy imageUrls list each declare no more than 16 entries. The legacy imageUrl field can add one single preview. Akron removes duplicate URLs when it builds the preview list.
• Optimized catalog images are no larger than 2 MiB, no wider or taller than 2048 pixels, and no larger than 4,194,304 pixels in total.

Catalog reader limits

Value	Limit
Index JSON	1 MiB
Entries per index	512
Tags per entry	32
id, title, mapSid, authorName, and preview roomName	256 characters each
description	4,096 characters
URL fields	2,048 characters each
Each tag	64 characters

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.

One in-game upload captures at most 10 marked rooms. For StartPos uploads, Akron orders candidate rooms by the lowest saved StartPos slot in each room before applying that limit.

Catalog validation

Before publishing, verify the catalog-facing pack contract:

• Verify that the archive contains manifest.json, setup.json, and the exact v10 snapshot entry named by each StartPos.
• Verify that the manifest kind is setup.
• Ensure that setup.json uses the akron-setup-v7 format.
• Verify that the entry section exactly matches the setup section.
• Confirm that the download URL returns the expected .akr archive.
• Reject every section except StartPos, AutoKill, and AutoDeafen.

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.

The StartPos, Auto Kill, and Auto Deafen Discord forums are bot-authored showcases for approved catalog packs. Members can read and reply, but cannot create posts there. Keybind, HUD, audio, and recorder forums still accept direct member posts and remain outside the map catalog.

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.