incanto 0.3.3 → 0.4.0

package/dist/3d.d.ts

@@ -543,6 +543,51 @@ declare class Environment3D {
   dispose(): void;
 }
 //#endregion
+//#region src/3d/nodes/billboard-3d.d.ts
+/** Valid `Billboard3D.mode` values — drives the prop options AND validateJson. */
+declare const BILLBOARD_GROUP_MODES: readonly ["screen", "y", "none"];
+type BillboardGroupMode = (typeof BILLBOARD_GROUP_MODES)[number];
+/**
+* Billboard3D — a transform GROUP that orients itself toward the camera every
+* rendered frame; children inherit the rotation through the scene graph. Hang
+* world-space UI off a character — HP bars, markers, icons — without
+* hand-rolling camera math in game code.
+*
+* - `mode: "screen"` (default) copies the camera's orientation wholesale, so a
+*   child rectangle projects as an upright rectangle ANYWHERE on screen. This is
+*   what flat UI wants — a yaw-only look-at visibly tilts off-center shapes when
+*   the camera pitches. (Deliberately NOT the same as Sprite3D's `"full"`, which
+*   faces the camera POSITION and keeps that perspective tilt.)
+* - `mode: "y"` yaws the group's +Z upright toward the camera (like Sprite3D's
+*   `"y"`) — for standing content that must not pitch back as the camera rises.
+* - `mode: "none"` billboarding off — the authored transform applies again on
+*   the next frame (`_syncObject3D` re-stamps it), so toggling is lossless.
+*
+* The node's own `rotation` prop is overwritten while billboarding ("none"
+* restores it — also handy in the editor to pose children with the gizmo).
+* The group keeps orienting while `visible: false` ON PURPOSE: a hidden HP bar
+* revealed later is already correct — no one-frame orientation pop. Headless
+* runs never invoke the render hook — the group keeps its authored transform.
+*/
+declare class Billboard3D extends Node3D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  /** `"screen"` copy the camera orientation (screen-aligned) · `"y"` upright
+  *  yaw-to-camera · `"none"` billboarding off (authored rotation applies). */
+  mode: BillboardGroupMode;
+  /** Last successfully billboarded WORLD orientation — reapplied on the frames
+  *  where `"y"` has no answer (camera dead overhead), because `_syncObject3D`
+  *  re-stamps the authored rotation every frame and a bare early-return would
+  *  visibly snap the group to it. Lazily created; `null` until first success. */
+  private _lastDesired;
+  /** Scene-load validation: a typo'd mode must fail HARD, not silently behave
+  *  like one of the real modes (agents self-correct on load errors). */
+  static validateJson(node: Node): void;
+  /** @internal Orient the BACKING object each rendered frame — unlike Sprite3D
+  *  (which spins only its inner quad) the whole group turns, so children follow. */
+  _onRender3D(ctx: RenderContext3D): void;
+}
+//#endregion
 //#region src/3d/nodes/camera-3d.d.ts
 /**
 * A perspective camera. Mark exactly one camera `current: true`; with none
@@ -740,7 +785,11 @@ type FoliageStyle = "mesh" | "tufts" | "blades" | "simple";
 *   (`colorA`→`colorB`, clump-coherent, dry patches) and the ported sin·cos
 *   tuft sway. Dozens of overlapping textured fans read as a DENSE meadow
 *   (잔디밭) at a fraction of the instances — the look that per-blade
-*   geometry never reaches at sane budgets.
+*   geometry never reaches at sane budgets. NOTE: tuft cards are big — drawn
+*   ~1.5× the `height` prop and wider than tall — and opaque (depth-writing),
+*   so over a field of SMALL gameplay sprites (mobs, items) they legitimately
+*   occlude actors shorter than the grass. For such fields prefer `'blades'`
+*   (thin) or keep `height` low so actors read above the grass line.
 *
 * - `'mesh'` (default, kind 'grass' only): the per-blade path — ONE
 *   InstancedMesh where every instance is a REAL tapered blade (7-vertex
@@ -786,7 +835,9 @@ declare class Foliage3D extends Node3D implements SunConsumer3D {
   /** Instance cap (hard ceiling 200_000). */
   maxInstances: number;
   /** Base blade height in meters — mesh style additionally scales it 0.55–1.7×
-  * regionally (low-frequency noise: tall patches and short worn patches). */
+  * regionally (low-frequency noise: tall patches and short worn patches), and
+  * `tufts` cards render ~1.5× this value (so 0.4 ≈ 0.6 m tall). Keep it low under
+  * small gameplay sprites or they hide behind the grass — see the `style` doc. */
   height: number;
   /** colorA = bottom/lerp-start, colorB = top/lerp-end. Refinement pass 3:
   * lifted toward the reference's warm sunlit green (the old olives read
@@ -962,6 +1013,14 @@ interface MeshMaterialProps {
   flatShading?: boolean;
   /** 0..1 surface opacity; below 1 turns on transparency (glassy gems, etc.). */
   opacity?: number;
