Developing Goanna

This section is for people who build, change or test Goanna. The repository holds a Godot project in project/, a C++ GDExtension in src/, Luanti client code carried across from the luanti/ submodule, and the optional server mod in goanna_server_mod/. The luanti/, godot-cpp/ and whisper.cpp/ directories are submodules.

Start here

• Building and running: dependencies, the build, running against a server, the environment variables and release checks.
• Contributing: the relationship to Luanti, licensing, code style, commits and how work lands. Read it before your first change.
• Text style: Australian English, no em dashes, and the check that enforces it.
• Transplanting Luanti code: how Luanti's code is carried, and the inventory of copied files.
• Architecture: how the pieces fit: the threads, the layers in src/, the GDScript project, and where to start a change.
• The Godot project: what each folder under project/ holds, and how to move a script without breaking it.

Testing and measuring

• Testing: native tests, headless Godot checks and the container checks.
• Launch target: the acceptance checklist for a fresh install and a release.
• Formspec conformance and shader pack testing.
• Benchmarking graphics settings and the rendering baseline.

Materials and assets

• PBR authoring playbook: how the authored material maps are made.
• Community PBR review: the licence gate and acceptance for community packs.
• Asset bundles: how material maps are versioned, published and installed.

How the running client works is described subsystem by subsystem under systems, and plans under design. Coding agents start from AGENTS.md and the agents section.

Architecture in brief

Goanna keeps Luanti's networking, protocol, world state, movement prediction, node definitions, inventory and meshing rules. Godot provides the window, scene tree, renderer, materials, lighting, models, UI and input. The boundary is deliberately narrow so Luanti releases can be tracked without maintaining a second game engine.

The client has three important rendering paths:

1. Near terrain: full block meshes assembled into regional batches.
2. Far terrain: persistent block data and derived LOD chains, server summaries, occlusion and coarser regional meshes.
3. Presentation: Godot environment, sky, atmosphere, materials, entities, particles and optional Iris screen-space effects.

Background meshing consumes immutable snapshots. Render-thread objects are replaced only after a completed mesh is ready, so a detail transition should not remove the old surface before its replacement exists.

Contribution rules

Keep changes at the narrowest layer that can solve them. Preserve upstream copyright headers in transplanted code, document intentional deviations, and add a focused test or visual fixture for behaviour that can regress. Avoid recording dates, private debugging conversations or one-off measurements in the system description; put reproducible measurements in validation notes.