MineGeo/docs/panorama-contributions.md

# More panoramas and player contributions

Maps hold 5–24 captured locations. Each game chooses five distinct locations in random order. The server plugin now picks random safe surface positions, with `viewpoints: 24` as the default for new installations; existing config files keep their value until edited and reloaded. The Fabric mod captures where the player is standing and permits up to 24 local captures; the uploader sends as many as the map and player limits allow.

Round selection treats captures from the same block position as one location,
even when their panorama IDs differ. Shared image paths are also selected only
once. This applies to solo and multiplayer games, including older published maps.
A map needs five distinct locations to start a game. The Fabric mod blocks
another capture at an already captured block position and prevents captures
while another capture or upload is in progress.

## Owner workflow

Open the map in the dashboard. Under **Panorama settings**, enable **Allow players to add panoramas with you**. This is off by default. Share the map ID and its Minecraft X/Z bounds. Players must capture in the same world and inside those bounds. Owners can add their own captures using that map ID even when player contributions are disabled.

The map's limit includes all retained captures and pending uploads. Each non-owner can add at most 12 panoramas cumulatively to that map, across uploads and both tools. Accepted panoramas continue to count toward that player's limit. Rejected, withdrawn, and failed contributions release their reserved space. Deselecting an original map location keeps it available to restore and does not free a capture slot.

In **Player submissions**, inspect the submitted locations in 360°. Accept them into the map draft or reject with feedback. Acceptance adds the contributor's selected locations; unused captures stay private to the contributor. Save the combined selection and **Submit for review**. Moderators review both new maps and updates.

For an already published map, its approved name, description, panorama count, and revision stay live until a moderator approves the update. Rejecting an update leaves that version playable. Existing games continue using the revision they started with. Editing and accepting further submissions are locked while the update is under review.

## Refresh guessing map

**Map tools → Refresh guessing map** rebuilds only the overhead map through the worker. It consumes no panorama slots and leaves every panorama image unchanged. Choose the original capture, another processed capture you own, or an accepted contribution whose bounds and expected server address match the map exactly. To show new buildings, export and upload fresh terrain first. The published map and ongoing games keep their current image until the owner publishes the finished update; ongoing games retain their original revision.

New Fabric captures also record up to four surface layers from chunks already
loaded by the client. The standalone worker renders those blocks using the same
overhead renderer as plugin terrain, while the mod's panorama photographs remain
unchanged. Use **Rescan terrain** and revisit changed areas before uploading;
previously captured chunks remain available until they are rescanned. It does not
request unexplored chunks; revisit existing areas to capture terrain for older mod maps. Earlier Fabric exports without terrain keep
using their captured flat map. A standalone worker is required to process the new
terrain exports; the image-only serverless processor leaves them queued for it.

## Player workflow

Install the updated capture tool and link your own MineGeo account. A new map needs at least five panoramas; a contribution may contain just one.

- **Fabric:** Press G, paste the owner's map ID into **Add to map ID**, capture within the original bounds, and upload. Leave the field blank to upload a new map.
- **Plugin:** Set the website and your own contributor token, select an explored area within the map bounds, export it, then run `/minegeo contribute <map ID>`. Server permission `minegeo.admin` is still required for server exports. Players without that permission can use the Fabric mod.

The uploader keeps up to the available slots (24 for the map owner, 12 per guest), or fewer when the map has less room. Its saved selection and upload ledger make retries idempotent. After processing, open **Open contribution** in the dashboard, inspect/select locations, and **Submit to map owner**. You may withdraw a pending submission to release its reserved quota. A completed accepted submission cannot be edited or overwritten; use a fresh capture to add more.

Both tools can contribute to either kind of map. The original surface map and bounds remain the basis for guessing; contributions append panoramas. Owners and moderators must check that submissions show the correct world, useful views, and acceptable visual quality.

## Contribution server check

Owners can enter up to ten connection addresses separated by commas, for example
`play.example.com, mc.example.com:25566`. Matching any listed address is enough;
the backend still checks every upload and retry. Older capture tools defer the
alias check to the website. The updated tools check before uploading as well.

For a map that is already published, its owner can save the draft and select
**Publish update** to publish a validated revision without another moderator
review. A new map still requires its initial review. This also publishes any
player contributions the owner has already accepted into that draft.
When uploading the owner's own contribution to an already published map, the
contribution draft also offers **Update my map now**. It submits and accepts
the owner's selected panoramas and publishes the update together; it refuses to
run while the parent map has other unpublished edits.

Each map has a separate **Contribution server address** setting. New maps use the address recorded by their capture tool. Existing maps with a valid captured address are initialized from their own manifest. Maps whose old exports contain no address show **Server check is off** until the owner enters one.

When contributions are enabled, the map page shows that address. The owner can correct it in the dashboard, including a custom port. **Clear address and turn off check** removes the displayed address and permits submissions without matching a server. Clearing does not skip owner approval or moderator review.

The Fabric mod records the connected Minecraft server automatically and requires joining that capture's server before contributing. The plugin cannot infer a public address from its bind IP. Before exporting, its admin must set `server-address: 'play.example.com'` in `config.yml` and reload, or run `/minegeo server play.example.com`. Use the same connection hostname/IP that Fabric players enter. Existing exports must be recreated after changing this configuration; their recorded capture origin is retained on retry.

Both uploaders check the recorded capture address against the target map before sending assets, including cached retries. The website checks again when creating/signing/finalizing the upload, submitting it, and accepting it. A missing capture address is blocked when the map's check is enabled. Domain case, a trailing DNS dot, and the default `:25565` port are normalized. Different DNS aliases are not automatically treated as the same server.

This prevents accidental submissions from another server. Capture addresses are supplied by the tool; a modified client can forge them, and one address can host multiple worlds. Owner inspection and moderator review remain necessary. This is address matching, not authenticated proof of server membership.

## Deployment

The configured MineGeo Supabase project has the first four October 5 migrations applied. Apply `20261005200000_map_refresh_fixes.sql` before deploying this website/worker pair. For another database, apply `20261005063646_panorama_contributions.sql`, `20261005065029_withdraw_contribution.sql`, `20261005073253_contribution_server_check.sql`, `20261005141142_map_refresh.sql`, and `20261005200000_map_refresh_fixes.sql` after the existing migrations. Deploy the website and worker together. Replace both Minecraft JARs from `public/tools` and restart Minecraft/the server. An installed older tool does not acquire the new contribution controls when the website changes.

The new transactional functions are callable only by the server's service role. They verify map ownership, opt-in, bounds, processing validation and review state, and serialize uploads/edits/approvals using a map row lock. Media provenance is assigned by the server after acceptance; uploaders cannot choose another dataset's private media paths. Published revisions remain immutable.