MineGeo/docs/server-plugin.md

Server plugin 0.1.1

Update and connect

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

minegeo website https://your-minegeo-domain.example
minegeo link <token copied from the dashboard>

For LAN testing the website may be http://192.168.1.50:3000; use your actual address. localhost means the computer running Minecraft, which may be different from the Mac running the website. HTTP is supported for testing; use HTTPS when transmitting contributor tokens over a public connection.

Export before uploading

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

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:

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:

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.

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 website, 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. Fix the worker/setup or reduce the export area, then create and upload a new export. Keep the old folders until you no longer need them.

Expected limits: Minecraft 1.21.11 / Java 21, 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.