Servers and modpacks

Installing

• Install Spoor 0.1.0 on the server and on every player’s client, with the same version on both.
• It needs Minecraft 1.21.1 and NeoForge 21.1.248 or newer.
• Curios and Naturalist are optional and not bundled.
• This release uses network protocol 4. When you update, replace the jar on the server and on the clients together.

Visible or Item mode

The server decides who sees tracks, with mode in config/spoor-server.toml. See Configuration.

Mode	Who sees tracks
VISIBLE (default)	Everyone. Without goggles, prints are clear for 60 seconds and gone by three minutes. Goggle wearers read the whole trail.
ITEM	Only players wearing the Tracker Goggles.

Visible is the default in singleplayer and multiplayer. The server enforces the mode for every player, and players cannot override it. In Item mode the server does not send track data or track particles to players without goggles at all, so hiding tracks is not just a visual setting.

In both modes the goggles add the reading and the scent line.

You can switch modes while the server runs. See Changing settings while the game runs.

Player tracks

Player tracks are on by default. Set playerTracks = false to stop recording player tracks and remove existing player prints. Animal and mob tracks are not affected.

Tracks are not saved

Tracks live in memory only. They are gone when a dimension unloads or the server restarts, and they are never written to the world. Spoor never loads chunks to keep a trail and never reconstructs movement or weather it did not see.

Keeping it light

Trail history is capped, for each creature and for the whole server, and counts whole steps rather than feet. The first 30 seconds of a trail stay dense; older straight stretches thin out gradually, while turns, ends and gaps are kept. When the server cap is reached, the largest histories are trimmed first, whatever their category. A crowded server or a very winding route can therefore shorten how long trails last.

Creatures are recorded only within 64 blocks of a player who is not spectating. Each player receives only nearby prints in their own dimension and range, never the whole world’s history and never where a creature is now.

Limits and measurements

• Caps: maxTrailStepsPerServer (default 8,192 steps across all dimensions) and maxTrailStepsPerSource (default 1,024). Up to 16 foot contacts share one step.
• Thinning: an older straight stretch may be thinned when the gap left is at most 2 blocks before two minutes, 4 before five minutes, or 8 after that. Turns beyond 15 degrees and height changes above one block are kept.
• Each player gets at most four updates per simulation second, each holding at most 600 prints for goggle wearers and 300 for others. Clients never send tracking data to the server.
• Prints on removed or changed ground are cleared on a one-second maintenance pass.
• One crowded test reached the full 8,192 steps (about 27,000 foot contacts). Each update to a client then encoded to about 32 kB, roughly 130 kB per simulation second per client before compression. That update held up to 300 prints; a goggle wearer can now receive up to 600 prints per update, so their updates can be larger. This was measured over a local connection on one machine, not real internet bandwidth, and it is not a promise about your server’s performance.

Datapack profiles for modded creatures

Spoor’s vanilla feet ship as data, and a server datapack can add or replace the feet of any living creature, including modded ones, without changing Spoor itself. Profiles affect new prints only; existing prints keep their shape and fade normally.

Put an ordinary Minecraft 1.21.1 datapack in the world’s datapacks folder and run /reload with the usual operator permission. The file path names the creature:

pack.mcmeta
data/<entity namespace>/spoor_profiles/<entity path>.json

For example, data/examplemod/spoor_profiles/deer.json applies to examplemod:deer. examplemod is an illustrative placeholder. A profile for a mod that is not installed is simply unused.

pack.mcmeta:

{"pack":{"pack_format":48,"description":"My Spoor profiles"}}

A two-footed creature, in blocks:

{
  "schema": 1,
  "adult": {
    "baby_scale": 0.5,
    "feet": [
      {"width":0.25,"length":0.25,"side":0.125,"forward":0,"shape":"BOOT","phase":true},
      {"width":0.25,"length":0.25,"side":-0.125,"forward":0,"shape":"BOOT","phase":false}
    ]
  }
}

To stop a creature from leaving new tracks:

{"schema":1,"enabled":false}

Profile fields

• width and length describe one sole. side is positive to the creature’s left; forward is positive ahead.
• phase splits the feet into two alternating groups, and both groups need at least one foot. Two-footed creatures normally alternate feet; four-footed ones normally pair diagonal front and back feet in each group.
• An optional baby object has the same feet structure, measured for the baby model; it is not shrunk again. Without baby, babies reuse the adult feet scaled by baby_scale (default 0.5).
• Shapes: BOOT, HOOF, SOLID_HOOF, PAW, CAT_PAW, BEAR_PAW, BIRD, WEBBED, FLIPPER, RABBIT, BLOCK, ROUND, SLITHER, INSECT.
• Limits: 16 feet per variant, sole sizes above zero and at most two blocks, offsets within 4 blocks either way, baby_scale 0.01 to 2, 64 KiB per file and 1,024 profile files.
• Validation rejects unknown fields, missing numbers, numbers or booleans written as strings, unknown shapes and unsupported schema versions. An invalid file logs a warning and that creature uses its fallback. Removing a profile and reloading restores the fallback for new prints.
• Built-in exclusions stay in force, so a profile cannot give footless creatures such as the Breeze boots.
• Minecraft’s normal datapack priority picks the highest-priority file at the same path.

Modpacks

Spoor is licensed under LGPL-3.0-only, so you can include it in a modpack. Make sure the server and the clients in your pack use the same Spoor version.