CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

TorchCS-MC is a crossplatform Minecraft server software built on top of the Vanilla Java Edition server. It extends the Vanilla base with Bedrock Edition features (blocks, elements, PVP system) and replaces performance-critical subsystems (redstone engine, chunk processing) with native C implementations via JNI.

Languages: Java (core server logic), C (native performance hotspots via JNI), C++ (tooling/wrappers), Python (build automation) Build systems: Gradle (Java), CMake (C/C++)

Build Commands

Java (Gradle)

./gradlew build          # Full build
./gradlew test           # Run all tests
./gradlew test --tests "com.torchcs.SomeTest"  # Run single test
./gradlew run            # Start the server

Native (CMake)

cmake -B build -S native/ -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
cmake --build build --target <target>   # Build specific target

Python automation

python scripts/<script>.py   # Run an automation script

Architecture

Java ↔ Native boundary (JNI)

Performance-critical subsystems are implemented in C and called from Java via JNI. The JNI layer is the most fragile part of the codebase — mismatched signatures between Java native declarations and C function names cause UnsatisfiedLinkError at runtime, not compile time.

Java native method declarations live in the relevant subsystem package (e.g., com.torchcs.redstone, com.torchcs.world.chunk)
Corresponding C implementations follow the JNI naming convention: Java_<package_underscored>_<ClassName>_<methodName>
Shared libraries produced by CMake must be on java.library.path at runtime

Subsystems

Subsystem	Language	Notes
Redstone engine	C (JNI)	Replaces Vanilla Java implementation
Chunk processing	C (JNI)	Loading, saving, generation hooks
Bedrock PVP system	Java	Ported Bedrock combat mechanics
Bedrock blocks/elements	Java	Added on top of Vanilla block registry
Networking / protocol	Java	Vanilla base, extended as needed

Crossplatform C/C++

No platform-specific APIs (#ifdef _WIN32 etc.) without an abstraction layer
CMake targets must compile on Linux, Windows, and macOS
Use CMake's target_compile_features and avoid compiler-specific extensions

Python scripts

Automation scripts live in scripts/. They handle tasks such as build orchestration, code generation, or asset processing — not runtime server logic.

2.6 KiB Raw Permalink Blame History