phibelle-kit 1.0.9 → 1.0.12

package/README.md

@@ -23,5 +23,5 @@ npx phibelle-kit watch <sceneId>
 
 1. `cd <scene-folder>` to enter the scene directory.
 2. `npm install` to install dependencies (for types and intellisense).
-3. `npm run watch` in the scene folder to push edits, or run `npx phibelle-kit watch <sceneId>` from the parent directory.
+3. `npm run watch` in the scene folder to push edits, or run `npx phibelle-kit watch <sceneId>` from the project root.
 

package/dist/commands/watch-scene.js

@@ -13,7 +13,7 @@ import { BASE_URL } from "../lib/public-env.js";
 function createWatchCallbacks() {
     return {
         onPushed: (file) => console.log(chalk.green("  ✓ Pushed " + file + " to Convex")),
-        onNewEntity: (engineId) => console.log(chalk.green("  ✓ Created new entity " + engineId + " (entity-" + engineId + ".tsx)")),
+        onNewEntity: (engineId, fileName) => console.log(chalk.green("  ✓ Created new entity " + engineId + (fileName ? " (" + fileName + ")" : ""))),
         onError: (file, err) => console.log(chalk.red("  ✖ Failed to push " + file + ": " + err.message)),
     };
 }
@@ -71,7 +71,7 @@ export async function watchSceneCommand(sceneId) {
                     scriptWatcher = null;
                     try {
                         await unpackageScene(scene._id, sceneDir);
-                        console.log(chalk.green("  ✓ Re-unpackaged scene scripts (scene.tsx, entity-*.tsx, manifest.json)"));
+                        console.log(chalk.green("  ✓ Re-unpackaged scene scripts (scene.tsx, <entity-name>-<id>.tsx, manifest.json)"));
                         scriptWatcher = startScriptWatcher(scene, sceneDir);
                     }
                     catch (e) {

package/dist/lib/file-system.d.ts

@@ -1,3 +1,5 @@
+export declare const SCENE_APP_DIR = "app";
+export declare function getSceneAppDir(sceneDir: string): string;
 export declare function folderExists(folderPath: string): boolean;
 export declare function createFolder(folderPath: string): void;
 /** Scene name to folder name: lowercased, spaces to hyphens, safe for filesystem. */

package/dist/lib/file-system.js

@@ -1,5 +1,9 @@
 import * as path from "node:path";
 import * as fs from "fs";
+export const SCENE_APP_DIR = "app";
+export function getSceneAppDir(sceneDir) {
+    return path.join(sceneDir, SCENE_APP_DIR);
+}
 export function folderExists(folderPath) {
     return fs.existsSync(folderPath);
 }

package/dist/lib/first-run-setup.d.ts

@@ -2,7 +2,7 @@ import { type ScriptWatcher } from "./script-watcher.js";
 import type { Scene } from "./types.js";
 export type WatchCallbacks = {
     onPushed: (file: string) => void;
-    onNewEntity: (engineId: number) => void;
+    onNewEntity: (engineId: number, fileName?: string) => void;
     onError: (file: string, err: Error) => void;
 };
 /** Create scene dir, write scene.json, setup package.json/global.d.ts; log install hint if needed. */

package/dist/lib/first-run-setup.js

@@ -23,7 +23,7 @@ export function setupSceneFiles(scene, sceneDir, ignoreHint = false) {
 export async function unpackageWithLogging(sceneId, sceneDir, failHint) {
     try {
         await unpackageScene(sceneId, sceneDir);
-        console.log(chalk.green("  ✓ Unpacked scene scripts (scene.tsx, entity-*.tsx, manifest.json)"));
+        console.log(chalk.green("  ✓ Unpacked scene scripts (scene.tsx, <entity-name>-<id>.tsx, manifest.json)"));
     }
     catch (e) {
         console.log(chalk.yellow("  ⚠ Could not unpackage scene scripts: " + toErrorMessage(e)));

package/dist/lib/scene-packaging.d.ts

@@ -1,6 +1,13 @@
-/** Matches entity script filenames; group 1 is engine id. Use in both .test() and .match(). */
+/** Convert entity display name to slug: "Main Enemy" → "main-enemy". */
+export declare function entityNameToSlug(name: string): string;
+/** Convert slug to display name: "main-enemy" → "Main Enemy". */
+export declare function slugToEntityName(slug: string): string;
+/**
+ * Matches entity script filenames: <entity-name>-<engineId>.tsx (e.g. main-enemy-1.tsx).
+ * Group 1 = slug, group 2 = engine id.
+ */
 export declare const ENTITY_FILE_RE: RegExp;
 export declare function unpackageScene(sceneId: string, sceneDir: string): Promise<void>;
 export declare function pushScriptChange(sceneId: string, sceneDir: string, changedFile: string): Promise<void>;
-/** Add a new entity to the scene when user creates entity-<engineId>.tsx locally. */
-export declare function pushNewEntity(sceneId: string, sceneDir: string, engineId: number): Promise<void>;
+/** Add a new entity to the scene when user creates <entity-name>-<engineId>.tsx locally. */
+export declare function pushNewEntity(sceneId: string, sceneDir: string, engineId: number, fileName: string): Promise<void>;

package/dist/lib/scene-packaging.js

@@ -1,5 +1,6 @@
 import * as fs from "fs/promises";
 import * as path from "path";
+import { getSceneAppDir } from "./file-system.js";
 import { queryOnce, mutateOnce } from "./convex-client.js";
 import { api } from "../convex/_generated/api.js";
 import { getSessionId } from "./conf.js";
@@ -22,8 +23,28 @@ function parseSceneJson(content) {
         throw new Error("Invalid scene file: not valid JSON");
     }
 }
-/** Matches entity script filenames; group 1 is engine id. Use in both .test() and .match(). */
-export const ENTITY_FILE_RE = /^entity-(\d+)\.tsx$/;
+/** Convert entity display name to slug: "Main Enemy" → "main-enemy". */
+export function entityNameToSlug(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+    return slug || "entity";
+}
+/** Convert slug to display name: "main-enemy" → "Main Enemy". */
+export function slugToEntityName(slug) {
+    if (!slug || slug === "entity")
+        return "Entity";
+    return slug
+        .split("-")
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+}
+/**
+ * Matches entity script filenames: <entity-name>-<engineId>.tsx (e.g. main-enemy-1.tsx).
+ * Group 1 = slug, group 2 = engine id.
+ */
+export const ENTITY_FILE_RE = /^([a-z0-9]+(?:-[a-z0-9]+)*)-(\d+)\.tsx$/;
 async function uploadSceneJsonAndUpdate(sceneId, json) {
     const uploadUrl = await mutateOnce(api.storage.generateUploadUrl, {});
     if (typeof uploadUrl !== "string") {
@@ -53,13 +74,14 @@ async function uploadSceneJsonAndUpdate(sceneId, json) {
 export async function unpackageScene(sceneId, sceneDir) {
     const content = await getSceneFileContent(sceneId);
     const parsed = parseSceneJson(content);
-    await fs.mkdir(sceneDir, { recursive: true });
+    const appDir = getSceneAppDir(sceneDir);
+    await fs.mkdir(appDir, { recursive: true });
     // Remove existing entity files so entities deleted in the editor are removed from disk
     try {
-        const entries = await fs.readdir(sceneDir, { withFileTypes: true });
+        const entries = await fs.readdir(appDir, { withFileTypes: true });
         for (const ent of entries) {
             if (ent.isFile() && ENTITY_FILE_RE.test(ent.name)) {
-                await fs.unlink(path.join(sceneDir, ent.name));
+                await fs.unlink(path.join(appDir, ent.name));
             }
         }
     }
@@ -71,16 +93,23 @@ export async function unpackageScene(sceneId, sceneDir) {
         sceneScript: "scene.tsx",
         entities: {},
     };
-    await fs.writeFile(path.join(sceneDir, "scene.tsx"), parsed.sceneScriptStore?.sceneScript ?? "", "utf8");
+    await fs.writeFile(path.join(appDir, "scene.tsx"), parsed.sceneScriptStore?.sceneScript ?? "", "utf8");
     for (const idStr of Object.keys(entities)) {
         const entity = entities[idStr];
         if (!entity || typeof entity.script !== "string")
             continue;
         const engineId = String(entity.engineId ?? idStr);
-        const fileName = `entity-${engineId}.tsx`;
+        let slug = entityNameToSlug(entity.name ?? "Entity");
+        const redundantPrefix = `entity-${engineId}`;
+        if (slug === redundantPrefix)
+            slug = "entity";
+        else if (slug.startsWith(redundantPrefix + "-"))
+            slug = slug.slice((redundantPrefix + "-").length);
+        const fileName = `${slug}-${engineId}.tsx`;
         manifest.entities[engineId] = fileName;
-        await fs.writeFile(path.join(sceneDir, fileName), entity.script, "utf8");
+        await fs.writeFile(path.join(appDir, fileName), entity.script, "utf8");
     }
+    await fs.mkdir(sceneDir, { recursive: true });
     await fs.writeFile(path.join(sceneDir, "manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
 }
 export async function pushScriptChange(sceneId, sceneDir, changedFile) {
@@ -95,7 +124,8 @@ export async function pushScriptChange(sceneId, sceneDir, changedFile) {
     const manifest = JSON.parse(manifestRaw);
     const content = await getSceneFileContent(sceneId);
     const parsed = parseSceneJson(content);
-    const filePath = path.join(sceneDir, changedFile);
+    const appDir = getSceneAppDir(sceneDir);
+    const filePath = path.join(appDir, changedFile);
     let fileContent;
     try {
         fileContent = await fs.readFile(filePath, "utf8");
@@ -131,8 +161,8 @@ export async function pushScriptChange(sceneId, sceneDir, changedFile) {
 const DEFAULT_POSITION = '{"x":0,"y":0,"z":0}';
 const DEFAULT_ROTATION = '{"isEuler":true,"_x":0,"_y":0,"_z":0,"_order":"XYZ"}';
 const DEFAULT_SCALE = '{"x":1,"y":1,"z":1}';
-/** Add a new entity to the scene when user creates entity-<engineId>.tsx locally. */
-export async function pushNewEntity(sceneId, sceneDir, engineId) {
+/** Add a new entity to the scene when user creates <entity-name>-<engineId>.tsx locally. */
+export async function pushNewEntity(sceneId, sceneDir, engineId, fileName) {
     const manifestPath = path.join(sceneDir, "manifest.json");
     let manifestRaw;
     try {
@@ -148,8 +178,8 @@ export async function pushNewEntity(sceneId, sceneDir, engineId) {
     }
     const content = await getSceneFileContent(sceneId);
     const parsed = parseSceneJson(content);
-    const fileName = `entity-${engineId}.tsx`;
-    const filePath = path.join(sceneDir, fileName);
+    const appDir = getSceneAppDir(sceneDir);
+    const filePath = path.join(appDir, fileName);
     let script;
     try {
         script = await fs.readFile(filePath, "utf8");
@@ -157,6 +187,9 @@ export async function pushNewEntity(sceneId, sceneDir, engineId) {
     catch {
         throw new Error(`Could not read file: ${fileName}`);
     }
+    const match = fileName.match(ENTITY_FILE_RE);
+    const slug = match ? match[1] : "entity";
+    const entityDisplayName = slugToEntityName(slug);
     if (!parsed.entityStore) {
         parsed.entityStore = {
             _currId: 0,
@@ -173,7 +206,7 @@ export async function pushNewEntity(sceneId, sceneDir, engineId) {
         store.rootEntities.push(engineId);
     }
     store.entities[idStr] = {
-        name: `Entity-${engineId}`,
+        name: entityDisplayName,
         engineId,
         childrenIdsSet: [],
         childrenIds: [],

package/dist/lib/script-watcher.d.ts

@@ -3,7 +3,7 @@ export type ScriptWatcher = {
 };
 export type WatchCallbacks = {
     onPushed: (file: string) => void;
-    onNewEntity: (engineId: number) => void;
+    onNewEntity: (engineId: number, fileName?: string) => void;
     onError: (file: string, err: Error) => void;
 };
-export declare function createScriptWatcher(sceneId: string, sceneDir: string, onPushed: (file: string) => void, onNewEntity: (engineId: number) => void, onError: (file: string, err: Error) => void): ScriptWatcher;
+export declare function createScriptWatcher(sceneId: string, sceneDir: string, onPushed: (file: string) => void, onNewEntity: (engineId: number, fileName?: string) => void, onError: (file: string, err: Error) => void): ScriptWatcher;

package/dist/lib/script-watcher.js

@@ -1,10 +1,12 @@
 import * as path from "path";
 import * as fs from "fs";
 import chokidar from "chokidar";
+import { getSceneAppDir } from "./file-system.js";
 import { pushScriptChange, pushNewEntity, ENTITY_FILE_RE } from "./scene-packaging.js";
 const DEBOUNCE_MS = 600;
 export function createScriptWatcher(sceneId, sceneDir, onPushed, onNewEntity, onError) {
     const manifestPath = path.join(sceneDir, "manifest.json");
+    const appDir = getSceneAppDir(sceneDir);
     function readManifest() {
         try {
             const raw = fs.readFileSync(manifestPath, "utf8");
@@ -42,12 +44,12 @@ export function createScriptWatcher(sceneId, sceneDir, onPushed, onNewEntity, on
             }
             const entityMatch = basename.match(ENTITY_FILE_RE);
             if (entityMatch) {
-                const engineId = parseInt(entityMatch[1], 10);
+                const engineId = parseInt(entityMatch[2], 10);
                 const isNew = !manifest.entities[String(engineId)];
                 if (isNew) {
                     try {
-                        await pushNewEntity(sceneId, sceneDir, engineId);
-                        onNewEntity(engineId);
+                        await pushNewEntity(sceneId, sceneDir, engineId, basename);
+                        onNewEntity(engineId, basename);
                     }
                     catch (err) {
                         onError(basename, err instanceof Error ? err : new Error(String(err)));
@@ -65,7 +67,7 @@ export function createScriptWatcher(sceneId, sceneDir, onPushed, onNewEntity, on
             }
         }, DEBOUNCE_MS);
     }
-    const watcher = chokidar.watch(sceneDir, { ignoreInitial: true });
+    const watcher = chokidar.watch(appDir, { ignoreInitial: true });
     watcher.on("change", (filePath) => {
         const basename = path.basename(filePath);
         if (basename === "manifest.json")

package/dist/package/agents-md.d.ts

@@ -2,4 +2,4 @@
  * AGENTS.md content written into the scene directory when cloning.
  * Explains how the Phibelle engine works for AI agents and developers.
  */
-export declare const AGENTS_MD = "# Phibelle Engine \u2014 How It Works\n\nThis document describes how the Phibelle 3D engine runs your scene and entity scripts. Use it when editing `scene.tsx` and `entity-*.tsx` files or when an AI agent needs to understand the runtime.\n\n## Overview\n\n- **Phibelle** is a React Three Fiber based 3D engine used in the [Phibelle Studio](https://phibelle.studio) editor.\n- A **scene** has one **scene script** (`scene.tsx`) and zero or more **entity scripts** (`entity-<engineId>.tsx`).\n- You can **create new entities** by adding new entity script files (`entity-<engineId>.tsx`); when the watcher is running, they are synced and the new entities appear in the scene.\n- The engine **concatenates** these scripts and runs them in a single live-editing environment with pre-injected globals (no `import`/`export`).\n\n## Runtime Model\n\n1. **Scene script** must define a component named `SceneRender` that receives `sceneProperties` and `children` and renders an `R3F.Canvas` (or equivalent). It **must** render `{children}` inside the canvas; that is where entity trees are rendered.\n2. **Entity scripts** each define a component named `Render<engineId>` (e.g. `Render1`, `Render42`). The engine builds a registry mapping `engineId` \u2192 render component and mounts entities in a tree (root entities first, then children).\n3. **Live code** is produced by: (1) scene script, (2) all entity scripts, (3) a small bootstrap that wraps the scene in an error boundary, passes `entityRenderRegistry` into `PhibelleRoot`, and calls `render(<PhibelleScene />)`. Your scripts run inside that bootstrap with no direct imports.\n\n## What You Can Use in Scripts (Namespaces)\n\nScripts run with these globals; **do not** use `import` or `export`.\n\n| Namespace | Purpose |\n|-----------|---------|\n| `React` | Hooks and utilities: `React.useState`, `React.useEffect`, `React.useRef`, `React.memo`, etc. |\n| `THREE` | Three.js: `THREE.Vector3`, `THREE.Euler`, `THREE.Mesh`, `THREE.Color`, etc. |\n| `R3F` | React Three Fiber: `R3F.Canvas`, `R3F.useThree`, `R3F.useFrame`, `R3F.extend` |\n| `DREI` | @react-three/drei: `DREI.Environment`, `DREI.OrbitControls`, `DREI.Text`, `DREI.Html`, `DREI.Float`, `DREI.MeshTransmissionMaterial`, etc. |\n| `UIKIT` | @react-three/uikit for 3D UI |\n| `RAPIER` | @react-three/rapier for physics: `RAPIER.Physics`, `RAPIER.RigidBody`, `RAPIER.Collider`, etc. |\n| `PHI` | Engine-specific: `PHI.useEngineMode`, `PHI.usePlayModeFrame`, `PHI.useGamepad`, `PHI.useEntityThreeObject`, `PHI.phibelleResetSelectedEntityIds`, `PHI.globalStore` |\n\n## Scene Script (`scene.tsx`)\n\n- **Component name**: Must be `SceneRender`.\n- **Props**: `sceneProperties: PHI.Property[]`, `children: React.ReactNode`.\n- **Responsibility**: Create the single `R3F.Canvas`, set up lights/environment, and render `{children}`. Attach `onPointerMissed={PHI.phibelleResetSelectedEntityIds}` on the Canvas to clear selection when clicking empty space.\n\nExample:\n\n```tsx\nconst SceneRender = ({\n  sceneProperties,\n  children,\n}: {\n  sceneProperties: PHI.Property[];\n  children: React.ReactNode;\n}) => (\n  <R3F.Canvas\n    shadows\n    frameloop=\"always\"\n    gl={{ preserveDrawingBuffer: true }}\n    onPointerMissed={PHI.phibelleResetSelectedEntityIds}\n  >\n    <DREI.Environment preset=\"city\" />\n    {children}\n  </R3F.Canvas>\n);\n```\n\n## Entity Scripts (`entity-<engineId>.tsx`)\n\n- **Component name**: Must be `Render<engineId>` (e.g. `Render1` for `entity-1.tsx`).\n- **Props**: `entityData: PHI.EntityData`.\n- **entityData** contains: `name`, `engineId`, `threeId`, `parentId`, `childrenIds`, `transform`, `properties`.\n- **Properties**: Use `entityData.properties` **by index** (order is fixed in the editor), e.g. `const [colorProp, speedProp] = entityData.properties;`.\n- **Edit vs Play**: Use `PHI.useEngineMode()` \u2192 `{ editMode, playMode }`. For per-frame game logic use **`PHI.usePlayModeFrame(callback)`** only (not `R3F.useFrame`), so logic does not run in edit mode. Show helpers/gizmos only when `editMode === true`.\n\nExample:\n\n```tsx\nconst Render1 = ({ entityData }: { entityData: PHI.EntityData }) => {\n  const [colorProp] = entityData.properties;\n  const { editMode, playMode } = PHI.useEngineMode();\n\n  PHI.usePlayModeFrame((state, delta) => {\n    // Game logic here; runs only in play mode\n  });\n\n  return (\n    <group>\n      <mesh>\n        <boxGeometry args={[1, 1, 1]} />\n        <meshStandardMaterial color={colorProp.value} />\n      </mesh>\n      {editMode && <DREI.Helper type={THREE.BoxHelper} args={[\"yellow\"]} />}\n    </group>\n  );\n};\n```\n\n## Creating New Entities\n\nYou can add new entities to the scene by creating new entity script files. Add a file named `entity-<engineId>.tsx` (e.g. `entity-2.tsx`, `entity-3.tsx`) with a component `Render<engineId>` (e.g. `Render2`, `Render3`). When **watch** is running (`npm run watch` or `npx phibelle-kit watch <sceneId>`), the watcher detects the new file and creates the corresponding entity in the Phibelle Studio scene. Use a unique `engineId` that does not already exist in `manifest.json`.\n\n## File Layout After Clone\n\n- `scene.json`: Full scene state (from the app); used by the CLI, not by the runtime.\n- `scene.tsx`: Scene script (single `SceneRender`).\n- `entity-<engineId>.tsx`: One file per entity; each exports a `Render<engineId>` component by convention.\n- `manifest.json`: Maps engine IDs to filenames for the watch/sync process.\n- `package.json`: Scripts: `watch` (sync edits to the app), and dependencies for types/IntelliSense.\n- `global.d.ts`: Declares global `PHI`, `THREE`, `R3F`, `DREI`, `UIKIT`, `RAPIER` for type checking.\n\n## Sync Flow (phibelle-kit)\n\n- **clone**: Fetches scene from the app, creates the folder, writes `scene.json`, `package.json`, `global.d.ts`, `AGENTS.md`, and unpacks `scene.tsx`, `entity-*.tsx`, `manifest.json`.\n- **watch**: Watches the scene directory; when you change a script file, it pushes that file\u2019s content back to the scene in the app (and can create new entities when you add `entity-<id>.tsx`).\n\nEdits you make in `scene.tsx` or `entity-*.tsx` are synced to the Phibelle Studio scene when the watcher is running (`npm run watch` or `npx phibelle-kit watch <sceneId>`).\n";
+export declare const AGENTS_MD = "# Phibelle Engine \u2014 How It Works\n\nThis document describes how the Phibelle 3D engine runs your scene and entity scripts. Use it when editing `scene.tsx` and `<entity-name>-<id>.tsx` files or when an AI agent needs to understand the runtime.\n\n## Overview\n\n- **Phibelle** is a React Three Fiber based 3D engine used in the [Phibelle Studio](https://phibelle.studio) editor.\n- A **scene** has one **scene script** (`scene.tsx`) and zero or more **entity scripts** (`<entity-name>-<engineId>.tsx`, e.g. `main-enemy-1.tsx`). Entity names are lowercased with hyphens (e.g. \"Main Enemy\" \u2192 `main-enemy-1.tsx`).\n- You can **create new entities** by adding new entity script files (`<entity-name>-<engineId>.tsx`); when the watcher is running, they are synced and the new entities appear in the scene.\n- The engine **concatenates** these scripts and runs them in a single live-editing environment with pre-injected globals (no `import`/`export`).\n\n## Runtime Model\n\n1. **Scene script** must define a component named `SceneRender` that receives `sceneProperties` and `children` and renders an `R3F.Canvas` (or equivalent). It **must** render `{children}` inside the canvas; that is where entity trees are rendered.\n2. **Entity scripts** each define a component named `Render<engineId>` (e.g. `Render1`, `Render42`). The engine builds a registry mapping `engineId` \u2192 render component and mounts entities in a tree (root entities first, then children).\n3. **Live code** is produced by: (1) scene script, (2) all entity scripts, (3) a small bootstrap that wraps the scene in an error boundary, passes `entityRenderRegistry` into `PhibelleRoot`, and calls `render(<PhibelleScene />)`. Your scripts run inside that bootstrap with no direct imports.\n\n## What You Can Use in Scripts (Namespaces)\n\nScripts run with these globals; **do not** use `import` or `export`.\n\n| Namespace | Purpose |\n|-----------|---------|\n| `React` | Hooks and utilities: `React.useState`, `React.useEffect`, `React.useRef`, `React.memo`, etc. |\n| `THREE` | Three.js: `THREE.Vector3`, `THREE.Euler`, `THREE.Mesh`, `THREE.Color`, etc. |\n| `R3F` | React Three Fiber: `R3F.Canvas`, `R3F.useThree`, `R3F.useFrame`, `R3F.extend` |\n| `DREI` | @react-three/drei: `DREI.Environment`, `DREI.OrbitControls`, `DREI.Text`, `DREI.Html`, `DREI.Float`, `DREI.MeshTransmissionMaterial`, etc. |\n| `UIKIT` | @react-three/uikit for 3D UI |\n| `RAPIER` | @react-three/rapier for physics: `RAPIER.Physics`, `RAPIER.RigidBody`, `RAPIER.Collider`, etc. |\n| `PHI` | Engine-specific: `PHI.useEngineMode`, `PHI.usePlayModeFrame`, `PHI.useGamepad`, `PHI.useEntityThreeObject`, `PHI.phibelleResetSelectedEntityIds`, `PHI.globalStore` |\n\n## Scene Script (`scene.tsx`)\n\n- **Component name**: Must be `SceneRender`.\n- **Props**: `sceneProperties: PHI.Property[]`, `children: React.ReactNode`.\n- **Responsibility**: Create the single `R3F.Canvas`, set up lights/environment, and render `{children}`. Attach `onPointerMissed={PHI.phibelleResetSelectedEntityIds}` on the Canvas to clear selection when clicking empty space.\n\nExample:\n\n```tsx\nconst SceneRender = ({\n  sceneProperties,\n  children,\n}: {\n  sceneProperties: PHI.Property[];\n  children: React.ReactNode;\n}) => (\n  <R3F.Canvas\n    shadows\n    frameloop=\"always\"\n    gl={{ preserveDrawingBuffer: true }}\n    onPointerMissed={PHI.phibelleResetSelectedEntityIds}\n  >\n    <DREI.Environment preset=\"city\" />\n    {children}\n  </R3F.Canvas>\n);\n```\n\n## Entity Scripts (`<entity-name>-<engineId>.tsx`)\n\n- **File name**: `<entity-name>-<engineId>.tsx` where entity name is lowercased with hyphens (e.g. `main-enemy-1.tsx` for an entity named \"Main Enemy\" with engineId 1).\n- **Component name**: Must be `Render<engineId>` (e.g. `Render1` for `main-enemy-1.tsx`).\n- **Props**: `entityData: PHI.EntityData`.\n- **entityData** contains: `name`, `engineId`, `threeId`, `parentId`, `childrenIds`, `transform`, `properties`.\n- **Properties**: Use `entityData.properties` **by index** (order is fixed in the editor), e.g. `const [colorProp, speedProp] = entityData.properties;`.\n- **Edit vs Play**: Use `PHI.useEngineMode()` \u2192 `{ editMode, playMode }`. For per-frame game logic use **`PHI.usePlayModeFrame(callback)`** only (not `R3F.useFrame`), so logic does not run in edit mode. Show helpers/gizmos only when `editMode === true`.\n\nExample:\n\n```tsx\nconst Render1 = ({ entityData }: { entityData: PHI.EntityData }) => {\n  const [colorProp] = entityData.properties;\n  const { editMode, playMode } = PHI.useEngineMode();\n\n  PHI.usePlayModeFrame((state, delta) => {\n    // Game logic here; runs only in play mode\n  });\n\n  return (\n    <group>\n      <mesh>\n        <boxGeometry args={[1, 1, 1]} />\n        <meshStandardMaterial color={colorProp.value} />\n      </mesh>\n      {editMode && <DREI.Helper type={THREE.BoxHelper} args={[\"yellow\"]} />}\n    </group>\n  );\n};\n```\n\n## Creating New Entities\n\nYou can add new entities to the scene by creating new entity script files. Add a file named `<entity-name>-<engineId>.tsx` (e.g. `player-2.tsx`, `main-enemy-3.tsx`) with a component `Render<engineId>` (e.g. `Render2`, `Render3`). The entity name in the filename is lowercased with hyphens (e.g. \"Main Enemy\" \u2192 `main-enemy`). When **watch** is running (`npm run watch` or `npx phibelle-kit watch <sceneId>`), the watcher detects the new file and creates the corresponding entity in the Phibelle Studio scene. Use a unique `engineId` that does not already exist in `manifest.json`.\n\n## File Layout After Clone\n\n- `scene.json`: Full scene state (from the app); used by the CLI, not by the runtime.\n- `manifest.json`: Maps engine IDs to filenames for the watch/sync process.\n- `package.json`: Scripts: `watch` (sync edits to the app), and dependencies for types/IntelliSense.\n- `global.d.ts`: Declares global `PHI`, `THREE`, `R3F`, `DREI`, `UIKIT`, `RAPIER` for type checking.\n- `app/scene.tsx`: Scene script (single `SceneRender`).\n- `app/<entity-name>-<engineId>.tsx`: One file per entity (e.g. `main-enemy-1.tsx`); each exports a `Render<engineId>` component by convention.\n\n## Sync Flow (phibelle-kit)\n\n- **clone**: Fetches scene from the app, creates the folder, writes `scene.json`, `package.json`, `global.d.ts`, `AGENTS.md`, and unpacks `scene.tsx`, `<entity-name>-<id>.tsx`, `manifest.json`.\n- **watch**: Watches the scene directory; when you change a script file, it pushes that file\u2019s content back to the scene in the app (and can create new entities when you add `<entity-name>-<id>.tsx`).\n\nEdits you make in `scene.tsx` or `<entity-name>-<id>.tsx` are synced to the Phibelle Studio scene when the watcher is running (`npm run watch` or `npx phibelle-kit watch <sceneId>`).\n";

package/dist/package/agents-md.js

@@ -4,13 +4,13 @@
  */
 export const AGENTS_MD = `# Phibelle Engine — How It Works
 
-This document describes how the Phibelle 3D engine runs your scene and entity scripts. Use it when editing \`scene.tsx\` and \`entity-*.tsx\` files or when an AI agent needs to understand the runtime.
+This document describes how the Phibelle 3D engine runs your scene and entity scripts. Use it when editing \`scene.tsx\` and \`<entity-name>-<id>.tsx\` files or when an AI agent needs to understand the runtime.
 
 ## Overview
 
 - **Phibelle** is a React Three Fiber based 3D engine used in the [Phibelle Studio](https://phibelle.studio) editor.
-- A **scene** has one **scene script** (\`scene.tsx\`) and zero or more **entity scripts** (\`entity-<engineId>.tsx\`).
-- You can **create new entities** by adding new entity script files (\`entity-<engineId>.tsx\`); when the watcher is running, they are synced and the new entities appear in the scene.
+- A **scene** has one **scene script** (\`scene.tsx\`) and zero or more **entity scripts** (\`<entity-name>-<engineId>.tsx\`, e.g. \`main-enemy-1.tsx\`). Entity names are lowercased with hyphens (e.g. "Main Enemy" → \`main-enemy-1.tsx\`).
+- You can **create new entities** by adding new entity script files (\`<entity-name>-<engineId>.tsx\`); when the watcher is running, they are synced and the new entities appear in the scene.
 - The engine **concatenates** these scripts and runs them in a single live-editing environment with pre-injected globals (no \`import\`/\`export\`).
 
 ## Runtime Model
@@ -61,9 +61,10 @@ const SceneRender = ({
 );
 \`\`\`
 
-## Entity Scripts (\`entity-<engineId>.tsx\`)
+## Entity Scripts (\`<entity-name>-<engineId>.tsx\`)
 
-- **Component name**: Must be \`Render<engineId>\` (e.g. \`Render1\` for \`entity-1.tsx\`).
+- **File name**: \`<entity-name>-<engineId>.tsx\` where entity name is lowercased with hyphens (e.g. \`main-enemy-1.tsx\` for an entity named "Main Enemy" with engineId 1).
+- **Component name**: Must be \`Render<engineId>\` (e.g. \`Render1\` for \`main-enemy-1.tsx\`).
 - **Props**: \`entityData: PHI.EntityData\`.
 - **entityData** contains: \`name\`, \`engineId\`, \`threeId\`, \`parentId\`, \`childrenIds\`, \`transform\`, \`properties\`.
 - **Properties**: Use \`entityData.properties\` **by index** (order is fixed in the editor), e.g. \`const [colorProp, speedProp] = entityData.properties;\`.
@@ -94,21 +95,21 @@ const Render1 = ({ entityData }: { entityData: PHI.EntityData }) => {
 
 ## Creating New Entities
 
-You can add new entities to the scene by creating new entity script files. Add a file named \`entity-<engineId>.tsx\` (e.g. \`entity-2.tsx\`, \`entity-3.tsx\`) with a component \`Render<engineId>\` (e.g. \`Render2\`, \`Render3\`). When **watch** is running (\`npm run watch\` or \`npx phibelle-kit watch <sceneId>\`), the watcher detects the new file and creates the corresponding entity in the Phibelle Studio scene. Use a unique \`engineId\` that does not already exist in \`manifest.json\`.
+You can add new entities to the scene by creating new entity script files. Add a file named \`<entity-name>-<engineId>.tsx\` (e.g. \`player-2.tsx\`, \`main-enemy-3.tsx\`) with a component \`Render<engineId>\` (e.g. \`Render2\`, \`Render3\`). The entity name in the filename is lowercased with hyphens (e.g. "Main Enemy" → \`main-enemy\`). When **watch** is running (\`npm run watch\` or \`npx phibelle-kit watch <sceneId>\`), the watcher detects the new file and creates the corresponding entity in the Phibelle Studio scene. Use a unique \`engineId\` that does not already exist in \`manifest.json\`.
 
 ## File Layout After Clone
 
 - \`scene.json\`: Full scene state (from the app); used by the CLI, not by the runtime.
-- \`scene.tsx\`: Scene script (single \`SceneRender\`).
-- \`entity-<engineId>.tsx\`: One file per entity; each exports a \`Render<engineId>\` component by convention.
 - \`manifest.json\`: Maps engine IDs to filenames for the watch/sync process.
 - \`package.json\`: Scripts: \`watch\` (sync edits to the app), and dependencies for types/IntelliSense.
 - \`global.d.ts\`: Declares global \`PHI\`, \`THREE\`, \`R3F\`, \`DREI\`, \`UIKIT\`, \`RAPIER\` for type checking.
+- \`app/scene.tsx\`: Scene script (single \`SceneRender\`).
+- \`app/<entity-name>-<engineId>.tsx\`: One file per entity (e.g. \`main-enemy-1.tsx\`); each exports a \`Render<engineId>\` component by convention.
 
 ## Sync Flow (phibelle-kit)
 
-- **clone**: Fetches scene from the app, creates the folder, writes \`scene.json\`, \`package.json\`, \`global.d.ts\`, \`AGENTS.md\`, and unpacks \`scene.tsx\`, \`entity-*.tsx\`, \`manifest.json\`.
-- **watch**: Watches the scene directory; when you change a script file, it pushes that file’s content back to the scene in the app (and can create new entities when you add \`entity-<id>.tsx\`).
+- **clone**: Fetches scene from the app, creates the folder, writes \`scene.json\`, \`package.json\`, \`global.d.ts\`, \`AGENTS.md\`, and unpacks \`scene.tsx\`, \`<entity-name>-<id>.tsx\`, \`manifest.json\`.
+- **watch**: Watches the scene directory; when you change a script file, it pushes that file’s content back to the scene in the app (and can create new entities when you add \`<entity-name>-<id>.tsx\`).
 
-Edits you make in \`scene.tsx\` or \`entity-*.tsx\` are synced to the Phibelle Studio scene when the watcher is running (\`npm run watch\` or \`npx phibelle-kit watch <sceneId>\`).
+Edits you make in \`scene.tsx\` or \`<entity-name>-<id>.tsx\` are synced to the Phibelle Studio scene when the watcher is running (\`npm run watch\` or \`npx phibelle-kit watch <sceneId>\`).
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phibelle-kit",
-  "version": "1.0.9",
+  "version": "1.0.12",
   "description": "CLI tool for interacting with the Phibelle engine",
   "type": "module",
   "bin": {