Development & Build Guide

Developer documentation

This page is for source contributors and toolchain work. Server operators should start with the platform selector. Build commands below are for local source trees; this wiki is not a source repository.

Current Dev/Test

1. VonixGuardian Build Architecture

VonixGuardian avoids runtime abstraction layers (such as Architectury Runtime) to keep artifacts lean and maintain classloader transparency. The project is organized into pure Java core and per-version loader glue:

core/                          Pure-Java engine (JDBC, queue, log, query parser,
                               rollback engine, config). Zero MC deps.
mc-<ver>/common/               Per-MC shared surface (NBT codecs, command tree,
                               event payload models). Mojmap.
mc-<ver>/{fabric,forge,neoforge}/  Thin loader glue (event subscriptions, mod entry,
                                   permission bridges).

Gradle Build Profiles

Because configuring multiple Fabric Loom versions simultaneously in a single Gradle daemon can trigger classloader conflicts, builds are partitioned into target profiles:

# 1. Run core JUnit tests (Pure Java)
./gradlew -PbuildProfile=coreonly :core:test

# 2. Build MC 1.18.2 (Fabric & Forge)
./gradlew -PbuildProfile=mc1182 :mc-1.18.2:fabric:build :mc-1.18.2:forge:build

# 3. Build MC 1.19.2 (Fabric & Forge)
./gradlew -PbuildProfile=mc1192 :mc-1.19.2:fabric:build :mc-1.19.2:forge:build

# 4. Build MC 1.20.1 (Fabric & Forge)
./gradlew -PbuildProfile=mc1201 :mc-1.20.1:fabric:build :mc-1.20.1:forge:build

# 5. Build MC 1.21.1 (Fabric & NeoForge)
./gradlew -PbuildProfile=mc1211 :mc-1.21.1:fabric:build :mc-1.21.1:neoforge:build

# 6. Build MC 26.1.2 (NeoForge with Java 25)
./gradlew -PbuildProfile=mc2612 :mc-26.1.2:neoforge:build

JarInJar Verification

Always verify that native SQLite binaries are preserved and that JDBC driver classes do not leak into the outer jar:

# Verify Fabric JarInJar structure
./gradlew -PbuildProfile=mc1211 :mc-1.21.1:fabric:verifyJarInJarPackaging

---

2. Vonix Server Utilities Build Architecture

VSU uses a multi-template Architectury repository layout, with an independent Gradle project for each Minecraft version lane:

• vonix_server_utils-1.18.2-fabric-forge-template/ (Java 17)
• vonix_server_utils-1.19.2-fabric-forge-template/ (Java 17)
• vonix_server_utils-1.20.1-fabric-forge-template/ (Java 17)
• vonix_server_utils-1.21.1-fabric-neoforgetemplate/ (Java 21)
• vonix_server_utils-26.1.2-neoforge-template/ (Java 25, standalone ModDevGradle)

Building an Individual Target

cd vonix_server_utils-1.21.1-fabric-neoforgetemplate
./gradlew --no-daemon :common:build :neoforge:build :fabric:build

Interactive Multi-Version Build Tool

To build all lanes with automated JDK switching:

python build-menu.py

Porting Workflow (port.py)

Code changes applied to common handlers in one template are synchronized across sibling templates using the repository’s internal port.py sync script, preserving loader adaptations.

---

3. Contribution & License Guidelines

Project	License Model	Contribution Requirements
VonixGuardian	MIT License	Open-source clean-room implementation. Inspired by CoreProtect and Ledger without copying GPL/proprietary code.
Vonix Server Utilities	All Rights Reserved (Vonix Network)	Proprietary repository line. Unmodified binary distribution permitted; source modifications require team review.

Quality & Safety Invariants

1. Never Commit Secrets: Sample configuration strings must always use placeholders ([REDACTED] or example.net). Never commit live database credentials or private operational keys.
2. Preserve JNI Symbols: Never shade or relocate org.sqlite or JDBC drivers.
3. Fail-Safe Hydration: All asynchronous database handlers must fail closed during server startup if database connectivity is impaired.