octoturge
73e10d34e5
Test-first from here on (per request after Phase 2's backend commit): LinkCodeGenerator has a standalone test (common/src/test) written and confirmed failing before the implementation existed. common: LinkCodeGenerator produces a 6-character code from an unambiguous charset (excludes 0/O/1/I/L — it gets read off a chat line and typed back). BackendConnection grows sendLinkRequest (now actually implemented, was a Phase 1 stub), sendChatMessage, and setChatListener/ ChatListener for inbound web->game chat, all wired into DefaultBackendConnection's existing JSON wire protocol. forge-1_12_2: LinkCommand (/mcmapper link) generates a code, resolves online/offline from the server's actual auth mode (MinecraftServer#isServerInOnlineMode), and shows it to the player. Forge1122ChatBridge implements the inbound half (injects web chat into real in-game chat via the player list) — injectWaypointShare is a documented Phase 4 stub, same pattern as sendLinkRequest was in Phase 1. MCMapperMod hooks ServerChatEvent to forward in-game chat out and wires the chat listener to the bridge. Verified end-to-end against a live MCMapper-Backend instance through the real Java client (not a stand-in): a mod-generated link code correctly redeems via the backend's HTTP endpoint to an account with the mod- supplied username, and a browser chat message correctly round-trips all the way to the mod's live ChatListener callback.
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 (seecommon/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 (seeTHIRD_PARTY_NOTICES.md).forge-1_7_10/— MC 1.7.10 Forge. Second priority. Builds with legacy ForgeGradle 1.2, same fork family, one Forge-tooling generation further back.neoforge-26_1/— MC 26.1.2 (NeoForge, assumed). Lowest MVP priority. Structurally scaffolded, not yet wired into the default build (seesettings.gradle).
Version targets and priority
- MC 1.12.2 Forge — highest priority (Enigmatica 2)
- MC 1.7.10 Forge — also a priority
- 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 (Phase 1: forge-1_12_2)
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). No periodic reconciliation sweep yet (Phase 7),
and only the overworld — other dimensions and forge-1_7_10/neoforge-26_1 land in later
phases. 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.
Attribution
See THIRD_PARTY_NOTICES.md.