Home

Falco

Falco is a high-performance Anvil chunk loader and light engine for Minestom, plus an Instance implementation that cleans up after itself and a migration engine for worlds older than the server you run. Four modules, no dependency between them, all opt-in.

The repository README says what the project is and carries a five-step quick start. Everything below is the documentation.

---

New here? Tutorial Load your first world with Falco takes you from an empty Gradle project to a server serving a stored world with working light, in about fifteen minutes.

Trying to get something done? The how-to guides cover adding Falco to a build, loading a world, computing light, migrating an old world and running the benchmarks.

Looking up a value? Reference Modules and coordinates for artefacts and endpoints, Reference Supported versions for the floors, Reference Measured results for every published table, Reference Exceptions and faults for what a failure means.

Wondering how it works, or why? Explanation Choosing between Falco and the built-in loader and Explanation Scope and non-goals are the two pages most people need first.

---

Getting started

• Tutorial Load your first world with Falco — the one guided path through the project.

How-to guides

Setting up

• How-to Add Falco to your build
• How-to Build Falco from source

Loading worlds

• How-to Load an Anvil world
• How-to Migrate a world from an older version
• How-to Replace the version and unknown-entry policies

Light

• How-to Compute light for a loaded world
• How-to Keep chunk light up to date automatically

Instances

• How-to Use FalcoInstance instead of InstanceContainer

Measuring

• How-to Run the JMH benchmark suite
• How-to Reproduce a published measurement

Reference

• Reference Modules and coordinates — artefacts, repositories, Javadoc addresses
• Reference Supported versions — Java, Minestom, the chunk version floor, compression schemes
• Reference API surface and stability — what is experimental and what that means
• Reference Replaceable policies — the three services and their resolution rules
• Reference Migration modes — the modes, their cost, and the backup
• Reference Exceptions and faults — the exception types and what each entry point does on failure
• Reference Logging — loggers, levels, message schema, throttling
• Reference Measured results — every published table, with the run behind each one
• Reference Benchmark catalogue — every benchmark class and its parameters

Reference Measured results owns every figure quoted anywhere in this wiki. Where a table disagrees with anything printed outside it, the table wins.

Background

Deciding whether to adopt

• Explanation Choosing between Falco and the built-in loader
• Explanation Choosing between FalcoInstance and InstanceContainer
• Explanation When light computation actually runs — for most Falco workloads, it does not
• Explanation Scope and non-goals — what Falco deliberately does not do

How it works

• Explanation How the Anvil loader is built
• Explanation How the light engine works
• Explanation How the concurrency design works
• Explanation How world migration works
• Explanation The chunk version guard

Why it is built this way

• Explanation Why a second Anvil loader
• Explanation Why a custom light engine
• Explanation Why falco-instance exists
• Explanation Comparing the light engine with Minestoms

What the numbers mean

• Explanation What a measurement here means — the one definition of what the ± covers
• Explanation What the benchmarks establish

Project record

Not documentation of the software — the record of building it. Kept because each answers a question that will be asked again.

• Project Status — what is in the branch, the defects found and fixed, what is still open, and what was investigated and deliberately not built
• Research — the index of the investigations
• Documentation conventions — how this wiki is organised and which page owns which fact

Working on Falco

• Contributing — what a change is built, tested and released with
• Build Setup — module structure and why falco-bom is special-cased
• Versioning and Releases · Dependency Management · Publishing
• Testing and Javadoc · Benchmarks and Demo · Architecture Rules