Falco

Falco is a set of modules for Minestom servers that load worlds saved in the Anvil format. It provides a chunk loader, a block and sky light engine, and an Instance that unloads everything it loaded. It is for server developers who want a loader that fails loudly on a bad read instead of quietly generating over real data.

• Anvil chunk loader — reads and writes region files in parallel, and throws on a read failure.
• Light engine — block and sky light, thread-safe per call, usable with any chunk type.
• Automatic relighting — chunks keep their light current as blocks change.
• FalcoInstance — unregistering it unloads every chunk it loaded.
• Shared worlds — FalcoSharedInstance on a plain container.
• Version guard — refuses worlds older than snapshot 21w43a instead of reading them as air.
• World migration — falco-migration moves older worlds forward. It has no release yet.

All published modules are experimental. See API surface and stability.

Quick start

1. Declare the dependency

repositories {
    mavenCentral()
    maven("https://repo.onelitefeather.dev/releases")
}

dependencies {
    // One version for all three, so they cannot drift into a combination nobody tested.
    implementation(platform("net.onelitefeather:falco-bom:3.0.1"))

    implementation("net.onelitefeather:falco-anvil")     // reading and writing Anvil worlds
    implementation("net.onelitefeather:falco-light")     // block and sky light
    implementation("net.onelitefeather:falco-instance")  // the instance and the chunk

    // Minestom is compileOnly in Falco, so it does not arrive with these
    // artefacts. Falco declares no version for it, on purpose. You pick it.
    // The version Falco compiles and measures against is recorded in the documentation:
    // https://docs.onelitefeather.net/falco/contributing#environment
    implementation("net.minestom:minestom:<version>")
}

Take only the modules you need. The platform constrains a version for each module; it does not pull any in. Individual coordinates, Maven and snapshots are in Installation.

2. Serve a stored world

import net.kyori.adventure.key.Key;
import net.minestom.server.MinecraftServer;
import net.minestom.server.instance.InstanceContainer;
import net.minestom.server.world.DimensionType;
import net.onelitefeather.falco.anvil.FalcoAnvilLoader;

import java.io.IOException;
import java.nio.file.Path;

public final class FirstServer {

    public static void main(String[] args) {
        MinecraftServer server = MinecraftServer.init();

        InstanceContainer instance = MinecraftServer.getInstanceManager()
                .createInstanceContainer(DimensionType.OVERWORLD);

        Key dimension = DimensionType.OVERWORLD.key();
        FalcoAnvilLoader loader = new FalcoAnvilLoader(Path.of("worlds", "lobby"), dimension);

        instance.setChunkLoader(loader);
        instance.enableAutoChunkLoad(true);

        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
            try {
                loader.close();
            } catch (IOException exception) {
                exception.printStackTrace();
            }
        }));

        server.start("0.0.0.0", 25565);
    }
}

Copy a saved world into the project as worlds/lobby, so that its region files sit in worlds/lobby/dimensions/minecraft/overworld/region. Run the class and connect to localhost:25565. You are standing in the stored world, not in generated terrain.

The tutorial goes on to light the world with falco-light and to check a clean shutdown. Worlds saved before Minecraft 26.1 use a different directory layout; see Load an Anvil world.

Documentation

The full documentation is on GitBook at docs.onelitefeather.net/falco. It is organised in four parts:

• Tutorials — a guided first project, start to finish.
• How-to guides — steps for a specific task, such as migrating a world or reproducing a measurement.
• Reference — modules, supported versions, the API surface, policies, exceptions and measured results.
• Explanation — why the modules are built the way they are, and what they deliberately do not do.

Contributing

The shortest path from a clone to a green build, and the one credential problem that stops it, are in CONTRIBUTING.md. The contributing guide covers conventions, testing, releases and what review looks for.

Licence

AGPL-3.0. See LICENSE.