MCMapper-Mod/README.md

MCMapper-Mod

Thin, version-independent Forge/NeoForge client for MCMapper-Backend. Streams delta block updates out to the backend instead of rendering the map on the MC server itself (the Bluemap/Dynmap resource problem this project exists to avoid). Full architecture and phased delivery plan lives in the backend repo's planning docs / was tracked during design in Claude Code's plan mode.

Repo layout

• common/ — loader-agnostic Java: protocol types, config model, and the interfaces (ChunkAdapter, ChatBridge, BackendConnection) each leaf implements. Not a compiled dependency — pulled in as source per leaf (see common/README.md).
• forge-1_12_2/ — primary leaf, MC 1.12.2 Forge. First implemented; this is the actual driving use case (an Enigmatica 2 modpack server). Builds with legacy ForgeGradle 2.3 via anatawa12's Gradle-7-compatible fork (see THIRD_PARTY_NOTICES.md).
• forge-1_7_10/ — MC 1.7.10 Forge (Phase 9). Second priority, fully wired against the same common interfaces as forge-1_12_2. Builds with legacy ForgeGradle 1.2, same fork family, one Forge-tooling generation further back — pre-block-state (raw Block + metadata int, no IBlockState) and pre-FML-repackage (cpw.mods.fml.*, not net.minecraftforge.fml.*).
• neoforge-26_1/ — MC 26.1.2 (NeoForge, assumed). Lowest MVP priority. Structurally scaffolded, not yet wired into the default build (see settings.gradle).

Version targets and priority

1. MC 1.12.2 Forge — highest priority (Enigmatica 2)
2. MC 1.7.10 Forge — also a priority
3. MC 26.1.2 — lowest of the three MVP targets

Fabric support is an explicit future phase, not part of the MVP.

Building

Both legacy leaves share one root build, on Gradle 7.6 / JDK 8 (pinned via org.gradle.java.home in gradle.properties — see settings.gradle for why):

./gradlew :forge-1_12_2:build
./gradlew :forge-1_7_10:build

The first build downloads Minecraft/Forge artifacts and MCP mappings from Forge's Maven and can take a while / needs network access. neoforge-26_1 is not yet buildable from the root — it needs Gradle 8+ and JDK 17+ (ModDevGradle), incompatible with the legacy leaves' toolchain within one Gradle invocation; see settings.gradle's comment for the workaround until Phase 10 gives it a proper isolated build.

Configuration (forge-1_12_2 and forge-1_7_10)

On first server start the leaf writes config/mcmapper.cfg with defaults. Set:

backendUrl=ws://<backend-host>:3000/ws
serverToken=<token from MCMapper-Backend's `bun run seed`>

then restart. With those set, the mod connects to the backend, backfills already-loaded overworld chunks, and streams event-driven column deltas (block place/break) in batches every deltaFlushIntervalTicks (default 20 = 1s). A periodic reconciliation sweep (Phase 7) also walks a bounded number of currently-loaded chunks per tick (reconciliationChunksPerSweep, default 4) and re-sends any that drifted from what the backend last acknowledged, to catch mutations event hooks miss (world-gen, other mods, /fill). Only the overworld is tracked — other dimensions and neoforge-26_1 land in a later phase. The WS client and JSON encoding are hand-rolled (no third-party dependency) — see common/src/main/java/.../ws/SimpleWebSocketClient.java and .../json/MiniJson.java for why. forge-1_7_10 implements the identical config/flush/reconciliation/player-tracking behavior against 1.7.10's own API generation (see Forge1710ChunkAdapter's javadoc for what differs) — it has no MultiPlaceEvent hook (that class doesn't reliably exist at this Forge version), so multi-block placements like doors/beds are only caught by the reconciliation sweep rather than immediately, unlike forge-1_12_2.

Player position tracking (Phase 7b)

When playerTrackingEnabled (default true), the leaf sends a throttled roster of online overworld players ({"type":"player_positions",...}, see DefaultBackendConnection's class-level wire-protocol doc comment) every playerPositionIntervalTicks (default 40 = 2s) — always the full current roster, not a diff, so a logged-out player simply stops appearing in the next send. This is a mod-local toggle only: whether the backend actually relays positions on to web viewers is a separate, independent per-server admin setting on the backend side (see MCMapper-Backend's README) — a server operator can track positions server-side without exposing them publicly, or vice versa.

Attribution

See THIRD_PARTY_NOTICES.md.