BlueGit

timfa questward

Files

questward / shared / definitions / tiles.js

tiles.js

2f0bc2de History
tiles.js 23.7 KiB Download Raw
1import
2{
3 ORE_BEARING_MATERIALS,
4 oreBoulderState,
5 materialFromOreBoulderState,
6 MATERIAL_DISPLAY_NAME,
7 isGemstoneMaterial,
8 WoodTier,
9 WOOD_TIER_ORDER
10} from "./materialTiers.js";
11import
12{
13 FLOWER_COLOR_ORDER,
14 FLOWER_COLOR_DISPLAY,
15 flowerBlockState
16} from "./dyes.js";
17import
18{
19 HERB_ORDER,
20 HERB_DEFINITIONS,
21 herbDefinition
22} from "./herbs.js";
23import { spriteImageName, defaultStateForType } from "./tileSprites.js";
24import { isSeasonalStumpState, SeasonId } from "../world/season.js";
25import
26{
27 composeNeighborConnectState,
28 definitionUsesMaterialNeighborConnect
29} from "../world/neighborConnect.js";
30
31export const GroundType = Object.freeze({
32 grass: 1,
33 wood: 2,
34 water: 3,
35 deepWater: 4,
36 dirt: 5
37});
38
39export const BlockType = Object.freeze({
40 stoneWall: 1,
41 torch: 2,
42 /** @deprecated Legacy authored block; migrated into chunk `spawners[]` on load. */
43 spawner: 3,
44 bank: 4,
45 churchAltar: 5,
46 cauldron: 6,
47 boulder: 7,
48 furnace: 8,
49 anvil: 9,
50 woodworkingBench: 10,
51 craftingBench: 11,
52 pineTree: 12,
53 marketplace: 13,
54 table: 14,
55 flower: 15,
56 cottonPlant: 16,
57 spinningWheel: 17,
58 loom: 18,
59 tailorBench: 19,
60 bountyOffice: 20,
61 barber: 23,
62 /** Folklore herbs — state is herbId (`sage`, `mint`, …); sprites in `assets/herbs/`. */
63 herbPlant: 24,
64 birchTree: 21,
65 oakTree: 22,
66 ebonyTree: 25,
67 lignumTree: 26,
68 heartwoodTree: 27,
69 elderTree: 28,
70 leatherworkingTable: 29,
71 doorway: 30,
72 campfire: 31,
73 oven: 32,
74 fishingSpot: 33,
75 jeweleringStation: 34,
76 flaxPlant: 35,
77 silkCocoon: 36,
78 fence: 37
79});
80
81export const GROUND_DEFINITIONS = Object.freeze({
82 [GroundType.grass]: Object.freeze({
83 id: GroundType.grass,
84 key: "grass",
85 displayName: "Grass",
86 passable: true,
87 wades: false,
88 water: false,
89 frames: 1,
90 framesPerRow: 1,
91 animationSpeed: 0,
92 /** Outdoor grounds should expose summer/fall/winter (legacy `grass` ok for summer). */
93 outdoor: true,
94 /** Soft-terrain edge blend when the player enables Soft terrain. */
95 blendable: true
96 }),
97 [GroundType.wood]: Object.freeze({
98 id: GroundType.wood,
99 key: "wood",
100 displayName: "Wood",
101 passable: true,
102 wades: false,
103 water: false,
104 frames: 1,
105 framesPerRow: 1,
106 animationSpeed: 0,
107 outdoor: false
108 }),
109 [GroundType.water]: Object.freeze({
110 id: GroundType.water,
111 key: "water",
112 displayName: "Water",
113 passable: true,
114 wades: true,
115 water: true,
116 frames: 4,
117 framesPerRow: 4,
118 animationSpeed: 0.12,
119 outdoor: true
120 }),
121 [GroundType.deepWater]: Object.freeze({
122 id: GroundType.deepWater,
123 key: "deep-water",
124 displayName: "Deep water",
125 passable: false,
126 wades: false,
127 water: true,
128 frames: 4,
129 framesPerRow: 4,
130 animationSpeed: 0.12,
131 outdoor: true
132 }),
133 [GroundType.dirt]: Object.freeze({
134 id: GroundType.dirt,
135 key: "dirt",
136 displayName: "Dirt",
137 passable: true,
138 wades: false,
139 water: false,
140 frames: 1,
141 framesPerRow: 1,
142 animationSpeed: 0,
143 outdoor: true,
144 blendable: true
145 })
146});
147
148function treeBlockDef (id, woodTier)
149{
150 const name = MATERIAL_DISPLAY_NAME[woodTier] ?? woodTier;
151 return Object.freeze({
152 id,
153 key: `${woodTier}-tree`,
154 displayName: `${name} tree`,
155 passable: false,
156 /** Canopy: light passes but each tree tile adds +1 falloff distance. */
157 blocksLight: "partial",
158 lightRangeTiles: 0,
159 frames: 1,
160 framesPerRow: 1,
161 animationSpeed: 0,
162 outdoor: true,
163 gatherable: true,
164 woodTier
165 });
166}
167
168export const BLOCK_DEFINITIONS = Object.freeze({
169 [BlockType.stoneWall]: Object.freeze({
170 id: BlockType.stoneWall,
171 key: "stone-wall",
172 displayName: "Stone wall",
173 passable: false,
174 lightRangeTiles: 0,
175 frames: 1,
176 framesPerRow: 1,
177 animationSpeed: 0,
178 /** Building walls count as indoor (no seasonal art required). */
179 outdoor: false
180 }),
181 [BlockType.torch]: Object.freeze({
182 id: BlockType.torch,
183 key: "torch",
184 displayName: "Torch",
185 passable: true,
186 lightRangeTiles: 8,
187 frames: 1,
188 framesPerRow: 1,
189 animationSpeed: 0,
190 outdoor: false
191 }),
192 [BlockType.spawner]: Object.freeze({
193 id: BlockType.spawner,
194 key: "spawner",
195 displayName: "Spawner",
196 passable: true,
197 lightRangeTiles: 0,
198 frames: 1,
199 framesPerRow: 1,
200 animationSpeed: 0,
201 /** Not shown in the placeable block palette; use the Spawners tab. */
202 editorHidden: true,
203 outdoor: false
204 }),
205 [BlockType.bank]: Object.freeze({
206 id: BlockType.bank,
207 key: "bank",
208 displayName: "Bank",
209 passable: false,
210 lightRangeTiles: 0,
211 frames: 1,
212 framesPerRow: 1,
213 animationSpeed: 0,
214 outdoor: false
215 }),
216 [BlockType.churchAltar]: Object.freeze({
217 id: BlockType.churchAltar,
218 key: "church-altar",
219 displayName: "Church altar",
220 passable: false,
221 lightRangeTiles: 0,
222 frames: 1,
223 framesPerRow: 1,
224 animationSpeed: 0,
225 outdoor: false
226 }),
227 [BlockType.cauldron]: Object.freeze({
228 id: BlockType.cauldron,
229 key: "cauldron",
230 displayName: "Cauldron",
231 passable: false,
232 blocksLight: false,
233 lightRangeTiles: 0,
234 frames: 1,
235 framesPerRow: 1,
236 animationSpeed: 0,
237 outdoor: false
238 }),
239 [BlockType.boulder]: Object.freeze({
240 id: BlockType.boulder,
241 key: "boulder",
242 displayName: "Boulder",
243 passable: false,
244 blocksLight: false,
245 lightRangeTiles: 0,
246 frames: 1,
247 framesPerRow: 1,
248 animationSpeed: 0,
249 /** Ore states are synthesized in the sprite catalog (tinted boulder-ore). */
250 gatherable: true,
251 outdoor: true
252 }),
253 [BlockType.furnace]: Object.freeze({
254 id: BlockType.furnace,
255 key: "furnace",
256 displayName: "Furnace",
257 passable: false,
258 blocksLight: false,
259 lightRangeTiles: 4,
260 frames: 1,
261 framesPerRow: 1,
262 animationSpeed: 0,
263 craftingStationId: "furnace",
264 outdoor: false
265 }),
266 [BlockType.campfire]: Object.freeze({
267 id: BlockType.campfire,
268 key: "campfire",
269 displayName: "Campfire",
270 passable: true,
271 blocksLight: false,
272 blocksRangedAttacks: false,
273 lightRangeTiles: 4,
274 frames: 1,
275 framesPerRow: 1,
276 animationSpeed: 0,
277 craftingStationId: "fireplace",
278 /** State is wood tier id; tinted like logs. Bloom companion is fire only. */
279 tintFromTier: true,
280 /** Lit/expires at runtime — per-tile draw, not chunk atlas (see chunk-delta). */
281 perTileBlock: true,
282 outdoor: true
283 }),
284 [BlockType.oven]: Object.freeze({
285 id: BlockType.oven,
286 key: "oven",
287 displayName: "Oven",
288 passable: false,
289 blocksLight: false,
290 lightRangeTiles: 2,
291 frames: 1,
292 framesPerRow: 1,
293 animationSpeed: 0,
294 craftingStationId: "oven",
295 outdoor: false
296 }),
297 [BlockType.fishingSpot]: Object.freeze({
298 id: BlockType.fishingSpot,
299 key: "fishing-spot",
300 displayName: "Fishing spot",
301 passable: true,
302 blocksLight: false,
303 blocksRangedAttacks: false,
304 lightRangeTiles: 0,
305 /** Ripple / splash strip (temp art; 3 frames). */
306 frames: 3,
307 framesPerRow: 3,
308 animationSpeed: 0.18,
309 outdoor: true,
310 /** Requires water / deepWater under the tile (editor + server). */
311 requiresWater: true
312 }),
313 [BlockType.anvil]: Object.freeze({
314 id: BlockType.anvil,
315 key: "anvil",
316 displayName: "Anvil",
317 passable: false,
318 blocksLight: false,
319 lightRangeTiles: 0,
320 frames: 1,
321 framesPerRow: 1,
322 animationSpeed: 0,
323 craftingStationId: "anvil",
324 outdoor: false
325 }),
326 [BlockType.jeweleringStation]: Object.freeze({
327 id: BlockType.jeweleringStation,
328 key: "jewelering-station",
329 displayName: "Jewelering station",
330 passable: false,
331 blocksLight: false,
332 lightRangeTiles: 0,
333 frames: 1,
334 framesPerRow: 1,
335 animationSpeed: 0,
336 craftingStationId: "jewelering-station",
337 outdoor: false
338 }),
339 [BlockType.woodworkingBench]: Object.freeze({
340 id: BlockType.woodworkingBench,
341 key: "woodworking-bench",
342 displayName: "Woodworking bench",
343 passable: false,
344 blocksLight: false,
345 lightRangeTiles: 0,
346 frames: 1,
347 framesPerRow: 1,
348 animationSpeed: 0,
349 craftingStationId: "woodworking-bench",
350 outdoor: false
351 }),
352 [BlockType.craftingBench]: Object.freeze({
353 id: BlockType.craftingBench,
354 key: "crafting-bench",
355 displayName: "Crafting bench",
356 passable: false,
357 blocksLight: false,
358 lightRangeTiles: 0,
359 frames: 1,
360 framesPerRow: 1,
361 animationSpeed: 0,
362 craftingStationId: "crafting-bench",
363 outdoor: false
364 }),
365 [BlockType.pineTree]: treeBlockDef(BlockType.pineTree, WoodTier.pine),
366 [BlockType.birchTree]: treeBlockDef(BlockType.birchTree, WoodTier.birch),
367 [BlockType.oakTree]: treeBlockDef(BlockType.oakTree, WoodTier.oak),
368 [BlockType.ebonyTree]: treeBlockDef(BlockType.ebonyTree, WoodTier.ebony),
369 [BlockType.lignumTree]: treeBlockDef(BlockType.lignumTree, WoodTier.lignum),
370 [BlockType.heartwoodTree]: treeBlockDef(BlockType.heartwoodTree, WoodTier.heartwood),
371 [BlockType.elderTree]: treeBlockDef(BlockType.elderTree, WoodTier.elder),
372 [BlockType.marketplace]: Object.freeze({
373 id: BlockType.marketplace,
374 key: "marketplace",
375 displayName: "Central Exchange counter",
376 passable: false,
377 /** Furniture: blocks movement but not baked/dynamic light rays. */
378 blocksLight: false,
379 lightRangeTiles: 0,
380 frames: 1,
381 framesPerRow: 1,
382 animationSpeed: 0,
383 outdoor: false,
384 /** Autotile via N/E/S/W bitmask states `"0"`…`"15"`. */
385 neighborConnect: true
386 }),
387 [BlockType.table]: Object.freeze({
388 id: BlockType.table,
389 key: "table",
390 displayName: "Table",
391 passable: false,
392 blocksLight: false,
393 blocksRangedAttacks: false,
394 lightRangeTiles: 0,
395 frames: 1,
396 framesPerRow: 1,
397 animationSpeed: 0,
398 outdoor: false,
399 /** Magenta base `0`–`15` (strip-union line tables); catalog expands `${wood}-${mask}`.
400 * Filled-rectangle corners can later add diagonal-aware sprites without replacing these. */
401 neighborConnect: true,
402 neighborConnectByMaterial: true,
403 defaultNeighborMaterial: WoodTier.pine
404 }),
405 [BlockType.fence]: Object.freeze({
406 id: BlockType.fence,
407 key: "fence",
408 displayName: "Fence",
409 passable: false,
410 blocksLight: false,
411 blocksRangedAttacks: false,
412 lightRangeTiles: 0,
413 frames: 1,
414 framesPerRow: 1,
415 animationSpeed: 0,
416 outdoor: true,
417 /** Magenta base `0`–`15`; catalog expands `${wood}-${mask}` like tables. */
418 neighborConnect: true,
419 neighborConnectByMaterial: true,
420 defaultNeighborMaterial: WoodTier.pine
421 }),
422 [BlockType.flower]: Object.freeze({
423 id: BlockType.flower,
424 key: "flower",
425 displayName: "Flower",
426 passable: true,
427 blocksLight: false,
428 lightRangeTiles: 0,
429 frames: 1,
430 framesPerRow: 1,
431 animationSpeed: 0,
432 outdoor: true,
433 gatherable: true,
434 plantGather: Object.freeze({ kind: "flower", requiresClippers: false, skillId: "herbalism" })
435 }),
436 [BlockType.cottonPlant]: Object.freeze({
437 id: BlockType.cottonPlant,
438 key: "cotton-plant",
439 displayName: "Cotton plant",
440 passable: true,
441 blocksLight: false,
442 lightRangeTiles: 0,
443 frames: 1,
444 framesPerRow: 1,
445 animationSpeed: 0,
446 outdoor: true,
447 gatherable: true,
448 plantGather: Object.freeze({ kind: "cotton", requiresClippers: false, skillId: "herbalism" })
449 }),
450 [BlockType.flaxPlant]: Object.freeze({
451 id: BlockType.flaxPlant,
452 key: "flax-plant",
453 displayName: "Flax plant",
454 passable: true,
455 blocksLight: false,
456 lightRangeTiles: 0,
457 frames: 1,
458 framesPerRow: 1,
459 animationSpeed: 0,
460 outdoor: true,
461 gatherable: true,
462 plantGather: Object.freeze({
463 kind: "flax",
464 requiresClippers: true,
465 /** Linen-rank clippers or better (steel↔linen). */
466 minClothTier: "linen",
467 skillId: "herbalism"
468 })
469 }),
470 [BlockType.silkCocoon]: Object.freeze({
471 id: BlockType.silkCocoon,
472 key: "silk-cocoon",
473 displayName: "Silk cocoon",
474 passable: true,
475 blocksLight: false,
476 lightRangeTiles: 0,
477 frames: 1,
478 framesPerRow: 1,
479 animationSpeed: 0,
480 outdoor: true,
481 gatherable: true,
482 plantGather: Object.freeze({
483 kind: "silk",
484 requiresClippers: true,
485 /** Silk-rank clippers or better (adamantium↔silk). */
486 minClothTier: "silk",
487 skillId: "herbalism"
488 })
489 }),
490 [BlockType.spinningWheel]: Object.freeze({
491 id: BlockType.spinningWheel,
492 key: "spinning-wheel",
493 displayName: "Spinning wheel",
494 passable: false,
495 blocksLight: false,
496 lightRangeTiles: 0,
497 frames: 1,
498 framesPerRow: 1,
499 animationSpeed: 0,
500 craftingStationId: "spinning-wheel",
501 outdoor: false
502 }),
503 [BlockType.loom]: Object.freeze({
504 id: BlockType.loom,
505 key: "loom",
506 displayName: "Loom",
507 passable: false,
508 blocksLight: false,
509 lightRangeTiles: 0,
510 frames: 1,
511 framesPerRow: 1,
512 animationSpeed: 0,
513 craftingStationId: "loom",
514 outdoor: false
515 }),
516 [BlockType.tailorBench]: Object.freeze({
517 id: BlockType.tailorBench,
518 key: "tailor-bench",
519 displayName: "Tailor's bench",
520 passable: false,
521 blocksLight: false,
522 lightRangeTiles: 0,
523 frames: 1,
524 framesPerRow: 1,
525 animationSpeed: 0,
526 craftingStationId: "tailor-bench",
527 outdoor: false
528 }),
529 [BlockType.leatherworkingTable]: Object.freeze({
530 id: BlockType.leatherworkingTable,
531 key: "leatherworking-table",
532 displayName: "Leatherworking table",
533 passable: false,
534 blocksLight: false,
535 lightRangeTiles: 0,
536 frames: 1,
537 framesPerRow: 1,
538 animationSpeed: 0,
539 craftingStationId: "leatherworking-station",
540 outdoor: false
541 }),
542 [BlockType.bountyOffice]: Object.freeze({
543 id: BlockType.bountyOffice,
544 key: "bounty-office",
545 displayName: "Bounty office",
546 passable: false,
547 blocksLight: false,
548 lightRangeTiles: 0,
549 frames: 1,
550 framesPerRow: 1,
551 animationSpeed: 0,
552 outdoor: false
553 }),
554 [BlockType.barber]: Object.freeze({
555 id: BlockType.barber,
556 key: "barber",
557 displayName: "Barber",
558 passable: false,
559 blocksLight: false,
560 lightRangeTiles: 0,
561 frames: 1,
562 framesPerRow: 1,
563 animationSpeed: 0,
564 outdoor: false
565 }),
566 [BlockType.doorway]: Object.freeze({
567 id: BlockType.doorway,
568 key: "doorway",
569 displayName: "Doorway",
570 passable: true,
571 blocksLight: false,
572 lightRangeTiles: 0,
573 frames: 1,
574 framesPerRow: 1,
575 animationSpeed: 0,
576 outdoor: false,
577 /** Visual variants under `blocks/doorway/`. */
578 doorway: true,
579 defaultState: "door"
580 }),
581 [BlockType.herbPlant]: Object.freeze({
582 id: BlockType.herbPlant,
583 key: "herb",
584 displayName: "Herb",
585 passable: true,
586 blocksLight: false,
587 lightRangeTiles: 0,
588 frames: 1,
589 framesPerRow: 1,
590 animationSpeed: 0,
591 outdoor: true,
592 gatherable: true,
593 /** Sprites live under `assets/herbs/` (shared with items), not `blocks/herb/`. */
594 assetFolder: "herbs",
595 plantGather: Object.freeze({
596 kind: "herb",
597 requiresClippers: true,
598 skillId: "herbalism"
599 })
600 })
601});
602
603/** Grounds and real blocks the editor may place (excludes legacy/hidden entries). */
604export function listPlaceableGrounds ()
605{
606 return Object.values(GROUND_DEFINITIONS);
607}
608
609export function listPlaceableBlocks ()
610{
611 return Object.values(BLOCK_DEFINITIONS).filter((def) => !def.editorHidden);
612}
613
614/** Display name for an ore boulder state (`copper-ore` → "Copper ore boulder"). */
615export function oreBoulderDisplayName (state)
616{
617 const material = materialFromOreBoulderState(state);
618 if (!material)
619 { return null; }
620 const label = MATERIAL_DISPLAY_NAME[material] ?? material;
621 if (material === "coal")
622 { return "Coal boulder"; }
623 if (isGemstoneMaterial(material))
624 { return `${label} boulder`; }
625 return `${label} ore boulder`;
626}
627
628/**
629 * Hover / UI label for a gatherable resource node.
630 * Ore boulders and chopable trees; fishing / herbs can extend this later.
631 * Returns null when the block is not an active resource node.
632 */
633export function resourceNodeDisplayName (block)
634{
635 if (!block)
636 { return null; }
637 if (block.typeId === BlockType.fishingSpot && block.state !== "exhausted")
638 { return "Fishing spot"; }
639 if (block.typeId === BlockType.boulder)
640 { return oreBoulderDisplayName(block.state); }
641 if (isChopableTreeBlock(block))
642 {
643 const def = BLOCK_DEFINITIONS[block.typeId];
644 return def?.displayName ?? "Tree";
645 }
646 if (block.typeId === BlockType.flower)
647 {
648 const color = FLOWER_COLOR_DISPLAY[block.state];
649 return color ? `${color} flower` : "Flower";
650 }
651 if (block.typeId === BlockType.cottonPlant)
652 { return "Cotton plant"; }
653 if (block.typeId === BlockType.flaxPlant)
654 { return "Flax plant"; }
655 if (block.typeId === BlockType.silkCocoon)
656 { return "Silk cocoon"; }
657 if (block.typeId === BlockType.herbPlant)
658 {
659 const herb = herbDefinition(block.state);
660 return herb ? herb.displayName : "Herb";
661 }
662 return null;
663}
664
665/** Wood tier for a tree block type, or null. */
666export function woodTierForTreeBlock (typeId)
667{
668 const def = BLOCK_DEFINITIONS[typeId];
669 return def?.woodTier ?? null;
670}
671
672/** True when this block is a standing (non-stump) gatherable tree. */
673export function isChopableTreeBlock (block)
674{
675 if (!block || woodTierForTreeBlock(block.typeId) == null)
676 { return false; }
677 return !isSeasonalStumpState(block.state);
678}
679
680/** Plant gather config from block def, or null. */
681export function plantGatherForBlock (block)
682{
683 if (!block)
684 { return null; }
685 const def = BLOCK_DEFINITIONS[block.typeId];
686 return def?.plantGather ?? null;
687}
688
689export function isPickablePlantBlock (block)
690{
691 return !!plantGatherForBlock(block);
692}
693
694/**
695 * Blocks baked into chunk atlas rows. Gather nodes and pickables stay as per-tile
696 * sprites so chunkDelta can hide or restyle them without rebaking the row.
697 */
698export function isChunkAtlasBakedBlock (block)
699{
700 if (!block)
701 { return false; }
702 const entry = normalizeBlock(block);
703 if (!entry)
704 { return false; }
705 const def = BLOCK_DEFINITIONS[entry.typeId];
706 if (!def || def.editorHidden)
707 { return false; }
708 if (def.perTileBlock)
709 { return false; }
710 if (resourceNodeDisplayName(entry))
711 { return false; }
712 if (isPickablePlantBlock(entry))
713 { return false; }
714 return true;
715}
716
717/**
718 * Editor palette cards: one entry per placeable, with boulder expanded into
719 * plain rock + each ore/coal variant (shared BlockType, distinct state).
720 * Flowers are a single card; colour is rolled when painting (and on respawn).
721 */
722export function listPlaceableBlockPaletteEntries (catalog = null)
723{
724 const entries = [];
725 for (const def of listPlaceableBlocks())
726 {
727 if (def.id === BlockType.boulder)
728 {
729 entries.push({
730 typeId: def.id,
731 state: "boulder",
732 key: def.key,
733 displayName: "Boulder",
734 spriteName: spriteImageName("block", def.key, "boulder")
735 });
736 for (const material of ORE_BEARING_MATERIALS)
737 {
738 const state = oreBoulderState(material);
739 entries.push({
740 typeId: def.id,
741 state,
742 key: def.key,
743 displayName: oreBoulderDisplayName(state) ?? state,
744 spriteName: spriteImageName("block", def.key, state)
745 });
746 }
747 continue;
748 }
749 if (def.id === BlockType.flower)
750 {
751 const state = flowerBlockState(FLOWER_COLOR_ORDER[0]);
752 entries.push({
753 typeId: def.id,
754 state,
755 key: def.key,
756 displayName: "Flower",
757 spriteName: spriteImageName("block", def.key, state)
758 });
759 continue;
760 }
761 if (def.id === BlockType.herbPlant)
762 {
763 for (const herbId of HERB_ORDER)
764 {
765 const herb = HERB_DEFINITIONS[herbId];
766 entries.push({
767 typeId: def.id,
768 state: herbId,
769 key: def.key,
770 displayName: herb?.displayName ?? herbId,
771 spriteName: spriteImageName("block", def.key, herbId)
772 });
773 }
774 continue;
775 }
776 if (def.neighborConnect)
777 {
778 if (definitionUsesMaterialNeighborConnect(def))
779 {
780 for (const material of WOOD_TIER_ORDER)
781 {
782 const state = composeNeighborConnectState(def, material, 0);
783 const label = MATERIAL_DISPLAY_NAME[material] ?? material;
784 const noun = String(def.displayName ?? def.key).toLowerCase();
785 entries.push({
786 typeId: def.id,
787 state,
788 key: def.key,
789 displayName: `${label} ${noun}`,
790 spriteName: spriteImageName("block", def.key, state)
791 });
792 }
793 continue;
794 }
795 entries.push({
796 typeId: def.id,
797 state: "0",
798 key: def.key,
799 displayName: def.displayName,
800 spriteName: spriteImageName("block", def.key, "0")
801 });
802 continue;
803 }
804 const state = defaultStateForType(catalog, "block", def.key);
805 entries.push({
806 typeId: def.id,
807 state,
808 key: def.key,
809 displayName: def.displayName,
810 spriteName: state
811 ? spriteImageName("block", def.key, state)
812 : spriteImageName("block", def.key, def.key)
813 });
814 }
815 return entries;
816}
817
818export function groundDefinition (typeId)
819{
820 return GROUND_DEFINITIONS[typeId] ?? null;
821}
822
823export function blockDefinition (typeId)
824{
825 return BLOCK_DEFINITIONS[typeId] ?? null;
826}
827
828export function isGroundPassable (typeId)
829{
830 const def = groundDefinition(typeId);
831 if (!def)
832 { return true; }
833 return def.passable !== false;
834}
835
836export function isWaterGround (typeId)
837{
838 return !!groundDefinition(typeId)?.water;
839}
840
841export function isWadeGround (typeId)
842{
843 return !!groundDefinition(typeId)?.wades;
844}
845
846/**
847 * Liquid water for foam / wade (shallow water freezes in winter and is solid ice).
848 * Deep water stays liquid year-round.
849 */
850export function isLiquidWaterGround (typeId, seasonId = null)
851{
852 if (!isWaterGround(typeId))
853 { return false; }
854 if (typeId === GroundType.water && seasonId === SeasonId.winter)
855 { return false; }
856 return true;
857}
858
859/** Wade clip/foam only on liquid shallow water (not winter ice). */
860export function isWadeGroundInSeason (typeId, seasonId = null)
861{
862 return isWadeGround(typeId) && isLiquidWaterGround(typeId, seasonId);
863}
864
865export function isBlockPassable (typeId)
866{
867 if (typeId == null)
868 { return true; }
869
870 const def = blockDefinition(typeId);
871 return def ? def.passable : false;
872}
873
874/**
875 * Whether a block stops ranged attack / spell line of sight.
876 * `blocksRangedAttacks`: explicit override; `craftingStationId` defaults to clear;
877 * otherwise impassable blocks block and passable blocks do not.
878 */
879export function blockBlocksRangedAttacks (typeId)
880{
881 if (typeId == null)
882 { return false; }
883 const def = blockDefinition(typeId);
884 if (!def)
885 { return true; }
886 if (def.blocksRangedAttacks === false)
887 { return false; }
888 if (def.blocksRangedAttacks === true)
889 { return true; }
890 if (def.craftingStationId)
891 { return false; }
892 return def.passable === false;
893}
894
895/**
896 * Light ray occlusion for a block tile.
897 * - `clear` (0): no effect (default for passable; set `blocksLight: false` for furniture)
898 * - `partial` (1): ray continues; each such tile adds +1 to falloff distance (2× cost)
899 * - `solid` (2): ray stops (default for impassable; set `blocksLight: true` explicitly)
900 */
901export const LightOcclusion = Object.freeze({
902 clear: 0,
903 partial: 1,
904 solid: 2
905});
906
907/**
908 * Resolve light occlusion for a block tile (type + visual state).
909 * Stumps are a runtime/editor state override: no occlusion even on tree types.
910 */
911export function blockLightOcclusionForBlock (block)
912{
913 if (!block)
914 { return LightOcclusion.clear; }
915 if (isSeasonalStumpState(block.state))
916 { return LightOcclusion.clear; }
917 return blockLightOcclusion(block.typeId ?? null);
918}
919
920/**
921 * Resolve light occlusion for a block type id.
922 * `blocksLight`: `true` | `false` | `"partial"`; omitted → solid iff `!passable`.
923 * `blocksRangedAttacks`: `true` | `false`; omitted → false when `craftingStationId` is set,
924 * otherwise blocks iff `!passable` (furniture/stations may block movement but not magic/ranged).
925 * Prefer {@link blockLightOcclusionForBlock} when block state is known.
926 */
927export function blockLightOcclusion (typeId)
928{
929 if (typeId == null)
930 { return LightOcclusion.clear; }
931 const def = blockDefinition(typeId);
932 if (!def)
933 { return LightOcclusion.solid; }
934 if (def.blocksLight === "partial")
935 { return LightOcclusion.partial; }
936 if (def.blocksLight === false)
937 { return LightOcclusion.clear; }
938 if (def.blocksLight === true)
939 { return LightOcclusion.solid; }
940 return def.passable === false ? LightOcclusion.solid : LightOcclusion.clear;
941}
942
943/** True when a block fully stops light rays (not partial canopy). */
944export function isBlockOccludingLight (typeId)
945{
946 return blockLightOcclusion(typeId) === LightOcclusion.solid;
947}
948
949export function blockLightRange (typeId)
950{
951 const def = blockDefinition(typeId);
952 return def ? def.lightRangeTiles : 0;
953}
954
955export function normalizeGround (value, fallbackTypeId = GroundType.grass)
956{
957 if (typeof value === "number")
958 { return { typeId: value, state: null }; }
959 if (value && Number.isInteger(value.typeId))
960 { return { typeId: value.typeId, state: value.state ?? null }; }
961 return { typeId: fallbackTypeId, state: null };
962}
963
964export function normalizeBlock (value)
965{
966 if (!value || !Number.isInteger(value.typeId))
967 { return null; }
968 return { typeId: value.typeId, state: value.state ?? null, config: value.config ?? null };
969}
970
971export function setBlockVisualState (block, state)
972{
973 if (!block)
974 { return null; }
975 block.state = state ?? null;
976 return block;
977}