M0: scaffold bnstoolkit mod (NeoForge 1.21.1)

Empty mod that loads cleanly on client + dedicated server. Sets up the
package layout and milestone TODOs for the BNS in-game UI work.

- uk.sijbers.bnstoolkit.{BnsToolkit, BnsToolkitClient} mod entries
- 5 placeholder screens extending a shared BaseBnsScreen
  (TierUpgrade, BountyBoard, QuestLog, PlotPurchase, ShopBrowser)
- 3 key bindings (T/B/P) registered, handlers TODO M1+
- SpurHud overlay placeholder for M4
- Network: payload registrar + one smoke-test C2S/S2C pair
  (RequestTierState / TierStateUpdate)
- en_us.json for screen + keybind labels
- neoforge.mods.toml pinned to neo_version 21.1.228 (live server match)

Build verified: ./gradlew build -> bnstoolkit-0.1.0.jar (15.6 KB).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.gitattributes

@@ -0,0 +1,5 @@
+# Disable autocrlf on generated files, they always generate with LF
+# Add any extra files or paths here to make git stop saying they
+# are changed when only line endings change.
+src/generated/**/.cache/* text eol=lf
+src/generated/**/*.json text eol=lf

.github/workflows/build.yml

@@ -0,0 +1,25 @@
+name: Build
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Setup JDK 21
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Build with Gradle
+        run: ./gradlew build

.gitignore

@@ -0,0 +1,40 @@
+### Gradle ###
+.gradle
+build/
+!gradle/wrapper/gradle-wrapper.jar
+!**/src/**/build/
+
+### IntelliJ IDEA ###
+.idea/
+*.iws
+*.iml
+*.ipr
+out/
+!**/src/**/out/
+
+.run/
+
+### Eclipse ###
+.apt_generated
+.classpath
+.eclipse/
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+bin/
+!**/src/**/bin/
+
+### VS Code ###
+.vscode/
+
+### Mac OS ###
+.DS_Store
+
+### Minecraft Modding ###
+run/
+!**/src/**/run/
+**/src/generated/**/.cache/
+repo/
+!**/src/**/repo/

README.md

@@ -0,0 +1,61 @@
+# bnstoolkit
+
+Companion mod for the Brass and Sigil modpack. NeoForge 1.21.1.
+
+Provides the in-game UI surface for the KubeJS-driven civic tier, bounty,
+plot, and shop systems. Pure client visuals + a thin C2S/S2C network
+bridge over the existing server-side state — no server-side gameplay
+logic lives here, just transport and presentation.
+
+## Status
+
+M0 — scaffold only. Loads cleanly on client and dedicated server. No
+screens are open-able yet (key bindings register but their handlers are
+TODO). One network round-trip pair is wired as a smoke test.
+
+See `docs/bnstoolkit-architecture.md` in the brass-and-sigil repo for
+the full spec.
+
+## Building
+
+```
+./gradlew build
+```
+
+The output jar lands in `build/libs/bnstoolkit-<version>.jar`. Drop it
+into the modpack's `pack/overrides/mods/` directory.
+
+## Package layout
+
+```
+uk.sijbers.bnstoolkit
+├── BnsToolkit                   # common mod entry
+├── BnsToolkitClient             # client mod entry
+├── client
+│   ├── BnsKeyBindings           # T / B / P defaults
+│   ├── hud
+│   │   └── SpurHud              # spurs + tier overlay
+│   └── screens
+│       ├── BaseBnsScreen        # shared parent (will swap to FTB Library)
+│       ├── TierUpgradeScreen
+│       ├── BountyBoardScreen
+│       ├── QuestLogScreen
+│       ├── PlotPurchaseScreen
+│       └── ShopBrowserScreen
+└── network
+    ├── BnsNetwork               # payload registrar
+    ├── c2s
+    │   └── RequestTierStatePacket
+    └── s2c
+        └── TierStateUpdatePacket
+```
+
+## Milestones
+
+| Milestone | Scope |
+|---|---|
+| M0 (now) | Scaffold, keybinds, network smoke-test packet pair |
+| M1 | Tier upgrade screen + KubeJS bridge for tier/balance |
+| M2 | Quest log + shop browser screens |
+| M3 | Bounty board + plot purchase screens |
+| M4 | HUD overlay, mod settings screen, FTB Library swap |

build.gradle

