# 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:

```sh
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](docs/local-network.md).

```sh
npm run dev
# Production:
npm run build
npm start
```

`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.

`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; the project owner can set their profile's role to `moderator` using the database dashboard, then use `/moderation` on the website.

## Install the capture tools

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](docs/server-plugin.md).
- **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:

```sh
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

```sh
npm test
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.

## 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`.