MineGeo

A Minecraft panorama guessing game: Next.js website, Fabric capture mod, and standalone Bukkit/Paper exporter. The interface is English; the game uses fixed 360° views and Minecraft X/Z coordinates.

Run the website

Use Node.js 22 or later. From the repository root on Windows, macOS, or Linux:

npm install
npm run setup

Fill .env.local with the dedicated Supabase project's URL, publishable key, and server secret. Apply the SQL files in supabase/migrations in filename order to a new project. Never put the server secret in a NEXT_PUBLIC_ variable. Configure the sign-in callback as described in LAN and domain setup.

npm run dev
# Production:
npm run build
npm start

Before public deployment, follow the production launch guide. npm run check runs unit tests, TypeScript checking and the production build. With the compiled site running, npm run test:production -- http://localhost:3000 checks HTTP routes, privacy, signed images and five-round gameplay against the configured Supabase project. It creates and removes one temporary guest game; at least one map must be published.

npm start and npm run dev supervise both the website and processing worker. The worker is required to turn an upload into a previewable draft. npm run worker also loads .env.local when run separately. Setup downloads the pinned vanilla rendering assets and the Chromium runtime used by the existing terrain-rendering worker. Browser UI checks are separate from this worker.

Missing vanilla assets are also prepared automatically when a plugin export is rendered. For an existing failed or empty draft, stop the worker and use npm run reprocess -- <dataset UUID> before restarting. This retains the raw upload. See empty-render recovery.

GET /api/v1/health checks database connectivity. An empty catalog means no map has passed moderator review yet. Moderator access is controlled by profiles.role in Supabase; follow moderator setup and the first beta map. Contributors and moderators can inspect all six panorama faces before submission or approval, and saved draft selections retain excluded locations.

Install the capture tools

Maps support up to 24 locations and games choose five at random. Owners can opt into player contributions, with a cumulative 12-panorama limit per guest player and owner approval followed by moderator review. See panorama contributions for both tool workflows and deployment instructions.

Contributions check the server address recorded during capture. Owners can correct or clear the map's expected address. Fabric records the connected server automatically; plugin admins must set server-address or run /minegeo server <hostname[:port]> before exporting.

In Dashboard → Open map → Map tools, owners can add their own panoramas with /minegeo contribute <map ID> even when guest contributions are disabled. Owners can fill all 24 slots; other players retain their cumulative 12-location limit. Processed captures must be submitted and accepted in the map’s inbox, then the map update submitted for moderator review.

Refresh guessing map rerenders only the overhead map through the worker, without consuming panorama slots or changing panorama images. Choose the original capture, another processed capture you own, or an accepted contribution with exactly matching boundaries and the expected server address. To reflect new builds, export/upload fresh terrain first (a separate map upload also works when the original map is full). Fabric refreshes use the uploaded surface capture. The approved map and ongoing games keep their previous image until moderation approves the update. Apply the map_refresh migration and restart both the website and worker when updating an existing installation.

Ready-to-install JARs are committed under public/tools/plugin and public/tools/mod and served by /downloads. After pulling an update, replace the Minecraft server's installed JAR and restart that server; pulling the website alone does not update an already installed plugin.

• Server: Java 21 and Bukkit/Paper 1.21.11. Follow the plugin guide.
• Player: Minecraft 1.21.11, Fabric Loader and Fabric API. Put the mod JAR in mods/, press G, enter the website address, link your account, capture at least five positions, and upload.

To rebuild both tools with Java 21 installed:

npm run java:build

The build copies both JARs to their Git-visible download folders. Include those files in your commit before pulling on another machine.

Checks

The public /leaderboard and homepage preview rank signed-in players by their best completed five-round expedition. Ties use average score, then games played. Difficulty filters, literal player-name search, and pagination run in Postgres; guest and incomplete games are excluded. Apply the player_leaderboard migration when updating an existing installation. The score query is server-only and does not expose session tokens, round locations, or contact information.

npm run test:leaderboard verifies ranking and permissions in an isolated Postgres runtime. It uses the optional PGlite package already used for SQL checks (npm install --prefix .data/sql-verification --no-save --package-lock=false @electric-sql/pglite@0.3.14).

Accounts support display names, email/password login and password recovery. See account settings and Supabase configuration.

npm test
npm run test:renderer
npm run typecheck -- --incremental false
npm run build
node --import tsx scripts/test-plugin.ts

The plugin regression uses the Paper JAR already downloaded into .cache/paper-proof/paper.jar, starts a temporary loopback-only Paper server on port 25580, and stops it automatically. It verifies export, manifest validation, missing-export instructions, interrupted TUS upload/resume, idempotent retries, and cancellation. Its upload endpoint is a local test server; it does not publish a real community map or launch a Minecraft client.

The renderer regression exercises the product's headless terrain worker with grass, water, trees and a building, verifies nonempty map/cubemap output, and checks that a missing model fails. It starts no Minecraft server and uses no website UI automation. Output is written to .cache/renderer-regression. To use an existing Paper export instead, run npm run test:renderer -- <export-folder> after setup.

Rendering scope

Plugin exports include generated Overworld surface terrain (up to 24 blocks below each column's top), vanilla block states, and biome identifiers. Buried opaque blocks are omitted. Each export is limited to 5 million retained blocks, 240 MiB of raw terrain JSON, and 50 MiB compressed. Start with a 128 × 128 area, check the preview, then increase coverage. Lighting is simplified; custom packs, entities, and dynamic block-entity visuals are not captured by the server exporter.

The pixel heading font is VT323 by Peter Hull, distributed under the SIL Open Font License. Its license is in public/fonts/OFL-VT323.txt.

The homepage uses Minecraft 1.21.11’s original assets/minecraft/textures/map/map_background.png, extracted unchanged from the cached vanilla client to public/images/minecraft-map-background.png. The texture belongs to Mojang; its pixel detail and transparent parchment edges are retained.