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 carries a four-step quick start; everything below is the long-form documentation that used to live in the repository as Markdown files.

Getting started

• Installation — the modules, the BOM, snapshots, Maven, the rendered Javadoc, and building from source.
• 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 — what each published table does and does not establish, how to run the JMH suite, and how a third party can re-perform any of it.
• Project Status — the state of the project: test counts, environment, decisions, the full measured numbers, defects found and fixed, and what is still open.

These two pages are the measured record. Every figure quoted anywhere else in this wiki belongs to a table on one of them, and where the two disagree with anything printed outside the wiki, the table wins. What the ± after a number means, and what it does not bound, is defined once in Rationale: Measurement.

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 of the five investigations and the recurring lesson across them.
• 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.