octoturge
5ed4d32a56
api: chunk_sections table (per 16x16x16 section, base64-encoded u16 blockStateId array) and mesh_pointers table, additive to Phase 1's column-based chunk_columns/tile_pointers — 2D tile rendering keeps using the cheap column path unchanged. New "sections" WS message (backfill on chunk load + delta resend on flush, same "current state, not a diff" philosophy as columns) reuses the existing dirty-chunk Redis event, so one event now triggers the worker to re-render both the 2D tile and any 3D meshes for that chunk. New mesh-serving routes. worker: a from-scratch greedy mesher (per-axis 2D mask sweep + rectangle merge — the standard voxel-meshing technique, reimplemented from its public description, not copied from any codebase) producing a compact custom binary vertex buffer per non-empty section. Verified with unit tests, including one that specifically checks a uniform section collapses to exactly 6 merged quads rather than one quad per voxel face (the decisive signal that merging, not just per-voxel face emission, is actually happening). frontend: a barebones Babylon.js 3D viewer (/3d) that loads a fixed radius of chunks, parses the mesh binary format, and renders each section as its own mesh (no cross-section merging yet, no camera-based streaming yet — both reasonable follow-ups once there's a reason to optimize). End-to-end verified against live containers, including through the real mod-side Java WS client (see MCMapper-Mod's matching commit): a known half-solid section correctly round-trips to exactly 24 vertices / 36 indices at the mesh-serving endpoint, matching the "6 merged outer faces" the unit tests predict.
MCMapper-Backend
Map-render backend for MCMapper-Mod. Does all the heavy lifting a thin in-game mod shouldn't: persists world state, renders 2D tiles and 3D meshes, relays chat, and serves the web map viewer — instead of the MC server itself burning CPU/RAM on rendering the way Bluemap/Dynmap do.
Services
Three independently-deployable services, each its own docker-compose service:
api/— ElysiaJS on Bun. The I/O layer: WS gateway for mod connections, chat relay, chunk store, marker/waypoint sharing, admin config, region export, tile/mesh serving.worker/— Rust. CPU-bound rendering: tile rasterization and chunk meshing, consumed off a Redis dirty-chunk stream. Stateless — scale it withdocker compose up --scale worker=N, or run instances on separate hardware pointed at the same Postgres/Redis/MinIO over a private network. Rendering strategy (cpu/gpu/hybrid) is config-selectable behind aRenderBackendtrait; onlycpu(rayon) exists so far —gpu/hybrid(wgpu) land in Phase 8.frontend/— ElysiaJS + Pug + Tailwind 4 + Alpine.js. The public-facing pages (map viewer, chat, admin panel). Stateless — no DB access, callsapifor anything server-rendered; the browser's own live map/chat/tile traffic talks toapidirectly, not proxied through here.
Plus postgres (source chunk data, accounts, chat history, config, render-artifact metadata
pointers), redis (dirty-chunk queue, pub/sub, link-code TTLs), and caddy (reverse proxy:
/ws + /api/* → api, everything else → frontend).
Postgres/Redis are never exposed publicly — only reachable on the compose network or a private
network (VPN/Tailscale/LAN) for remote worker instances.
Object storage
Rendered tile PNGs and mesh binaries live in a mcmapper-tiles bucket on an existing shared
MinIO instance (devstack-minio on octo-winsrv) rather than a per-stack minio container —
kept out of Postgres so backups stay free of large binaries, and any worker instance (local or
remote) has a shared place to write output. api/worker authenticate with a dedicated
mcmapper access key whose policy (mcmapper-tiles-rw) only grants
GetObject/PutObject/DeleteObject/ListBucket on that one bucket — it can't see or touch
anything else on the shared instance. Provisioned via:
mc mb myminio/mcmapper-tiles
mc admin policy create myminio mcmapper-tiles-rw mcmapper-policy.json # see git history for the policy JSON
mc admin user add myminio mcmapper <generated secret>
mc admin policy attach myminio mcmapper-tiles-rw --user mcmapper
api/.env.example/worker/.env.example point MINIO_ENDPOINT/MINIO_PORT at that instance's
LAN address; swap to the public gateway (s3.octoturge.com:443, MINIO_USE_SSL=true) if a
stack isn't on the same LAN. MINIO_SECRET_KEY is a real credential and is deliberately not
committed — set it in an untracked ./api/.env / ./worker/.env (docker-compose layers those on
top of the tracked .env.example, see docker-compose.yml).
Running
docker compose up
api on :3000, frontend on :3001, both behind Caddy on :80. api applies its Postgres
migrations on startup (see api/src/db/migrate.ts); worker consumes the mcmapper:dirty-chunks
Redis stream via a consumer group (mcmapper-workers) so multiple instances split work safely.
Phase 1: connecting a mod instance
There's no admin registration API yet (Phase 6) — seed one server row by hand, then point the
mod's MapperConfig at the same token:
docker compose run --rm api bun run seed
reads MCMAPPER_SEED_SERVER_NAME/MCMAPPER_SEED_SERVER_TOKEN from api/.env.example (edit
those first, or override with -e). Once the mod connects and sends its initial chunk backfill,
tiles appear at GET /api/tiles/:serverId/:dimension/:zoom/:tileX/:tileY.png (zoom is always 0
for now — see worker/src/render/cpu.rs) and the frontend's Leaflet viewer picks them up
automatically from GET /api/servers.
Attribution
See THIRD_PARTY_NOTICES.md.