diff --git a/content/projects/de/falco.md b/content/projects/de/falco.md new file mode 100644 index 00000000..2e605282 --- /dev/null +++ b/content/projects/de/falco.md @@ -0,0 +1,44 @@ +--- +slug: 'falco' +translationKey: 'falco' +title: 'Falco' +summary: 'Ein Anvil-Chunk-Loader, eine Lichtberechnung und eine Instanzimplementierung für Minestom.' +status: 'active' +releasedAt: '2026-07-31' +publishedAt: '2026-10-10' +updatedAt: '2026-10-10' +platforms: + - 'Minestom' +license: 'AGPL-3.0' +links: + docs: 'https://github.com/OneLiteFeatherNET/Falco/wiki' + source: 'https://github.com/OneLiteFeatherNET/Falco' + issues: 'https://github.com/OneLiteFeatherNET/Falco/issues' +maintainers: + - 'themeinerlp' +alternates: + - hreflang: 'de' + href: 'https://onelitefeather.net/de/projects/falco' + - hreflang: 'en' + href: 'https://onelitefeather.net/en/projects/falco' + - hreflang: 'x-default' + href: 'https://onelitefeather.net/en/projects/falco' +--- + +## Was ist das? + +Falco ist eine Sammlung von Java-Bibliotheken für [Minestom](https://github.com/Minestom/Minestom), kein Plugin für Paper oder einen anderen Server. Es besteht aus drei Modulen, die sich einzeln verwenden lassen: einem Anvil-Chunk-Loader, einer Block- und Himmelslicht-Berechnung und einer Instanzimplementierung, die ihre Chunks beim Abmelden freigibt. + +## Was die Module tun + +- **falco-anvil** liest und schreibt Anvil-Welten. Lesen, Dekomprimierung und das Parsen der NBT-Daten laufen parallel. Schlägt ein Lesevorgang fehl, wirft der Loader einen Fehler, statt den Chunk als fehlend zu melden. So kann der Server gespeicherte Daten nicht mit einem neu erzeugten Chunk überschreiben. Welten, die älter als der Snapshot 21w43a sind, werden abgelehnt. +- **falco-light** berechnet Block- und Himmelslicht. Jeder Aufruf ist thread-sicher, und die Engine ist an keine bestimmte Chunk-Implementierung gebunden. +- **falco-instance** stellt eine `Instance` und ihren `Chunk` bereit. Beim Abmelden entlädt sie jeden geladenen Chunk. Minestoms `InstanceManager.unregisterInstance` entlädt nur die Chunks eines `InstanceContainer`. Bei anderen Instanzen bleiben Chunks, Tick-Partitionen und Entities zurück. Für dieses Modul wird kein Geschwindigkeitsvorteil behauptet. + +## Was du vor dem Einsatz wissen solltest + +- **Die API ist experimentell.** Jeder öffentliche Typ trägt `@ApiStatus.Experimental`. Signaturen und Verhalten können sich in einem Minor-Release ändern. +- **Java 25 ist erforderlich.** Das Build zielt auf Java 25. +- **Minestom ist nicht enthalten.** Die Artefakte kompilieren gegen Minestom, bringen es aber nicht mit. Die Version wählst du selbst. Release 3.0.0 ist gegen Minestom `2026.08.28-26.2` gebaut und läuft nicht auf `26.1.2`. +- **Die Leistungswerte sind Messungen, keine Versprechen.** Die README nennt Benchmark-Ergebnisse. In einem Lauf las der Anvil-Loader Chunks auf zwei Threads 1,9-mal schneller als Minestoms eigener Loader. Ein zweiter Lauf hat diesen Faktor nicht bestätigt. Die Lichtberechnung war in sechs Szenarien 1,11- bis 1,71-mal schneller. Alle Werte stammen von vor dem Wechsel auf Minestom 26.2 und wurden dort nicht erneut gemessen. +- **Einrichtung.** Schnellstart, Maven-Koordinaten und Build-Anleitung stehen im [Wiki](https://github.com/OneLiteFeatherNET/Falco/wiki/Installation). Die Artefakte werden im Maven-Repository von OneLiteFeather unter `repo.onelitefeather.dev` veröffentlicht. diff --git a/content/projects/en/falco.md b/content/projects/en/falco.md new file mode 100644 index 00000000..e1b091ea --- /dev/null +++ b/content/projects/en/falco.md @@ -0,0 +1,44 @@ +--- +slug: 'falco' +translationKey: 'falco' +title: 'Falco' +summary: 'An Anvil chunk loader, a light engine and an instance implementation for Minestom.' +status: 'active' +releasedAt: '2026-07-31' +publishedAt: '2026-10-10' +updatedAt: '2026-10-10' +platforms: + - 'Minestom' +license: 'AGPL-3.0' +links: + docs: 'https://github.com/OneLiteFeatherNET/Falco/wiki' + source: 'https://github.com/OneLiteFeatherNET/Falco' + issues: 'https://github.com/OneLiteFeatherNET/Falco/issues' +maintainers: + - 'themeinerlp' +alternates: + - hreflang: 'de' + href: 'https://onelitefeather.net/de/projects/falco' + - hreflang: 'en' + href: 'https://onelitefeather.net/en/projects/falco' + - hreflang: 'x-default' + href: 'https://onelitefeather.net/en/projects/falco' +--- + +## What is this? + +Falco is a set of Java libraries for [Minestom](https://github.com/Minestom/Minestom), not a plugin for Paper or any other server. It has three modules that work on their own: an Anvil chunk loader, a block and sky light engine, and an instance implementation that releases its chunks when it is unregistered. + +## What the modules do + +- **falco-anvil** reads and writes Anvil worlds. Reading, decompression and NBT parsing run in parallel. If a read fails, the loader throws instead of reporting the chunk as missing, so the server cannot overwrite stored data with a freshly generated chunk. Worlds older than snapshot 21w43a are refused. +- **falco-light** calculates block and sky light. Each call is thread-safe, and the engine is not tied to a particular chunk implementation. +- **falco-instance** provides an `Instance` and its `Chunk`. Unregistering it unloads every chunk it loaded. Minestom's `InstanceManager.unregisterInstance` only unloads the chunks of an `InstanceContainer`; for other instances it leaves chunks, tick partitions and entities behind. Falco makes no claim of a speed gain for this module. + +## What to know before you use it + +- **The API is experimental.** Every public type carries `@ApiStatus.Experimental`, and signatures and behaviour may change in a minor release. +- **Java 25 is required.** The build targets Java 25. +- **Minestom is not included.** The artefacts compile against Minestom but do not bring it along, so you choose the version. Release 3.0.0 is built against Minestom `2026.08.28-26.2` and does not run on `26.1.2`. +- **The performance figures are measurements, not promises.** The README quotes benchmark results. In one run the Anvil loader read chunks 1.9 times faster than Minestom's own loader on two threads, but a second run did not reproduce that factor. The light engine was 1.11 to 1.71 times faster across six scenarios. All figures were taken before the move to Minestom 26.2 and have not been measured again on it. +- **Setup.** The quick start, the Maven coordinates and the build instructions are in the [wiki](https://github.com/OneLiteFeatherNET/Falco/wiki/Installation). The artefacts are published to the OneLiteFeather Maven repository at `repo.onelitefeather.dev`.