@@ -0,0 +1,134 @@
+plugins {
+    id 'java-library'
+    id 'maven-publish'
+    id 'net.neoforged.moddev' version '2.0.141'
+    id 'idea'
+}
+
+tasks.named('wrapper', Wrapper).configure {
+    distributionType = Wrapper.DistributionType.BIN
+}
+
+version = mod_version
+group = mod_group_id
+
+sourceSets.main.resources {
+    srcDir('src/generated/resources')
+    exclude("**/*.bbmodel")
+    exclude("src/generated/**/.cache")
+}
+
+repositories {
+    // FTB Library / FTB Chunks / FTB Quests live here. Used compileOnly
+    // when we wire screens to the FTB UI framework (M1+).
+    maven {
+        name = 'FTB'
+        url = 'https://maven.ftb.dev/releases'
+        content { includeGroup 'dev.ftb.mods' }
+    }
+    // Numismatics + Create dependencies live on Modrinth's maven mirror.
+    maven {
+        name = 'ModrinthMaven'
+        url = 'https://api.modrinth.com/maven'
+    }
+}
+
+base {
+    archivesName = mod_id
+}
+
+java.toolchain.languageVersion = JavaLanguageVersion.of(21)
+
+neoForge {
+    version = project.neo_version
+
+    parchment {
+        mappingsVersion = project.parchment_mappings_version
+        minecraftVersion = project.parchment_minecraft_version
+    }
+
+    runs {
+        client {
+            client()
+            systemProperty 'neoforge.enabledGameTestNamespaces', project.mod_id
+        }
+
+        server {
+            server()
+            programArgument '--nogui'
+            systemProperty 'neoforge.enabledGameTestNamespaces', project.mod_id
+        }
+
+        data {
+            data()
+            programArguments.addAll '--mod', project.mod_id, '--all', '--output', file('src/generated/resources/').getAbsolutePath(), '--existing', file('src/main/resources/').getAbsolutePath()
+        }
+
+        configureEach {
+            systemProperty 'forge.logging.markers', 'REGISTRIES'
+            logLevel = org.slf4j.event.Level.DEBUG
+        }
+    }
+
+    mods {
+        "${mod_id}" {
+            sourceSet(sourceSets.main)
+        }
+    }
+}
+
+configurations {
+    runtimeClasspath.extendsFrom localRuntime
+}
+
+dependencies {
+    // TODO(matt M1): wire FTB Library compileOnly dep when first FTB-UI screen lands.
+    // Candidate coord (verify version pinning against pack):
+    //   compileOnly "dev.ftb.mods:ftb-library-neoforge:2101.1.31"
+    //
+    // TODO(matt M2): Numismatics compileOnly dep for the shop block integration.
+    // Modrinth maven path: maven.modrinth/numismatics/<version>
+}
+
+var generateModMetadata = tasks.register("generateModMetadata", ProcessResources) {
+    var replaceProperties = [
+            minecraft_version      : minecraft_version,
+            minecraft_version_range: minecraft_version_range,
+            neo_version            : neo_version,
+            loader_version_range   : loader_version_range,
+            mod_id                 : mod_id,
+            mod_name               : mod_name,
+            mod_license            : mod_license,
+            mod_version            : mod_version,
+    ]
+    inputs.properties replaceProperties
+    expand replaceProperties
+    from "src/main/templates"
+    into "build/generated/sources/modMetadata"
+}
+sourceSets.main.resources.srcDir generateModMetadata
+neoForge.ideSyncTask generateModMetadata
+
+publishing {
+    publications {
+        register('mavenJava', MavenPublication) {
+            from components.java
+        }
+    }
+    repositories {
+        maven {
+            url "file://${project.projectDir}/repo"
+        }
+    }
+}
+
+tasks.withType(JavaCompile).configureEach {
+    options.encoding = 'UTF-8'
+}
+
+idea {
+    module {
+        downloadSources = true
+        downloadJavadoc = true
+    }
+}

gradle.properties

@@ -0,0 +1,23 @@
+# Sets default memory used for gradle commands. Can be overridden by user or command line properties.
+org.gradle.jvmargs=-Xmx2G
+org.gradle.daemon=true
+org.gradle.parallel=true
+org.gradle.caching=true
+org.gradle.configuration-cache=true
+
+# Parchment mappings (parameter names + javadocs)
+parchment_minecraft_version=1.21.1
+parchment_mappings_version=2024.11.17
+
+# Environment Properties — must match the live BNS server
+minecraft_version=1.21.1
+minecraft_version_range=[1.21.1]
+neo_version=21.1.228
+loader_version_range=[1,)
+
+## Mod Properties
+mod_id=bnstoolkit
+mod_name=Brass and Sigil Toolkit
+mod_license=All Rights Reserved
+mod_version=0.1.0
+mod_group_id=uk.sijbers.bnstoolkit

gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.2.1-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

gradlew

@@ -0,0 +1,251 @@
+#!/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\n' "$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="\\\"\\\""
+
+
+# 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='"-Xmx64m" "-Xms64m"'
+
+# Collect all arguments for the java command:
+#   * DEFAULT_JVM_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" \
+        -jar "$APP_HOME/gradle/wrapper/gradle-wrapper.jar" \
+        "$@"
+
+# 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" "$@"

gradlew.bat

@@ -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="-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=
+
+
+@rem Execute Gradle
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" -jar "%APP_HOME%\gradle\wrapper\gradle-wrapper.jar" %*
+
+: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

settings.gradle

@@ -0,0 +1,11 @@
+pluginManagement {
+    repositories {
+        gradlePluginPortal()
+    }
+}
+
+plugins {
+    id 'org.gradle.toolchains.foojay-resolver-convention' version '1.0.0'
+}
+
+rootProject.name = 'bnstoolkit'

src/main/java/uk/sijbers/bnstoolkit/BnsToolkit.java

@@ -0,0 +1,39 @@
+package uk.sijbers.bnstoolkit;
+
+import net.neoforged.bus.api.IEventBus;
+import net.neoforged.fml.common.Mod;
+import net.neoforged.fml.event.lifecycle.FMLCommonSetupEvent;
+import net.neoforged.neoforge.common.NeoForge;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import uk.sijbers.bnstoolkit.network.BnsNetwork;
+
+/**
+ * Brass and Sigil Toolkit — common (client+server) mod entry.
+ *
+ * Mod ID matches {@link #MOD_ID}. The matching value lives in
+ * gradle.properties (mod_id=bnstoolkit) and is interpolated into
+ * src/main/templates/META-INF/neoforge.mods.toml at build time.
+ *
+ * Scope (M0): empty scaffold. Registers no items, blocks, or screens yet.
+ * Just loads cleanly on client and dedicated server so the deploy pipeline
+ * works end-to-end before we start adding real surface area.
+ */
+@Mod(BnsToolkit.MOD_ID)
+public final class BnsToolkit {
+    public static final String MOD_ID = "bnstoolkit";
+    public static final Logger LOG = LoggerFactory.getLogger(MOD_ID);
+
+    public BnsToolkit(IEventBus modBus) {
+        LOG.info("[bnstoolkit] mod entry constructed");
+
+        BnsNetwork.register(modBus);
+
+        modBus.addListener(this::onCommonSetup);
+        NeoForge.EVENT_BUS.register(this);
+    }
+
+    private void onCommonSetup(final FMLCommonSetupEvent event) {
+        LOG.info("[bnstoolkit] common setup complete (M0 scaffold — no surface yet)");
+    }
+}

src/main/java/uk/sijbers/bnstoolkit/BnsToolkitClient.java

@@ -0,0 +1,30 @@
+package uk.sijbers.bnstoolkit;
+
+import net.neoforged.api.distmarker.Dist;
+import net.neoforged.bus.api.IEventBus;
+import net.neoforged.fml.common.Mod;
+import net.neoforged.fml.event.lifecycle.FMLClientSetupEvent;
+import uk.sijbers.bnstoolkit.client.BnsKeyBindings;
+
+/**
+ * Client-only mod entry. Hosts key bindings + screen registration so the
+ * dedicated server never loads them.
+ *
+ * Activated via the {@code dist = Dist.CLIENT} parameter on the @Mod
+ * annotation — NeoForge will skip this class entirely on the server side.
+ */
+@Mod(value = BnsToolkit.MOD_ID, dist = Dist.CLIENT)
+public final class BnsToolkitClient {
+
+    public BnsToolkitClient(IEventBus modBus) {
+        BnsToolkit.LOG.info("[bnstoolkit] client entry constructed");
+        modBus.addListener(this::onClientSetup);
+        modBus.addListener(BnsKeyBindings::onRegisterKeyMappings);
+    }
+
+    private void onClientSetup(final FMLClientSetupEvent event) {
+        // TODO(matt M1): register screens here when bnstoolkit ships its first GUI.
+        //   MenuScreens.register(BnsMenus.TIER_UPGRADE.get(), TierUpgradeScreen::new);
+        BnsToolkit.LOG.info("[bnstoolkit] client setup complete");
+    }
+}

