BlueGit

timfa questward

Clear light occlusion on tree stumps via live block state.

Standing trees keep partial canopy falloff; stump states from woodcutting CHUNK_DELTA snapshots skip occlusion dynamically without rebaking saved lightmaps.

timfa Tim Falken · pushed by timfa

Authored 2026-08-25 · 2 months ago

Hash
e42fc282f1547f8cd0838fa6f34aba2285036acc
Parent
06b93801
5 files changed +44 −7
docs/FEATURES.md +1 −1
@@ -58,7 +58,7 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
58 58 ## Baked lighting
59 59
60 60 **Status:** full
61 **Spec:** On chunk save, raycast light from blocks with `lightRangeTiles` through tiles that do not occlude light, including across chunk borders. Occlusion defaults to `!passable`; set `blocksLight: false` on furniture (tables, marketplace counters, crafting stations, ore nodes, cauldron) to let light through while remaining impassable. Set `blocksLight: "partial"` (e.g. pine trees) so the ray continues but each such tile adds +1 to falloff distance (that step costs twice as much). Store a 16×16 intensity map (0–255, smoothstep falloff by effective tile distance). Torch range is 8 tiles; furnace is 4.
61 **Spec:** On chunk save, raycast light from blocks with `lightRangeTiles` through tiles that do not occlude light, including across chunk borders. Occlusion defaults to `!passable`; set `blocksLight: false` on furniture (tables, marketplace counters, crafting stations, ore nodes, cauldron) to let light through while remaining impassable. Set `blocksLight: "partial"` on standing trees so the ray continues but each canopy tile adds +1 to falloff distance; **tree stumps** (`*-stump` state from woodcutting) clear that occlusion at runtime via live chunk snapshots (same dynamic path as torches, without rebaking). Store a 16×16 intensity map (0–255, smoothstep falloff by effective tile distance). Torch range is 8 tiles; furnace is 4.
62 62 **Code:** `server/src/lighting/baker.js`, `shared/lighting/raycast.js`, `shared/definitions/tiles.js` (`LightOcclusion` / `blocksLight`), tests in `server/tests/lighting.test.js`
63 63
64 64 ## World editor (server)
@@ -58,7 +58,7 @@ Each entry is a short note on behaviour and where the code lives. Update this fi
58## Baked lighting
58## Baked lighting
59
59
60**Status:** full
60**Status:** full
61**Spec:** On chunk save, raycast light from blocks with `lightRangeTiles` through tiles that do not occlude light, including across chunk borders. Occlusion defaults to `!passable`; set `blocksLight: false` on furniture (tables, marketplace counters, crafting stations, ore nodes, cauldron) to let light through while remaining impassable. Set `blocksLight: "partial"` (e.g. pine trees) so the ray continues but each such tile adds +1 to falloff distance (that step costs twice as much). Store a 16×16 intensity map (0–255, smoothstep falloff by effective tile distance). Torch range is 8 tiles; furnace is 4.
61**Spec:** On chunk save, raycast light from blocks with `lightRangeTiles` through tiles that do not occlude light, including across chunk borders. Occlusion defaults to `!passable`; set `blocksLight: false` on furniture (tables, marketplace counters, crafting stations, ore nodes, cauldron) to let light through while remaining impassable. Set `blocksLight: "partial"` on standing trees so the ray continues but each canopy tile adds +1 to falloff distance; **tree stumps** (`*-stump` state from woodcutting) clear that occlusion at runtime via live chunk snapshots (same dynamic path as torches, without rebaking). Store a 16×16 intensity map (0–255, smoothstep falloff by effective tile distance). Torch range is 8 tiles; furnace is 4.
62**Code:** `server/src/lighting/baker.js`, `shared/lighting/raycast.js`, `shared/definitions/tiles.js` (`LightOcclusion` / `blocksLight`), tests in `server/tests/lighting.test.js`
62**Code:** `server/src/lighting/baker.js`, `shared/lighting/raycast.js`, `shared/definitions/tiles.js` (`LightOcclusion` / `blocksLight`), tests in `server/tests/lighting.test.js`
63
63
64## World editor (server)
64## World editor (server)
server/src/world/chunkData.js +2 −2
@@ -3,7 +3,7 @@ import {
3 3 GroundType,
4 4 BlockType,
5 5 isBlockPassable,
6 blockLightOcclusion,
6 blockLightOcclusionForBlock,
7 7 LightOcclusion,
8 8 isGroundPassable,
9 9 blockLightRange,
@@ -166,7 +166,7 @@ export function chunkTileLightOcclusion (data, localX, localY)
166 166 if (!isGroundPassable(ground.typeId))
167 167 { return LightOcclusion.solid; }
168 168 const block = data.blocks[index];
169 return blockLightOcclusion(block?.typeId ?? null);
169 return blockLightOcclusionForBlock(block);
170 170 }
171 171
172 172 /** True when light rays are not solid-stopped (partial canopy still clears). */
@@ -3,7 +3,7 @@ import {
3 GroundType,
3 GroundType,
4 BlockType,
4 BlockType,
5 isBlockPassable,
5 isBlockPassable,
6 blockLightOcclusion,
6 blockLightOcclusionForBlock,
7 LightOcclusion,
7 LightOcclusion,
8 isGroundPassable,
8 isGroundPassable,
9 blockLightRange,
9 blockLightRange,
@@ -166,7 +166,7 @@ export function chunkTileLightOcclusion (data, localX, localY)
166 if (!isGroundPassable(ground.typeId))
166 if (!isGroundPassable(ground.typeId))
167 { return LightOcclusion.solid; }
167 { return LightOcclusion.solid; }
168 const block = data.blocks[index];
168 const block = data.blocks[index];
169 return blockLightOcclusion(block?.typeId ?? null);
169 return blockLightOcclusionForBlock(block);
170}
170}
171
171
172/** True when light rays are not solid-stopped (partial canopy still clears). */
172/** True when light rays are not solid-stopped (partial canopy still clears). */
server/tests/lighting.test.js +25 −2
@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
3 3 import { createEmptyChunkData } from "../src/world/chunkData.js";
4 4 import { bakeLightMaps } from "../src/lighting/baker.js";
5 5 import { bresenhamTiles, dynamicLightAtTile, evaluateLightRay, rayReaches } from "../../shared/lighting/raycast.js";
6 import { BlockType, LightOcclusion } from "../../shared/definitions/tiles.js";
6 import { BlockType, LightOcclusion, blockLightOcclusionForBlock } from "../../shared/definitions/tiles.js";
7 7 import { CHUNK_SIZE } from "../../shared/protocol/constants.js";
8 8
9 9 test("Bresenham visits start and end tiles", () =>
@@ -119,7 +119,7 @@ test("pine trees partially occlude baked light", () =>
119 119 const withTree = createEmptyChunkData();
120 120 withTree.open = true;
121 121 withTree.blocks[0] = { typeId: BlockType.torch, config: null };
122 withTree.blocks[1] = { typeId: BlockType.pineTree, config: null };
122 withTree.blocks[1] = { typeId: BlockType.pineTree, state: "summer", config: null };
123 123
124 124 const open = createEmptyChunkData();
125 125 open.open = true;
@@ -143,3 +143,26 @@ test("pine trees partially occlude baked light", () =>
143 143 assert.ok(litTree.light[2] > 0, "light passes through pine canopy");
144 144 assert.ok(litTree.light[2] < litOpen.light[2], "pine darkens tiles beyond vs open air");
145 145 });
146
147 test("tree stumps do not occlude light rays", () =>
148 {
149 assert.equal(
150 blockLightOcclusionForBlock({ typeId: BlockType.pineTree, state: "summer-stump" }),
151 LightOcclusion.clear
152 );
153 assert.equal(
154 blockLightOcclusionForBlock({ typeId: BlockType.pineTree, state: "summer" }),
155 LightOcclusion.partial
156 );
157
158 const stump = (x, y) => (x === 1 && y === 0
159 ? blockLightOcclusionForBlock({ typeId: BlockType.pineTree, state: "summer-stump" })
160 : LightOcclusion.clear);
161 const tree = (x, y) => (x === 1 && y === 0
162 ? blockLightOcclusionForBlock({ typeId: BlockType.pineTree, state: "summer" })
163 : LightOcclusion.clear);
164 const sources = [{ tileX: 0, tileY: 0, range: 8, intensity: 1 }];
165 const pastStump = dynamicLightAtTile(2, 0, sources, stump);
166 const pastTree = dynamicLightAtTile(2, 0, sources, tree);
167 assert.ok(pastStump > pastTree, "stump clears canopy penalty vs standing tree");
168 });
@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
3import { createEmptyChunkData } from "../src/world/chunkData.js";
3import { createEmptyChunkData } from "../src/world/chunkData.js";
4import { bakeLightMaps } from "../src/lighting/baker.js";
4import { bakeLightMaps } from "../src/lighting/baker.js";
5import { bresenhamTiles, dynamicLightAtTile, evaluateLightRay, rayReaches } from "../../shared/lighting/raycast.js";
5import { bresenhamTiles, dynamicLightAtTile, evaluateLightRay, rayReaches } from "../../shared/lighting/raycast.js";
6import { BlockType, LightOcclusion } from "../../shared/definitions/tiles.js";
6import { BlockType, LightOcclusion, blockLightOcclusionForBlock } from "../../shared/definitions/tiles.js";
7import { CHUNK_SIZE } from "../../shared/protocol/constants.js";
7import { CHUNK_SIZE } from "../../shared/protocol/constants.js";
8
8
9test("Bresenham visits start and end tiles", () =>
9test("Bresenham visits start and end tiles", () =>
@@ -119,7 +119,7 @@ test("pine trees partially occlude baked light", () =>
119 const withTree = createEmptyChunkData();
119 const withTree = createEmptyChunkData();
120 withTree.open = true;
120 withTree.open = true;
121 withTree.blocks[0] = { typeId: BlockType.torch, config: null };
121 withTree.blocks[0] = { typeId: BlockType.torch, config: null };
122 withTree.blocks[1] = { typeId: BlockType.pineTree, config: null };
122 withTree.blocks[1] = { typeId: BlockType.pineTree, state: "summer", config: null };
123
123
124 const open = createEmptyChunkData();
124 const open = createEmptyChunkData();
125 open.open = true;
125 open.open = true;
@@ -143,3 +143,26 @@ test("pine trees partially occlude baked light", () =>
143 assert.ok(litTree.light[2] > 0, "light passes through pine canopy");
143 assert.ok(litTree.light[2] > 0, "light passes through pine canopy");
144 assert.ok(litTree.light[2] < litOpen.light[2], "pine darkens tiles beyond vs open air");
144 assert.ok(litTree.light[2] < litOpen.light[2], "pine darkens tiles beyond vs open air");
145});
145});
146
147test("tree stumps do not occlude light rays", () =>
148{
149 assert.equal(
150 blockLightOcclusionForBlock({ typeId: BlockType.pineTree, state: "summer-stump" }),
151 LightOcclusion.clear
152 );
153 assert.equal(
154 blockLightOcclusionForBlock({ typeId: BlockType.pineTree, state: "summer" }),
155 LightOcclusion.partial
156 );
157
158 const stump = (x, y) => (x === 1 && y === 0
159 ? blockLightOcclusionForBlock({ typeId: BlockType.pineTree, state: "summer-stump" })
160 : LightOcclusion.clear);
161 const tree = (x, y) => (x === 1 && y === 0
162 ? blockLightOcclusionForBlock({ typeId: BlockType.pineTree, state: "summer" })
163 : LightOcclusion.clear);
164 const sources = [{ tileX: 0, tileY: 0, range: 8, intensity: 1 }];
165 const pastStump = dynamicLightAtTile(2, 0, sources, stump);
166 const pastTree = dynamicLightAtTile(2, 0, sources, tree);
167 assert.ok(pastStump > pastTree, "stump clears canopy penalty vs standing tree");
168});
shared/definitions/tiles.js +14 −0
@@ -473,9 +473,23 @@ export const LightOcclusion = Object.freeze({
473 473 solid: 2
474 474 });
475 475
476 /**
477 * Resolve light occlusion for a block tile (type + visual state).
478 * Stumps are a runtime/editor state override: no occlusion even on tree types.
479 */
480 export function blockLightOcclusionForBlock (block)
481 {
482 if (!block)
483 { return LightOcclusion.clear; }
484 if (isSeasonalStumpState(block.state))
485 { return LightOcclusion.clear; }
486 return blockLightOcclusion(block.typeId ?? null);
487 }
488
476 489 /**
477 490 * Resolve light occlusion for a block type id.
478 491 * `blocksLight`: `true` | `false` | `"partial"`; omitted → solid iff `!passable`.
492 * Prefer {@link blockLightOcclusionForBlock} when block state is known.
479 493 */
480 494 export function blockLightOcclusion (typeId)
481 495 {
@@ -473,9 +473,23 @@ export const LightOcclusion = Object.freeze({
473 solid: 2
473 solid: 2
474});
474});
475
475
476/**
477 * Resolve light occlusion for a block tile (type + visual state).
478 * Stumps are a runtime/editor state override: no occlusion even on tree types.
479 */
480export function blockLightOcclusionForBlock (block)
481{
482 if (!block)
483 { return LightOcclusion.clear; }
484 if (isSeasonalStumpState(block.state))
485 { return LightOcclusion.clear; }
486 return blockLightOcclusion(block.typeId ?? null);
487}
488
476/**
489/**
477 * Resolve light occlusion for a block type id.
490 * Resolve light occlusion for a block type id.
478 * `blocksLight`: `true` | `false` | `"partial"`; omitted → solid iff `!passable`.
491 * `blocksLight`: `true` | `false` | `"partial"`; omitted → solid iff `!passable`.
492 * Prefer {@link blockLightOcclusionForBlock} when block state is known.
479 */
493 */
480export function blockLightOcclusion (typeId)
494export function blockLightOcclusion (typeId)
481{
495{
shared/lighting/tilePassable.js +2 −2
@@ -1,6 +1,6 @@
1 1 import { CHUNK_SIZE } from "../protocol/constants.js";
2 2 import {
3 blockLightOcclusion,
3 blockLightOcclusionForBlock,
4 4 isGroundPassable,
5 5 LightOcclusion,
6 6 normalizeGround
@@ -26,7 +26,7 @@ export function makeSnapshotLightOcclusion (chunks)
26 26 if (!isGroundPassable(ground.typeId))
27 27 { return LightOcclusion.solid; }
28 28 const block = snapshot.blocks?.[index];
29 return blockLightOcclusion(block?.typeId ?? null);
29 return blockLightOcclusionForBlock(block);
30 30 };
31 31 }
32 32
@@ -1,6 +1,6 @@
1import { CHUNK_SIZE } from "../protocol/constants.js";
1import { CHUNK_SIZE } from "../protocol/constants.js";
2import {
2import {
3 blockLightOcclusion,
3 blockLightOcclusionForBlock,
4 isGroundPassable,
4 isGroundPassable,
5 LightOcclusion,
5 LightOcclusion,
6 normalizeGround
6 normalizeGround
@@ -26,7 +26,7 @@ export function makeSnapshotLightOcclusion (chunks)
26 if (!isGroundPassable(ground.typeId))
26 if (!isGroundPassable(ground.typeId))
27 { return LightOcclusion.solid; }
27 { return LightOcclusion.solid; }
28 const block = snapshot.blocks?.[index];
28 const block = snapshot.blocks?.[index];
29 return blockLightOcclusion(block?.typeId ?? null);
29 return blockLightOcclusionForBlock(block);
30 };
30 };
31}
31}
32
32