Skip to content

Latest commit

 

History

History
83 lines (62 loc) · 3.4 KB

CONTRIBUTING.md

File metadata and controls

83 lines (62 loc) · 3.4 KB

Contributing Guide

Prerequisites

  • Java 25 — Uses Preview/Finalized features: Scoped Values, Structured Concurrency, Panama FFI (Foreign Function & Memory API)
  • Maven 4.x — Build system

Technical Principles

Prefer Java 25 high-performance features over legacy APIs:

Scenario Use Avoid
Thread-local state ScopedValue ThreadLocal
Native function calls Panama FFI (Linker, Arena, FunctionDescriptor) JNI, JNA
Memory management Arena.ofShared() / scoped arena sun.misc.Unsafe, ByteBuffer.allocateDirect
Type-safe method refs MethodHandle.invokeExact() Method.invoke()
Immutable data record Hand-written POJOs
Pattern matching switch patterns, instanceof patterns Cascading if-else + casts
String templates String templates (when available) String concatenation
Lightweight concurrency Virtual Threads Platform threads, ExecutorService
Structured concurrency StructuredTaskScope CompletableFuture
Null safety Optional Raw null returns
Sealed hierarchies sealed classes Open class hierarchies
Local variable inference var Redundant type declarations
Multi-line strings Text blocks (""") + concatenation

Architecture Constraints

Zero Runtime Reflection

Runtime reflection is prohibited in godot-java-core/src/main/java/. Type and annotation discovery must happen at compile time through the APT processor.

Prohibited patterns:

Pattern Replacement
Class.forName(dynamic string) APT-generated static Map lookup
setAccessible(true) Protected accessors or APT-generated lambdas
Method.invoke() MethodHandle.invokeExact(), dispatch code generated by APT
Field.get/set on private fields Protected accessors or APT-generated VarHandle
Runtime getDeclaredMethods/Fields() APT compile-time scanning, results written to generated code
Runtime getAnnotation() APT compile-time reading, results written to generated code
privateLookupIn() + findConstructor() GodotClassRegistry.create()

Exception: The APT processor (org.godot.processor.*) and code generator may use reflection — they only run at compile time.

Rationale: GraalVM native image compatibility + performance (Method.invoke is 10-100x slower than MethodHandle.invokeExact).

Documentation Comments Must Use Markdown

All documentation comments (Javadoc) must use Java 23's Markdown format with /// markers instead of traditional /** */ Javadoc. This enables the register-docs feature to convert Markdown directly to Godot BBCode documentation.

/// Calculates the damage based on attack type.
///
/// GDScript can override this method to provide custom damage
/// calculations. If not overridden, returns a default value.
@GodotMethod(virtual = true)
public int calculateDamage(int attackType) {
    return 10;
}

Build Commands

# Build framework (skip tests and spotbugs)
mvn install -DskipTests -Dspotbugs.skip=true

# Build demo project
cd godot-java-3d-demo && mvn package -DskipTests

# Run demo
/Applications/Godot.app/Contents/MacOS/Godot --debug --path godot-java-3d-demo

Code Style

  • Code comments in English only
  • No Co-Authored-By commit tags
  • All Java→Godot calls through Panama FFI Bridge, no JNI helpers
  • Do not push to remote repository unless explicitly requested