@directivegames/genesys.js 3.1.24

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@directivegames/genesys.js",
+  "version": "3.1.24",
+  "description": "Mini game engine built on top of three.js",
+  "license": "UNLICENSED",
+  "main": "./dist/src/index.js",
+  "type": "module",
+  "files": [
+    "dist",
+    "src",
+    "games",
+    "assets",
+    "scripts",
+    "docs",
+    "eslint-rules",
+    ".cursor/rules",
+    ".cursorrules"
+  ],
+  "lint-staged": {
+    "*.glb": [
+      "pnpm exec tsx ./scripts/optimize-glb-wrapper.ts"
+    ]
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "pnpm exec tsc && pnpm lint && pnpm test && pnpm test-world-loading && pnpm dump-templates && vite build && pnpm check-asset-path && pnpm generate-prefabs && pnpm build-browser-bundle",
+    "compile": "tsc",
+    "pack": "pnpm build && pnpm pack",
+    "preview": "vite preview",
+    "doc": "typedoc",
+    "lint": "eslint . --fix --ext .ts,.tsx",
+    "bundle": "pnpm exec esbuild ./src/index.ts --bundle --outfile=dist/bundle.js --platform=browser --format=esm",
+    "build-browser-bundle": "pnpm exec tsx scripts/build-browser-bundle.ts",
+    "loc": "pnpm exec tsx scripts/loc.ts",
+    "check-asset-path": "pnpm exec tsx scripts/check-asset-path.ts",
+    "postinstall": "pnpm exec tsx scripts/generate-dependencies.ts",
+    "session-server": "pnpm exec tsx scripts/session-server.ts --port 8080 --lag --min-delay 200 --max-delay 500 --packet-loss 0",
+    "dump-templates": "pnpm exec tsx scripts/dump-templates.ts",
+    "test-world-loading": "pnpm exec tsx scripts/test-world-loading.ts",
+    "generate-prefabs": "pnpm exec tsx scripts/generate-prefabs.ts",
+    "optimize-glb": "pnpm exec tsx scripts/optimize-glb.ts ./assets/models --recursive --optimize",
+    "test": "pnpm exec tsx node_modules/qunit/bin/qunit.js test/**/*.test.ts",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "@dimforge/rapier3d-compat": "^0.18.2",
+    "@recast-navigation/three": "^0.39.0",
+    "@tweakpane/core": "^2.0.5",
+    "@tweenjs/tween.js": "^25.0.0",
+    "@types/three": "^0.177.0",
+    "@webxr-input-profiles/assets": "^1.0.19",
+    "@webxr-input-profiles/motion-controllers": "^1.0.0",
+    "dat.gui": "^0.7.9",
+    "esbuild-wasm": "^0.25.2",
+    "manifold-3d": "^3.0.1",
+    "nanoid": "^5.1.5",
+    "nipplejs": "^0.10.2",
+    "postprocessing": "^6.38.0",
+    "recast-navigation": "^0.39.0",
+    "reflect-metadata": "^0.2.2",
+    "stats.js": "^0.17.0",
+    "three": "^0.177.0",
+    "three-mesh-bvh": "^0.9.1",
+    "three-pathfinding": "^1.3.0",
+    "tsx": "^4.19.4",
+    "tweakpane": "^4.0.5",
+    "wawa-vfx-vanilla": "^1.2.10",
+    "xatlas-three": "^0.2.1",
+    "yaml": "^2.8.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@gltf-transform/cli": "^4.2.1",
+    "@gltf-transform/core": "^4.2.1",
+    "@gltf-transform/extensions": "^4.2.1",
+    "@gltf-transform/functions": "^4.2.1",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@types/dat.gui": "^0.7.13",
+    "@types/jsdom": "^21.1.7",
+    "@types/qunit": "^2.19.13",
+    "@types/ws": "^8.5.10",
+    "@typescript-eslint/eslint-plugin": "^8.29.1",
+    "@typescript-eslint/parser": "^8.29.1",
+    "@typescript-eslint/utils": "^8.29.1",
+    "esbuild": "^0.25.2",
+    "eslint": "^9.24.0",
+    "eslint-plugin-import": "^2.31.0",
+    "husky": "^9.1.7",
+    "jsdom": "^26.1.0",
+    "lint-staged": "^16.1.5",
+    "qunit": "^2.24.3",
+    "qunit-puppeteer": "^1.0.1",
+    "rollup-plugin-visualizer": "^6.0.3",
+    "sharp": "^0.34.3",
+    "ts-node": "^10.9.2",
+    "typedoc": "^0.28.2",
+    "typedoc-plugin-markdown": "^4.6.1",
+    "typescript": "^5.8.2",
+    "vite": "^6.2.4",
+    "vite-plugin-mkcert": "^1.17.8",
+    "vite-plugin-wasm": "^3.4.1",
+    "ws": "^8.18.0"
+  }
+}

