- Java 25 — Uses Preview/Finalized features: Scoped Values, Structured Concurrency, Panama FFI (Foreign Function & Memory API)
- Maven 4.x — Build system
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 |
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).
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 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 comments in English only
- No
Co-Authored-Bycommit tags - All Java→Godot calls through Panama FFI Bridge, no JNI helpers
- Do not push to remote repository unless explicitly requested