@directivegames/genesys.sdk 3.2.2 → 3.2.5

package/src/asset-pack/scripts/postinstall.ts

@@ -1,81 +1,81 @@
-#!/usr/bin/env node
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { fileURLToPath } from 'url';
-
-// Get the directory of this script
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-/**
- * Find the parent project root by traversing up from node_modules
- * For pnpm structure like: /project/node_modules/.pnpm/package@version/node_modules/package
- * We want to find: /project
- */
-function findProjectRoot(): string | null {
-  // Split the current directory path into parts
-  const parts = __dirname.split(path.sep);
-  
-  // Find the first occurrence of 'node_modules' in the path
-  const nodeModulesIndex = parts.indexOf('node_modules');
-  
-  if (nodeModulesIndex > 0) {
-    // Take everything before 'node_modules' and join it back
-    return parts.slice(0, nodeModulesIndex).join(path.sep);
-  }
-  
-  return null;
-}
-
-// Only run when installed as a dependency in another project
-// Skip if running in the package's own directory during development
-const isInstalledAsDependency = __dirname.includes('node_modules');
-
-if (isInstalledAsDependency) {
-  try {
-    // Read package.json to get the package name
-    const packageJsonPath = path.resolve(__dirname, '../../package.json');
-    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-    const packageName = packageJson.name;
-
-    // Source: assets folder in this package
-    const sourceAssetsDir = path.resolve(__dirname, '../../assets');
-    
-    // Find the parent project root
-    const parentProjectRoot = findProjectRoot();
-    
-    if (!parentProjectRoot) {
-      console.error('Error: Could not find parent project root');
-      process.exit(1);
-    }
-    
-    // Destination: <parent-project>/packs/<package-name>/assets
-    const targetPackDir = path.join(parentProjectRoot, 'packs', packageName);
-    const targetAssetsDir = path.join(targetPackDir, 'assets');
-    
-    // Check if source assets directory exists
-    if (fs.existsSync(sourceAssetsDir)) {
-      // Delete target directory if it already exists
-      if (fs.existsSync(targetPackDir)) {
-        fs.rmSync(targetPackDir, { recursive: true, force: true });
-      }
-
-      // Create target directory
-      fs.mkdirSync(targetPackDir, { recursive: true });
-
-      // Copy entire assets folder
-      fs.cpSync(sourceAssetsDir, targetAssetsDir, { recursive: true });
-
-      console.log(`✓ Assets from "${packageName}" copied to: ${path.relative(parentProjectRoot, targetPackDir)}`);
-    } else {
-      console.log(`⚠ No assets folder found in "${packageName}"`);
-    }
-  } catch (error) {
-    console.error('Error during postinstall:', error);
-    process.exit(1);
-  }
-}
-
-export {};
-
+#!/usr/bin/env node
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+
+// Get the directory of this script
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Find the parent project root by traversing up from node_modules
+ * For pnpm structure like: /project/node_modules/.pnpm/package@version/node_modules/package
+ * We want to find: /project
+ */
+function findProjectRoot(): string | null {
+  // Split the current directory path into parts
+  const parts = __dirname.split(path.sep);
+
+  // Find the first occurrence of 'node_modules' in the path
+  const nodeModulesIndex = parts.indexOf('node_modules');
+
+  if (nodeModulesIndex > 0) {
+    // Take everything before 'node_modules' and join it back
+    return parts.slice(0, nodeModulesIndex).join(path.sep);
+  }
+
+  return null;
+}
+
+// Only run when installed as a dependency in another project
+// Skip if running in the package's own directory during development
+const isInstalledAsDependency = __dirname.includes('node_modules');
+
+if (isInstalledAsDependency) {
+  try {
+    // Read package.json to get the package name
+    const packageJsonPath = path.resolve(__dirname, '../../package.json');
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+    const packageName = packageJson.name;
+
+    // Source: assets folder in this package
+    const sourceAssetsDir = path.resolve(__dirname, '../../assets');
+
+    // Find the parent project root
+    const parentProjectRoot = findProjectRoot();
+
+    if (!parentProjectRoot) {
+      console.error('Error: Could not find parent project root');
+      process.exit(1);
+    }
+
+    // Destination: <parent-project>/packs/<package-name>/assets
+    const targetPackDir = path.join(parentProjectRoot, 'packs', packageName);
+    const targetAssetsDir = path.join(targetPackDir, 'assets');
+
+    // Check if source assets directory exists
+    if (fs.existsSync(sourceAssetsDir)) {
+      // Delete target directory if it already exists
+      if (fs.existsSync(targetPackDir)) {
+        fs.rmSync(targetPackDir, { recursive: true, force: true });
+      }
+
+      // Create target directory
+      fs.mkdirSync(targetPackDir, { recursive: true });
+
+      // Copy entire assets folder
+      fs.cpSync(sourceAssetsDir, targetAssetsDir, { recursive: true });
+
+      console.log(`✓ Assets from "${packageName}" copied to: ${path.relative(parentProjectRoot, targetPackDir)}`);
+    } else {
+      console.log(`⚠ No assets folder found in "${packageName}"`);
+    }
+  } catch (error) {
+    console.error('Error during postinstall:', error);
+    process.exit(1);
+  }
+}
+
+export {};
+