package/scripts/build-browser-bundle.ts

@@ -0,0 +1,75 @@
+import { resolve } from 'path';
+import { dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+import * as esbuild from 'esbuild';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Build configuration for browser bundles
+ */
+async function buildBrowserBundles() {
+  const baseConfig: esbuild.BuildOptions = {
+    entryPoints: [resolve(__dirname, '../src/index.ts')],
+    bundle: true,
+    platform: 'browser',
+    format: 'esm', // Changed from 'iife' to 'esm' for ES module
+    target: 'es2021',
+    sourcemap: true,
+    external: [
+      // These libraries are dynamically imported or loaded via CDN
+      // so they don't need to be in the bundle
+    ],
+    define: {
+      // Define global variables for browser compatibility
+      'process.env.NODE_ENV': '"production"',
+      'global': 'globalThis',
+    },
+    alias: {
+      // Browser-compatible aliases for Node.js modules
+      'path': resolve(__dirname, '../src/utils/browser-polyfills/path.ts'),
+      'module': resolve(__dirname, '../src/utils/browser-polyfills/module.ts'),
+    },
+    loader: {
+      '.wasm': 'file',
+      '.glb': 'file',
+      '.gltf': 'file',
+      '.png': 'file',
+      '.jpg': 'file',
+      '.jpeg': 'file',
+      '.hdr': 'file',
+      '.mp3': 'file',
+      '.wav': 'file',
+      '.ogg': 'file',
+    },
+  };
+
+  try {
+    // Build minified ES module browser bundle (production)
+    console.log('Building minified ES module browser bundle...');
+    await esbuild.build({
+      ...baseConfig,
+      outfile: resolve(__dirname, '../dist/genesys.min.mjs'),
+      minify: true,
+      sourcemap: false,
+      legalComments: 'none',
+    });
+
+    console.log('✅ ES module browser bundle built successfully!');
+    console.log('📁 Production bundle: dist/genesys.min.mjs');
+    console.log('🌐 Import: import * as GENESYS from "./genesys.min.mjs"');
+
+  } catch (error) {
+    console.error('❌ Build failed:', error);
+    process.exit(1);
+  }
+}
+
+// Execute if this file is run directly
+if (process.argv[1]?.includes('build-browser-bundle')) {
+  buildBrowserBundles().catch(console.error);
+}
+
+export { buildBrowserBundles };

package/scripts/check-asset-path.ts

@@ -0,0 +1,166 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function findAssetPaths(content: string): string[] {
+  const lines = content.split('\n');
+  const assetPaths: string[] = [];
+
+  for (const line of lines) {
+    // Skip commented lines (both // and /* */ comments)
+    const trimmedLine = line.trim();
+    if (trimmedLine.startsWith('//') || trimmedLine.startsWith('*') || trimmedLine.startsWith('/*')) {
+      continue;
+    }
+
+    // Check for assets in non-commented parts of the line
+    // Match both direct asset paths and @engine/ prefixed paths
+    const assetPathRegex = /['"](@engine\/)?(\/?assets\/[^'"]+)['"]/g;
+    const matches = line.matchAll(assetPathRegex);
+    const filteredPaths = Array.from(matches)
+      .map(match => {
+        // If it has @engine/ prefix, include it; otherwise just the asset path
+        return match[1] ? match[1] + match[2] : match[2];
+      })
+      .filter(path => !path.includes('*')); // Skip glob patterns
+    assetPaths.push(...filteredPaths);
+  }
+
+  return assetPaths;
+}
+
+function findAssetPathsInJSON(obj: any, paths: string[] = []): string[] {
+  if (obj === null || obj === undefined) {
+    return paths;
+  }
+
+  if (typeof obj === 'string') {
+    // Check if the string contains an asset path
+    if (obj.includes('assets/')) {
+      // Handle @engine/ prefix
+      const cleanPath = obj.replace('@engine/', '');
+      if (cleanPath.startsWith('assets/') || cleanPath.startsWith('/assets/')) {
+        paths.push(cleanPath);
+      }
+    }
+  } else if (Array.isArray(obj)) {
+    for (const item of obj) {
+      findAssetPathsInJSON(item, paths);
+    }
+  } else if (typeof obj === 'object') {
+    for (const value of Object.values(obj)) {
+      findAssetPathsInJSON(value, paths);
+    }
+  }
+
+  return paths;
+}
+
+function validateAssetPath(assetPath: string, assetFolder: string, sourceFile: string): void {
+  // Handle @engine/ prefix
+  const cleanPath = assetPath.replace('@engine/', '');
+  // Remove both '/assets/' and 'assets/' prefixes
+  const relativePath = cleanPath.replace(/^\/?assets\//, '');
+  const fullAssetPath = path.join(assetFolder, relativePath);
+
+  if (!fs.existsSync(fullAssetPath)) {
+    console.error(`❌ Asset not found: ${assetPath} (referenced in ${sourceFile})`);
+    return;
+  }
+
+  // On Windows, we need to check case sensitivity differently
+  if (process.platform === 'win32') {
+    const dir = path.dirname(fullAssetPath);
+    const fileName = path.basename(fullAssetPath);
+    const files = fs.readdirSync(dir);
+
+    // Find the actual filename with correct casing
+    const actualFileName = files.find(f => f.toLowerCase() === fileName.toLowerCase());
+
+    if (actualFileName && actualFileName !== fileName) {
+      console.error(`❌ Case sensitivity mismatch: ${assetPath} (referenced in ${sourceFile})`);
+      console.error(`   Expected: ${fileName}`);
+      console.error(`   Actual: ${actualFileName}`);
+    }
+  } else {
+    // On Unix-like systems, we can use realpathSync
+    const actualPath = fs.realpathSync(fullAssetPath);
+    const expectedPath = path.resolve(fullAssetPath);
+
+    if (actualPath !== expectedPath) {
+      console.error(`❌ Case sensitivity mismatch: ${assetPath} (referenced in ${sourceFile})`);
+      console.error(`   Expected: ${expectedPath}`);
+      console.error(`   Actual: ${actualPath}`);
+    }
+  }
+}
+
+function scanDirectory(dir: string, assetFolder: string): void {
+  const files = fs.readdirSync(dir);
+
+  for (const file of files) {
+    const fullPath = path.join(dir, file);
+    const stat = fs.statSync(fullPath);
+
+    if (stat.isDirectory()) {
+      scanDirectory(fullPath, assetFolder);
+    } else if (file.endsWith('.ts') || file.endsWith('.tsx')) {
+      const content = fs.readFileSync(fullPath, 'utf-8');
+      const assetPaths = findAssetPaths(content);
+
+      for (const assetPath of assetPaths) {
+        validateAssetPath(assetPath, assetFolder, fullPath);
+      }
+    } else if (file.endsWith('.genesys-scene') || file.endsWith('.prefab.json')) {
+      try {
+        let content = fs.readFileSync(fullPath, 'utf-8');
+        // Remove BOM if present
+        if (content.charCodeAt(0) === 0xFEFF) {
+          content = content.slice(1);
+        }
+        const jsonData = JSON.parse(content);
+        const assetPaths = findAssetPathsInJSON(jsonData);
+
+        for (const assetPath of assetPaths) {
+          validateAssetPath(assetPath, assetFolder, fullPath);
+        }
+      } catch (error) {
+        console.error(`❌ Failed to parse JSON in ${fullPath}: ${error}`);
+      }
+    }
+  }
+}
+
+function main() {
+  const projectRoot = path.resolve(__dirname, '..');
+  const assetFolder = path.join(projectRoot, 'assets');
+  const srcFolder = path.join(projectRoot, 'src');
+  const gamesFolder = path.join(projectRoot, 'games');
+
+  if (!fs.existsSync(assetFolder)) {
+    console.error(`❌ Assets folder not found at: ${assetFolder}`);
+    process.exit(1);
+  }
+
+  console.log('🔍 Scanning TypeScript, .genesys-scene, and .prefab.json files for asset references...');
+
+  if (fs.existsSync(srcFolder)) {
+    scanDirectory(srcFolder, assetFolder);
+  }
+
+  if (fs.existsSync(gamesFolder)) {
+    scanDirectory(gamesFolder, assetFolder);
+  }
+
+  // Also scan the assets folder itself for .genesys-scene files
+  if (fs.existsSync(assetFolder)) {
+    scanDirectory(assetFolder, assetFolder);
+  }
+
+  console.log('✅ Asset path validation complete');
+}
+
+main();

package/scripts/dump-templates.ts

@@ -0,0 +1,21 @@
+import fs from 'fs';
+import path from 'path';
+
+import { generateClassTemplate } from '../src/world-commands/generate-code.js';
+
+
+function fixUpTemplate(template: string): string {
+  return template
+    .replace('genesys.js', '../index.js')  // fix import path
+    .replace('@ENGINE.GameClass()', '// @ENGINE.GameClass()');  // skip registering as that's not really needed
+}
+
+const target_dir = path.join('src', 'templates');
+fs.mkdirSync(target_dir, { recursive: true });
+fs.writeFileSync(path.join(target_dir, 'README.md'), 'Files here are generated by dump-template-code.ts for lint and build verification. Do not modify manually', 'utf8');
+
+const actorTemplate = fixUpTemplate(await generateClassTemplate('MyActor', 'ENGINE.Actor', 'actor'));
+fs.writeFileSync(path.join(target_dir, 'MyActor.ts'), actorTemplate, 'utf8');
+
+const sceneComponentTemplate = fixUpTemplate(await generateClassTemplate('MySceneComponent', 'ENGINE.SceneComponent', 'component'));
+fs.writeFileSync(path.join(target_dir, 'MySceneComponent.ts'), sceneComponentTemplate, 'utf8');

package/scripts/generate-dependencies.ts

@@ -0,0 +1,145 @@
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+import { parse } from 'yaml';
+
+interface PackageJson {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  name?: string;
+}
+
+interface PnpmLockYaml {
+  importers?: {
+    '.'?: {
+      dependencies?: Record<string, {
+        specifier: string;
+        version: string;
+      }>;
+      devDependencies?: Record<string, {
+        specifier: string;
+        version: string;
+      }>;
+    };
+  };
+}
+
+function isInstalledAsDependency(): boolean {
+  try {
+    // Check if we're in a node_modules directory
+    const cwd = process.cwd();
+    if (cwd.includes('node_modules')) {
+      return true;
+    }
+
+    // Check if the package.json name matches our package name
+    const packageJsonPath = join(cwd, 'package.json');
+    const packageJsonContent = readFileSync(packageJsonPath, 'utf-8');
+    const packageJson: PackageJson = JSON.parse(packageJsonContent);
+
+    // If the package name is not "genesys.js", we're running as a dependency
+    return packageJson.name !== 'genesys.js';
+  } catch {
+    // If we can't read package.json, assume we're a dependency
+    return true;
+  }
+}
+
+function generateDependenciesFile(): void {
+  // Skip if running as a dependency in another project
+  if (isInstalledAsDependency()) {
+    console.log('🔄 Skipping dependencies file generation (running as dependency)');
+    return;
+  }
+
+  try {
+    // Read package.json to get dependency lists
+    const packageJsonPath = join(process.cwd(), 'package.json');
+    const packageJsonContent = readFileSync(packageJsonPath, 'utf-8');
+    const packageJson: PackageJson = JSON.parse(packageJsonContent);
+
+    // Read pnpm-lock.yaml to get exact versions
+    const pnpmLockPath = join(process.cwd(), 'pnpm-lock.yaml');
+    const pnpmLockContent = readFileSync(pnpmLockPath, 'utf-8');
+    const pnpmLock: PnpmLockYaml = parse(pnpmLockContent);
+
+    // Extract dependency lists from package.json
+    const dependencyNames = Object.keys(packageJson.dependencies ?? {});
+    const devDependencyNames = Object.keys(packageJson.devDependencies ?? {});
+
+    // Get exact versions from pnpm-lock.yaml
+    const dependencies: Record<string, string> = {};
+    const devDependencies: Record<string, string> = {};
+
+    // Helper function to extract base version (remove peer dependency info)
+    const extractBaseVersion = (version: string): string => {
+      // Version format can be like "0.18.2" or "0.18.2(@types/three@0.177.0)(three@0.177.0)"
+      // Extract just the base version before the first '('
+      const match = version.match(/^([^(]+)/);
+      return match ? match[1] : version;
+    };
+
+    const importerDeps = pnpmLock.importers?.['.']?.dependencies ?? {};
+    const importerDevDeps = pnpmLock.importers?.['.']?.devDependencies ?? {};
+
+    // Process production dependencies
+    for (const depName of dependencyNames) {
+      const lockEntry = importerDeps[depName];
+      if (lockEntry?.version) {
+        dependencies[depName] = extractBaseVersion(lockEntry.version);
+      }
+    }
+
+    // Process dev dependencies
+    for (const depName of devDependencyNames) {
+      const lockEntry = importerDevDeps[depName];
+      if (lockEntry?.version) {
+        devDependencies[depName] = extractBaseVersion(lockEntry.version);
+      }
+    }
+
+    // Generate TypeScript content
+    const tsContent = `/**
+ * Auto-generated file containing all package dependencies and their exact installed versions.
+ * This file is generated by the post-install script.
+ * Do not edit manually - it will be overwritten on next install.
+ *
+ * Versions are extracted from pnpm-lock.yaml to show exact installed versions,
+ * not the version ranges from package.json.
+ */
+
+export const DEPENDENCIES = {
+${Object.entries(dependencies)
+    .map(([name, version]) => `  '${name}': '${version}',`)
+    .join('\n')}
+} as const;
+
+export const DEV_DEPENDENCIES = {
+${Object.entries(devDependencies)
+    .map(([name, version]) => `  '${name}': '${version}',`)
+    .join('\n')}
+} as const;
+
+export const ALL_DEPENDENCIES = {
+  ...DEPENDENCIES,
+  ...DEV_DEPENDENCIES,
+} as const;
+
+export type DependencyName = keyof typeof ALL_DEPENDENCIES;
+`;
+
+    // Write the TypeScript file
+    const outputPath = join(process.cwd(), 'src', 'dependencies.ts');
+    writeFileSync(outputPath, tsContent, 'utf-8');
+
+    console.log('✅ Dependencies file generated successfully at src/dependencies.ts');
+    console.log(`📦 Found ${Object.keys(dependencies).length} production dependencies with exact versions`);
+    console.log(`🔧 Found ${Object.keys(devDependencies).length} development dependencies with exact versions`);
+  } catch (error) {
+    console.error('❌ Error generating dependencies file:', error);
+    process.exit(1);
+  }
+}
+
+// Run the script
+generateDependenciesFile();

package/scripts/generate-prefabs.ts

@@ -0,0 +1,120 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import { JSDOM } from 'jsdom';
+import * as THREE from 'three';
+
+
+import { mockBrowserEnvironment } from '../src/index.js';
+import * as ENGINE from '../src/index.js';
+
+import type { GLTF } from 'three/examples/jsm/Addons.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// override the resource manager to return null for all models to avoid errors
+class CustomResourceManager extends ENGINE.ResourceManager {
+  constructor() {
+    super(); // Call parent constructor to set up Meshopt decoder
+  }
+
+  override async loadModel(path: ENGINE.AssetPath): Promise<GLTF | null> {
+    return null;
+  }
+}
+
+ENGINE.setResourceManager(new CustomResourceManager());
+
+function stripUUID(obj: any): any {
+  if (obj === null || obj === undefined) return obj;
+  if (typeof obj === 'object') {
+    if (obj.uuid) delete obj.uuid;
+    for (const key in obj) {
+      obj[key] = stripUUID(obj[key]);
+    }
+  }
+  return obj;
+}
+
+function main() {
+  mockBrowserEnvironment(JSDOM);
+
+  const actors: Record<string, ENGINE.Actor> = {};
+  const components: Record<string, ENGINE.SceneComponent> = {};
+
+  // demo_health_pickup
+  actors.demo_health_pickup = new ENGINE.Actor({
+    sceneComponents: [
+      new ENGINE.GLTFMeshComponent({
+        modelUrl: '@engine/assets/models/PickupActors/SM_Pickup_Health.glb',
+        physicsOptions: {
+          enabled: true,
+          motionType: ENGINE.PhysicsMotionType.Static,
+          density: 1,
+          generateCollisionEvents: true,
+          collisionMeshType: ENGINE.CollisionMeshType.ConvexHull,
+          enableCCD: false,
+          collisionProfile: ENGINE.DefaultCollisionProfile.Trigger,
+        },
+        scale: new THREE.Vector3(2, 2, 2),
+      }),
+      new ENGINE.AnimationComponent({
+        autoPlay: true,
+        loopMode: 'LoopRepeat',
+        clip: 'Idle',
+      }),
+      new ENGINE.HealthPickupComponent({
+        healAmount: 50,
+        sound: {
+          pickupSoundUrl: '@engine/assets/sounds/pickup.mp3',
+          volume: 0.6,
+          maxDistance: 15,
+        },
+      }),
+    ],
+  });
+
+  // demo_health_pickup_spawner
+  actors.demo_health_pickup_spawner = new ENGINE.Actor({
+    sceneComponents: [
+      new ENGINE.GLTFMeshComponent({
+        modelUrl: '@engine/assets/models/PickupActors/SM_Pickup_Station.glb',
+        physicsOptions: {
+          enabled: false,
+        },
+        scale: new THREE.Vector3(2, 2, 2),
+      }),
+      new ENGINE.PickupSpawnerComponent({
+        prefabPath: '@engine/assets/prefabs/actors/demo_health_pickup.prefab.json',
+        spawnInterval: 5.0,
+        spawnOffset: new THREE.Vector3(0, 0.3, 0),
+        sound: {
+          volume: 0.5,
+          maxDistance: 15,
+        },
+      })
+    ],
+  });
+
+  // dump actor prefabs
+  const actorPrefabPath = path.join(__dirname, '../assets/prefabs/actors');
+  fs.mkdirSync(actorPrefabPath, { recursive: true });
+  for (const [name, actor] of Object.entries(actors)) {
+    const fullPath = path.join(actorPrefabPath, `${name}.prefab.json`);
+    fs.writeFileSync(fullPath, JSON.stringify(stripUUID(actor.asExportedObject(false)), null, 2));
+    console.log(`Wrote prefab to ${fullPath}`);
+  }
+
+  // dump component prefabs
+  const componentPrefabPath = path.join(__dirname, '../assets/prefabs/components');
+  fs.mkdirSync(componentPrefabPath, { recursive: true });
+  for (const [name, component] of Object.entries(components)) {
+    const fullPath = path.join(componentPrefabPath, `${name}.prefab.json`);
+    fs.writeFileSync(fullPath, JSON.stringify(stripUUID(component.asExportedObject(false)), null, 2));
+    console.log(`Wrote prefab to ${fullPath}`);
+  }
+}
+
+main();

package/scripts/load-save-world.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env pnpm exec tsx
+
+import { readFileSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+
+import * as ENGINE from '../src/index.js';
+
+import { defaultWorldOptions } from './test-world-loading.js';
+
+// Get the file path from command line arguments
+const args = process.argv.slice(2);
+if (args.length === 0) {
+  console.error('Usage: pnpm exec tsx scripts/load-save-world.ts <path-to-world.json>');
+  process.exit(1);
+}
+
+const filePath = resolve(args[0]);
+
+try {
+  // Read the JSON file
+  console.log(`Loading world from: ${filePath}`);
+  const jsonContent = readFileSync(filePath, 'utf-8');
+  // Remove BOM if present
+  const cleanJsonContent = jsonContent.replace(/^\uFEFF/, '');
+  const worldData = JSON.parse(cleanJsonContent);
+
+  // Create a new world and load the data
+  const world = new ENGINE.World(defaultWorldOptions);
+
+  // Load the world data
+  await ENGINE.WorldSerializer.loadWorld(world, worldData);
+
+  // Export the world back to JSON
+  const exportedData = world.asExportedObject();
+
+  // Save back to the same file
+  const jsonOutput = JSON.stringify(exportedData, null, 2);
+  writeFileSync(filePath, jsonOutput, 'utf-8');
+  console.log(`World saved back to: ${filePath}`);
+
+} catch (error) {
+  console.error('Error processing world file:', error);
+  process.exit(1);
+}