incanto 0.3.3 → 0.4.0

package/editor/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Incanto Scene Editor</title>
     <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'><rect width='16' height='16' rx='3' fill='%236ee7dc'/><text x='8' y='12' text-anchor='middle' font-size='11' font-family='monospace' fill='%230e1018'>i</text></svg>" />
-    <script type="module" crossorigin src="./assets/index-DMghTAy4.js"></script>
+    <script type="module" crossorigin src="./assets/index-BN0hHg3U.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/GameServer-C56iOUgF.js">
     <link rel="stylesheet" crossorigin href="./assets/index-DF3tMeKJ.css">
   </head>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incanto",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",

package/schemas/scene.schema.json

@@ -187,6 +187,9 @@
         {
           "$ref": "#/$defs/AudioPlayer"
         },
+        {
+          "$ref": "#/$defs/Billboard3D"
+        },
         {
           "$ref": "#/$defs/Camera2D"
         },
@@ -918,6 +921,97 @@
       },
       "required": ["name", "type"]
     },
+    "Billboard3D": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "Billboard3D"
+        },
+        "groups": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tags": {
+          "type": "object"
+        },
+        "props": {
+          "type": "object",
+          "properties": {
+            "position": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 3,
+              "maxItems": 3,
+              "default": [0, 0, 0]
+            },
+            "rotation": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 3,
+              "maxItems": 3,
+              "default": [0, 0, 0]
+            },
+            "scale": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 3,
+              "maxItems": 3,
+              "default": [1, 1, 1]
+            },
+            "visible": {
+              "type": "boolean",
+              "default": true
+            },
+            "renderOrder": {
+              "type": "number",
+              "default": 0
+            },
+            "mode": {
+              "type": "string",
+              "enum": ["screen", "y", "none"],
+              "default": "screen"
+            }
+          },
+          "additionalProperties": false
+        },
+        "script": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "props": {
+              "type": "object"
+            }
+          },
+          "required": ["name"]
+        },
+        "network": {
+          "type": "object"
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/node"
+          }
+        }
+      },
+      "required": ["name", "type"]
+    },
     "Camera2D": {
       "type": "object",
       "properties": {

package/skills/incanto-building-3d-games.md

@@ -62,7 +62,7 @@ All 3D nodes extend `Node3D` and therefore have the transform props:
 |---|---|---|
 | `mesh` | `"box"` | `box \| sphere \| capsule \| plane \| cylinder \| gem` — `gem` is a faceted crystal (icosahedron); with `material.flatShading: true` + low `roughness` it reads as a sparkling jewel (spin/tumble it for the sparkle) |
 | `size` | `[1,1,1]` | box: extents · sphere/gem: radius = x · capsule: radius = x, height = y · plane: x·z ground (laid FLAT on XZ) · cylinder: radius = x, height = y |
-| `material` | `{}` | `{color: '#hex', metalness: 0..1, roughness: 0..1, opacity: 0..1, wireframe, flatShading, emissive, emissiveIntensity, map, normalMap, repeat: [u,v]}` — the object IS the material state: omitted keys reset to defaults (`#ffffff`, 0, 1, 1, false, false). `opacity < 1` turns on transparency; `flatShading` gives faceted per-face glints (the gem sparkle). `map`/`normalMap` are texture URLs (lazy-loaded, headless-safe; map samples sRGB, normalMap linear), tiled `repeat` times across each face — box/plane UVs span 0..1 per face, so for worldspace density use `repeat: [length/tile, height/tile]` (e.g. a 6×2.5 m brick wall at one tile per 2 m → `[3, 1.25]`). `color` tints the map (near-white keeps the texture's own color). NB: under ACES a very bright `emissiveIntensity` blows out to white — keep it modest (~1–2) + a saturated color for a vivid GLOWING look. Unknown keys, malformed `repeat`, or `repeat` without a map hard-fail at load |
+| `material` | `{}` | `{color: '#hex', metalness: 0..1, roughness: 0..1, opacity: 0..1, wireframe, flatShading, depthTest, depthWrite, emissive, emissiveIntensity, map, normalMap, repeat: [u,v]}` — the object IS the material state: omitted keys reset to defaults (`#ffffff`, 0, 1, 1, false, false, depthTest/Write true). `opacity < 1` turns on transparency; `flatShading` gives faceted per-face glints (the gem sparkle). `depthTest: false` (+ a high `renderOrder`) makes a flat `plane`/`cylinder` an ALWAYS-ON-TOP ground decal — AoE telegraphs, selection/spawn rings — that never z-fights with or is hidden by bumpy terrain (`depthWrite: false` keeps it from occluding later effects). `map`/`normalMap` are texture URLs (lazy-loaded, headless-safe; map samples sRGB, normalMap linear), tiled `repeat` times across each face — box/plane UVs span 0..1 per face, so for worldspace density use `repeat: [length/tile, height/tile]` (e.g. a 6×2.5 m brick wall at one tile per 2 m → `[3, 1.25]`). `color` tints the map (near-white keeps the texture's own color). NB: under ACES a very bright `emissiveIntensity` blows out to white — keep it modest (~1–2) + a saturated color for a vivid GLOWING look. Unknown keys, malformed `repeat`, or `repeat` without a map hard-fail at load |
 | `castShadow` / `receiveShadow` | `false` | |
 
 ### `Sprite3D` / `AnimatedSprite3D` (2D billboard sprites — the 2.5D look)
@@ -108,6 +108,54 @@ Drop sprites onto terrain height like any 3D node (their feet are the anchor). I
 a top-down / quarter view, `billboard: "y"` keeps characters readable from every
 camera yaw.
 
+### `Billboard3D` (a group that turns toward the camera — children follow)
+A transform container that orients itself toward the camera every rendered frame;
+**children inherit the rotation** through the scene graph. Hang world-space UI
+under it — HP bars, pickup markers, floating icons — instead of hand-rolling
+camera math in game code. (There is no 3D text node — a nameplate or damage
+number is a canvas-rendered texture on a child `Sprite3D`.)
+
+| Prop | Default | Notes |
+|---|---|---|
+| `mode` | `"screen"` | `"screen"` copies the camera's orientation wholesale (screen-aligned) — a child rectangle projects as an **upright rectangle anywhere on screen** · `"y"` stays vertical and only yaws toward the camera (standing content) · `"none"` billboarding off — the authored rotation applies again |
+
+- Use `"screen"` for flat UI shapes (bars, plates). A yaw-only look-at — the
+  tempting hand-rolled version — visibly TILTS off-center shapes when the camera
+  pitches down; `"screen"` is immune. (This is deliberately not the same as
+  Sprite3D's `"full"`, which faces the camera POSITION and keeps that tilt.)
+- Unlike `Sprite3D` (which spins only its own textured quad, never its children),
+  `Billboard3D` rotates the whole group. Parent one under a character and offset
+  it upward. The node's own `rotation` prop is overwritten while billboarding —
+  set `mode: "none"` to pose children with the editor gizmo, then switch back.
+- A typo'd `mode` (e.g. Sprite3D's `"full"`) fails HARD at scene load — it never
+  silently falls back to another mode.
+- It keeps orienting while `visible: false` on purpose: a hidden HP bar revealed
+  on first hit is already correctly oriented (no one-frame pop).
+
+```json
+{ "name": "Slime", "type": "AnimatedSprite3D",
+  "props": {
+    "position": [4, 0, -2], "size": [1.5, 1.5],
+    "sheet": "https://example.com/slime.png", "frameWidth": 32, "frameHeight": 32,
+    "animations": { "idle": { "frames": [0, 3], "fps": 4, "loop": true } },
+    "autoplay": "idle" },
+  "children": [
+    { "name": "HpBar", "type": "Billboard3D", "props": { "position": [0, 1.8, 0] },
+      "children": [
+        { "name": "Back", "type": "MeshInstance3D",
+          "props": { "mesh": "box", "size": [1, 0.12, 0.04],
+                     "material": { "color": "#150a0a" } } },
+        { "name": "Fill", "type": "MeshInstance3D",
+          "props": { "mesh": "box", "size": [1, 0.12, 0.06], "position": [0, 0, 0.01],
+                     "material": { "color": "#ff3b3b", "emissive": "#ff3b3b" } } }
+      ] }
+  ] }
+```
+Drain the fill from game code with **`scale`, not `size`** — resizing a mesh
+rebuilds its geometry every call, scaling is free: `Fill.scale = [frac, 1, 1]`
+and `Fill.position = [-(1 - frac) / 2, 0, 0.01]`. The offsets stay local to the
+(rotated) bar, so the drain always hugs the bar's left edge.
+
 ### `Camera3D`
 `fov: 60`, `near: 0.1`, `far: 1000`, `current: false`.
 Mark exactly ONE camera `current: true` (otherwise the first camera in tree order is used).

package/skills/incanto-environment.md

@@ -268,7 +268,7 @@ Four looks, picked by `style`:
 
 | style | what renders | when to pick it |
 |---|---|---|
-| `"tufts"` | ONE InstancedMesh of 3-crossed-quad CARDS (12 verts each) carrying a baked multi-blade alpha-cutout texture, per-instance clump-coherent green tints + dry patches, ported sin·cos sway — kind `grass` only | the dense 잔디밭 — the ez-tree demo's actual grass mechanism; overlapping textured fans read as a full meadow at a fraction of the instances. Layer a sparse `mesh` field on top for close-up blade silhouettes |
+| `"tufts"` | ONE InstancedMesh of 3-crossed-quad CARDS (12 verts each) carrying a baked multi-blade alpha-cutout texture, per-instance clump-coherent green tints + dry patches, ported sin·cos sway — kind `grass` only | the dense 잔디밭 — the ez-tree demo's actual grass mechanism; overlapping textured fans read as a full meadow at a fraction of the instances. Layer a sparse `mesh` field on top for close-up blade silhouettes. ⚠️ Cards are BIG (drawn ~1.5× `height`, wide) + opaque, so over a field of small gameplay sprites (mobs/items) they hide actors shorter than the grass — there, prefer `"blades"` (thin) or keep `height` low |
 | `"mesh"` (default) | ONE InstancedMesh where EVERY instance is a real tapered blade (7-vertex strip) curved along a vertex-shader quadratic bezier — kind `grass` only | real per-blade geometry — best up close; reads thin at field scale |
 | `"blades"` | TWO crossed quads per slot; the fragment shader draws 8 procedural SDF blades per quad — kind `grass` only; bends to the player (`interaction`) and receives scene `fog` (distant fields melt into the haze like the mesh grass / trees / water) | pinning the pre-mesh ported look |
 | `"simple"` | legacy crossed quads, per-instance colorA→colorB lerp, whole-field shear sway | `flowers`/`reeds` (their only look); ultra-cheap set dressing |

package/skills/incanto-node-reference.md

@@ -109,6 +109,17 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 
 Signals: `finished`
 
+## `Billboard3D` — `incanto/3d`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `position` | `[0,0,0]` | array |
+| `rotation` | `[0,0,0]` | array |
+| `scale` | `[1,1,1]` | array |
+| `visible` | `true` | boolean |
+| `renderOrder` | `0` | number |
+| `mode` | `"screen"` | one of: `screen` `y` `none` |
+
 ## `Camera2D` — `incanto/2d`
 
 | Prop | Default | Kind |