octoturge
699f09f081
Adds a hand-rolled RFC 6455 WS client and minimal JSON codec to common/ (no third-party deps, keeping legacy ForgeGradle's classpath untouched), a DefaultBackendConnection implementing hello/hello_ack auth and reconnect with backoff, and Forge1122ChunkAdapter deriving top-of-column state from the vanilla heightmap for both initial chunk backfill and event-driven deltas (block break/place, deferred one tick to read post-mutation state). MCMapperMod wires it up with config-driven backendUrl/serverToken and a tick-based flush batch. Verified against a live MCMapper-Backend api instance (real WS handshake, hello_ack, and 256-column batch landing correctly in Postgres).
65 lines
3.0 KiB
Markdown
65 lines
3.0 KiB
Markdown
# MCMapper-Mod
|
|
|
|
Thin, version-independent Forge/NeoForge client for [MCMapper-Backend](https://git.octoturge.com/octoturge/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. 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 (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 (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`.
|