Skip to content

Map File Distribution

GOKZ.TOP production can distribute validated map BSP files through Cloudflare R2.

The distributor is production-only. Local and staging environments should not download Workshop files, update archives, or upload map objects.

Stored Artifacts

The backend keeps long-lived map files under MAP_FILE_STORAGE_DIR, normally mounted as /app/.maps in Docker:

  • raw/<map_name>.bsp
  • packages/GlobalMaps.7z

R2 receives:

  • maps/<map_name>.bsp
  • maps/<map_name>.bsp.bz2 for BSP files below 150 MB
  • packages/GlobalMaps.7z
  • packages/map-releases/maps-release-YYYY-MM-DD.zip

Large uploads use R2 multipart upload. The defaults start multipart at 256 MiB with 64 MiB parts.

The public map APIs expose only download_url, which points at the raw BSP object when available.

Manual Seed

The starter GlobalMaps.7z is optional seed data for maps that may no longer exist in the Steam Workshop. It is never downloaded automatically.

Seed it from an operator-provided archive:

kztop map-files seed /path/to/GlobalMaps.7z

To also persist that archive as the local full package seed:

kztop map-files seed /path/to/GlobalMaps.7z --copy-package

If the seed is not provided, the distributor still downloads maps that exist in the Workshop and records errors for missing or deleted Workshop items.

Sync Behavior

The production map-distributor service runs kztop map-files run-worker.

For each validated map whose file metadata is missing or stale:

  • Use a seeded raw BSP when no file metadata exists yet.
  • Otherwise download the map from Steam Workshop with anonymous SteamCMD for app id 730.
  • Upload the raw BSP to R2 under maps/.
  • Upload a .bz2 copy only when the raw BSP is below 150 MB.
  • Update packages/GlobalMaps.7z incrementally with 7-Zip where possible.
  • Rebuild the full archive only if it is missing, corrupt, or incremental update fails.
  • Create release ZIPs grouped by the map's UTC updated_at date for maps refreshed in that run.

Superusers can trigger the same sync manually:

POST /v1/maps/files/sync

The endpoint returns 403 outside production.