@gnsx/genesys.sdk 4.2.9

package/src/templates/scripts/genesys/migrate-scenes-and-prefabs.ts

@@ -0,0 +1,301 @@
+/**
+ * Migration script for Genesys scene, prefab, and material files.
+ *
+ * Migration order: Scenes → Prefabs → Materials
+ * This order is important because the engine cannot load new prefab data with old scene data.
+ *
+ * The migration runs TWICE:
+ * - Pass 1: Updates all files to the new format
+ * - Pass 2: Re-processes all files to ensure prefab instances in scenes are saved correctly
+ *           (prefab instances are only serialized properly when both the prefab and scene
+ *           data are at the same version)
+ *
+ * Usage: pnpm migrate (requires running `pnpm build` first to compile game classes)
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+import * as ENGINE from '@gnsx/genesys.js';
+
+import { getProjectRoot } from './common.js';
+import { mockBrowserEnvironment } from './mock.js';
+import { StorageProvider } from './storageProvider.js';
+
+// Import game module to register game classes (tsx compiles TypeScript on the fly)
+import '../../src/game.js';
+
+// Set up browser environment for Node.js (provides document, window, etc.)
+mockBrowserEnvironment();
+
+// Set up storage provider for file operations
+const storageProvider = new StorageProvider();
+ENGINE.projectContext({ project: 'local-project', storageProvider: storageProvider });
+
+
+interface FileInfo {
+  path: string;
+  type: 'scene' | 'prefab' | 'material';
+}
+
+const defaultWorldOptions = {
+  rendererDomElement: document.createElement('div'),
+  gameContainer: document.createElement('div'),
+  backgroundColor: 0x2E2E2E,
+  physicsOptions: {
+    engine: ENGINE.PhysicsEngine.Rapier,
+    gravity: ENGINE.MathHelpers.makeVector({ up: -9.81 }),
+  },
+  navigationOptions: {
+    engine: ENGINE.NavigationEngine.RecastNavigation,
+  },
+  useManifold: true
+};
+
+function findScenesAndPrefabs(dir: string, files: FileInfo[] = []): FileInfo[] {
+  const entries = fs.readdirSync(dir);
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry);
+    const stat = fs.statSync(fullPath);
+
+    if (stat.isDirectory()) {
+      // Skip common directories that shouldn't be processed
+      if (entry === 'node_modules' || entry === 'dist' || entry === '.git' || entry === '.engine') {
+        continue;
+      }
+      findScenesAndPrefabs(fullPath, files);
+    } else if (entry.endsWith('.genesys-scene')) {
+      files.push({ path: fullPath, type: 'scene' });
+    } else if (entry.endsWith('.prefab.json')) {
+      files.push({ path: fullPath, type: 'prefab' });
+    } else if (entry.endsWith('.material.json')) {
+      files.push({ path: fullPath, type: 'material' });
+    }
+  }
+
+  return files;
+}
+
+async function migrateSceneFile(data: any, filePath: string, relativePath: string): Promise<boolean> {
+  // Create a world and load into it
+  const world = new ENGINE.World(defaultWorldOptions);
+
+  if (ENGINE.isLegacyData(data)) {
+    // Use WorldSerializer for legacy data
+    await ENGINE.WorldSerializer.loadWorld(world, data);
+  } else {
+    // Use Loader for new format
+    const loader = new ENGINE.Loader();
+    await loader.loadToInstanceAsync(data, world);
+  }
+
+  // Dump the world
+  const dumper = new ENGINE.Dumper();
+  const newData = dumper.dump(world);
+
+  // Write back to file
+  const newContent = JSON.stringify(newData, null, 2);
+  fs.writeFileSync(filePath, newContent, 'utf-8');
+
+  console.log(`✅ ${relativePath}`);
+  return true;
+}
+
+async function migratePrefabFile(data: any, filePath: string, relativePath: string): Promise<boolean> {
+  let instance: any;
+
+  if (ENGINE.isLegacyData(data)) {
+    // Use WorldSerializer for legacy data
+    console.log(`🔍 Migrating legacy prefab: ${relativePath}`);
+    instance = await ENGINE.WorldSerializer.loadActor(data);
+    console.log(`✅ ${relativePath}`);
+  } else {
+    // Use Loader for new format
+    const loader = new ENGINE.Loader();
+    instance = await loader.loadAsync(data);
+  }
+
+  if (!instance) {
+    console.log(`⚠️  ${relativePath}: Loaded instance is null, skipping`);
+    return false;
+  }
+
+  // Dump using Dumper
+  const dumper = new ENGINE.Dumper({flags: ENGINE.DumperFlags.AsPrefab});
+  const newData = dumper.dump(instance);
+
+  // Write back to file
+  const newContent = JSON.stringify(newData, null, 2);
+  fs.writeFileSync(filePath, newContent, 'utf-8');
+
+  console.log(`✅ ${relativePath}`);
+  return true;
+}
+
+async function migrateMaterialFile(data: any, filePath: string, relativePath: string): Promise<boolean> {
+  let material: any;
+
+  if (ENGINE.isLegacyData(data)) {
+    console.log(`🔍 Migrated legacy material: ${relativePath}`);
+    material = ENGINE.WorldSerializer.importObject(data);
+    console.log(`✅ ${relativePath}`);
+  } else {
+    const loader = new ENGINE.Loader();
+    material = await loader.loadAsync(data);
+  }
+
+  if (!material) {
+    console.log(`⚠️  ${relativePath}: Loaded material is null, skipping`);
+    return false;
+  }
+
+  // Dump using Dumper
+  const dumper = new ENGINE.Dumper({flags:ENGINE.DumperFlags.AsPrefab});
+  const newData = dumper.dump(material);
+  // Write back to file
+  const newContent = JSON.stringify(newData, null, 2);
+  fs.writeFileSync(filePath, newContent, 'utf-8');
+
+  console.log(`✅ ${relativePath}`);
+  return true;
+}
+
+async function migrateFile(fileInfo: FileInfo): Promise<'success' | 'failure' | 'skipped'> {
+  const { path: filePath, type } = fileInfo;
+  const relativePath = path.relative(getProjectRoot(), filePath);
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const data = JSON.parse(content);
+  // if (ENGINE.isUpdateToDateData(data)) {
+  //   console.log(`ℹ️  ${relativePath}: Already up to date, skipping`);
+  //   // return 'skipped';
+  // }
+
+  try {
+    if (type === 'scene') {
+      return await migrateSceneFile(data, filePath, relativePath) ? 'success' : 'failure';
+    } else if (type === 'prefab') {
+      return await migratePrefabFile(data, filePath, relativePath) ? 'success' : 'failure';
+    } else if (type === 'material') {
+      return await migrateMaterialFile(data, filePath, relativePath) ? 'success' : 'failure';
+    }
+  } catch (error) {
+    console.error(`❌ ${relativePath}: ${error instanceof Error ? error.message : String(error)}`);
+    return 'failure';
+  } finally {
+    console.log('');
+  }
+  return 'skipped';
+}
+
+interface MigrationResult {
+  successCount: number;
+  failCount: number;
+}
+
+async function runMigrationPass(
+  sceneFiles: FileInfo[],
+  prefabFiles: FileInfo[],
+  materialFiles: FileInfo[],
+  passNumber: number
+): Promise<MigrationResult> {
+  let successCount = 0;
+  let failCount = 0;
+
+  console.log(`\n${'='.repeat(60)}`);
+  console.log(`Migration Pass ${passNumber}`);
+  console.log(`${'='.repeat(60)}\n`);
+
+  // Migrate scenes first (must be done before prefabs to ensure engine can load new prefab data)
+  if (sceneFiles.length > 0) {
+    console.log('🌍 Migrating scenes...\n');
+    for (const fileInfo of sceneFiles) {
+      const success = await migrateFile(fileInfo);
+      if (success) {
+        successCount++;
+      } else {
+        failCount++;
+      }
+    }
+  }
+
+  // Then migrate prefabs
+  if (prefabFiles.length > 0) {
+    console.log('\n📦 Migrating prefabs...\n');
+    for (const fileInfo of prefabFiles) {
+      const success = await migrateFile(fileInfo);
+      if (success) {
+        successCount++;
+      } else {
+        failCount++;
+      }
+    }
+  }
+
+  // Finally migrate materials
+  if (materialFiles.length > 0) {
+    console.log('\n🎨 Migrating materials...\n');
+    for (const fileInfo of materialFiles) {
+      const success = await migrateFile(fileInfo);
+      if (success) {
+        successCount++;
+      } else {
+        failCount++;
+      }
+    }
+  }
+
+  return { successCount, failCount };
+}
+
+async function main() {
+  // Game classes are registered via the top-level import of dist/src/game.js
+  // Make sure to run `pnpm build` first!
+
+  const projectRoot = getProjectRoot();
+  const assetsFolder = path.join(projectRoot, 'assets');
+  console.log(`📁 Scanning for scene and prefab files in: ${assetsFolder}\n`);
+
+  // Find all scene and prefab files in the assets folder
+  const files = findScenesAndPrefabs(assetsFolder);
+
+  if (files.length === 0) {
+    console.log('⚠️  No scene or prefab files found.');
+    return;
+  }
+
+  const prefabFiles = files.filter(f => f.type === 'prefab');
+  const sceneFiles = files.filter(f => f.type === 'scene');
+  const materialFiles = files.filter(f => f.type === 'material');
+  console.log(`Found ${files.length} files to migrate:`);
+  console.log(`  - ${sceneFiles.length} scene file(s)`);
+  console.log(`  - ${prefabFiles.length} prefab file(s)`);
+  console.log(`  - ${materialFiles.length} material file(s)`);
+
+  // Run migration twice to ensure prefab instances in scenes are saved properly
+  // (prefab instances are only saved correctly when both prefab and scene data are the same version)
+  const pass1 = await runMigrationPass(sceneFiles, prefabFiles, materialFiles, 1);
+  const pass2 = await runMigrationPass(sceneFiles, prefabFiles, materialFiles, 2);
+
+  const totalSuccess = pass1.successCount + pass2.successCount;
+  const totalFail = pass1.failCount + pass2.failCount;
+
+  console.log(`\n${'='.repeat(60)}`);
+  console.log('Migration Summary:');
+  console.log(`  Total files per pass: ${files.length}`);
+  console.log(`  Pass 1 - Successful: ${pass1.successCount}, Failed: ${pass1.failCount}`);
+  console.log(`  Pass 2 - Successful: ${pass2.successCount}, Failed: ${pass2.failCount}`);
+  console.log(`  Total - Successful: ${totalSuccess}, Failed: ${totalFail}`);
+  console.log(`${'='.repeat(60)}`);
+
+  if (totalFail > 0) {
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error('Unexpected error:', error);
+  console.error('Stack trace:', error.stack);
+  process.exit(1);
+});

package/src/templates/scripts/genesys/misc.ts

@@ -0,0 +1,42 @@
+import path from 'path';
+
+import * as ENGINE from '@gnsx/genesys.js';
+
+import { getProjectRoot } from './common.js';
+import { isSubclass } from './mcp/utils.js';
+import { fixUpClassName, registerGameClasses } from './mcp/utils.js';
+import { StorageProvider } from './storageProvider.js';
+
+
+export async function generateCode(className: string, filePath: string, baseClassName: string): Promise<boolean> {
+  try {
+    baseClassName = fixUpClassName(baseClassName);
+  }
+  catch (error) {
+    // if the base class name is not found, register all game classes and try again
+    await registerGameClasses();
+    baseClassName = fixUpClassName(baseClassName);
+  }
+
+  using context = ENGINE.scopedProjectContext({project: 'mcp-project', storageProvider: new StorageProvider()});
+
+  const testIsSubclass = (childName: string, parent: Function) => {
+    const child = ENGINE.ClassRegistry.getRegistry().get(childName);
+    if (!child) {
+      return false;
+    }
+    return isSubclass(child, parent);
+  };
+
+  const fullFilePath = path.isAbsolute(filePath) ? filePath : path.join(getProjectRoot(), filePath);
+
+  let fileGenerated = false;
+  const isSubclassOfActor = testIsSubclass(baseClassName, ENGINE.Actor);
+  if (isSubclassOfActor) {
+    await ENGINE.WorldCommands.generateActorTemplateFile(className, fullFilePath, baseClassName);
+    fileGenerated = true;
+  }
+
+  return fileGenerated;
+}
+

package/src/templates/scripts/genesys/mock.ts

@@ -0,0 +1,6 @@
+import { mockBrowserEnvironment as engineMock } from '@gnsx/genesys.js';
+import { JSDOM } from 'jsdom';
+
+export function mockBrowserEnvironment() {
+  engineMock(JSDOM);
+}

package/src/templates/scripts/genesys/place-actors.ts

@@ -0,0 +1,179 @@
+import * as ENGINE from '@gnsx/genesys.js';
+import * as THREE from 'three';
+
+import { ThreeEulerSchema, ThreeVector3Schema } from './mcp/search-actors.js';
+import { loadWorld, registerGameClassesIfAnyNotRegistered } from './mcp/utils.js';
+import { mockBrowserEnvironment } from './mock.js';
+
+import '../src/game.js';
+
+
+mockBrowserEnvironment();
+
+function convertConstructorParams(value: any): any {
+  // If not an object, return as is
+  if (!value || typeof value !== 'object') {
+    return value;
+  }
+
+  // Check if it's a Vector3
+  const vector3Result = ThreeVector3Schema.safeParse(value);
+  if (vector3Result.success) {
+    return new THREE.Vector3(
+      vector3Result.data.x,
+      vector3Result.data.y,
+      vector3Result.data.z
+    );
+  }
+
+  // Check if it's an Euler
+  const eulerResult = ThreeEulerSchema.safeParse(value);
+  if (eulerResult.success) {
+    return new THREE.Euler(
+      eulerResult.data.x,
+      eulerResult.data.y,
+      eulerResult.data.z
+    );
+  }
+
+  // Handle arrays
+  if (Array.isArray(value)) {
+    return value.map(convertConstructorParams);
+  }
+
+  // Handle objects
+  const result: Record<string, any> = {};
+  for (const [key, val] of Object.entries(value)) {
+    result[key] = convertConstructorParams(val);
+  }
+  return result;
+}
+
+
+export async function placePrimitive(args: {
+  sceneName: string;
+  primitiveActors: ENGINE.WorldCommands.PrimitiveActorArgs[];
+}): Promise<string[]> {
+
+  using worldResource = await loadWorld(args.sceneName, { skipLoadingGLTF: true });
+
+  const actors = ENGINE.WorldCommands.placePrimitives({
+    world: worldResource.world,
+    primitiveActors: args.primitiveActors,
+  });
+
+  return actors.map(actor => actor.uuid);
+}
+
+
+export async function removeActors(args: {
+  sceneName: string;
+  actorIds: string[];
+}) {
+  using worldResource = await loadWorld(args.sceneName, { skipLoadingGLTF: true });
+
+  ENGINE.WorldCommands.removeActorsByUuids({
+    world: worldResource.world,
+    actorIds: args.actorIds,
+  });
+}
+
+export async function addGltf(args: {
+  sceneName: string;
+  gltfs: ENGINE.WorldCommands.GltfArgs[];
+}) {
+  using worldResource = await loadWorld(args.sceneName, { skipLoadingGLTF: true });
+
+  const actors = await ENGINE.WorldCommands.placeGltfs({
+    world: worldResource.world,
+    gltfs: args.gltfs
+  });
+
+  return actors.map(actor => actor.uuid);
+}
+
+export async function placePrefab(args: {
+  sceneName: string;
+  prefabs: ENGINE.WorldCommands.PrefabArgs[];
+}) {
+  using worldResource = await loadWorld(args.sceneName, { skipLoadingGLTF: true });
+
+  const actors = await ENGINE.WorldCommands.placePrefabs({
+    world: worldResource.world,
+    prefabs: args.prefabs
+  });
+
+  return actors.map(actor => actor.uuid);
+}
+
+export async function placeJsClassActor(args: {
+  sceneName: string;
+  jsClasses: {
+    className: string;
+    constructorParams?: Record<string, any>[]
+    actorInfo?: ENGINE.WorldCommands.ActorMiscInfo;
+  }[]
+}): Promise<string[]> {
+  await registerGameClassesIfAnyNotRegistered(
+    args.jsClasses.map(jsClass => jsClass.className)
+  );
+  using worldResource = await loadWorld(args.sceneName, { skipLoadingGLTF: true });
+
+  const actors: ENGINE.Actor[] = [];
+
+  for (const { className, constructorParams, actorInfo } of args.jsClasses) {
+    try {
+      // Convert constructor parameters if they exist
+      const convertedParams = constructorParams ? convertConstructorParams(constructorParams) : [];
+
+      const actor = ENGINE.ClassRegistry.constructObject(className, false, ...convertedParams);
+      if (actorInfo) {
+        Object.assign(actor.editorData, actorInfo);
+      }
+      actors.push(actor);
+    } catch (e) {
+      console.error(`Error constructing object ${className}`, e);
+    }
+  }
+
+  worldResource.world.addActors(...actors);
+  return actors.map(actor => actor.uuid);
+}
+
+
+export async function updateActors(args: {
+  sceneName: string;
+  actorsToUpdate: {
+    uuid: string;
+    transform?: ENGINE.WorldCommands.Transform;
+    actorInfo?: ENGINE.WorldCommands.ActorMiscInfo;
+  }[];
+}): Promise<number> {
+  const readonly = args.actorsToUpdate.length == 0;
+  using worldResource = await loadWorld(args.sceneName, { readonly, skipLoadingGLTF: true });
+  let count = 0;
+
+  for (const { uuid, transform, actorInfo } of args.actorsToUpdate) {
+    const actor = worldResource.world.getActorByUuid(uuid);
+    if (!actor) {
+      continue;
+    }
+    if (transform) {
+      if (transform.position) {
+        actor.setWorldPosition(transform.position);
+      }
+      if (transform.rotation) {
+        actor.setWorldRotation(transform.rotation);
+      }
+      if (transform.scale) {
+        actor.setWorldScale(transform.scale);
+      }
+      if (actorInfo) {
+        Object.assign(actor.editorData, actorInfo);
+      }
+    }
+    count += 1;
+  }
+  return count;
+}
+

package/src/templates/scripts/genesys/post-install.ts

@@ -0,0 +1,39 @@
+import fs from 'fs';
+import path from 'path';
+
+import { getProjectRoot } from './common.js';
+
+
+async function main() {
+  const engineInstallFolder = path.join(getProjectRoot(), 'node_modules/@gnsx/genesys.js');
+  if (!fs.existsSync(engineInstallFolder)) {
+    return;
+  }
+  const copiedEngineFolder = path.join(getProjectRoot(), '.engine');
+  if (fs.existsSync(copiedEngineFolder)) {
+    fs.rmdirSync(copiedEngineFolder, { recursive: true });
+  }
+  fs.mkdirSync(copiedEngineFolder, { recursive: true });
+
+  const foldersToCopy: string[] = [
+    'games/examples',
+    'src'
+  ];
+  for (const folder of foldersToCopy) {
+    const engineFolderPath = path.join(engineInstallFolder, folder);
+    const localFolderPath = path.join(copiedEngineFolder, folder);
+    fs.cpSync(engineFolderPath, localFolderPath, { recursive: true });
+  }
+
+  // copy all *.md files
+  const files = fs.readdirSync(engineInstallFolder);
+  for (const file of files) {
+    if (file.endsWith('.md')) {
+      const engineFilePath = path.join(engineInstallFolder, file);
+      const localFilePath = path.join(copiedEngineFolder, file);
+      fs.copyFileSync(engineFilePath, localFilePath);
+    }
+  }
+}
+
+main();

package/src/templates/scripts/genesys/prefab.schema.json

@@ -0,0 +1,85 @@
+{
+    "$schema": "https://json-schema.org/draft-07/schema",
+    "$id": "genesys.js.prefab.schema.json",
+    "type": "object",
+    "properties": {
+        "$version": {
+            "type": "integer"
+        },
+        "class": {
+            "$ref": "class_string"
+        },
+        "ctor": {
+            "$ref": "actor_ctor"
+        },
+        "properties": {
+            "$ref": "actor_properties"
+        }
+    },
+    "definitions": {
+        "actor_ctor": {
+            "type": "object",
+            "properties": {
+                "rootComponent": {
+                    "$ref": "component"
+                }
+            }
+        },
+        "actor_properties": {
+            "type": "object"
+        },
+        "component_ctor": {
+            "type": "object"
+        },
+        "component_properties": {
+            "type": "object",
+            "properties": {
+                "position": {
+                    "$ref": "type_vector3"
+                },
+                "rotation": {
+                    "$ref": "type_euler"
+                },
+                "scale": {
+                    "$ref": "type_euler"
+                }
+            }
+        },
+        "type_vector3": {
+            "type": "array",
+            "minItems": 4,
+            "maxItems": 4,
+            "examples": [[0, 0, 0, "v"]]
+        },
+        "type_euler": {
+            "type": "array",
+            "minItems": 4,
+            "maxItems": 4,
+            "examples": [[0, 0, 0, "e"]]
+        },
+        "component": {
+            "type": "object",
+            "properties": {
+                "class": {
+                    "$ref": "class_string"
+                },
+                "ctor": {
+                    "$ref": "component_ctor"
+                },
+                "properties": {
+                    "$ref": "component_properties"
+                },
+                "children": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "component"
+                    }
+                }
+            }
+        },
+        "class_string": {
+            "type": "string",
+            "pattern": "(GAME|ENGINE)\\..*"
+        }
+    }
+}