src/main/java/uk/sijbers/bnstoolkit/client/BnsKeyBindings.java

@@ -0,0 +1,50 @@
+package uk.sijbers.bnstoolkit.client;
+
+import com.mojang.blaze3d.platform.InputConstants;
+import net.minecraft.client.KeyMapping;
+import net.neoforged.neoforge.client.event.RegisterKeyMappingsEvent;
+import net.neoforged.neoforge.client.settings.KeyConflictContext;
+import org.lwjgl.glfw.GLFW;
+import uk.sijbers.bnstoolkit.BnsToolkit;
+
+/**
+ * Key bindings for the toolkit screens. All keys are CLIENT-only and live
+ * under a "Brass and Sigil" category in the controls menu.
+ *
+ * Default assignments are placeholders — picked to avoid known FTB
+ * Library / FTB Chunks / Numismatics defaults. Players can rebind in the
+ * vanilla controls menu like any other mod.
+ *
+ * Wiring: each binding gets polled in a {@code ClientTickEvent} handler
+ * once the corresponding screen is implemented; M0 keeps them inert.
+ */
+public final class BnsKeyBindings {
+    private BnsKeyBindings() {}
+
+    private static final String CATEGORY = "key.category." + BnsToolkit.MOD_ID;
+
+    public static final KeyMapping OPEN_TIER = new KeyMapping(
+            "key." + BnsToolkit.MOD_ID + ".tier",
+            KeyConflictContext.IN_GAME,
+            InputConstants.Type.KEYSYM.getOrCreate(GLFW.GLFW_KEY_T),
+            CATEGORY);
+
+    public static final KeyMapping OPEN_BOUNTIES = new KeyMapping(
+            "key." + BnsToolkit.MOD_ID + ".bounties",
+            KeyConflictContext.IN_GAME,
+            InputConstants.Type.KEYSYM.getOrCreate(GLFW.GLFW_KEY_B),
+            CATEGORY);
+
+    public static final KeyMapping OPEN_PLOTS = new KeyMapping(
+            "key." + BnsToolkit.MOD_ID + ".plots",
+            KeyConflictContext.IN_GAME,
+            InputConstants.Type.KEYSYM.getOrCreate(GLFW.GLFW_KEY_P),
+            CATEGORY);
+
+    public static void onRegisterKeyMappings(RegisterKeyMappingsEvent event) {
+        event.register(OPEN_TIER);
+        event.register(OPEN_BOUNTIES);
+        event.register(OPEN_PLOTS);
+        BnsToolkit.LOG.info("[bnstoolkit] registered 3 key bindings under {}", CATEGORY);
+    }
+}

src/main/java/uk/sijbers/bnstoolkit/client/hud/SpurHud.java

@@ -0,0 +1,30 @@
+package uk.sijbers.bnstoolkit.client.hud;
+
+import net.minecraft.client.DeltaTracker;
+import net.minecraft.client.gui.GuiGraphics;
+
+/**
+ * Tiny on-screen overlay showing the player's spurs balance + civic tier.
+ *
+ * Spec ref: docs/bnstoolkit-architecture.md §4.6 (HUD overlay)
+ *
+ * TODO(matt M4): wire this up via {@code RegisterGuiLayersEvent} when the
+ * NeoForge gui-layer registration lands. The signature here matches the
+ * {@code LayeredDraw.Layer} contract (a render method taking GuiGraphics +
+ * DeltaTracker), so the eventual implementation only has to add the
+ * "implements" clause and the registration call.
+ *
+ * Position default: top-left, below buff icons. Player can disable in mod
+ * settings (no settings screen yet — comes with the FTB Library swap).
+ */
+public final class SpurHud {
+    public static final SpurHud INSTANCE = new SpurHud();
+
+    private SpurHud() {}
+
+    public void render(GuiGraphics graphics, DeltaTracker delta) {
+        // TODO(matt M4): draw "<tier-icon> <tier-name>   <spurs> spurs"
+        // Data source: client-side cache populated by S2C TierStateUpdate
+        // packets the server emits whenever balance or tier changes.
+    }
+}

src/main/java/uk/sijbers/bnstoolkit/client/screens/BaseBnsScreen.java

