incanto 0.1.0 → 0.2.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-Dl2pjA8e.js"></script>
+    <script type="module" crossorigin src="./assets/index-CxJ6dZLb.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.1.0",
+  "version": "0.2.0",
   "description": "Vibe-coding-first web game engine SDK — JSON-driven scenes on three.js",
   "keywords": [
     "game-engine",

package/schemas/scene.schema.json

@@ -175,6 +175,9 @@
         {
           "$ref": "#/$defs/AnimatedSprite2D"
         },
+        {
+          "$ref": "#/$defs/AnimatedSprite3D"
+        },
         {
           "$ref": "#/$defs/Area2D"
         },
@@ -253,6 +256,9 @@
         {
           "$ref": "#/$defs/Sprite2D"
         },
+        {
+          "$ref": "#/$defs/Sprite3D"
+        },
         {
           "$ref": "#/$defs/StaticBody2D"
         },
@@ -453,6 +459,160 @@
       },
       "required": ["name", "type"]
     },
+    "AnimatedSprite3D": {
+      "type": "object",
+      "x-signals": ["animationFinished"],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "AnimatedSprite3D"
+        },
+        "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
+            },
+            "texture": {
+              "type": "string",
+              "default": ""
+            },
+            "size": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 2,
+              "maxItems": 2,
+              "default": [1, 1]
+            },
+            "billboard": {
+              "type": "string",
+              "enum": ["y", "full", "none"],
+              "default": "y"
+            },
+            "anchor": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 2,
+              "maxItems": 2,
+              "default": [0.5, 0]
+            },
+            "tint": {
+              "type": "string",
+              "default": "#ffffff"
+            },
+            "opacity": {
+              "type": "number",
+              "default": 1
+            },
+            "flipX": {
+              "type": "boolean",
+              "default": false
+            },
+            "pixelArt": {
+              "type": "boolean",
+              "default": true
+            },
+            "alphaTest": {
+              "type": "number",
+              "default": 0.5
+            },
+            "sheet": {
+              "type": "string",
+              "default": ""
+            },
+            "frameWidth": {
+              "type": "number",
+              "default": 0
+            },
+            "frameHeight": {
+              "type": "number",
+              "default": 0
+            },
+            "animations": {
+              "type": "object",
+              "default": {}
+            },
+            "autoplay": {
+              "type": "string",
+              "default": ""
+            }
+          },
+          "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"]
+    },
     "Area2D": {
       "type": "object",
       "x-signals": ["triggerEnter", "triggerExit"],
@@ -3378,6 +3538,139 @@
       },
       "required": ["name", "type"]
     },
