Home

Welcome to the Falco wiki! Falco is a high-performance Anvil chunk loader and light engine for Minestom, plus an Instance implementation that cleans up after itself. The repository README covers what the project is and how to add it to a build; everything below is the long-form documentation that used to live in the repository as Markdown files.

Getting started

• Anvil Chunk Loader — what the loader does, how to use it, and what it deliberately does not do.
• Light Engine — the engine, its guarantees and its limits.
• Benchmarking — headline results, how to run the JMH suite, and what each benchmark measures.
• Project Status — the state of the project: test counts, environment, decisions, the full measured numbers, defects found and fixed, and what is still open.

Background: rationale

Why Falco is built the way it is, not just what it does. Written for someone deciding whether to trust the code, and for whoever re-opens one of these questions later:

• Rationale — overview and how to read the other five pages.
• Rationale: Chunk Loading
• Rationale: Lighting
• Rationale: Instances and Chunks
• Rationale: Concurrency
• Rationale: Measurement

Background: research

Findings from the multi-agent investigations run while building the experimental Anvil chunk loader and the instance, kept because each answers a question that will be asked again:

• Research — overview and the recurring lesson across all four investigations.
• Research: Exception Hierarchy
• Research: Instance Container
• Research: Light Engine
• Research: Shared Instances and Batches
• Instance Performance Research — where a speed advantage for falco-instance could plausibly exist, what stands in the way, and what would have to be measured first.

Gradle build

The rationale behind Falco's Gradle build setup — why things are structured the way they are, not just what the build files contain:

• Build Setup — module structure, why the root project has no sources, why falco-bom is excluded from the standard java-library configuration and how it gets java-platform instead.
• Versioning and Releases — the single line Release Please rewrites, and how snapshot versions are derived from it.
• Dependency Management — why repositories live only in settings.gradle.kts, notable version catalog entries, and why Minestom, fastutil and adventure-nbt are compileOnly.
• Publishing — how the four published modules share one repository configuration, and why falco-bom publishes differently from the three library modules.
• Testing and Javadoc — the -Werror doclint policy and the test heap size needed for the chunk loader tests.
• Benchmarks and Demo — what falco-benchmarks and falco-demo are for, and why neither is ever published from a build perspective. For what the benchmarks measure and how to run them, see Benchmarking.