@@ -0,0 +1,37 @@
+package uk.sijbers.bnstoolkit.client.screens;
+
+import net.minecraft.client.gui.GuiGraphics;
+import net.minecraft.client.gui.screens.Screen;
+import net.minecraft.network.chat.Component;
+
+/**
+ * Shared base for all toolkit screens.
+ *
+ * TODO(matt M1): swap parent to {@code dev.ftb.mods.ftblibrary.ui.BaseScreen}
+ * once the FTB Library compileOnly dependency is wired in build.gradle. The
+ * vanilla {@link Screen} parent is a stand-in so M0 compiles without FTB
+ * Library on the classpath and we can ship a "loads cleanly" mod first.
+ *
+ * When the swap lands, each subclass moves from
+ *   {@code render(GuiGraphics, ...)}  ->  the FTB Lib panel/widget tree
+ * Visual styling (background tile, title bar, close button) comes for
+ * free from FTB Library, matching FTB Quests / FTB Chunks look-and-feel.
+ */
+public abstract class BaseBnsScreen extends Screen {
+    protected BaseBnsScreen(Component title) {
+        super(title);
+    }
+
+    @Override
+    public void render(GuiGraphics graphics, int mouseX, int mouseY, float partialTick) {
+        this.renderBackground(graphics, mouseX, mouseY, partialTick);
+        super.render(graphics, mouseX, mouseY, partialTick);
+        // Centred title — placeholder styling.
+        graphics.drawCenteredString(this.font, this.title, this.width / 2, 16, 0xFFFFFFFF);
+    }
+
+    @Override
+    public boolean isPauseScreen() {
+        return false;
+    }
+}

src/main/java/uk/sijbers/bnstoolkit/client/screens/BountyBoardScreen.java

@@ -0,0 +1,29 @@
+package uk.sijbers.bnstoolkit.client.screens;
+
+import net.minecraft.network.chat.Component;
+
+/**
+ * Bounty board screen — replaces /bns bounty list / accept / turnin.
+ *
+ * Spec ref: docs/bnstoolkit-architecture.md §4.3 (BountyBoardScreen)
+ *
+ * TODO(matt M3): Layout to confirm tomorrow:
+ *   - Left pane: list of 5 available bounties for today (refreshes every 24h
+ *     server-side; the screen just renders what the server sent)
+ *   - Right pane: detail for the highlighted bounty — target entity, count,
+ *     payout, state (AVAILABLE / ACTIVE / READY / COOLDOWN)
+ *   - Bottom row: ACCEPT / CANCEL / TURN IN buttons (enable based on state)
+ *   - Slot indicator: "Active bounties: 2/5" using the player's tier cap
+ *
+ * Two C2S packets drive it:
+ *   - RequestBountyList (board open / refresh)
+ *   - RequestBountyAction (accept | cancel | turnin)
+ * One S2C: BountyBoardSnapshot.
+ */
+public final class BountyBoardScreen extends BaseBnsScreen {
+    public BountyBoardScreen() {
+        super(Component.translatable("screen.bnstoolkit.bounty_board"));
+    }
+
+    // TODO(matt M3): init() + widgets
+}

src/main/java/uk/sijbers/bnstoolkit/client/screens/PlotPurchaseScreen.java

@@ -0,0 +1,32 @@
+package uk.sijbers.bnstoolkit.client.screens;
+
+import net.minecraft.network.chat.Component;
+
+/**
+ * Plot purchase + management screen — replaces /bns plot list / buy / release.
+ *
+ * Spec ref: docs/bnstoolkit-architecture.md §4.4 (PlotPurchaseScreen)
+ *
+ * TODO(matt M3): Layout to confirm tomorrow:
+ *   - Top-down minimap of the spawn plot region, plots coloured by state
+ *     (OWN / AVAILABLE / TAKEN_BY_OTHER), hover for owner + price
+ *   - Right pane: highlighted plot details — id, chunk bounds, price,
+ *     owner, release refund preview
+ *   - Bottom: BUY / RELEASE buttons (price + refund displayed inline)
+ *   - Slot indicator: "Plots owned: 1/2" using the player's tier cap
+ *
+ * Two C2S packets:
+ *   - RequestPlotMap (open / refresh)
+ *   - RequestPlotAction (buy | release, with plot id)
+ * One S2C: PlotMapSnapshot.
+ *
+ * Open trigger options (decide tomorrow): keybind P, an in-game block at
+ * the spawn building, or both. Both is easy — they're not exclusive.
+ */
+public final class PlotPurchaseScreen extends BaseBnsScreen {
+    public PlotPurchaseScreen() {
+        super(Component.translatable("screen.bnstoolkit.plot_purchase"));
+    }
+
+    // TODO(matt M3): init() + map widget + action buttons
+}

src/main/java/uk/sijbers/bnstoolkit/client/screens/QuestLogScreen.java

