Phase 0: scaffold Gradle multi-project mod skeleton

common/ (shared source) plus three leaf modules: forge-1_12_2 (primary, Enigmatica 2 target) and forge-1_7_10 both build via anatawa12's Gradle-7-compatible ForgeGradle 1.2/2.3 forks (verified: both leaves build clean on Gradle 7.6 / JDK 8). neoforge-26_1 is structurally scaffolded but excluded from the default build pending its own toolchain in Phase 10.
2026-08-08 14:10:01 +02:00
commit 621ea7c10d
26 changed files with 925 additions and 0 deletions
@@ -0,0 +1,24 @@
+# Gradle
+.gradle/
+build/
+out/
+
+# Per-leaf Forge/NeoForge run dirs
+run/
+runs/
+logs/
+
+# IDE
+.idea/
+*.iml
+.vscode/
+.classpath
+.project
+.settings/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local overrides
+local.properties
@@ -0,0 +1,48 @@
+# 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.
+
+## Attribution
+
+See `THIRD_PARTY_NOTICES.md`.
@@ -0,0 +1,32 @@
+# Third-party notices
+
+This project may adapt ideas, publicly documented formats, or (rarely) small snippets from
+other open-source projects, always with attribution here and a comment at the point of use.
+Nothing is copied from closed-source projects — in particular, Xaero's Minimap/Worldmap are
+closed-source, so any Xaero-compatible waypoint link support is implemented purely from
+publicly documented/community-reverse-engineered wire format, never from Xaero's code.
+
+## ForgeGradle 2.3 (Gradle-7-compatible fork)
+- Source: https://github.com/anatawa12/ForgeGradle-2.3
+- License: LGPL-2.1 (same as upstream MinecraftForge/ForgeGradle FG_2.3 branch, which this forks)
+- Used in: `forge-1_12_2/build.gradle` (buildscript classpath)
+- What was adapted: not adapted/copied — used as-is as a build-tool dependency (Gradle plugin),
+  chosen because the official `net.minecraftforge.gradle:ForgeGradle:2.3-SNAPSHOT` no longer
+  resolves and never supported Gradle 7+ regardless.
+
+## ForgeGradle 1.2 (Gradle-7-compatible fork)
+- Source: https://github.com/anatawa12/ForgeGradle-1.2
+- License: LGPL-2.1 (same as upstream MinecraftForge/ForgeGradle FG_1.2 branch, which this forks)
+- Used in: `forge-1_7_10/build.gradle` (buildscript classpath)
+- What was adapted: not adapted/copied — used as-is as a build-tool dependency (Gradle plugin),
+  same rationale as the FG2.3 fork above, one Forge-tooling generation further back for 1.7.10.
+
+Further entries will be added here as more third-party material lands, in the form:
+
+```
+## <thing adapted>
+- Source: <project name and URL>
+- License: <license>
+- Used in: <file path>
+- What was adapted: <short description>
+```
@@ -0,0 +1,14 @@
+// Root project intentionally has no plugins applied — each leaf module (forge-1_7_10,
+// forge-1_12_2, neoforge-26_1) uses a different loader-tooling generation and configures
+// itself independently. `common` is shared as source, not as a compiled artifact, since
+// its consumers target different Java versions (Java 8 for the legacy Forge leaves, a
+// modern JDK for neoforge-26_1) — see common/README.md.
+
+allprojects {
+    group = 'com.octoturge.mcmapper'
+    version = '0.1.0-SNAPSHOT'
+
+    repositories {
+        mavenCentral()
+    }
+}
@@ -0,0 +1,19 @@
+# common
+
+Loader-agnostic Java: protocol types, config model, and the interfaces each leaf module
+(`forge-1_7_10`, `forge-1_12_2`, `neoforge-26_1`) implements against its own Minecraft/Forge
+API generation.
+
+This module is **not** consumed as a compiled binary dependency. The legacy leaves (1.7.10,
+1.12.2) target Java 8; `neoforge-26_1` targets a modern JDK. To avoid cross-version binary
+compatibility issues, each leaf module adds `common/src/main/java` directly to its own source
+set (see the `sourceSets.main.java.srcDirs` line in each leaf's `build.gradle`) and compiles it
+itself, once per leaf, against its own toolchain. Keep this module free of any
+Minecraft/Forge/NeoForge API usage — it must compile standalone under plain `javac`.
+
+## Layout
+
+- `protocol/` — wire types shared with the backend (delta events, chat/waypoint payloads, link
+  request/response). Mirrors the WS protocol described in the root plan.
+- `config/` — the common config model (backend URL, server token, tracking/reconciliation
+  intervals) each leaf loads via its own loader-specific config system.
@@ -0,0 +1,42 @@
+package com.octoturge.mcmapper.common;
+
+import com.octoturge.mcmapper.common.protocol.DeltaEvent;
+import com.octoturge.mcmapper.common.protocol.LinkRequest;
+
+import java.util.List;
+
+/**
+ * Outbound WS client to the backend `api` service. One implementation shared by all leaf
+ * modules (pure Java, no Minecraft API usage) — a docker-network hostname, LAN IP, or public
+ * domain in {@code MapperConfig#backendUrl} all work identically.
+ *
+ * Left as an interface with a no-op stub for Phase 0 scaffolding; the real WS client
+ * (handshake, reconnect/backoff, batching) lands in Phase 1.
+ */
+public interface BackendConnection {
+    void connect(String url, String serverToken);
+
+    void sendDeltas(List<DeltaEvent> deltas);
+
+    void sendLinkRequest(LinkRequest request);
+
+    void disconnect();
+
+    final class NoOp implements BackendConnection {
+        @Override
+        public void connect(String url, String serverToken) {
+        }
+
+        @Override
+        public void sendDeltas(List<DeltaEvent> deltas) {
+        }
+
+        @Override
+        public void sendLinkRequest(LinkRequest request) {
+        }
+
+        @Override
+        public void disconnect() {
+        }
+    }
+}
@@ -0,0 +1,20 @@
+package com.octoturge.mcmapper.common;
+
+import com.octoturge.mcmapper.common.protocol.WaypointShare;
+
+/**
+ * Loader-specific chat integration. Implementations inject web-originated chat into real
+ * in-game chat, and build the clickable waypoint chat component for whichever
+ * {@link WaypointShare.Format} is configured — that's text-component API and is different
+ * per Minecraft era, so it can't live in {@code common}.
+ */
+public interface ChatBridge {
+    void injectWebChatMessage(String displayName, String message);
+
+    void injectWaypointShare(WaypointShare waypoint);
+
+    /** Called by the loader's own chat event hook; forwards to the backend over the WS connection. */
+    interface OutboundSink {
+        void onInGameChatMessage(String uuid, String username, String message);
+    }
+}
@@ -0,0 +1,23 @@
+package com.octoturge.mcmapper.common;
+
+import com.octoturge.mcmapper.common.protocol.DeltaEvent;
+
+import java.util.List;
+
+/**
+ * The seam between a specific Minecraft/Forge API generation and the shared delta-capture and
+ * networking logic. Each leaf module (forge-1_7_10, forge-1_12_2, neoforge-26_1) provides one
+ * implementation, adapting its own era's block-id/block-state representation into the
+ * {@code blockStateId} carried by {@link DeltaEvent}.
+ */
+public interface ChunkAdapter {
+    /** Bulk-read a chunk's current state for initial sync / reconciliation, as delta events. */
+    List<DeltaEvent> readChunk(String dimension, int chunkX, int chunkZ);
+
+    /** Register the loader-specific hooks (block place/break, chunk load/unload) that feed the dirty buffer. */
+    void registerEventHooks(DeltaSink sink);
+
+    interface DeltaSink {
+        void onDelta(DeltaEvent event);
+    }
+}
@@ -0,0 +1,15 @@
+package com.octoturge.mcmapper.common.config;
+
+/**
+ * Loader-agnostic config model. Each leaf module owns loading/saving these values through
+ * its own loader's config system (Forge Config API for the legacy leaves, NeoForge's config
+ * system for neoforge-26_1) and constructs one of these to hand to the common connection code.
+ */
+public class MapperConfig {
+    public String backendUrl = "ws://localhost:3000/ws";
+    public String serverToken = "";
+
+    public boolean playerTrackingEnabled = true;
+    public int deltaFlushIntervalTicks = 20;
+    public int reconciliationIntervalTicks = 20 * 60 * 5;
+}
@@ -0,0 +1,32 @@
+package com.octoturge.mcmapper.common.protocol;
+
+/**
+ * A single block change, produced by either the event-driven capture path or the periodic
+ * reconciliation sweep. {@code blockStateId} is a palette index into whatever block/state
+ * palette the leaf module's {@code ChunkAdapter} maintains — the common module never
+ * interprets it, it just carries it to the backend.
+ */
+public class DeltaEvent {
+    public final String dimension;
+    public final int x;
+    public final int y;
+    public final int z;
+    public final int blockStateId;
+    public final long timestamp;
+    public final Source source;
+
+    public DeltaEvent(String dimension, int x, int y, int z, int blockStateId, long timestamp, Source source) {
+        this.dimension = dimension;
+        this.x = x;
+        this.y = y;
+        this.z = z;
+        this.blockStateId = blockStateId;
+        this.timestamp = timestamp;
+        this.source = source;
+    }
+
+    public enum Source {
+        EVENT,
+        RECONCILIATION
+    }
+}
@@ -0,0 +1,25 @@
+package com.octoturge.mcmapper.common.protocol;
+
+/**
+ * Sent when a player runs the link command in-game. {@code authMode} mirrors the MC server's
+ * own online-mode setting and tells the backend whether {@code uuid} is a real Mojang UUID
+ * (safe to merge across servers) or an offline-mode hash (scoped to this server only).
+ */
+public class LinkRequest {
+    public final String uuid;
+    public final String username;
+    public final String code;
+    public final AuthMode authMode;
+
+    public LinkRequest(String uuid, String username, String code, AuthMode authMode) {
+        this.uuid = uuid;
+        this.username = username;
+        this.code = code;
+        this.authMode = authMode;
+    }
+
+    public enum AuthMode {
+        ONLINE,
+        OFFLINE
+    }
+}
@@ -0,0 +1,32 @@
+package com.octoturge.mcmapper.common.protocol;
+
+/**
+ * Structured payload pushed from the backend when a web visitor shares a marker to chat.
+ * {@code x, y, z} are all populated by the backend (y auto-derived from its heightmap at
+ * placement time) — the mod's only job is to render this as a clickable chat component in
+ * whichever {@link Format} the server admin configured.
+ */
+public class WaypointShare {
+    public final String name;
+    public final int x;
+    public final int y;
+    public final int z;
+    public final String dimension;
+    public final String color;
+    public final Format format;
+
+    public WaypointShare(String name, int x, int y, int z, String dimension, String color, Format format) {
+        this.name = name;
+        this.x = x;
+        this.y = y;
+        this.z = z;
+        this.dimension = dimension;
+        this.color = color;
+        this.format = format;
+    }
+
+    public enum Format {
+        JOURNEYMAP,
+        XAERO
+    }
+}
@@ -0,0 +1,38 @@
+buildscript {
+    repositories {
+        mavenCentral()
+        maven { url = 'https://maven.minecraftforge.net/' }
+    }
+    dependencies {
+        classpath('com.anatawa12.forge:ForgeGradle:2.3-1.0.+') {
+            changing = true
+        }
+    }
+}
+
+// Legacy ForgeGradle 2.3, via anatawa12's modern-Gradle-compatible fork of the official
+// FG_2.3 branch (net.minecraftforge.gradle:ForgeGradle:2.3-SNAPSHOT doesn't resolve anymore
+// and the official plugin never supported Gradle 7+ anyway). See THIRD_PARTY_NOTICES.md.
+apply plugin: 'net.minecraftforge.gradle.forge'
+
+sourceCompatibility = targetCompatibility = '1.8'
+compileJava.options.encoding = 'UTF-8'
+
+// Pull in the shared common/ source directly — see common/README.md for why it's not a
+// compiled dependency.
+sourceSets {
+    main {
+        java {
+            srcDir '../common/src/main/java'
+        }
+    }
+}
+
+minecraft {
+    version = "${project.minecraft_1_12_2_version}-${project.forge_1_12_2_version}"
+    runDir = "run"
+    mappings = project.mcp_1_12_2_mappings
+}
+
+dependencies {
+}
@@ -0,0 +1,25 @@
+package com.octoturge.mcmapper.forge1122;
+
+import net.minecraftforge.fml.common.Mod;
+import net.minecraftforge.fml.common.event.FMLPreInitializationEvent;
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+/**
+ * Entry point for the 1.12.2 leaf — the primary/first-implemented target (Enigmatica 2).
+ * Phase 0 scaffolding only: connection, delta capture, chat bridge and link-command wiring
+ * land in Phase 1, built on the {@code common} interfaces via a 1.12.2 {@code ChunkAdapter}
+ * and {@code ChatBridge} implementation (not yet present in this package).
+ */
+@Mod(modid = MCMapperMod.MOD_ID, name = "MCMapper", version = MCMapperMod.VERSION)
+public class MCMapperMod {
+    public static final String MOD_ID = "mcmapper";
+    public static final String VERSION = "0.1.0-SNAPSHOT";
+
+    private static final Logger LOGGER = LogManager.getLogger(MOD_ID);
+
+    @Mod.EventHandler
+    public void preInit(FMLPreInitializationEvent event) {
+        LOGGER.info("MCMapper (1.12.2 leaf) scaffolding loaded — no-op until Phase 1");
+    }
+}
@@ -0,0 +1,15 @@
+[
+  {
+    "modid": "mcmapper",
+    "name": "MCMapper",
+    "description": "Thin delta-streaming client for the MCMapper web map backend.",
+    "version": "${version}",
+    "mcversion": "1.12.2",
+    "url": "https://git.octoturge.com/octoturge/MCMapper-Mod",
+    "authorList": ["Octoturge"],
+    "credits": "",
+    "logoFile": "",
+    "screenshots": [],
+    "dependencies": []
+  }
+]
@@ -0,0 +1,38 @@
+buildscript {
+    repositories {
+        mavenCentral()
+        maven { url = 'https://maven.minecraftforge.net/' }
+    }
+    dependencies {
+        classpath('com.anatawa12.forge:ForgeGradle:1.2-1.1.+') {
+            changing = true
+        }
+    }
+}
+
+// Legacy ForgeGradle 1.2 (the FG lineage 1.7.10 actually needs — one major generation older
+// than forge-1_12_2's FG2.3), via anatawa12's modern-Gradle-compatible fork. See
+// THIRD_PARTY_NOTICES.md.
+apply plugin: 'forge'
+
+// Forge 1.7.10 runs on Java 6-8; we target 8 to match the other legacy leaf and common/.
+sourceCompatibility = targetCompatibility = '1.8'
+compileJava.options.encoding = 'UTF-8'
+
+// Pull in the shared common/ source directly — see common/README.md for why it's not a
+// compiled dependency.
+sourceSets {
+    main {
+        java {
+            srcDir '../common/src/main/java'
+        }
+    }
+}
+
+minecraft {
+    version = "${project.minecraft_1_7_10_version}-${project.forge_1_7_10_version}"
+    runDir = "run"
+}
+
+dependencies {
+}
@@ -0,0 +1,11 @@
+package com.octoturge.mcmapper.forge1710;
+
+/**
+ * Stub for the 1.7.10 leaf (Phase 9 — higher priority than 26.1.2, ships after 1.12.2 proves
+ * the architecture). Not wired to the Forge {@code @Mod} annotation yet since this leaf's
+ * ForgeGradle 2.1 toolchain isn't active in the root build — see build.gradle.
+ */
+public class MCMapperMod {
+    public static final String MOD_ID = "mcmapper";
+    public static final String VERSION = "0.1.0-SNAPSHOT";
+}
@@ -0,0 +1,25 @@
+org.gradle.jvmargs=-Xmx3G
+org.gradle.daemon=false
+
+# forge-1_12_2 and forge-1_7_10 (legacy ForgeGradle 1.2/2.3, see their build.gradle + this repo's
+# README) need the Gradle daemon itself running on JDK 8 — newer JDKs aren't supported by that
+# tooling. Point org.gradle.java.home at a JDK 8 install, either via a JAVA_HOME env var or by
+# adding org.gradle.java.home=/path/to/jdk-8 to a local, untracked override (see local.properties
+# in .gitignore — Gradle also honours a gradle.properties in $GRADLE_USER_HOME for this without
+# touching this tracked file at all).
+
+mod_version=0.1.0-SNAPSHOT
+mod_id=mcmapper
+
+# forge-1_7_10
+minecraft_1_7_10_version=1.7.10
+forge_1_7_10_version=10.13.4.1614-1.7.10
+
+# forge-1_12_2
+minecraft_1_12_2_version=1.12.2
+forge_1_12_2_version=14.23.5.2847
+mcp_1_12_2_mappings=stable_39
+
+# neoforge-26_1 (loader assumed NeoForge — confirm before Phase 10, see plan's Open Assumptions)
+minecraft_26_1_version=26.1.2
+neoforge_26_1_version=26.1.2
@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.6-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists
@@ -0,0 +1,252 @@
+#!/bin/sh
+
+#
+# Copyright © 2015-2021 the original authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+##############################################################################
+#
+#   Gradle start up script for POSIX generated by Gradle.
+#
+#   Important for running:
+#
+#   (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is
+#       noncompliant, but you have some other compliant shell such as ksh or
+#       bash, then to run this script, type that shell name before the whole
+#       command line, like:
+#
+#           ksh Gradle
+#
+#       Busybox and similar reduced shells will NOT work, because this script
+#       requires all of these POSIX shell features:
+#         * functions;
+#         * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,
+#           «${var#prefix}», «${var%suffix}», and «$( cmd )»;
+#         * compound commands having a testable exit status, especially «case»;
+#         * various built-in commands including «command», «set», and «ulimit».
+#
+#   Important for patching:
+#
+#   (2) This script targets any POSIX shell, so it avoids extensions provided
+#       by Bash, Ksh, etc; in particular arrays are avoided.
+#
+#       The "traditional" practice of packing multiple parameters into a
+#       space-separated string is a well documented source of bugs and security
+#       problems, so this is (mostly) avoided, by progressively accumulating
+#       options in "$@", and eventually passing that to Java.
+#
+#       Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,
+#       and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;
+#       see the in-line comments for details.
+#
+#       There are tweaks for specific operating systems such as AIX, CygWin,
+#       Darwin, MinGW, and NonStop.
+#
+#   (3) This script is generated from the Groovy template
+#       https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       within the Gradle project.
+#
+#       You can find Gradle at https://github.com/gradle/gradle/.
+#
+##############################################################################
+
+# Attempt to set APP_HOME
+
+# Resolve links: $0 may be a link
+app_path=$0
+
+# Need this for daisy-chained symlinks.
+while
+    APP_HOME=${app_path%"${app_path##*/}"}  # leaves a trailing /; empty if no leading path
+    [ -h "$app_path" ]
+do
+    ls=$( ls -ld "$app_path" )
+    link=${ls#*' -> '}
+    case $link in             #(
+      /*)   app_path=$link ;; #(
+      *)    app_path=$APP_HOME$link ;;
+    esac
+done
+
+# This is normally unused
+# shellcheck disable=SC2034
+APP_BASE_NAME=${0##*/}
+# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
+APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s
+' "$PWD" ) || exit
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD=maximum
+
+warn () {
+    echo "$*"
+} >&2
+
+die () {
+    echo
+    echo "$*"
+    echo
+    exit 1
+} >&2
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "$( uname )" in                #(
+  CYGWIN* )         cygwin=true  ;; #(
+  Darwin* )         darwin=true  ;; #(
+  MSYS* | MINGW* )  msys=true    ;; #(
+  NONSTOP* )        nonstop=true ;;
+esac
+
+CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
+
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+        # IBM's JDK on AIX uses strange locations for the executables
+        JAVACMD=$JAVA_HOME/jre/sh/java
+    else
+        JAVACMD=$JAVA_HOME/bin/java
+    fi
+    if [ ! -x "$JAVACMD" ] ; then
+        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+else
+    JAVACMD=java
+    if ! command -v java >/dev/null 2>&1
+    then
+        die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+fi
+
+# Increase the maximum file descriptors if we can.
+if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
+    case $MAX_FD in #(
+      max*)
+        # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        MAX_FD=$( ulimit -H -n ) ||
+            warn "Could not query maximum file descriptor limit"
+    esac
+    case $MAX_FD in  #(
+      '' | soft) :;; #(
+      *)
+        # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        ulimit -n "$MAX_FD" ||
+            warn "Could not set maximum file descriptor limit to $MAX_FD"
+    esac
+fi
+
+# Collect all arguments for the java command, stacking in reverse order:
+#   * args from the command line
+#   * the main class name
+#   * -classpath
+#   * -D...appname settings
+#   * --module-path (only if needed)
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.
+
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if "$cygwin" || "$msys" ; then
+    APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
+    CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" )
+
+    JAVACMD=$( cygpath --unix "$JAVACMD" )
+
+    # Now convert the arguments - kludge to limit ourselves to /bin/sh
+    for arg do
+        if
+            case $arg in                                #(
+              -*)   false ;;                            # don't mess with options #(
+              /?*)  t=${arg#/} t=/${t%%/*}              # looks like a POSIX filepath
+                    [ -e "$t" ] ;;                      #(
+              *)    false ;;
+            esac
+        then
+            arg=$( cygpath --path --ignore --mixed "$arg" )
+        fi
+        # Roll the args list around exactly as many times as the number of
+        # args, so each arg winds up back in the position where it started, but
+        # possibly modified.
+        #
+        # NB: a `for` loop captures its iteration list before it begins, so
+        # changing the positional parameters here affects neither the number of
+        # iterations, nor the values presented in `arg`.
+        shift                   # remove old arg
+        set -- "$@" "$arg"      # push replacement arg
+    done
+fi
+
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='-Dfile.encoding=UTF-8 "-Xmx64m" "-Xms64m"'
+
+# Collect all arguments for the java command:
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
+#     and any embedded shellness will be escaped.
+#   * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
+#     treated as '${Hostname}' itself on the command line.
+
+set -- \
+        "-Dorg.gradle.appname=$APP_BASE_NAME" \
+        -classpath "$CLASSPATH" \
+        org.gradle.wrapper.GradleWrapperMain \
+        "$@"
+
+# Stop when "xargs" is not available.
+if ! command -v xargs >/dev/null 2>&1
+then
+    die "xargs is not available"
+fi
+
+# Use "xargs" to parse quoted args.
+#
+# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
+#
+# In Bash we could simply go:
+#
+#   readarray ARGS < <( xargs -n1 <<<"$var" ) &&
+#   set -- "${ARGS[@]}" "$@"
+#
+# but POSIX shell has neither arrays nor command substitution, so instead we
+# post-process each arg (as a line of input to sed) to backslash-escape any
+# character that might be a shell metacharacter, then use eval to reverse
+# that process (while maintaining the separation between arguments), and wrap
+# the whole thing up as a single "set" statement.
+#
+# This will of course break if any of these variables contains a newline or
+# an unmatched quote.
+#
+
+eval "set -- $(
+        printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |
+        xargs -n1 |
+        sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' |
+        tr '\n' ' '
+    )" '"$@"'
+
+exec "$JAVACMD" "$@"
@@ -0,0 +1,94 @@
+@rem
+@rem Copyright 2015 the original author or authors.
+@rem
+@rem Licensed under the Apache License, Version 2.0 (the "License");
+@rem you may not use this file except in compliance with the License.
+@rem You may obtain a copy of the License at
+@rem
+@rem      https://www.apache.org/licenses/LICENSE-2.0
+@rem
+@rem Unless required by applicable law or agreed to in writing, software
+@rem distributed under the License is distributed on an "AS IS" BASIS,
+@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+@rem See the License for the specific language governing permissions and
+@rem limitations under the License.
+@rem
+@rem SPDX-License-Identifier: Apache-2.0
+@rem
+
+@if "%DEBUG%"=="" @echo off
+@rem ##########################################################################
+@rem
+@rem  Gradle startup script for Windows
+@rem
+@rem ##########################################################################
+
+@rem Set local scope for the variables with windows NT shell
+if "%OS%"=="Windows_NT" setlocal
+
+set DIRNAME=%~dp0
+if "%DIRNAME%"=="" set DIRNAME=.
+@rem This is normally unused
+set APP_BASE_NAME=%~n0
+set APP_HOME=%DIRNAME%
+
+@rem Resolve any "." and ".." in APP_HOME to make it shorter.
+for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
+
+@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+set DEFAULT_JVM_OPTS=-Dfile.encoding=UTF-8 "-Xmx64m" "-Xms64m"
+
+@rem Find java.exe
+if defined JAVA_HOME goto findJavaFromJavaHome
+
+set JAVA_EXE=java.exe
+%JAVA_EXE% -version >NUL 2>&1
+if %ERRORLEVEL% equ 0 goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:findJavaFromJavaHome
+set JAVA_HOME=%JAVA_HOME:"=%
+set JAVA_EXE=%JAVA_HOME%/bin/java.exe
+
+if exist "%JAVA_EXE%" goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:execute
+@rem Setup the command line
+
+set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
+
+
+@rem Execute Gradle
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
+
+:end
+@rem End local scope for the variables with windows NT shell
+if %ERRORLEVEL% equ 0 goto mainEnd
+
+:fail
+rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
+rem the _cmd.exe /c_ return code!
+set EXIT_CODE=%ERRORLEVEL%
+if %EXIT_CODE% equ 0 set EXIT_CODE=1
+if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
+exit /b %EXIT_CODE%
+
+:mainEnd
+if "%OS%"=="Windows_NT" endlocal
+
+:omega
@@ -0,0 +1,32 @@
+// Loader assumed to be NeoForge (see root plan's Open Assumptions — confirm the actual 26.1.x
+// loader ecosystem before Phase 10). Uses the modern ModDevGradle plugin; requires a recent JDK
+// (21+) unlike the two legacy leaves.
+
+plugins {
+    id 'net.neoforged.moddev' version '2.0.+'
+}
+
+sourceCompatibility = targetCompatibility = JavaVersion.VERSION_21
+
+sourceSets {
+    main {
+        java {
+            srcDir '../common/src/main/java'
+        }
+    }
+}
+
+neoForge {
+    version = project.neoforge_26_1_version
+
+    runs {
+        client {}
+        server {}
+    }
+
+    mods {
+        mcmapper {
+            sourceSet sourceSets.main
+        }
+    }
+}
@@ -0,0 +1,21 @@
+package com.octoturge.mcmapper.neoforge261;
+
+import net.neoforged.bus.api.IEventBus;
+import net.neoforged.fml.common.Mod;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Entry point for the 26.1.2 leaf — lowest MVP priority (Phase 10), stubbed structurally now.
+ * Loader assumed NeoForge; see root plan's Open Assumptions for the verification note.
+ */
+@Mod(MCMapperMod.MOD_ID)
+public class MCMapperMod {
+    public static final String MOD_ID = "mcmapper";
+
+    private static final Logger LOGGER = LoggerFactory.getLogger(MCMapperMod.class);
+
+    public MCMapperMod(IEventBus modEventBus) {
+        LOGGER.info("MCMapper (neoforge-26_1 leaf) scaffolding loaded — no-op until Phase 10");
+    }
+}
@@ -0,0 +1,17 @@
+modLoader = "javafml"
+loaderVersion = "[1,)"
+license = "MIT"
+
+[[mods]]
+modId = "mcmapper"
+version = "${file.jarVersion}"
+displayName = "MCMapper"
+description = "Thin delta-streaming client for the MCMapper web map backend."
+authors = "Octoturge"
+
+[[dependencies.mcmapper]]
+    modId = "neoforge"
+    type = "required"
+    versionRange = "[26.1,)"
+    ordering = "NONE"
+    side = "BOTH"
@@ -0,0 +1,24 @@
+pluginManagement {
+    repositories {
+        gradlePluginPortal()
+        maven { url = 'https://maven.minecraftforge.net/' }
+        maven { url = 'https://maven.neoforged.net/releases' }
+        mavenCentral()
+    }
+}
+
+rootProject.name = 'mcmapper-mod'
+
+// `common` is not a buildable Gradle subproject — it's shared source, pulled directly into
+// each leaf's own source set (see common/README.md for why).
+include 'forge-1_7_10'
+include 'forge-1_12_2'
+
+// neoforge-26_1 is intentionally NOT included in the default build: both legacy leaves
+// (forge-1_7_10, forge-1_12_2) use anatawa12's ForgeGradle 1.2/2.3 forks, which need Gradle 7.6
+// and JDK 8 (see gradle.properties' org.gradle.java.home pin and this project's
+// gradle-wrapper.properties). ModDevGradle (used by neoforge-26_1) needs Gradle 8+ and JDK 17+
+// to even apply the plugin — incompatible with that daemon within one invocation. Until Phase 10
+// gives it a proper isolated build setup, it can only be built by pointing org.gradle.java.home
+// at a JDK 21+ install and invoking Gradle (8+) from inside the neoforge-26_1/ directory
+// directly, with its own wrapper. The module itself is fully scaffolded and ready.