feat: serve the lobby world through Falco (Stage 1)

[TheMeinerLP]

Stacked on #214. Implements spec Stage 1 — US-1.01 … US-1.06.

What changed

Engine. MapProvider now loads through FalcoAnvilLoader instead of Minestom's AnvilLoader, and lights chunks through falco-light's ChunkLightService instead of LightingChunk.relight(...). The loader is created once per world root rather than per saveMap call — it holds region files open — so MapProvider became AutoCloseable and Titan.terminate() closes it.

The bug this stage exists to fix. MapPool.peekMap() used to ignore TITAN_LOBBY_MAP whenever exactly one world existed, and threw a bare NoSuchElementException otherwise. So a typo was invisible locally and killed startup in production, without naming the world it looked for. Now the property is always honoured; a missing world logs a warning naming both what was searched for and what was found, then falls back to world. Only an empty worlds/ is still fatal.

Tests — 70 green

MapPoolTest (11 cases) covers the regression directly: missing named world with several worlds present. Plus MapProviderIntegrationTest (3 Cyano cases) asserting the loader type, the lighting chunk supplier, and that close() really closes the loader.

Three things reviewers should know

1. Falco is 2.1.0, not the 0.3.0 the spec named. 0.3.0 predates Minestom 26.1. Side effect: Falco brings mycelium-bom 1.7.2 where aonyx-bom 0.8.0 brings 1.7.1, so Minestom moves 2026.06.05-26.1.2 → 2026.06.20-26.1.2. Same protocol, but it is an unrequested bump — flagging it rather than burying it.

2. falco-light 2.1.0 has a packaging defect. FalcoLightingChunk extends net.onelitefeather.falco.instance.FalcoChunk, but the artifact neither bundles falco-instance nor declares a dependency on it, so ChunkLightScheduler.supplier() does not link. This PR therefore takes the explicit ChunkLightService route. Worth a fix in Falco — its main already changed the superclass to DynamicChunk, so this looks fixed but unreleased.

3. Minestom still owns sky light. calculateWithNeighbours writes block light only; LightingChunk stays the chunk type so light is sent and the sky pass still runs. "Falco instead of Minestom's light engine" is therefore only half true today. calculateSky(chunk) exists but is per-chunk with no neighbour exchange and would seam at chunk borders — judged a regression against Minestom's neighbour-aware pass and left alone.

Known gaps

• US-1.02 has no direct test — it is Falco's behaviour, and testing it needs a deliberately corrupted region fixture. Covered indirectly by the closed-loader assertion.
• InstanceChunkLoadEvent is dispatched after the chunk future completes, so a player may already hold the chunk when the listener runs. Pre-existing; mitigated with invalidate() + invalidateResendDelay(). The scheduler route would remove it once point 2 is fixed.
• :setup does not close the provider — it has no shutdown hook at all. Left alone.
• Pre-existing landmine untouched: MapPool.clear() nulls referenceList, after which getAvailableMaps() NPEs.

[github-actions]

Test results

 72 files   72 suites   44s ⏱️
 77 tests  75 ✅ 2 💤 0 ❌
234 runs  228 ✅ 6 💤 0 ❌

Results for commit f80ede1.

♻️ This comment has been updated with latest results.

[TheMeinerLP]

All six review findings fixed — 78 tests green

I was wrong about the scheduler, and the agent proved it

I told the implementing agent that the ChunkLightScheduler blocker was "over-broad" because FalcoLightingChunk is only named inside a lambda body, so it would never be resolved unless the lambda ran. That is not how the JVM works here. The type is resolved at link time: the verifier must prove FalcoLightingChunk is assignable to the Chunk return type of lambda$supplier$0, which loads it and its FalcoChunk supertype.

Probed against the published 2.1.0 artifacts on a bare classpath:

OK   net.onelitefeather.falco.light.ChunkLightService
OK   net.onelitefeather.falco.light.ChunkLightArea
FAIL net.onelitefeather.falco.light.ChunkLightScheduler
       -> NoClassDefFoundError: net/onelitefeather/falco/instance/FalcoChunk

new ChunkLightScheduler(service) dies before markDirty is ever reached. But the original "not usable" conclusion was also wrong: falco-instance:2.1.0 is published. Declaring it (runtime-only — nothing in Titan names a type from it) makes every probe pass, so the scheduler is now used and no fallback was needed.

This is a genuine falco-light packaging defect worth reporting upstream: the artifact does not declare a dependency it cannot be loaded without.

The old test was blind by construction

testTheLobbyChunksCarryLight is deleted. It asserted the chunk supplier returns a LightingChunk and never loaded a chunk or read a light level — all four defects passed it.

The replacement builds a world on disk (generates chunks in a throwaway instance, writes them through a FalcoAnvilLoader, closes it) and reads light back out of chunks the provider loaded from that region file. That path is the point: a generated chunk goes through Chunk#onGenerate(), which invalidates every section — any test that generates its world cannot see these defects.

Per defect

	Status	Evidence
D1 light computed once from an incomplete neighbourhood	fixed	Red on pre-fix code: expected: <14> but was: <0>
D2 concurrent overlapping neighbourhoods	fixed	Four adjacent chunks, four virtual threads. Red before (inside 0 / across 14). Being a race test it passed by luck sometimes on the old code — D1/D3 are the deterministic ones
D3 sky light never computed	fixed	The test first proves its own premise (reads the region back with a bare loader, asserts sky level 0), then asserts 15 above the floor and 0 beneath
D4 :setup never closed the provider	fixed, untested	:setup has no test infrastructure (junit only, no cyano) — verified by reading
D5 close() left the loader wired in	fixed	closed flag, listeners removed, instance handed ChunkLoader.noop(), saveMap/loadMapData guarded. The constructor-leak path is not tested — no way found to force a failure at that point without a test-only seam
D6 wrong fallback message, clear() nulled the list	fixed	Message now names the world actually selected. clear() empties instead of nulling — and the list is copied on the way in, because one of the two filters returns an immutable list, so the old clear() would have thrown there

NFR-001 fixed and measured

mycelium-bom is excluded from all three falco dependencies. Verified by resolving, not by assuming: :common, :app and :setup all resolve net.minestom:minestom:2026.06.05-26.1.2 on compile, runtime and testRuntime, and :bridge compiles against the same — so the :bridge/:app divergence closes with it. Excluding the BOM did not break Falco, and both fat jars still carry falco/{anvil,light,instance}.

The catalog comment claiming 2.1.0 "resolves against the Minestom version the aonyx BOM pins" is corrected: it did not resolve against it, it overrode it.

Design note

LightingChunk stays the chunk type — scheduler.supplier() would have been a far larger change and the docs commit to LightingChunk for sending. The load listener only calls markChanged; an InstanceTickEvent listener drives onTick. Since that event carries a duration rather than a timestamp, the pass counter is a local AtomicLong, and because LightingChunk is not LightUpdateAware, the resend timer is armed from the scheduler's onAreaCompleted callback.