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.