package/src/asset-pack/tsconfig.json

@@ -1,34 +1,34 @@
-{
-  "compilerOptions": {
-    "target": "ES2021",
-    "useDefineForClassFields": true,
-    "module": "ESNext",
-    "lib": [
-      "ES2021",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "skipLibCheck": true,
-    "moduleResolution": "node",
-    "allowSyntheticDefaultImports": true,
-    "resolveJsonModule": true,
-    "isolatedModules": true,
-    "jsx": "preserve",
-    "strict": true,
-    "noUnusedLocals": false,
-    "noUnusedParameters": false,
-    "noFallthroughCasesInSwitch": true,
-    "outDir": "./dist",
-    "rootDir": ".",
-    "declaration": true,
-    "inlineSourceMap": true,
-    "experimentalDecorators": true,
-    "noImplicitOverride": true,
-    "noEmit": false,
-    "types": ["node"]
-  },
-  "include": [
-    "src/**/*",
-    "scripts/**/*"
-  ]
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": [
+      "ES2021",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "skipLibCheck": true,
+    "moduleResolution": "node",
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "strict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noFallthroughCasesInSwitch": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "declaration": true,
+    "inlineSourceMap": true,
+    "experimentalDecorators": true,
+    "noImplicitOverride": true,
+    "noEmit": false,
+    "types": ["node"]
+  },
+  "include": [
+    "src/**/*",
+    "scripts/**/*"
+  ]
 }

package/src/templates/.cursor/mcp.json

@@ -1,20 +1,20 @@
-{
-  "mcpServers": {},
-  "DISABLED_mcpServers": {
-    "genesys": {
-      "command": "npx",
-      "args": [
-        "tsx",
-        "./scripts/genesys/genesys-mcp.ts",
-        "cursor"
-      ]
-    },
-    "genesys-docs": {
-      "command": "npx",
-      "args": [
-        "tsx",
-        "./scripts/genesys/doc-server.ts"
-      ]
-    }
-  }
-}
+{
+  "mcpServers": {},
+  "DISABLED_mcpServers": {
+    "genesys": {
+      "command": "npx",
+      "args": [
+        "tsx",
+        "./scripts/genesys/genesys-mcp.ts",
+        "cursor"
+      ]
+    },
+    "genesys-docs": {
+      "command": "npx",
+      "args": [
+        "tsx",
+        "./scripts/genesys/doc-server.ts"
+      ]
+    }
+  }
+}

package/src/templates/.cursorignore

