Home

Falco

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.

Using Falco

• 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.

The runnable examples are in Anvil Chunk Loader and Light Engine, both under Usage; which workloads run light computation at all, and which never reach the engine, is settled by the table under When this is worth using; and the Minestom version behind the <version> placeholder in the README's quick start is recorded in Project Status under Environment.

The measured record

• 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 — why a second Anvil loader exists at all, why a failed read throws instead of reporting the chunk as absent, and where the built-in loader remains the better tool.
• Rationale: Lighting — why falco-light exists given that Minestom computes light and Starlight and Phosphor exist, and which of the usual arguments did not survive being checked.
• Rationale: Instances and Chunks — why falco-instance exists although it claims no speed advantage, and the chunk leak that is the whole argument for it.
• Rationale: Concurrency — why the region files are guarded by a per-entry seqlock and a hard refusal after close() rather than by the locks a reviewer would reach for first.
• Rationale: Measurement — why someone who did not run the benchmarks should believe them, and which numbers are thin.

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.
• Research: Fluent API — whether the three modules should get a fluent construction surface, what shape it would take, and the blocker that stopped the three from being combined. Kept as the record of the investigation, with the three places marked where the implementation departed from it; for what can be called, see the pages above.

Working on the 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.
• Architecture Rules — what falco-archunit enforces, why the module sees only main sources, and which invariants it deliberately cannot check.

The command lines themselves live elsewhere: Installation under Building from source carries the build invocation and the credentials it needs, Project Status under Working on this the everyday Gradle invocations including the benchmark jar, and Testing and Javadoc under Reproducing a test run what check adds to test in each module.

Everything above is the long-form documentation. The four-step quick start that precedes it is in the repository README.