+  /** Depth-test against the scene (default true). Set false so the mesh ALWAYS
+  * draws on top of geometry behind it — the standard trick for flat ground
+  * decals (AoE telegraphs, selection rings) that must never z-fight with or be
+  * occluded by bumpy terrain. Pair with a high `renderOrder`. */
+  depthTest?: boolean;
+  /** Write to the depth buffer (default true). Set false for additive/overlay
+  * decals so they don't occlude effects drawn after them. */
+  depthWrite?: boolean;
   /** Color texture URL (sampled sRGB, tinted by `color`). */
   map?: string;
   /** Tangent-space normal map URL (sampled linear). */
@@ -978,10 +1037,12 @@ interface MeshMaterialProps {
 * - `size [x,y,z]`: box extents; sphere/gem radius = x; capsule radius = x,
 *   height = y; plane = x·z ground plane (laid flat); cylinder radius = x, height = y
 * - `material`: `{color, metalness, roughness, wireframe, flatShading, opacity,
-*   emissive, emissiveIntensity, map, normalMap, repeat}` — `map`/`normalMap` are
-*   texture URLs loaded lazily (headless-safe: geometry and physics never
-*   wait on them), tiled by `repeat: [u, v]`. `gem` + `flatShading: true` + a low
-*   `roughness` reads as a sparkling faceted jewel (spin it for the sparkle).
+*   depthTest, depthWrite, emissive, emissiveIntensity, map, normalMap, repeat}` —
+*   `map`/`normalMap` are texture URLs loaded lazily (headless-safe: geometry and
+*   physics never wait on them), tiled by `repeat: [u, v]`. `gem` + `flatShading:
+*   true` + a low `roughness` reads as a sparkling faceted jewel (spin it for the
+*   sparkle). `depthTest: false` makes a flat `plane`/`cylinder` an always-on-top
+*   ground decal (AoE telegraph, selection ring) — no z-fighting with terrain.
 */
 declare class MeshInstance3D extends Node3D {
   static override readonly typeName: string;
@@ -1860,4 +1921,4 @@ interface WalkState {
   alpha: number;
 }
 //#endregion
-export { Area3D, AssetStore3D, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, type Environment3DConfig, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, type FlowerVariety, Flowers3D, type FogEnvironment, Foliage3D, type FoliageKind, type FoliageStyle, type Game3D, type Heightmap, type HeightmapOptions, MeshInstance3D, type MeshKind, type MeshMaterialProps, type ModelEntry, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, type Physics3DOptions, PhysicsBody3D, QUARTER_PITCH, type RenderContext3D, type RenderHook3D, Renderer3D, type Renderer3DOptions, type RigView, RigidBody3D, type Ripple, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainTheme, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_MAX_RIPPLES, Water3D, buildHeightmap, cameraRelative, createGame3D, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers };
+export { Area3D, AssetStore3D, Billboard3D, type BillboardGroupMode, Camera3D, CharacterBody3D, CharacterController3D, type CreateGame3DOptions, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, type Environment3DConfig, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, type FlowerVariety, Flowers3D, type FogEnvironment, Foliage3D, type FoliageKind, type FoliageStyle, type Game3D, type Heightmap, type HeightmapOptions, MeshInstance3D, type MeshKind, type MeshMaterialProps, type ModelEntry, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, type Physics3DOptions, PhysicsBody3D, QUARTER_PITCH, type RenderContext3D, type RenderHook3D, Renderer3D, type Renderer3DOptions, type RigView, RigidBody3D, type Ripple, type ShadowsEnvironment, type SkyEnvironment, StaticBody3D, type SunConsumer3D, type SyncOptions, type SyncResult, TERRAIN_THEMES, Terrain3D, type TerrainLayer, type TerrainTheme, Tree3D, type TreeTier, type TreeType, VOXEL_PALETTE, type VoxelBlock, VoxelGrid3D, WATER_MAX_RIPPLES, Water3D, buildHeightmap, cameraRelative, createGame3D, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers };

package/dist/3d.js

@@ -1,5 +1,5 @@
-import { a as Environment3D, c as sunDirectionFromElevationAzimuth, i as syncTree, l as sunDirectionFromSky, o as horizonColorFromSky, r as Renderer3D, s as parseEnvironment3D, t as createGame3D, u as AssetStore3D } from "./create-game-DKdR28SI.js";
-import { A as QUARTER_PITCH, C as Area3D, D as StaticBody3D, E as RigidBody3D, M as keyboardIntensity, N as movementState, O as Node3D, P as rigPose, S as terrainThemeLayers, T as PhysicsBody3D, _ as CharacterController3D, a as VoxelGrid3D, b as DEFAULT_TERRAIN_TEXTURE_BASE, c as ModelInstance3D, d as OmniLight3D, f as Foliage3D, g as FLOWER_VARIETIES, h as resolveFlowerDensity, i as VOXEL_PALETTE, j as cameraRelative, l as MeshInstance3D, m as Flowers3D, n as Water3D, o as Tree3D, p as DENSITY_PRESETS, r as WATER_MAX_RIPPLES, s as Particles3D, t as registerNodes3D, u as DirectionalLight3D, v as Camera3D, w as CharacterBody3D, x as TERRAIN_THEMES, y as Terrain3D } from "./register-CljkZG08.js";
+import { a as Environment3D, c as sunDirectionFromElevationAzimuth, i as syncTree, l as sunDirectionFromSky, o as horizonColorFromSky, r as Renderer3D, s as parseEnvironment3D, t as createGame3D, u as AssetStore3D } from "./create-game-DlTZUCSj.js";
+import { C as terrainThemeLayers, D as RigidBody3D, E as PhysicsBody3D, F as rigPose, M as cameraRelative, N as keyboardIntensity, O as StaticBody3D, P as movementState, S as TERRAIN_THEMES, T as CharacterBody3D, _ as CharacterController3D, a as VoxelGrid3D, b as Terrain3D, c as ModelInstance3D, d as OmniLight3D, f as Foliage3D, g as FLOWER_VARIETIES, h as resolveFlowerDensity, i as VOXEL_PALETTE, j as QUARTER_PITCH, k as Node3D, l as MeshInstance3D, m as Flowers3D, n as Water3D, o as Tree3D, p as DENSITY_PRESETS, r as WATER_MAX_RIPPLES, s as Particles3D, t as registerNodes3D, u as DirectionalLight3D, v as Camera3D, w as Area3D, x as DEFAULT_TERRAIN_TEXTURE_BASE, y as Billboard3D } from "./register-9mSsSUS1.js";
 import { n as splatWeights, t as buildHeightmap } from "./heightmap-CroQPEER.js";
-import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-DXODbpY1.js";
-export { Area3D, AssetStore3D, Camera3D, CharacterBody3D, CharacterController3D, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, Flowers3D, Foliage3D, MeshInstance3D, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, PhysicsBody3D, QUARTER_PITCH, Renderer3D, RigidBody3D, StaticBody3D, TERRAIN_THEMES, Terrain3D, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_MAX_RIPPLES, Water3D, buildHeightmap, cameraRelative, createGame3D, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers };
+import { n as enablePhysics3D, t as Physics3D } from "./physics-3d-Yvle9Clx.js";
+export { Area3D, AssetStore3D, Billboard3D, Camera3D, CharacterBody3D, CharacterController3D, DEFAULT_TERRAIN_TEXTURE_BASE, DirectionalLight3D, Environment3D, DENSITY_PRESETS as FLOWER_DENSITY_PRESETS, FLOWER_VARIETIES, Flowers3D, Foliage3D, MeshInstance3D, ModelInstance3D, Node3D, OmniLight3D, Particles3D, Physics3D, PhysicsBody3D, QUARTER_PITCH, Renderer3D, RigidBody3D, StaticBody3D, TERRAIN_THEMES, Terrain3D, Tree3D, VOXEL_PALETTE, VoxelGrid3D, WATER_MAX_RIPPLES, Water3D, buildHeightmap, cameraRelative, createGame3D, enablePhysics3D, horizonColorFromSky, keyboardIntensity, movementState, parseEnvironment3D, registerNodes3D, resolveFlowerDensity, rigPose, splatWeights, sunDirectionFromElevationAzimuth, sunDirectionFromSky, syncTree, terrainThemeLayers };

package/dist/{create-game-DKdR28SI.js → create-game-DlTZUCSj.js}

@@ -6,8 +6,8 @@ import { r as AudioPlayer } from "./register-BuUV1_KB.js";
 import { i as resolveRendering, n as attachTouchControls } from "./touch-031PxtCR.js";
 import { n as registerGameplayBehaviors } from "./gameplay-Ccruc3Wd.js";
 import { t as debugSources } from "./debug-draw-CZmOYjL2.js";
-import { O as Node3D, T as PhysicsBody3D, c as ModelInstance3D, t as registerNodes3D, u as DirectionalLight3D, v as Camera3D } from "./register-CljkZG08.js";
-import { n as enablePhysics3D } from "./physics-3d-DXODbpY1.js";
+import { E as PhysicsBody3D, c as ModelInstance3D, k as Node3D, t as registerNodes3D, u as DirectionalLight3D, v as Camera3D } from "./register-9mSsSUS1.js";
+import { n as enablePhysics3D } from "./physics-3d-Yvle9Clx.js";
 import { ACESFilmicToneMapping, AmbientLight, BufferAttribute, BufferGeometry, Color, DepthTexture, EquirectangularReflectionMapping, FloatType, Fog, LineBasicMaterial, LineSegments, Matrix4, Mesh, PCFShadowMap, PMREMGenerator, PerspectiveCamera, PlaneGeometry, Quaternion, Raycaster, Scene, ShaderMaterial, Vector2, Vector3, WebGLRenderTarget, WebGLRenderer } from "three";
 import { VRMLoaderPlugin, VRMUtils } from "@pixiv/three-vrm";
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";

package/dist/index.js

@@ -57,6 +57,6 @@ function newUid() {
 //#endregion
 //#region src/index.ts
 /** Engine version. Kept in sync with package.json by the release pipeline. */
-const VERSION = "0.3.3";
+const VERSION = "0.4.0";
 //#endregion
 export { AudioBuses, AudioPlayer, Behavior, CONST_REF_KEY, Engine, IncantoError, InputMap, LogManager, MusicManager, Node, PARTICLE_PRESETS, PARTICLE_PRESET_NAMES, ParticleSim, ROLLOFF_MODELS, Rng, SCENE_FORMAT, SFX_PRESETS, SFX_PRESET_NAMES, Scene, SceneTree, SfxEngine, Signal, Timer, TouchControls, VERSION, WebAudioMusicBackend, applyParticlePreset, assetUrls, attachTouchControls, clearBehaviors, clearRegistry, computeViewport, createNode, createNoise2D, crossfadeGains, duplicateNode, fadeGain, getBehavior, getNodeSchema, getNodeSignals, getNodeType, isAudioContextAvailable, isConstRef, joystickVector, jsonClone, jsonEquals, jsonKind, loadScene, mergeStaticSignals, newUid, parseNodePath, preloadUrls, registerBehavior, registerCoreNodes, registerNode, registeredBehaviors, registeredTypes, resolveConstants, resolveRendering, resolveViewport, serializeNode, spatialGain, spatialPan, synthSfx };

package/dist/{physics-3d-DXODbpY1.js → physics-3d-Yvle9Clx.js}

@@ -1,7 +1,7 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
 import { n as registerDebugSource } from "./debug-draw-CZmOYjL2.js";
-import { C as Area3D, E as RigidBody3D, O as Node3D, T as PhysicsBody3D, k as validateCollider3D, w as CharacterBody3D, y as Terrain3D } from "./register-CljkZG08.js";
+import { A as validateCollider3D, D as RigidBody3D, E as PhysicsBody3D, T as CharacterBody3D, b as Terrain3D, k as Node3D, w as Area3D } from "./register-9mSsSUS1.js";
 import { Euler, Quaternion } from "three";
 //#region src/3d/physics/physics-3d.ts
 var physics_3d_exports = /* @__PURE__ */ __exportAll({

package/dist/react.js

@@ -156,7 +156,7 @@ function IncantoCanvas(props) {
 				pointer: latest.pointer,
 				...keyboard !== void 0 ? { keyboard } : {}
 			};
-			const next = await (_gameFactory ?? (mode === "3d" ? async (o) => (await import("./create-game-DKdR28SI.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-CZHROKcT.js").then((n) => n.n)).createGame2D(o)))(opts);
+			const next = await (_gameFactory ?? (mode === "3d" ? async (o) => (await import("./create-game-DlTZUCSj.js").then((n) => n.n)).createGame3D(o) : async (o) => (await import("./create-game-CZHROKcT.js").then((n) => n.n)).createGame2D(o)))(opts);
 			if (disposed) {
 				next.dispose();
 				return;

package/dist/{register-CljkZG08.js → register-9mSsSUS1.js}

@@ -1339,9 +1339,9 @@ function blobTexture() {
 	_blobTex = new CanvasTexture(c);
 	return _blobTex;
 }
-const Z_AXIS = new Vector3(0, 0, 1);
+const Z_AXIS$1 = new Vector3(0, 0, 1);
 const _spritePos = new Vector3();
-const _dir = new Vector3();
+const _dir$1 = new Vector3();
 const _target = new Quaternion();
 const _parent = new Quaternion();
 const _sunLocal = new Vector3();
@@ -1550,22 +1550,22 @@ var Sprite3D = class extends Node3D {
 	/** @internal Aim the quad's +Z at a world point, honoring billboard mode. */
 	_faceToward(quad, targetWorld) {
 		quad.getWorldPosition(_spritePos);
-		_dir.copy(targetWorld).sub(_spritePos);
-		if (this.billboard === "y") _dir.y = 0;
-		if (_dir.lengthSq() < 1e-12) return;
-		_dir.normalize();
-		_target.setFromUnitVectors(Z_AXIS, _dir);
+		_dir$1.copy(targetWorld).sub(_spritePos);
+		if (this.billboard === "y") _dir$1.y = 0;
+		if (_dir$1.lengthSq() < 1e-12) return;
+		_dir$1.normalize();
+		_target.setFromUnitVectors(Z_AXIS$1, _dir$1);
 		quad.parent?.getWorldQuaternion(_parent);
 		quad.quaternion.copy(_parent.invert()).multiply(_target);
 	}
 	/** @internal Aim a mesh's +Z along a world DIRECTION (vs a point), honoring
 	*  billboard mode — keeps the silhouette shadow caster broad to the light. */
 	_faceDir(mesh, dir) {
-		_dir.copy(dir);
-		if (this.billboard === "y") _dir.y = 0;
-		if (_dir.lengthSq() < 1e-12) return;
-		_dir.normalize();
-		_target.setFromUnitVectors(Z_AXIS, _dir);
+		_dir$1.copy(dir);
+		if (this.billboard === "y") _dir$1.y = 0;
+		if (_dir$1.lengthSq() < 1e-12) return;
+		_dir$1.normalize();
+		_target.setFromUnitVectors(Z_AXIS$1, _dir$1);
 		mesh.parent?.getWorldQuaternion(_parent);
 		mesh.quaternion.copy(_parent.invert()).multiply(_target);
 	}
@@ -1694,6 +1694,87 @@ function resolveFrames(frames, name) {
 	return [...frames];
 }
 //#endregion
+//#region src/3d/nodes/billboard-3d.ts
+const _parentQ = new Quaternion();
+const _rotQ = new Quaternion();
+const _pos = new Vector3();
+const _camPos = new Vector3();
+const _dir = new Vector3();
+const Z_AXIS = new Vector3(0, 0, 1);
+/** Valid `Billboard3D.mode` values — drives the prop options AND validateJson. */
+const BILLBOARD_GROUP_MODES = [
+	"screen",
+	"y",
+	"none"
+];
+/**
+* Billboard3D — a transform GROUP that orients itself toward the camera every
+* rendered frame; children inherit the rotation through the scene graph. Hang
+* world-space UI off a character — HP bars, markers, icons — without
+* hand-rolling camera math in game code.
+*
+* - `mode: "screen"` (default) copies the camera's orientation wholesale, so a
+*   child rectangle projects as an upright rectangle ANYWHERE on screen. This is
+*   what flat UI wants — a yaw-only look-at visibly tilts off-center shapes when
+*   the camera pitches. (Deliberately NOT the same as Sprite3D's `"full"`, which
+*   faces the camera POSITION and keeps that perspective tilt.)
+* - `mode: "y"` yaws the group's +Z upright toward the camera (like Sprite3D's
+*   `"y"`) — for standing content that must not pitch back as the camera rises.
+* - `mode: "none"` billboarding off — the authored transform applies again on
+*   the next frame (`_syncObject3D` re-stamps it), so toggling is lossless.
+*
+* The node's own `rotation` prop is overwritten while billboarding ("none"
+* restores it — also handy in the editor to pose children with the gizmo).
+* The group keeps orienting while `visible: false` ON PURPOSE: a hidden HP bar
+* revealed later is already correct — no one-frame orientation pop. Headless
+* runs never invoke the render hook — the group keeps its authored transform.
+*/
+var Billboard3D = class extends Node3D {
+	static typeName = "Billboard3D";
+	static props = { mode: {
+		default: "screen",
+		options: BILLBOARD_GROUP_MODES
+	} };
+	/** `"screen"` copy the camera orientation (screen-aligned) · `"y"` upright
+	*  yaw-to-camera · `"none"` billboarding off (authored rotation applies). */
+	mode = "screen";
+	/** Last successfully billboarded WORLD orientation — reapplied on the frames
+	*  where `"y"` has no answer (camera dead overhead), because `_syncObject3D`
+	*  re-stamps the authored rotation every frame and a bare early-return would
+	*  visibly snap the group to it. Lazily created; `null` until first success. */
+	_lastDesired = null;
+	/** Scene-load validation: a typo'd mode must fail HARD, not silently behave
+	*  like one of the real modes (agents self-correct on load errors). */
+	static validateJson(node) {
+		const b = node;
+		if (!BILLBOARD_GROUP_MODES.includes(b.mode)) throw new IncantoError("BAD_FORMAT", `Billboard3D '${node.name}' mode must be one of [${BILLBOARD_GROUP_MODES.join(", ")}], got '${b.mode}'.`, {
+			prop: "mode",
+			validOptions: BILLBOARD_GROUP_MODES
+		});
+	}
+	/** @internal Orient the BACKING object each rendered frame — unlike Sprite3D
+	*  (which spins only its inner quad) the whole group turns, so children follow. */
+	_onRender3D(ctx) {
+		if (this.mode === "none") return;
+		const o = this._ensureObject3D();
+		if (this.mode === "screen") ctx.camera.getWorldQuaternion(_rotQ);
+		else {
+			o.getWorldPosition(_pos);
+			ctx.camera.getWorldPosition(_camPos);
+			_dir.copy(_camPos).sub(_pos);
+			_dir.y = 0;
+			if (_dir.lengthSq() >= 1e-12) _rotQ.setFromUnitVectors(Z_AXIS, _dir.normalize());
+			else if (this._lastDesired) _rotQ.copy(this._lastDesired);
+			else return;
+		}
+		if (!this._lastDesired) this._lastDesired = new Quaternion();
+		this._lastDesired.copy(_rotQ);
+		o.parent?.getWorldQuaternion(_parentQ);
+		if (o.parent) o.quaternion.copy(_parentQ.invert()).multiply(_rotQ);
+		else o.quaternion.copy(_rotQ);
+	}
+};
+//#endregion
 //#region src/3d/nodes/camera-3d.ts
 /**
 * A perspective camera. Mark exactly one camera `current: true`; with none
@@ -3981,7 +4062,11 @@ const BEND_AIR_GAP = .5;
 *   (`colorA`→`colorB`, clump-coherent, dry patches) and the ported sin·cos
 *   tuft sway. Dozens of overlapping textured fans read as a DENSE meadow
 *   (잔디밭) at a fraction of the instances — the look that per-blade
-*   geometry never reaches at sane budgets.
+*   geometry never reaches at sane budgets. NOTE: tuft cards are big — drawn
+*   ~1.5× the `height` prop and wider than tall — and opaque (depth-writing),
+*   so over a field of SMALL gameplay sprites (mobs, items) they legitimately
+*   occlude actors shorter than the grass. For such fields prefer `'blades'`
+*   (thin) or keep `height` low so actors read above the grass line.
 *
 * - `'mesh'` (default, kind 'grass' only): the per-blade path — ONE
 *   InstancedMesh where every instance is a REAL tapered blade (7-vertex
@@ -4062,7 +4147,9 @@ var Foliage3D = class Foliage3D extends Node3D {
 	/** Instance cap (hard ceiling 200_000). */
 	maxInstances = 5e4;
 	/** Base blade height in meters — mesh style additionally scales it 0.55–1.7×
-	* regionally (low-frequency noise: tall patches and short worn patches). */
+	* regionally (low-frequency noise: tall patches and short worn patches), and
+	* `tufts` cards render ~1.5× this value (so 0.4 ≈ 0.6 m tall). Keep it low under
+	* small gameplay sprites or they hide behind the grass — see the `style` doc. */
 	height = .25;
 	/** colorA = bottom/lerp-start, colorB = top/lerp-end. Refinement pass 3:
 	* lifted toward the reference's warm sunlit green (the old olives read
@@ -4797,6 +4884,8 @@ const MATERIAL_KEYS = [
 	"wireframe",
 	"flatShading",
 	"opacity",
+	"depthTest",
+	"depthWrite",
 	"map",
 	"normalMap",
 	"repeat"
@@ -4807,10 +4896,12 @@ const MATERIAL_KEYS = [
 * - `size [x,y,z]`: box extents; sphere/gem radius = x; capsule radius = x,
 *   height = y; plane = x·z ground plane (laid flat); cylinder radius = x, height = y
 * - `material`: `{color, metalness, roughness, wireframe, flatShading, opacity,
-*   emissive, emissiveIntensity, map, normalMap, repeat}` — `map`/`normalMap` are
-*   texture URLs loaded lazily (headless-safe: geometry and physics never
-*   wait on them), tiled by `repeat: [u, v]`. `gem` + `flatShading: true` + a low
-*   `roughness` reads as a sparkling faceted jewel (spin it for the sparkle).
+*   depthTest, depthWrite, emissive, emissiveIntensity, map, normalMap, repeat}` —
+*   `map`/`normalMap` are texture URLs loaded lazily (headless-safe: geometry and
+*   physics never wait on them), tiled by `repeat: [u, v]`. `gem` + `flatShading:
+*   true` + a low `roughness` reads as a sparkling faceted jewel (spin it for the
+*   sparkle). `depthTest: false` makes a flat `plane`/`cylinder` an always-on-top
+*   ground decal (AoE telegraph, selection ring) — no z-fighting with terrain.
 */
 var MeshInstance3D = class extends Node3D {
 	static typeName = "MeshInstance3D";
@@ -4873,6 +4964,8 @@ var MeshInstance3D = class extends Node3D {
 		const opacity = this.material.opacity ?? 1;
 		mat.opacity = opacity;
 		mat.transparent = opacity < 1;
+		mat.depthTest = this.material.depthTest ?? true;
+		mat.depthWrite = this.material.depthWrite ?? true;
 		const flat = this.material.flatShading ?? false;
 		if (mat.flatShading !== flat) {
 			mat.flatShading = flat;
@@ -4948,7 +5041,12 @@ function validateMaterial(material, name) {
 		const value = material[key];
 		if (value !== void 0 && !(typeof value === "number" && value >= 0 && value <= 1)) fail(`material.${key} must be a number in 0..1, got ${JSON.stringify(value)}.`);
 	}
-	for (const key of ["wireframe", "flatShading"]) {
+	for (const key of [
+		"wireframe",
+		"flatShading",
+		"depthTest",
+		"depthWrite"
+	]) {
 		const value = material[key];
 		if (value !== void 0 && typeof value !== "boolean") fail(`material.${key} must be a boolean, got ${JSON.stringify(value)}.`);
 	}
@@ -10993,6 +11091,7 @@ function registerNodes3D() {
 	registerNode(MeshInstance3D);
 	registerNode(Sprite3D);
 	registerNode(AnimatedSprite3D);
+	registerNode(Billboard3D);
 	registerNode(CharacterController3D);
 	registerNode(VoxelGrid3D);
 	registerNode(Terrain3D);
@@ -11010,4 +11109,4 @@ function registerNodes3D() {
 	registerNode(CharacterBody3D);
 }
 //#endregion
-export { QUARTER_PITCH as A, Area3D as C, StaticBody3D as D, RigidBody3D as E, keyboardIntensity as M, movementState as N, Node3D as O, rigPose as P, terrainThemeLayers as S, PhysicsBody3D as T, CharacterController3D as _, VoxelGrid3D as a, DEFAULT_TERRAIN_TEXTURE_BASE as b, ModelInstance3D as c, OmniLight3D as d, Foliage3D as f, FLOWER_VARIETIES as g, resolveFlowerDensity as h, VOXEL_PALETTE as i, cameraRelative as j, validateCollider3D as k, MeshInstance3D as l, Flowers3D as m, Water3D as n, Tree3D as o, DENSITY_PRESETS as p, WATER_MAX_RIPPLES as r, Particles3D as s, registerNodes3D as t, DirectionalLight3D as u, Camera3D as v, CharacterBody3D as w, TERRAIN_THEMES as x, Terrain3D as y };
+export { validateCollider3D as A, terrainThemeLayers as C, RigidBody3D as D, PhysicsBody3D as E, rigPose as F, cameraRelative as M, keyboardIntensity as N, StaticBody3D as O, movementState as P, TERRAIN_THEMES as S, CharacterBody3D as T, CharacterController3D as _, VoxelGrid3D as a, Terrain3D as b, ModelInstance3D as c, OmniLight3D as d, Foliage3D as f, FLOWER_VARIETIES as g, resolveFlowerDensity as h, VOXEL_PALETTE as i, QUARTER_PITCH as j, Node3D as k, MeshInstance3D as l, Flowers3D as m, Water3D as n, Tree3D as o, DENSITY_PRESETS as p, WATER_MAX_RIPPLES as r, Particles3D as s, registerNodes3D as t, DirectionalLight3D as u, Camera3D as v, Area3D as w, DEFAULT_TERRAIN_TEXTURE_BASE as x, Billboard3D as y };

package/dist/test.js

@@ -5,7 +5,7 @@ import { n as jsonEquals, t as jsonClone } from "./json-BLk7H2Qa.js";
 import { i as getNodeSchema, s as mergeStaticProps } from "./registry-BVJ2HbCn.js";
 import { n as registerGameplayBehaviors } from "./gameplay-Ccruc3Wd.js";
 import { t as registerNodes2D } from "./register-DPEV9_9t.js";
-import { t as registerNodes3D } from "./register-CljkZG08.js";
+import { t as registerNodes3D } from "./register-9mSsSUS1.js";
 import { t as registerNodesNet } from "./register-Dasmnurl.js";
 //#region src/test/index.ts
 /**
@@ -132,7 +132,7 @@ async function runScript(json, opts) {
 		const { enablePhysics2D } = await import("./physics-2d-KuMWPTf6.js").then((n) => n.r);
 		await enablePhysics2D(engine);
 	} else if (physics === "3d" || physics === "auto" && scene.dimension === "3d") {
-		const { enablePhysics3D } = await import("./physics-3d-DXODbpY1.js").then((n) => n.r);
+		const { enablePhysics3D } = await import("./physics-3d-Yvle9Clx.js").then((n) => n.r);
 		await enablePhysics3D(engine);
 	}
 	const failures = [];
@@ -237,7 +237,7 @@ async function createPlaySession(json, opts = {}) {
 		const { enablePhysics2D } = await import("./physics-2d-KuMWPTf6.js").then((n) => n.r);
 		await enablePhysics2D(engine);
 	} else if (physics === "3d" || physics === "auto" && scene.dimension === "3d") {
-		const { enablePhysics3D } = await import("./physics-3d-DXODbpY1.js").then((n) => n.r);
+		const { enablePhysics3D } = await import("./physics-3d-Yvle9Clx.js").then((n) => n.r);
 		await enablePhysics3D(engine);
 	}
 	const stepMs = 1e3 / (opts.fixedHz ?? 60);

package/editor/assets/{agent8-CXBTOrkj.js → agent8-B-6dWaK9.js}

@@ -1 +1 @@
-import{t as e}from"./index-DMghTAy4.js";async function t(t){return new n((await e(()=>import(`./GameServer-C56iOUgF.js`),[],import.meta.url)).GameServer,t)}var n=class{raw;active=new Map;constructor(e,t){this.raw=new e({...t})}get account(){return this.raw.account}get connected(){return this.raw.connected}connect(){return this.rawConnect()}rawConnect(){return this.raw.connect({onDisconnect:()=>void this.reconnect()})}disconnect(){for(let e of this.active.values())e.off();return this.active.clear(),this.raw.disconnect()}remoteFunction(e,t,n){return this.raw.remoteFunction(e,t,n)}track(e){let t=Symbol(`sub`),n={make:e,off:e()};return this.active.set(t,n),()=>{n.off(),this.active.delete(t)}}async reconnect(){await this.rawConnect();for(let e of this.active.values())e.off(),e.off=e.make()}subscribeRoomState(e,t){return this.track(()=>this.raw.subscribeRoomState(e,t))}subscribeRoomMyState(e,t){return this.track(()=>this.raw.subscribeRoomMyState(e,t))}subscribeRoomAllUserStates(e,t){return this.track(()=>this.raw.subscribeRoomAllUserStates(e,e=>{let n={};for(let t of e??[]){if(!t||typeof t.account!=`string`||t.__leaved)continue;let{account:e,__updated:r,__leaved:i,...a}=t;n[e]=a}t(n)}))}subscribeRoomCollection(e,t,n){return this.track(()=>this.raw.subscribeRoomCollection(e,t,({items:e})=>{let t={};for(let n of e??[])n&&typeof n.__id==`string`&&(t[n.__id]=n);n(t)}))}onRoomMessage(e,t,n){return this.track(()=>this.raw.onRoomMessage(e,t,n))}onRoomUserJoin(e,t){return this.track(()=>this.raw.onRoomUserJoin(e,t))}onRoomUserLeave(e,t){return this.track(()=>this.raw.onRoomUserLeave(e,t))}subscribeGlobalState(e){return this.track(()=>this.raw.subscribeGlobalState(e))}subscribeGlobalMyState(e){return this.track(()=>this.raw.subscribeGlobalMyState(e))}subscribeGlobalUserState(e,t){return this.track(()=>this.raw.subscribeGlobalUserState(e,t))}subscribeGlobalCollection(e,t){return this.track(()=>this.raw.subscribeGlobalCollection(e,({items:e})=>{let n={};for(let t of e??[])t&&typeof t.__id==`string`&&(n[t.__id]=t);t(n)}))}subscribeAsset(e,t){return this.track(()=>this.raw.subscribeAsset(e,t))}onGlobalMessage(e,t){return this.track(()=>this.raw.onGlobalMessage(e,t))}};export{t as createAgent8Server};
+import{t as e}from"./index-BN0hHg3U.js";async function t(t){return new n((await e(()=>import(`./GameServer-C56iOUgF.js`),[],import.meta.url)).GameServer,t)}var n=class{raw;active=new Map;constructor(e,t){this.raw=new e({...t})}get account(){return this.raw.account}get connected(){return this.raw.connected}connect(){return this.rawConnect()}rawConnect(){return this.raw.connect({onDisconnect:()=>void this.reconnect()})}disconnect(){for(let e of this.active.values())e.off();return this.active.clear(),this.raw.disconnect()}remoteFunction(e,t,n){return this.raw.remoteFunction(e,t,n)}track(e){let t=Symbol(`sub`),n={make:e,off:e()};return this.active.set(t,n),()=>{n.off(),this.active.delete(t)}}async reconnect(){await this.rawConnect();for(let e of this.active.values())e.off(),e.off=e.make()}subscribeRoomState(e,t){return this.track(()=>this.raw.subscribeRoomState(e,t))}subscribeRoomMyState(e,t){return this.track(()=>this.raw.subscribeRoomMyState(e,t))}subscribeRoomAllUserStates(e,t){return this.track(()=>this.raw.subscribeRoomAllUserStates(e,e=>{let n={};for(let t of e??[]){if(!t||typeof t.account!=`string`||t.__leaved)continue;let{account:e,__updated:r,__leaved:i,...a}=t;n[e]=a}t(n)}))}subscribeRoomCollection(e,t,n){return this.track(()=>this.raw.subscribeRoomCollection(e,t,({items:e})=>{let t={};for(let n of e??[])n&&typeof n.__id==`string`&&(t[n.__id]=n);n(t)}))}onRoomMessage(e,t,n){return this.track(()=>this.raw.onRoomMessage(e,t,n))}onRoomUserJoin(e,t){return this.track(()=>this.raw.onRoomUserJoin(e,t))}onRoomUserLeave(e,t){return this.track(()=>this.raw.onRoomUserLeave(e,t))}subscribeGlobalState(e){return this.track(()=>this.raw.subscribeGlobalState(e))}subscribeGlobalMyState(e){return this.track(()=>this.raw.subscribeGlobalMyState(e))}subscribeGlobalUserState(e,t){return this.track(()=>this.raw.subscribeGlobalUserState(e,t))}subscribeGlobalCollection(e,t){return this.track(()=>this.raw.subscribeGlobalCollection(e,({items:e})=>{let n={};for(let t of e??[])t&&typeof t.__id==`string`&&(n[t.__id]=t);t(n)}))}subscribeAsset(e,t){return this.track(()=>this.raw.subscribeAsset(e,t))}onGlobalMessage(e,t){return this.track(()=>this.raw.onGlobalMessage(e,t))}};export{t as createAgent8Server};