> For the complete documentation index, see [llms.txt](https://docs.onelitefeather.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onelitefeather.net/falco/readme.md). # Falco Falco is a high-performance Anvil chunk loader and light engine for [Minestom](https://github.com/Minestom/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](https://github.com/OneLiteFeatherNET/Falco#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](/falco/tutorials/load-your-first-world-with-falco.md) 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](/falco/reference/modules-and-coordinates.md) for artefacts and endpoints, [Reference Supported versions](/falco/reference/supported-versions.md) for the floors, [Reference Measured results](/falco/reference/measured-results.md) for every published table, [Reference Exceptions and faults](/falco/reference/exceptions-and-faults.md) for what a failure means. **Wondering how it works, or why?** [Explanation Choosing between Falco and the built-in loader](/falco/explanation/choosing-between-falco-and-the-built-in-loader.md) and [Explanation Scope and non-goals](/falco/explanation/scope-and-non-goals.md) are the two pages most people need first. *** ## Getting started * [Tutorial Load your first world with Falco](/falco/tutorials/load-your-first-world-with-falco.md) — the one guided path through the project. ## How-to guides **Setting up** * [How-to Add Falco to your build](/falco/how-to-guides/add-falco-to-your-build.md) * [How-to Build Falco from source](/falco/how-to-guides/build-falco-from-source.md) **Loading worlds** * [How-to Load an Anvil world](/falco/how-to-guides/load-an-anvil-world.md) * [How-to Migrate a world from an older version](/falco/how-to-guides/migrate-a-world-from-an-older-version.md) * [How-to Replace the version and unknown-entry policies](/falco/how-to-guides/replace-the-version-and-unknown-entry-policies.md) **Light** * [How-to Compute light for a loaded world](/falco/how-to-guides/compute-light-for-a-loaded-world.md) * [How-to Keep chunk light up to date automatically](/falco/how-to-guides/keep-chunk-light-up-to-date-automatically.md) **Instances** * [How-to Use FalcoInstance instead of InstanceContainer](/falco/how-to-guides/use-falcoinstance-instead-of-instancecontainer.md) **Measuring** * [How-to Run the JMH benchmark suite](/falco/how-to-guides/run-the-jmh-benchmark-suite.md) * [How-to Reproduce a published measurement](/falco/how-to-guides/reproduce-a-published-measurement.md) ## Reference * [Reference Modules and coordinates](/falco/reference/modules-and-coordinates.md) — artefacts, repositories, Javadoc addresses * [Reference Supported versions](/falco/reference/supported-versions.md) — Java, Minestom, the chunk version floor, compression schemes * [Reference API surface and stability](/falco/reference/api-surface-and-stability.md) — what is experimental and what that means * [Reference Replaceable policies](/falco/reference/replaceable-policies.md) — the three services and their resolution rules * [Reference Migration modes](/falco/reference/migration-modes.md) — the modes, their cost, and the backup * [Reference Exceptions and faults](/falco/reference/exceptions-and-faults.md) — the exception types and what each entry point does on failure * [Reference Logging](/falco/reference/logging.md) — loggers, levels, message schema, throttling * [Reference Measured results](/falco/reference/measured-results.md) — **every published table, with the run behind each one** * [Reference Benchmark catalogue](/falco/reference/benchmark-catalogue.md) — every benchmark class and its parameters [**Reference Measured results**](/falco/reference/measured-results.md) **owns every figure quoted anywhere in this documentation.** 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](/falco/explanation/choosing-between-falco-and-the-built-in-loader.md) * [Explanation Choosing between FalcoInstance and InstanceContainer](/falco/explanation/choosing-between-falcoinstance-and-instancecontainer.md) * [Explanation When light computation actually runs](/falco/explanation/when-light-computation-actually-runs.md) — for most Falco workloads, it does not * [Explanation Scope and non-goals](/falco/explanation/scope-and-non-goals.md) — what Falco deliberately does not do **How it works** * [Explanation How the Anvil loader is built](/falco/explanation/how-the-anvil-loader-is-built.md) * [Explanation How the light engine works](/falco/explanation/how-the-light-engine-works.md) * [Explanation How the concurrency design works](/falco/explanation/how-the-concurrency-design-works.md) * [Explanation How world migration works](/falco/explanation/how-world-migration-works.md) * [Explanation The chunk version guard](/falco/explanation/the-chunk-version-guard.md) **Why it is built this way** * [Explanation Why a second Anvil loader](/falco/explanation/why-a-second-anvil-loader.md) * [Explanation Why a custom light engine](/falco/explanation/why-a-custom-light-engine.md) * [Explanation Why falco-instance exists](/falco/explanation/why-falco-instance-exists.md) * [Explanation Comparing the light engine with Minestoms](/falco/explanation/comparing-the-light-engine-with-minestoms.md) **What the numbers mean** * [Explanation What a measurement here means](/falco/explanation/what-a-measurement-here-means.md) — the one definition of what the `±` covers * [Explanation What the benchmarks establish](/falco/explanation/what-the-benchmarks-establish.md) ## 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](/falco/project-record/project-status.md) — what is in the branch, the defects found and fixed, what is still open, and what was investigated and deliberately not built * [Research](/falco/project-record/research.md) — the index of the investigations * [Documentation conventions](/falco/contributing/documentation-conventions.md) — how this documentation is organised and which page owns which fact ## Working on Falco * [Contributing](/falco/contributing/contributing.md) — what a change is built, tested and released with * [Build Setup](/falco/contributing/build-setup.md) — module structure and why `falco-bom` is special-cased * [Versioning and Releases](/falco/contributing/versioning-and-releases.md) · [Dependency Management](/falco/contributing/dependency-management.md) · [Publishing](/falco/contributing/publishing.md) * [Testing and Javadoc](/falco/contributing/testing-and-javadoc.md) · [Benchmarks and Demo](/falco/contributing/benchmarks-and-demo.md) · [Architecture Rules](/falco/contributing/architecture-rules.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.onelitefeather.net/falco/readme.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.