feat: client-side 1.17.1 block and sky light in the wasm mesher

[sandexzx]

Client-side 1.17.1 block and sky light in the wasm mesher. Section meshes carry versions so a block edit is not drawn from stale server light or from a neighbor column the mesh did not sample.

Context

Inspired by minecraft-web-client#304 (client-side light engine).

This branch also contains minecraft-renderer#93 (feat/entity-block-lighting), including the opt-in defaults fix (465cf22). #93 stays open as an independently mergeable entity-lighting PR.

In my view this still works roughly and needs review from @zardoy.

How to test in the web client

Use the client integration in minecraft-web-client#599 with a renderer build containing this PR (including lightOwnerWorker.js).

1. Add ?clientLight=1 to the client URL, or &clientLight=1 if it already has query parameters, and reload.
2. Manually enable Lighting in Newer Versions in the client settings (newVersionsLighting).
3. Join a Minecraft 1.17.1 world/server.
4. Place/remove a torch; build an opaque roof, break a block in it, then close the opening and check that light updates.

Both switches are required to see the recomputed lighting. The URL flag starts the experimental light owner; the setting enables lighting display. Both remain off by default. clientLightTrace=1 is optional diagnostics, not required for testing.

What turns on

enableClientLightOwner stays default false. ?clientLight=1 sets that flag. Spawn also requires the session version to be 1.17.1 (shouldSpawnClientLightOwner). Any other version leaves the flag set, does not start lightOwnerWorker, and does not load the 1.17.1 state-id tables. clientLightTrace=1 is a separate, default-off trace.

With the flag off, or when the version gate refuses spawn, the mesh displays server update_light. With the flag on and version 1.17.1, ClientLightOwner and lightOwnerWorker start, separate from mesh workers. The session stays starting until the worker reports ready, and goes to failed on worker error.

Guarantees

• Emission, lightBlock, and 2×2×2 occupancy come from 1.17.1 Blocks.java lightLevel registrations. LightEngine::opacity_of is vanilla getOpacity: max(1, getLightBlock()). Levels are 0–15. shape_occludes follows 1.17.1 LayerLightEngine.
• Sky is its own queue. An open column sources 15 downward. Unknown chunks are not sky 15. Omitted sky sections are absent. An empty bit zeros that section. LIGHT_ONLY is an external boundary and is not rewritten by BFS.
• Block-light spread of an edit stops at the 3×3 column neighborhood (promote_edit_column). Admission is one column at a time. Missing neighbors are not invented as air. A BlockChange for an unknown column does not jump the queue.
• shouldAcceptVersionedMesh is per section. Fast A→B→C keeps C. A late reply from the previous column incarnation is dropped when both sides carry columnIncarnation. Fresh topology with stale light is installed for the current frame; covering stays outstanding and is not dispatched again while the pending remesh already covers the requirement. Stale topology with fresh light is rejected. hadErrors is never an empty success.
• INITIAL_TOPOLOGY_REVISION is 0. nextTopologyRevision starts at 1, so the first edit misses the initial topology cache.
• provenMeshLightVersion stamps a section from the latest applied version of the 3×3 columns (±16 in x and z) that the mesh actually used. The version on the dirty job is not an input.
• On owner takeover the display cache is cloned once from incoming server light. Later owner deltas write display in place. Revert copies display back to the last incoming packet and does not zero omitted sections. Packed channels are 2048 bytes. A foreign publication with the wrong length is not written.
• selectReadySectionFlushes installs a face-adjacent group together. The group flushes when every visible neighbor has arrived, or when the oldest member hits 500 ms. With the owner live, the wait is topology-outstanding. Displayed GPU slots stay separate from unuploaded candidates.
• A player edit sets urgent. createMeshTickScheduler.kick runs on the next turn. Urgent columns are taken before the bulk cap of 4 (BULK_COLUMNS_PER_TICK). setSectionDirty dispatches immediately when nextDirtyUrgent or a light publication version is set, and does not enter the 100 ms trailing window. The edit stays in interactiveSections until geometry is committed at a publication newer than lightVersionAtEdit. A rejected sectionFinished decrements sectionsWaiting. legacyBootstrap still has to match epoch and incarnation when a required version exists.
• Entities sample packed column block and sky light on the renderer thread.

Limitations

• Tables and the worker start are 1.17.1 only.
• newVersionsLighting (default false in renderer options) only feeds resolveEnableLighting. It does not spawn the owner.
• With the owner off, singleplayer torch spread is whatever the server sends in update_light. With the owner on, a block edit is BlockChange (setBlockStateIdInner → onBlockChange). Emission for that edit comes from the 1.17.1 tables and does not wait for update_light.
• The web client needs minecraft-web-client#599 to copy lightOwnerWorker.js from MESHER_DIST_FILES; the old handwritten artifact list omits it.
• src/wasm-mesher/runtime-build/wasm_mesher_bg.wasm on this branch is the LightEngine build, including commit 879d982.

Mesh version contract vs checks

An owner mesh is expected to carry sessionEpoch, columnIncarnation, worldGeneration, topologyRevision, and lightPublicationVersion. The section requirement carries requiredVersion, worldGeneration, and optionally topologyRevision.

shouldAcceptVersionedMesh does not require every field to be present:

• hadErrors rejects.
• An owner-managed mesh with worldGeneration, lightPublicationVersion, topologyRevision, and sessionEpoch all absent is rejected, except legacyBootstrap when there is no requirement.
• legacyBootstrap with a requirement rejects a missing lightPublicationVersion.
• Epoch, incarnation, worldGeneration, topologyRevision, and light version are compared only when that field is present on the mesh (topology also needs required.topologyRevision).
• No requirement accepts. With the owner off, an unversioned mesh accepts.

Checks

Latest integration/defaults validation:

• pnpm exec vitest run --maxWorkers=2: 638 tests passed.
• pnpm typecheck: passed in the renderer.
• cargo test: 101 tests passed.
• Web-client unit tests: 124 passed; clean production build with the local renderer passed.
• Headless Chrome loaded the copied lightOwnerWorker.js and WASM and received ready.
• Web-client typecheck is not clean with the local renderer: renderer-source global declarations and dependency/type compatibility errors remain. This is not a claim of clean client CI.

pnpm unit-test (vitest) covers accept/reject rules, owner spawn including the 1.17.1 gate, publication skipping the 100 ms window, packed-light length, face-adjacent flush, display clone and revert, sampled-column proof, urgent kick ahead of the 50 ms poll, topology and tick parse caches, and the default-off trace.

cargo test in wasm-mesher covers LightEngine: torch place and remove, stone roof sky, slab occlusion, a 1.17.1 update_light fixture, and edit-column promotion ahead of bulk without materializing an unknown section as air.