+    "Sprite3D": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "uid": {
+          "type": "string"
+        },
+        "type": {
+          "const": "Sprite3D"
+        },
+        "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
+            },
+            "texture": {
+              "type": "string",
+              "default": ""
+            },
+            "size": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 2,
+              "maxItems": 2,
+              "default": [1, 1]
+            },
+            "billboard": {
+              "type": "string",
+              "enum": ["y", "full", "none"],
+              "default": "y"
+            },
+            "anchor": {
+              "type": "array",
+              "items": {
+                "type": "number"
+              },
+              "minItems": 2,
+              "maxItems": 2,
+              "default": [0.5, 0]
+            },
+            "tint": {
+              "type": "string",
+              "default": "#ffffff"
+            },
+            "opacity": {
+              "type": "number",
+              "default": 1
+            },
+            "flipX": {
+              "type": "boolean",
+              "default": false
+            },
+            "pixelArt": {
+              "type": "boolean",
+              "default": true
+            },
+            "alphaTest": {
+              "type": "number",
+              "default": 0.5
+            }
+          },
+          "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"]
+    },
     "StaticBody2D": {
       "type": "object",
       "x-signals": ["triggerEnter", "triggerExit"],

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

@@ -65,6 +65,47 @@ All 3D nodes extend `Node3D` and therefore have the transform props:
 | `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 |
 | `castShadow` / `receiveShadow` | `false` | |
 
+### `Sprite3D` / `AnimatedSprite3D` (2D billboard sprites — the 2.5D look)
+A 2D image drawn as a camera-facing quad inside the 3D world (Octopath / Don't
+Starve / classic MapleStory in a 3D scene). Unlit — the art shows as-is. The
+visual is an inner quad, so child nodes inherit neither its sizing nor its
+billboard spin. `Sprite3D`:
+
+| Prop | Default | Notes |
+|---|---|---|
+| `texture` | `""` | image URL (sampled sRGB, tinted by `tint`); empty = hidden |
+| `size` | `[1,1]` | quad `[width, height]` in world METERS (not pixels) |
+| `billboard` | `"y"` | `"y"` upright — yaws to face the camera, stays vertical when you look down (characters, props) · `"full"` always faces the camera (items, FX) · `"none"` fixed to the node's own rotation |
+| `anchor` | `[0.5,0]` | which point of the sprite sits at the node origin (0..1). `[0.5,0]` = bottom-center → the FEET stand on the ground; `[0.5,0.5]` = center |
+| `tint` | `"#ffffff"` | multiplies the texture (near-white keeps original colors) |
+| `opacity` | `1` | `< 1` turns on alpha blending |
+| `flipX` | `false` | mirror horizontally (face left vs right) |
+| `pixelArt` | `true` | nearest-filter for crisp pixels (`false` = smooth linear) |
+| `alphaTest` | `0.5` | discard texels below this alpha — a crisp cutout that depth-sorts against 3D geometry (a tree occludes it; it occludes the ground). Use `0` + `opacity < 1` for soft/feathered sprites (smoke, glow) |
+
+`AnimatedSprite3D` adds spritesheet animation (ALL Sprite3D props, plus):
+
+| Prop | Default | Notes |
+|---|---|---|
+| `sheet` | `""` | spritesheet image URL (used instead of `texture`) |
+| `frameWidth` / `frameHeight` | `0` | one frame cell's pixel size in the sheet |
+| `animations` | `{}` | `{ name: { frames, fps, loop } }` — `frames` is an inclusive `[start, end]` RANGE or an explicit list `[0,2,5]`. e.g. `{ "walk": {"frames":[0,7],"fps":10,"loop":true}, "attack": {"frames":[8,11],"fps":14,"loop":false} }` |
+| `autoplay` | `""` | animation name to start on load |
+
+- API: `node.play('walk')`, `node.stop()`. A non-looping animation clamps on its last frame and emits **`animationFinished(name)`** — chain `attack → idle` from it. Frames index left→right, top→bottom (`cols = floor(sheetWidth / frameWidth)`).
+
+```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" } }
+```
+Drop sprites onto terrain height like any 3D node (their feet are the anchor). In
+a top-down / quarter view, `billboard: "y"` keeps characters readable from every
+camera yaw.
+
 ### `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-node-reference.md

@@ -36,6 +36,32 @@ description: GENERATED complete reference of every Incanto node type — props,
 
 Signals: `animationFinished(name)`
 
+## `AnimatedSprite3D` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `position` | `[0,0,0]` | array |
+| `rotation` | `[0,0,0]` | array |
+| `scale` | `[1,1,1]` | array |
+| `visible` | `true` | boolean |
+| `renderOrder` | `0` | number |
+| `texture` | `""` | string |
+| `size` | `[1,1]` | array |
+| `billboard` | `"y"` | one of: `y` `full` `none` |
+| `anchor` | `[0.5,0]` | array |
+| `tint` | `"#ffffff"` | string |
+| `opacity` | `1` | number |
+| `flipX` | `false` | boolean |
+| `pixelArt` | `true` | boolean |
+| `alphaTest` | `0.5` | number |
+| `sheet` | `""` | string |
+| `frameWidth` | `0` | number |
+| `frameHeight` | `0` | number |
+| `animations` | `{}` | object |
+| `autoplay` | `""` | string |
+
+Signals: `animationFinished(name)`
+
 ## `Area2D` — `incanto/2d`
 
 | Prop | Default | Kind |
@@ -480,6 +506,25 @@ Signals: `triggerEnter(other)` · `triggerExit(other)`
 | `tint` | `"#ffffff"` | string |
 | `opacity` | `1` | number |
 
+## `Sprite3D` — `incanto`
+
+| Prop | Default | Kind |
+|---|---|---|
+| `position` | `[0,0,0]` | array |
+| `rotation` | `[0,0,0]` | array |
+| `scale` | `[1,1,1]` | array |
+| `visible` | `true` | boolean |
+| `renderOrder` | `0` | number |
+| `texture` | `""` | string |
+| `size` | `[1,1]` | array |
+| `billboard` | `"y"` | one of: `y` `full` `none` |
+| `anchor` | `[0.5,0]` | array |
+| `tint` | `"#ffffff"` | string |
+| `opacity` | `1` | number |
+| `flipX` | `false` | boolean |
+| `pixelArt` | `true` | boolean |
+| `alphaTest` | `0.5` | number |
+
 ## `StaticBody2D` — `incanto/2d`
 
 | Prop | Default | Kind |