@@ -1,2 +1,2 @@
-!**/.engine/**
-**/.engine/docs/**
+!**/.engine/**
+**/.engine/docs/**

package/src/templates/.gitattributes

@@ -1,89 +1,89 @@
-# Git LFS tracking for common large file types
-
-# 3D Models
-*.fbx filter=lfs diff=lfs merge=lfs -text
-*.obj filter=lfs diff=lfs merge=lfs -text
-*.dae filter=lfs diff=lfs merge=lfs -text
-*.3ds filter=lfs diff=lfs merge=lfs -text
-*.blend filter=lfs diff=lfs merge=lfs -text
-*.max filter=lfs diff=lfs merge=lfs -text
-*.maya filter=lfs diff=lfs merge=lfs -text
-*.mb filter=lfs diff=lfs merge=lfs -text
-*.ma filter=lfs diff=lfs merge=lfs -text
-*.glb filter=lfs diff=lfs merge=lfs -text
-*.gltf filter=lfs diff=lfs merge=lfs -text
-
-# Textures and Images
-*.png filter=lfs diff=lfs merge=lfs -text
-*.jpg filter=lfs diff=lfs merge=lfs -text
-*.jpeg filter=lfs diff=lfs merge=lfs -text
-*.tga filter=lfs diff=lfs merge=lfs -text
-*.tiff filter=lfs diff=lfs merge=lfs -text
-*.tif filter=lfs diff=lfs merge=lfs -text
-*.bmp filter=lfs diff=lfs merge=lfs -text
-*.psd filter=lfs diff=lfs merge=lfs -text
-*.exr filter=lfs diff=lfs merge=lfs -text
-*.hdr filter=lfs diff=lfs merge=lfs -text
-*.dds filter=lfs diff=lfs merge=lfs -text
-*.ktx filter=lfs diff=lfs merge=lfs -text
-*.ktx2 filter=lfs diff=lfs merge=lfs -text
-
-# Audio Files
-*.wav filter=lfs diff=lfs merge=lfs -text
-*.mp3 filter=lfs diff=lfs merge=lfs -text
-*.ogg filter=lfs diff=lfs merge=lfs -text
-*.flac filter=lfs diff=lfs merge=lfs -text
-*.aac filter=lfs diff=lfs merge=lfs -text
-*.m4a filter=lfs diff=lfs merge=lfs -text
-*.wma filter=lfs diff=lfs merge=lfs -text
-*.aiff filter=lfs diff=lfs merge=lfs -text
-
-# Video Files
-*.mp4 filter=lfs diff=lfs merge=lfs -text
-*.mov filter=lfs diff=lfs merge=lfs -text
-*.avi filter=lfs diff=lfs merge=lfs -text
-*.mkv filter=lfs diff=lfs merge=lfs -text
-*.webm filter=lfs diff=lfs merge=lfs -text
-*.wmv filter=lfs diff=lfs merge=lfs -text
-*.flv filter=lfs diff=lfs merge=lfs -text
-
-# Fonts
-*.ttf filter=lfs diff=lfs merge=lfs -text
-*.otf filter=lfs diff=lfs merge=lfs -text
-*.woff filter=lfs diff=lfs merge=lfs -text
-*.woff2 filter=lfs diff=lfs merge=lfs -text
-
-# Archives and Packages
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-
-# Game Engine Specific Files
-*.unity filter=lfs diff=lfs merge=lfs -text
-*.unitypackage filter=lfs diff=lfs merge=lfs -text
-*.asset filter=lfs diff=lfs merge=lfs -text
-*.prefab filter=lfs diff=lfs merge=lfs -text
-
-# Document Files (large ones)
-*.pdf filter=lfs diff=lfs merge=lfs -text
-*.doc filter=lfs diff=lfs merge=lfs -text
-*.docx filter=lfs diff=lfs merge=lfs -text
-*.ppt filter=lfs diff=lfs merge=lfs -text
-*.pptx filter=lfs diff=lfs merge=lfs -text
-
-# Binary executables and libraries
-*.exe filter=lfs diff=lfs merge=lfs -text
-*.dll filter=lfs diff=lfs merge=lfs -text
-*.so filter=lfs diff=lfs merge=lfs -text
-*.dylib filter=lfs diff=lfs merge=lfs -text
-*.a filter=lfs diff=lfs merge=lfs -text
-*.lib filter=lfs diff=lfs merge=lfs -text
-
-# Data files
-*.dat filter=lfs diff=lfs merge=lfs -text
-*.data filter=lfs diff=lfs merge=lfs -text
-*.cache filter=lfs diff=lfs merge=lfs -text
+# Git LFS tracking for common large file types
+
+# 3D Models
+*.fbx filter=lfs diff=lfs merge=lfs -text
+*.obj filter=lfs diff=lfs merge=lfs -text
+*.dae filter=lfs diff=lfs merge=lfs -text
+*.3ds filter=lfs diff=lfs merge=lfs -text
+*.blend filter=lfs diff=lfs merge=lfs -text
+*.max filter=lfs diff=lfs merge=lfs -text
+*.maya filter=lfs diff=lfs merge=lfs -text
+*.mb filter=lfs diff=lfs merge=lfs -text
+*.ma filter=lfs diff=lfs merge=lfs -text
+*.glb filter=lfs diff=lfs merge=lfs -text
+*.gltf filter=lfs diff=lfs merge=lfs -text
+
+# Textures and Images
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.tga filter=lfs diff=lfs merge=lfs -text
+*.tiff filter=lfs diff=lfs merge=lfs -text
+*.tif filter=lfs diff=lfs merge=lfs -text
+*.bmp filter=lfs diff=lfs merge=lfs -text
+*.psd filter=lfs diff=lfs merge=lfs -text
+*.exr filter=lfs diff=lfs merge=lfs -text
+*.hdr filter=lfs diff=lfs merge=lfs -text
+*.dds filter=lfs diff=lfs merge=lfs -text
+*.ktx filter=lfs diff=lfs merge=lfs -text
+*.ktx2 filter=lfs diff=lfs merge=lfs -text
+
+# Audio Files
+*.wav filter=lfs diff=lfs merge=lfs -text
+*.mp3 filter=lfs diff=lfs merge=lfs -text
+*.ogg filter=lfs diff=lfs merge=lfs -text
+*.flac filter=lfs diff=lfs merge=lfs -text
+*.aac filter=lfs diff=lfs merge=lfs -text
+*.m4a filter=lfs diff=lfs merge=lfs -text
+*.wma filter=lfs diff=lfs merge=lfs -text
+*.aiff filter=lfs diff=lfs merge=lfs -text
+
+# Video Files
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.mov filter=lfs diff=lfs merge=lfs -text
+*.avi filter=lfs diff=lfs merge=lfs -text
+*.mkv filter=lfs diff=lfs merge=lfs -text
+*.webm filter=lfs diff=lfs merge=lfs -text
+*.wmv filter=lfs diff=lfs merge=lfs -text
+*.flv filter=lfs diff=lfs merge=lfs -text
+
+# Fonts
+*.ttf filter=lfs diff=lfs merge=lfs -text
+*.otf filter=lfs diff=lfs merge=lfs -text
+*.woff filter=lfs diff=lfs merge=lfs -text
+*.woff2 filter=lfs diff=lfs merge=lfs -text
+
+# Archives and Packages
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+
+# Game Engine Specific Files
+*.unity filter=lfs diff=lfs merge=lfs -text
+*.unitypackage filter=lfs diff=lfs merge=lfs -text
+*.asset filter=lfs diff=lfs merge=lfs -text
+*.prefab filter=lfs diff=lfs merge=lfs -text
+
+# Document Files (large ones)
+*.pdf filter=lfs diff=lfs merge=lfs -text
+*.doc filter=lfs diff=lfs merge=lfs -text
+*.docx filter=lfs diff=lfs merge=lfs -text
+*.ppt filter=lfs diff=lfs merge=lfs -text
+*.pptx filter=lfs diff=lfs merge=lfs -text
+
+# Binary executables and libraries
+*.exe filter=lfs diff=lfs merge=lfs -text
+*.dll filter=lfs diff=lfs merge=lfs -text
+*.so filter=lfs diff=lfs merge=lfs -text
+*.dylib filter=lfs diff=lfs merge=lfs -text
+*.a filter=lfs diff=lfs merge=lfs -text
+*.lib filter=lfs diff=lfs merge=lfs -text
+
+# Data files
+*.dat filter=lfs diff=lfs merge=lfs -text
+*.data filter=lfs diff=lfs merge=lfs -text
+*.cache filter=lfs diff=lfs merge=lfs -text
 *.tmp filter=lfs diff=lfs merge=lfs -text

package/src/templates/.vscode/settings.json

@@ -1,6 +1,6 @@
-{
-    "editor.codeActionsOnSave": {
-      "source.fixAll.eslint": "always"
-    },
-    "eslint.validate": ["javascript", "typescript"]
-}
+{
+    "editor.codeActionsOnSave": {
+      "source.fixAll.eslint": "always"
+    },
+    "eslint.validate": ["javascript", "typescript"]
+}

package/src/templates/AGENTS.md

@@ -1,86 +1,86 @@
-# Assets
-
-## Engine Assets
-- The engine's default assets are located in the **`node_modules/genesys.js/assets`** directory.
-- To reference these assets in your code, replace the **`node_modules/genesys.js`** prefix with **`@engine`** in the asset path.
-
-  **Example:**  
-  If an asset is located at:  
-  `node_modules/genesys.js/assets/models/SM_Monkey.glb`  
-  Then the corresponding URL should be:  
-  `@engine/assets/models/SM_Monkey.glb`
-
-
-## Project Assets
-- The project's assets are located in the **`/assets`** directory.
-- To reference these assets in your code, use the **fully qualified path** with **`@project`** prefix.
-
-  **Example:**  
-  If an asset is located at:  
-  `/assets/models/tiger.glb`  
-  Then the corresponding URL should be:  
-  `@project/assets/models/tiger.glb`
-
-  **Important:** Always use the complete path with `@project/assets/` prefix rather than relative paths. This ensures compatibility with publishing tools and build processes. You should **never** construct a project path programmatically.
-
-## Resolve Asset Paths
-- Using asset paths containing `@engine` or `@project` in raw html will not work out of the box as the browser doesn't know how to resolve them.
-  The solution is to resolve them using **`ENGINE.resolveAssetPathsInText`** first.
-  Example:
-  ```
-  const htmlString = '...<img src="@engine/assets/textures/Checkerboard.png">...'
-  const resolvedHtml = await ENGINE.resolveAssetPathsInText(htmlString);
-  // then use resolvedHtml as normal
-  ```
-
-## Prefabs
-- Prefabs are json files stored within /assets/prefabs, with the suffix .prefab.json.
-- Prefabs can be validated via `pnpm validate-prefabs`.
-- When referencing classes in prefab, use the appropriate prefix.
-  Engine classes **must** be referenced as `ENGINE.{class name}`, example: `ENGINE.Actor`, `ENGINE.SceneComponent`.
-  Custom game classes **must** be referenced as `GAME.{class name}`, example: `GAME.MyCustomActor`, `GAME.MyCustomComponent`.
-
----
-
-# Coding Rules
-
-**CRITICAL**: Never edit `auto-imports.ts` - This file is automatically generated by the build pipeline to register all @ENGINE.GameClass() decorated classes. Any manual changes will be overwritten and may break the build system. Classes with proper @ENGINE.GameClass() decorators are automatically discovered and imported.
-
-## General Guidelines
-- Before implementing, take a hard look of the engine and figure out what can be used to implement the user's requirement. **Do not** reinvent wheels. When using the search tool, expand the search parameters with similar keywords.
-- Work **WITH** the engine architecture, **NOT** against it. 
-- Try to find and use appropriate art assets as needed if the user does not specify. Check both engine and project assets for something that fits the feature.
-- You **should avoid** writing **monolithic code** — do not place all logic, definitions, and configurations into a single file.  
-  Instead, structure your code into modular, reusable, and maintainable components.
-- Custom actor and component classes **must not** be registered as **`EngineClass`**, use **`GameClass`** instead.
-- **Do not** create documentation or test/example code unless specifically asked to.
-- Be **very brief** on the summary when the implementation is completed.
-
-## UI
-- Any HTML UI you create **MUST NOT** be added to the document root directly. Add them to the game UI container, which can be accessed through `world.gameContainer`.
-
-## Testing Constraints
-- You may **only** use `pnpm build` to verify code compilation.
-- You **must** use `pnpm lint` to detect and auto-fix linting issues.
-- Do **not** run `pnpm test`, `pnpm dev`, or `pnpm start` — these commands are **not supported**.
-- All testing is the responsibility of the user.  
-  You are encouraged to:
-  - Recommend suitable testing approaches.
-  - Collaborate with the user to evaluate test results.
-
-
-## Prompt Handling & Clarification
-
-Before implementing any user request, you **must** interpret the prompt, identify ambiguities, and either:
-- State clear assumptions **before** coding, or
-- Ask the user targeted clarification questions.
-
-### Required Steps
-1. **Understand intent** — Restate what the user is asking in your own words.
-2. **Identify ambiguities** — Look for vague or overloaded terms.
-3. **Clarify or assume** —
-   - If unclear, ask specific, short questions to confirm meaning.
-   - If the user cannot clarify, proceed with explicit, written assumptions.
-4. **Confirm scope** — Specify what systems, assets, or files you will change.
-
-This process **prevents incorrect implementations** when user wording is incomplete or ambiguous.
+# Assets
+
+## Engine Assets
+- The engine's default assets are located in the **`node_modules/@directivegames/genesys.js/assets`** directory.
+- To reference these assets in your code, replace the **`node_modules/@directivegames/genesys.js`** prefix with **`@engine`** in the asset path.
+
+  **Example:**  
+  If an asset is located at:  
+  `node_modules/@directivegames/genesys.js/assets/models/SM_Monkey.glb`  
+  Then the corresponding URL should be:  
+  `@engine/assets/models/SM_Monkey.glb`
+
+
+## Project Assets
+- The project's assets are located in the **`/assets`** directory.
+- To reference these assets in your code, use the **fully qualified path** with **`@project`** prefix.
+
+  **Example:**  
+  If an asset is located at:  
+  `/assets/models/tiger.glb`  
+  Then the corresponding URL should be:  
+  `@project/assets/models/tiger.glb`
+
+  **Important:** Always use the complete path with `@project/assets/` prefix rather than relative paths. This ensures compatibility with publishing tools and build processes. You should **never** construct a project path programmatically.
+
+## Resolve Asset Paths
+- Using asset paths containing `@engine` or `@project` in raw html will not work out of the box as the browser doesn't know how to resolve them.
+  The solution is to resolve them using **`ENGINE.resolveAssetPathsInText`** first.
+  Example:
+  ```
+  const htmlString = '...<img src="@engine/assets/textures/Checkerboard.png">...'
+  const resolvedHtml = await ENGINE.resolveAssetPathsInText(htmlString);
+  // then use resolvedHtml as normal
+  ```
+
+## Prefabs
+- Prefabs are json files stored within /assets/prefabs, with the suffix .prefab.json.
+- Prefabs can be validated via `pnpm validate-prefabs`.
+- When referencing classes in prefab, use the appropriate prefix.
+  Engine classes **must** be referenced as `ENGINE.{class name}`, example: `ENGINE.Actor`, `ENGINE.SceneComponent`.
+  Custom game classes **must** be referenced as `GAME.{class name}`, example: `GAME.MyCustomActor`, `GAME.MyCustomComponent`.
+
+---
+
+# Coding Rules
+
+**CRITICAL**: Never edit `auto-imports.ts` - This file is automatically generated by the build pipeline to register all @ENGINE.GameClass() decorated classes. Any manual changes will be overwritten and may break the build system. Classes with proper @ENGINE.GameClass() decorators are automatically discovered and imported.
+
+## General Guidelines
+- Before implementing, take a hard look of the engine and figure out what can be used to implement the user's requirement. **Do not** reinvent wheels. When using the search tool, expand the search parameters with similar keywords.
+- Work **WITH** the engine architecture, **NOT** against it. 
+- Try to find and use appropriate art assets as needed if the user does not specify. Check both engine and project assets for something that fits the feature.
+- You **should avoid** writing **monolithic code** — do not place all logic, definitions, and configurations into a single file.  
+  Instead, structure your code into modular, reusable, and maintainable components.
+- Custom actor and component classes **must not** be registered as **`EngineClass`**, use **`GameClass`** instead.
+- **Do not** create documentation or test/example code unless specifically asked to.
+- Be **very brief** on the summary when the implementation is completed.
+
+## UI
+- Any HTML UI you create **MUST NOT** be added to the document root directly. Add them to the game UI container, which can be accessed through `world.gameContainer`.
+
+## Testing Constraints
+- You may **only** use `pnpm build` to verify code compilation.
+- You **must** use `pnpm lint` to detect and auto-fix linting issues.
+- Do **not** run `pnpm test`, `pnpm dev`, or `pnpm start` — these commands are **not supported**.
+- All testing is the responsibility of the user.  
+  You are encouraged to:
+  - Recommend suitable testing approaches.
+  - Collaborate with the user to evaluate test results.
+
+
+## Prompt Handling & Clarification
+
+Before implementing any user request, you **must** interpret the prompt, identify ambiguities, and either:
+- State clear assumptions **before** coding, or
+- Ask the user targeted clarification questions.
+
+### Required Steps
+1. **Understand intent** — Restate what the user is asking in your own words.
+2. **Identify ambiguities** — Look for vague or overloaded terms.
+3. **Clarify or assume** —
+   - If unclear, ask specific, short questions to confirm meaning.
+   - If the user cannot clarify, proceed with explicit, written assumptions.
+4. **Confirm scope** — Specify what systems, assets, or files you will change.
+
+This process **prevents incorrect implementations** when user wording is incomplete or ambiguous.