@@ -0,0 +1,29 @@
+package uk.sijbers.bnstoolkit.client.screens;
+
+import net.minecraft.network.chat.Component;
+
+/**
+ * Quest log — the "What am I doing right now?" pane.
+ *
+ * Spec ref: docs/bnstoolkit-architecture.md §4.2 (QuestLogScreen)
+ *
+ * TODO(matt M2): Layout to confirm tomorrow:
+ *   - Tab bar at top: ACTIVE BOUNTIES | FTB QUESTS | PLOT TIMERS
+ *   - Active Bounties tab: same data as Bounty Board's right pane but
+ *     filtered to ACTIVE state, with kill-progress bars
+ *   - FTB Quests tab: read-only mirror of the player's current chapter,
+ *     showing in-progress quests + reward previews
+ *   - Plot Timers tab: list of owned plots with any pending refund/release
+ *     timers (when implemented)
+ *
+ * Refresh model: server pushes a QuestLogSnapshot whenever any tracked
+ * counter changes (kill count, quest reward, plot ownership). Screen re-
+ * renders from the latest snapshot.
+ */
+public final class QuestLogScreen extends BaseBnsScreen {
+    public QuestLogScreen() {
+        super(Component.translatable("screen.bnstoolkit.quest_log"));
+    }
+
+    // TODO(matt M2): init() + tab widgets
+}

src/main/java/uk/sijbers/bnstoolkit/client/screens/ShopBrowserScreen.java

@@ -0,0 +1,32 @@
+package uk.sijbers.bnstoolkit.client.screens;
+
+import net.minecraft.network.chat.Component;
+
+/**
+ * Bazaar shop browser — replaces /bns sell list / sell <item> [count].
+ *
+ * Spec ref: docs/bnstoolkit-architecture.md §4.5 (ShopBrowserScreen)
+ *
+ * TODO(matt M2): Layout to confirm tomorrow:
+ *   - Grid of sell-list items (9 in the current catalogue)
+ *   - Per cell: item icon, base price, effective price after DR + tier fee,
+ *     "you've sold X" counter
+ *   - Click cell -> count slider (1 / 16 / 64 / max-in-inventory) and SELL button
+ *   - Header: current spurs + effective fee%
+ *   - Future: BUY tab when buy-prices land (Phase 7 dynamic exchange)
+ *
+ * Two C2S packets:
+ *   - RequestShopCatalogue (open / refresh)
+ *   - RequestShopSell (item id, count)
+ * One S2C: ShopCatalogueSnapshot, plus per-sale ShopSellResult.
+ *
+ * Open trigger options: keybind, a Numismatics-style shop block at the
+ * Bazaar building, or both.
+ */
+public final class ShopBrowserScreen extends BaseBnsScreen {
+    public ShopBrowserScreen() {
+        super(Component.translatable("screen.bnstoolkit.shop_browser"));
+    }
+
+    // TODO(matt M2): init() + item grid + sell widget
+}

src/main/java/uk/sijbers/bnstoolkit/client/screens/TierUpgradeScreen.java

@@ -0,0 +1,28 @@
+package uk.sijbers.bnstoolkit.client.screens;
+
+import net.minecraft.network.chat.Component;
+
+/**
+ * Tier ladder + upgrade screen.
+ *
+ * Spec ref: docs/bnstoolkit-architecture.md §4.1 (TierUpgradeScreen)
+ *
+ * TODO(matt M1): Visual layout to confirm with you tomorrow:
+ *   - 13 rows, one per civic tier (Peasant -> Sovereign)
+ *   - Current tier row highlighted
+ *   - Each row: rank colour name, cost in spurs, perks summary
+ *     (chunks / plot-slots / bounty-slots / shop-fee)
+ *   - "Upgrade to <next>" button bottom-right (only enabled if affordable)
+ *   - Click pre-confirms cost + shows current balance, second click commits
+ *
+ * Backend wiring: button click sends a C2S RequestTierUpgrade packet.
+ * Server replies with TierUpgradeResult (success/failure + new tier + new
+ * balance). Same backend the /bns tier upgrade chat command already uses.
+ */
+public final class TierUpgradeScreen extends BaseBnsScreen {
+    public TierUpgradeScreen() {
+        super(Component.translatable("screen.bnstoolkit.tier_upgrade"));
+    }
+
+    // TODO(matt M1): override init() to lay out rows + button widgets.
+}

src/main/java/uk/sijbers/bnstoolkit/network/BnsNetwork.java

