Surveyor Map Framework

An open-source backend (and API) for world map and waypoint mods!
**Requires Connector and FFAPI on (neo)forge.
**

Surveyor is the map backend for mods like Antique Atlas 4, Hoofprint, and Via Romana.
Along with handling the generation and saving of map data like terrain and waypoints, Surveyor:

• Shows other players on your map, even hundreds of chunks away!
• Tracks your exploration, and will restore your map data from the server if it's lost or you change computers!
• Enables live map sharing with other players of your choosing - terrain, waypoints, the lot!
• Allows swapping map frontends any time without losing your map data!
• Imports waypoints from Xaero's Minimap, and has integration for mods like Waystones and OPAC.
• Is fully modular - so mods like Atlas HUD can utilize waypoints without enabling terrain scanning.

Commands

If you're a server admin or don't have a map frontend installed, surveyor comes with a few helpful commands:

• /surveyor displays summary of how many chunks and structures you've explored, and waypoints recorded.
• /surveyor share [player] and /surveyor unshare allows joining and leaving map sharing groups.
• /waypoints allows viewing and editing your recorded waypoints.
• /landmarks allows viewing and (op 2 or above) editing global waypoints.

Surveyor data is stored in plain NBT under data/surveyor (per-dim in singleplayer/servers, in .minecraft for clients).

Configuration

Surveyor's configuration can be edited in config/surveyor.toml, or in-game using McQoy. This includes:

• Toggling the terrain, structure, and landmark subsystems (otherwise set by installed frontends on clients)
• What data should be networked to clients / the server, and between group members.
• Whether all players on the server should be considered part of one global map sharing group.
• How often to send player position updates to clients, and how fast to sync missing terrain to clients.

Mod Developers

Feel free to reach out if you'd like to develop something with surveyor - or just make it! We appreciate:

• PRs making shots at [surveyor enhancements and bugs](https://github.com/sisby-folk/surveyor/issues?q=is:issue state:open (label:bug OR label:enhancement)).
• PRs containing ports to an older established versions (1.4.7, 1.17.10, 1.12.2, 1.16.5, 1.18.2) - or latest, per policy
• PRs containing API features that you'd benefit from - ideally post an issue first, and we can workshop it!
• Compat addons, world maps, minimaps, and waypoint frontends utilizing surveyor!
  Serverside, web map, minecraftless… we just want to cultivate fun new things in the map mod space.

Check out the frontend dev guide for a breakdown of the complicated parts of the internals.

Licensing + Credit

Please match your addon licenses to LGPLv3 if possible - it helps improve the surveyor ecosystem!
(LGPLv3 is a copyleft license, so this is required for anything directly adapted from Surveyor)

If you've made something, hit us up and we might link it here! We'll also answer questions for in-progress projects.
Devs can reach out via mastodon or email.

Afterword

Surveyor was built on the thoughts, advice, opinions, and past works of many modders in the community.

Thanks to everyone who helped make this project happen, even just by fluttering on the sidelines - it means a lot.

We made surveyor because it sounded cool - we hope it helps other artists/modders to make cool things!

An open-source backend (and API) for co-op-enabled world map and waypoint mods!
Requires Connector and FFAPI on (neo)forge.

Surveyor is the backend for map mods like Antique Atlas 4, Hoofprint, and Dead Reckoning.

When installed client-side, Surveyor allows you to:

• View explored terrain and mark points of interest with waypoints
• See on-map landmarks for other mods via compatibility addons, like for Waystones and OPAC
• Swap map frontends at any time, retaining all map data
• Automatically migrate waypoints directly from an existing Xaero's Minimap save

When installed on both sides, Surveyor allows you to:

• Explore map terrain and edit waypoints in co-operative groups (server-wide by default)
• See other players on your map, even far away or in other dimensions
• Swap instances or computers, with your map data restored from the server
• Use op commands to create server-wide landmarks for POIs like spawn, shops, warp hubs, etc.
• Copy exploration from and to vanilla maps by sneak+using a cartography table (style configurable)

As a mod developer, Surveyor allows you to:

• Create pure map frontends by handling all map data itself - terrain, structures, and waypoints
• Create addons for custom on-map landmarks, with a flexible component-style data system
• Create any kind of frontend - server-optional, ingame/mixed-side, external/browser-based, etc
• Utilize the waypoint system on its own, for small, lightweight waypoint/compass mods

Configuration

Surveyor can be configured via config/surveyor.toml, McQoy, or QoMC. Most changes require a restart.

• Disable server-wide co-op by setting globalSharing=false (recommended for public servers)
• Tweak what data is synchronized between players, groups, and the server in the Networking section
• Toggle builtin automatic waypoints (e.g. nether portals, grave markers) in the Builtins section

Commands

Surveyor can mostly be interacted with via map frontends, but comes with a few useful commands:

• When globalSharing=false, use /surveyor share/unshare to form groups to share waypoints and map data
• Use /surveyor, /waypoints, and /landmarks to review your waypoints and explored map data
• Use /waypoints new/remove to create/edit custom waypoints (e.g. if a frontend is not installed)
• Use /landmarks new/remove (op 2) to create/edit operator-level global waypoints (e.g. for server spawn)

Troubleshooting

Report any unique replicable issue to the issues page with logs, screenshots, and replication steps where possible.

Client data is stored in .minecraft/data/surveyor/[world]/[dim], singleplayer/server data in [world]/[dim]/data/surveyor
c.X.X files contain terrain regions, s.X.X files contain structures, and landmarks.dat contains waypoint data.

When encountering issues, you might like to try any of the following:

• Backing up the affected data and deleting it (e.g. for a structure-related error, wipe structure data)
• Disabling networking for a subsystem (e.g. for a terrain packet client kick, set networking.terrain to NONE)
• Disabling a subsystem (e.g. for extreme server memory usage, set terrain to DISABLED on the server)

Contributions / Addons

Feel free to reach out if you'd like to develop something with surveyor - or just go for it! We appreciate:

• PRs making shots at surveyor enhancements and bugs
• PRs containing ports to an older established versions (1.4.7, 1.17.10, 1.12.2, 1.16.5, 1.18.2) - or latest, per policy
• PRs containing API features that you'd benefit from - ideally post an issue first, and we can workshop it
• Compat addons, world maps, minimaps, and waypoint frontends utilizing surveyor!

Check out the frontend dev guide for a breakdown of the complicated parts of the internals.

Licensing / Credit

Please match your addon licenses to LGPLv3 if possible - it helps improve the surveyor ecosystem!
(LGPLv3 is a copyleft license, so this is required for anything directly adapted from Surveyor)

If you've written something, hit us up and we might link it here! We'll also answer questions for in-progress projects.
Devs can reach out on mastodon or via email.

Afterword

Surveyor was built on the thoughts, advice, opinions, and past works of many modders in the community.

Thanks to everyone who helped make this project happen, even just by fluttering on the sidelines - it means a lot.

We made surveyor because it sounded cool - we hope it helps other artists/modders to make cool things!