MineGeo/docs/server-plugin.md

# Server plugin 0.1.4

## Update and connect

1. Stop the Minecraft server, replace its old MineGeo JAR with `public/tools/plugin/minegeo-plugin-0.1.4.jar`, and restart. Run `version MineGeo` in the console to verify 0.1.4.
2. Open your MineGeo website dashboard, sign in, and generate a plugin token.
3. In the Minecraft server console, configure the Minecraft server address and contributor token. Console commands do not need the leading slash:

```text
minegeo server play.your-minecraft-server.example
minegeo link <token copied from the dashboard>
```

The website URL is built in: `https://minegeo.site`. Existing `website` settings are removed on startup; no URL configuration is needed. `minegeo website` displays the fixed endpoint. Account tokens remain private local configuration.

`minegeo server` sets the Minecraft connection hostname/IP, including a non-default port if needed. It is separate from the MineGeo website URL. Use the address players enter in Minecraft, or set `server-address` in `config.yml` and reload before exporting. The plugin records it in each export. Contributions to checked maps reject a missing or different capture address; old exports need to be recreated after configuring it. The map owner can override or clear the expected address in panorama settings. See [contribution server checks](panorama-contributions.md#contribution-server-check).

## Export before uploading

Choose a small, already generated area around your builds. Coordinates below are examples:

```text
minegeo area world -64 -64 64 64
minegeo export My Overworld
minegeo status
```

Wait for **Export complete**. The plugin reports the full path, for example:

```text
plugins/MineGeo/exports/export-1791117138143/
  terrain.json.gz
  manifest.json
```

Each attempt gets a separate folder. A manifest is created only after the complete export passes the local limits and has five safe viewpoints. If the area is unexplored, underwater, too large, or has too few safe positions, the console and status tell you why. No new terrain is generated by exporting.

If no area has been selected, export uses a 512 × 512 area centered on the player issuing the command, or on world spawn for console commands. The configured maximum area size still applies.

Then run:

```text
minegeo upload
minegeo status
```

Upload sends the latest **completed** export. It does not generate an export. The selection survives server restarts through `plugins/MineGeo/latest-export.txt`. Older `plugins/MineGeo/export/manifest.json` exports are still recognized when no newer selection exists.

## Finish on the website

The worker renders the map and panoramas. Open the private draft in your dashboard; the page updates while processing. Inspect the result, choose at least five locations, and submit for moderation. Once a moderator approves it, players can select it in the catalog.

Both the dashboard and draft show completed-work progress: downloading, reading/indexing terrain, loading models, building geometry, rendering panorama faces, rendering the surface map, and saving images. Percentages are not a time estimate. The terminal reports block/face counts as work advances. A large export can take longer on a Mac using software rendering.

The renderer compiles each block state's model transforms, textures and UVs once, then builds blocks synchronously into bounded typed buffers. Hidden faces use a compact bitset index. Meshes are split into 64 × 64-block regions so panorama cameras can cull distant/off-screen geometry while the surface map still covers the complete area. No terrain is downsampled by this optimization. Model loading and image uploads use bounded parallel requests, and panorama faces are encoded directly as WebP.

`MINEGEO_RENDER_BACKEND=auto` (the default) allows Chromium to use the GPU. If graphics initialization fails, the worker falls back to SwiftShader. To force the original software backend on a host with graphics driver issues, use `MINEGEO_RENDER_BACKEND=software` in `.env.local` and restart. The log names the actual graphics renderer; `auto` does not guarantee that the host has GPU acceleration.

Building logs now include blocks per second. Each job's local `render-report.json` records indexing/model/build times, emitted and hidden face counts, geometry bytes, mesh count and actual graphics backend; the worker prints this report when rendering finishes. Use those measurements to compare runs on the same Mac and export. An existing running worker must be restarted after pulling the optimizer to use the new builder.

Stopping the updated worker cancels its renderer and returns its job to the queue without using up a retry. The next worker renders that export from the beginning; completed published maps are unaffected.

If the worker stops renewing its lease, the page warns that it has stopped reporting. Renderer cancellation closes its browser, and `MINEGEO_RENDER_IDLE_SECONDS` (default 600) fails a renderer that reports no progress for that period. This is an inactivity limit, not a limit on total rendering time. Use a smaller export area or lower `MINEGEO_FACE_SIZE` if rendering one face exceeds it.

## Retry, cancel, and configure

- An interrupted transfer resumes with `minegeo upload`. Progress is saved in `.upload-state.json` beside the export. Already received exports are not submitted twice.
- `minegeo cancel` cancels capture or stops upload at the next transfer boundary. Completed exports are kept. HTTP requests already in flight can take up to their timeout to stop.
- `minegeo reload` reloads `config.yml` after you edit `server-name`, `chunks-per-tick`, or other settings.
- `minegeo status` reports the active stage and the last completed export folder.
- `minegeo help` lists commands.

If processing fails on the website, read the draft's error. A renderer/setup failure can be retried using the already uploaded export; you do not need to export or upload it again.

### Recover an empty render

A report with `meshes: 0`, `emittedFaces: 0`, and ordinary blocks such as stone and dirt in `unsupported` means Minecraft assets did not reach the renderer. Those renders previously completed incorrectly with sky-only images. Assets are local to each host: the ignored `.cache` folder does not transfer when pulling Git changes.

The worker now prepares missing/incomplete vanilla assets before rendering. Setup prepares them before installing Chromium, so a browser installation failure cannot skip the asset download. A completion marker is written after extraction; core models/textures are checked on subsequent runs. Missing models, zero geometry, lost graphics contexts and sky-only downward/map images fail processing instead of producing a playable draft.

To regenerate an existing unpublished draft after pulling this fix:

1. Stop MineGeo with Ctrl+C so its worker is stopped.
2. Run this from the repository root, replacing the UUID with the draft's ID:

   ```sh
   npm run reprocess -- 00ff0076-cae1-4a0d-ab81-9014833309f4
   ```

3. Restart with your usual `npm run dev` or `npm start` command. On the Mac test server:

   ```sh
   PORT=3008 MINEGEO_HOST=0.0.0.0 MINEGEO_ALLOW_ANY_ORIGIN=true npm run dev
   ```

The maintenance command prepares plugin rendering assets, keeps the original raw export, clears the previous preview metadata and queues a fresh render. It refuses published revisions and active jobs. Inspect the regenerated private draft and submit it for review again. If the export itself is invalid, create and upload a corrected export instead.

Expected limits: Minecraft 1.21.11 / Java 21, or Minecraft 26.1 and 26.2 / Java 25, Overworld only, five or more safe viewpoints, at most 2048 blocks per selected side and the worker's terrain/file-size limits. A large selection may need to be split into smaller maps.