@@ -0,0 +1,53 @@
+package uk.sijbers.bnstoolkit.network;
+
+import net.neoforged.bus.api.IEventBus;
+import net.neoforged.neoforge.network.event.RegisterPayloadHandlersEvent;
+import net.neoforged.neoforge.network.registration.PayloadRegistrar;
+import uk.sijbers.bnstoolkit.BnsToolkit;
+import uk.sijbers.bnstoolkit.network.c2s.RequestTierStatePacket;
+import uk.sijbers.bnstoolkit.network.s2c.TierStateUpdatePacket;
+
+/**
+ * Central registration for the toolkit's S2C and C2S packets.
+ *
+ * Spec ref: docs/bnstoolkit-architecture.md §5 (network contract).
+ *
+ * M0 ships one round-trip pair as a smoke-test of the wiring:
+ *   - C2S {@link RequestTierStatePacket}   ("hey server, what's my tier+balance?")
+ *   - S2C {@link TierStateUpdatePacket}    (answer + future push channel)
+ *
+ * The rest of the contract (bounty / plot / shop / quest log) will land in
+ * M1..M4 — each milestone adds its own packet pair under the matching
+ * sub-package.
+ *
+ * Versioning: bumped via the version() call below whenever the wire format
+ * changes incompatibly. Same protocol pattern FTB uses.
+ */
+public final class BnsNetwork {
+    private BnsNetwork() {}
+
+    public static final String VERSION = "0.1";
+
+    public static void register(IEventBus modBus) {
+        modBus.addListener(BnsNetwork::onRegisterPayloads);
+    }
+
+    private static void onRegisterPayloads(RegisterPayloadHandlersEvent event) {
+        final PayloadRegistrar reg = event.registrar(BnsToolkit.MOD_ID).versioned(VERSION);
+
+        // C2S: request my current tier + balance.
+        reg.playToServer(
+                RequestTierStatePacket.TYPE,
+                RequestTierStatePacket.STREAM_CODEC,
+                RequestTierStatePacket::handle);
+
+        // S2C: server pushes tier + balance (either in response to a request
+        // or unsolicited when something changes).
+        reg.playToClient(
+                TierStateUpdatePacket.TYPE,
+                TierStateUpdatePacket.STREAM_CODEC,
+                TierStateUpdatePacket::handle);
+
+        BnsToolkit.LOG.info("[bnstoolkit/net] registered payloads v{}", VERSION);
+    }
+}

src/main/java/uk/sijbers/bnstoolkit/network/c2s/RequestTierStatePacket.java

@@ -0,0 +1,42 @@
+package uk.sijbers.bnstoolkit.network.c2s;
+
+import net.minecraft.network.RegistryFriendlyByteBuf;
+import net.minecraft.network.codec.StreamCodec;
+import net.minecraft.network.protocol.common.custom.CustomPacketPayload;
+import net.minecraft.resources.ResourceLocation;
+import net.neoforged.neoforge.network.handling.IPayloadContext;
+import uk.sijbers.bnstoolkit.BnsToolkit;
+
+/**
+ * Client -> server: "Send me my tier + balance."
+ *
+ * Empty payload (no fields). The server identifies the player from
+ * {@link IPayloadContext#player()}. The response is a S2C
+ * {@code TierStateUpdatePacket}.
+ *
+ * TODO(matt M1): once the KubeJS bridge ships, the handler will:
+ *   1. Read player.persistentData.bnsTier (the KubeJS-owned NBT)
+ *   2. Sum Numismatics coin slots into a spurs total
+ *   3. Send a TierStateUpdatePacket back to the same player
+ *
+ * For now the handler just logs the request — proves the wire works.
+ */
+public record RequestTierStatePacket() implements CustomPacketPayload {
+    public static final Type<RequestTierStatePacket> TYPE = new Type<>(
+            ResourceLocation.fromNamespaceAndPath(BnsToolkit.MOD_ID, "request_tier_state"));
+
+    public static final StreamCodec<RegistryFriendlyByteBuf, RequestTierStatePacket> STREAM_CODEC =
+            StreamCodec.unit(new RequestTierStatePacket());
+
+    @Override
+    public Type<? extends CustomPacketPayload> type() {
+        return TYPE;
+    }
+
+    public static void handle(RequestTierStatePacket pkt, IPayloadContext ctx) {
+        ctx.enqueueWork(() -> {
+            // TODO(matt M1): read NBT + Numismatics balance, reply with TierStateUpdatePacket
+            BnsToolkit.LOG.info("[bnstoolkit/net] RequestTierState from {}", ctx.player().getName().getString());
+        });
+    }
+}

src/main/java/uk/sijbers/bnstoolkit/network/s2c/TierStateUpdatePacket.java

@@ -0,0 +1,44 @@
+package uk.sijbers.bnstoolkit.network.s2c;
+
+import net.minecraft.network.RegistryFriendlyByteBuf;
+import net.minecraft.network.codec.ByteBufCodecs;
+import net.minecraft.network.codec.StreamCodec;
+import net.minecraft.network.protocol.common.custom.CustomPacketPayload;
+import net.minecraft.resources.ResourceLocation;
+import net.neoforged.neoforge.network.handling.IPayloadContext;
+import uk.sijbers.bnstoolkit.BnsToolkit;
+
+/**
+ * Server -> client: pushes the player's current civic tier (1..13) and
+ * spurs balance.
+ *
+ * Sent in response to {@code RequestTierStatePacket} AND unsolicited
+ * whenever either value changes server-side (so the HUD updates in real
+ * time without polling).
+ *
+ * TODO(matt M1): client handler will cache the values in a static slot
+ * read by {@link uk.sijbers.bnstoolkit.client.hud.SpurHud} and any open
+ * screen.
+ */
+public record TierStateUpdatePacket(int tier, long spurs) implements CustomPacketPayload {
+    public static final Type<TierStateUpdatePacket> TYPE = new Type<>(
+            ResourceLocation.fromNamespaceAndPath(BnsToolkit.MOD_ID, "tier_state_update"));
+
+    public static final StreamCodec<RegistryFriendlyByteBuf, TierStateUpdatePacket> STREAM_CODEC =
+            StreamCodec.composite(
+                    ByteBufCodecs.VAR_INT,  TierStateUpdatePacket::tier,
+                    ByteBufCodecs.VAR_LONG, TierStateUpdatePacket::spurs,
+                    TierStateUpdatePacket::new);
+
+    @Override
+    public Type<? extends CustomPacketPayload> type() {
+        return TYPE;
+    }
+
+    public static void handle(TierStateUpdatePacket pkt, IPayloadContext ctx) {
+        ctx.enqueueWork(() -> {
+            // TODO(matt M1): stash in a client-side state holder for HUD + screens.
+            BnsToolkit.LOG.debug("[bnstoolkit/net] TierStateUpdate tier={} spurs={}", pkt.tier, pkt.spurs);
+        });
+    }
+}

src/main/resources/assets/bnstoolkit/lang/en_us.json

@@ -0,0 +1,12 @@
+{
+  "key.category.bnstoolkit": "Brass and Sigil",
+  "key.bnstoolkit.tier": "Open Tier Ladder",
+  "key.bnstoolkit.bounties": "Open Bounty Board",
+  "key.bnstoolkit.plots": "Open Plot Map",
+
+  "screen.bnstoolkit.tier_upgrade": "Civic Tier",
+  "screen.bnstoolkit.bounty_board": "Bounty Board",
+  "screen.bnstoolkit.quest_log": "Quest Log",
+  "screen.bnstoolkit.plot_purchase": "Plots",
+  "screen.bnstoolkit.shop_browser": "Bazaar"
+}

src/main/resources/pack.mcmeta

@@ -0,0 +1,6 @@
+{
+  "pack": {
+    "description": "Brass and Sigil Toolkit resources",
+    "pack_format": 34
+  }
+}

src/main/templates/META-INF/neoforge.mods.toml

@@ -0,0 +1,30 @@
+modLoader="javafml"
+loaderVersion="${loader_version_range}"
+license="${mod_license}"
+issueTrackerURL="http://10.16.5.102:3000/minecraft/bnstoolkit/issues"
+
+[[mods]]
+modId="${mod_id}"
+version="${mod_version}"
+displayName="${mod_name}"
+authors="matt (sijbers.uk)"
+description='''
+Brass and Sigil Toolkit — companion mod for the BNS modpack. Provides
+in-game UI for the KubeJS-driven civic tier, bounty, plot, and shop
+systems. Pure client visuals + thin C2S/S2C bridge over the existing
+server-side state.
+'''
+
+[[dependencies.${mod_id}]]
+modId="neoforge"
+type="required"
+versionRange="[${neo_version},)"
+ordering="NONE"
+side="BOTH"
+
+[[dependencies.${mod_id}]]
+modId="minecraft"
+type="required"
+versionRange="${minecraft_version_range}"
+ordering="NONE"
+side="BOTH"