@directivegames/genesys.js 3.1.24

package/docs/deprecated/TELEGRAM_MINIAPP_SUPPORT_PLAN.md

@@ -0,0 +1,283 @@
+# Telegram Mini App Support for Genesys.js - Implementation Plan
+
+## Overview
+
+This document outlines a plan to add Telegram Mini App support to Genesys.js. The goal is to enable Genesys games to run inside Telegram as Mini Apps while maintaining full backward compatibility with existing games and supporting mobile touch controls.
+
+**Key Principles:**
+- ✅ Zero impact on existing games
+- ✅ Graceful degradation (works everywhere, enhanced in Telegram)
+- ✅ Progressive enhancement (mobile controls + optional Telegram features)
+- ✅ Modular, opt-in architecture
+
+---
+
+## Original Integration Guide
+
+*The following section describes the basic integration approach for making a Genesys game work in Telegram.*
+
+### Adding Telegram Mini App Support
+
+To make this game run inside Telegram as a Mini App, follow the steps below.
+
+#### 1. Telegram WebApp Initialization
+
+In your main script (e.g. `main.ts`), add this at the top:
+
+```typescript
+declare global {
+  interface Window {
+    Telegram: any;
+  }
+}
+
+Then inside a DOMContentLoaded listener, add:
+
+document.addEventListener("DOMContentLoaded", () => {
+  const tg = window.Telegram.WebApp;
+  tg.ready();   // Notify Telegram the app is ready
+  tg.expand();  // Expand the app to full height
+});
+```
+
+#### 2. HTML Changes
+In your index.html, make sure your main game canvas is present:
+
+```html
+<canvas id="game-canvas"></canvas>
+```
+
+Optionally add mobile controls:
+
+```html
+<div id="controls" style="position: fixed; bottom: 20px; width: 100%; text-align: center; z-index: 10;">
+  <button id="left-btn">⬅️</button>
+  <button id="right-btn">➡️</button>
+</div>
+```
+
+#### 3. Input Handling (Keyboard + Touch)
+In your main script, add:
+
+```typescript
+let moveLeft = false;
+let moveRight = false;
+
+document.addEventListener("keydown", (e) => {
+  if (e.key === "ArrowLeft") moveLeft = true;
+  if (e.key === "ArrowRight") moveRight = true;
+});
+document.addEventListener("keyup", (e) => {
+  if (e.key === "ArrowLeft") moveLeft = false;
+  if (e.key === "ArrowRight") moveRight = false;
+});
+
+const leftBtn = document.getElementById("left-btn")!;
+const rightBtn = document.getElementById("right-btn")!;
+
+leftBtn.addEventListener("touchstart", () => moveLeft = true);
+rightBtn.addEventListener("touchstart", () => moveRight = true);
+leftBtn.addEventListener("touchend", () => moveLeft = false);
+rightBtn.addEventListener("touchend", () => moveRight = false);
+```
+
+#### 4. Notes
+You must serve this game over HTTPS for Telegram to load it. The Telegram WebApp object will only be available when the game is launched from Telegram.
+
+---
+
+## Technical Analysis
+
+### What Works Well
+1. **Non-Invasive Integration**: The approach correctly leverages existing Genesys architecture without requiring engine modifications
+2. **Touch Input Strategy**: Adding touch controls alongside keyboard controls aligns well with Genesys's InputManager → PlayerController → Pawn → MovementComponent flow
+3. **Canvas-Focused**: Using canvas rendering matches Genesys's THREE.js foundation
+
+### Key Insights
+- **Telegram Mini Apps are just web browsers** with some extra APIs available
+- **No engine changes needed** - Genesys.js will run exactly the same as in any browser
+- **Mobile support is the main requirement** - touch controls, responsive UI, performance optimization
+- **Telegram features are optional add-ons** - user info, cloud storage, payments, sharing, etc.
+
+### Areas for Enhancement
+
+#### 1. Engine-Level Integration
+Instead of manual DOM manipulation, create proper Genesys UI components that integrate with the engine's UI system (`UIManager`, `BaseUIComponent`, HTML/CSS template loading).
+
+#### 2. Platform Detection
+Add robust platform detection to conditionally enable mobile/Telegram features without affecting desktop gameplay.
+
+#### 3. Game Type Considerations
+Different Genesys game types need different control schemes:
+- **FPS games**: Virtual joystick + touch to look
+- **Third-person**: Virtual joystick + gesture controls  
+- **Airplane games**: Tilt controls or virtual throttle/stick
+- **Top-down**: Pan and zoom gestures
+
+---
+
+## Implementation Plan
+
+### New Files (Optional Extensions)
+
+#### Core Platform Support
+```
+src/platforms/
+├── telegram/
+│   ├── TelegramEnvironment.ts          # Detection & basic integration
+│   ├── TelegramCloudStorage.ts         # Save games to Telegram cloud
+│   ├── TelegramUserProfile.ts          # Access user info
+│   └── index.ts                        # Export all Telegram features
+
+├── mobile/
+│   ├── MobileDetection.ts              # Device/platform detection
+│   ├── TouchInputHandler.ts            # Touch event processing
+│   └── index.ts
+```
+
+#### Mobile UI Components
+```
+src/ui/components/mobile/
+├── VirtualJoystick.ts                  # Touch movement control
+├── TouchButton.ts                      # Action buttons
+├── MobileControlPanel.ts               # Complete mobile control layout
+└── index.ts
+
+assets/ui/templates/mobile/
+├── virtual-joystick.html
+├── mobile-controls.html
+└── touch-button.html
+
+assets/ui/styles/mobile/
+├── virtual-joystick.css
+├── mobile-controls.css
+└── touch-button.css
+```
+
+#### Examples & Documentation
+```
+games/
+├── telegram-demo.ts                    # Example game showing integration
+└── mobile-demo.ts                      # Example mobile-optimized game
+
+docs/guides/
+├── 15-mobile-support.md                # Mobile controls & optimization
+├── 16-telegram-integration.md          # Telegram Mini App features
+└── platform-support.md                # Cross-platform development guide
+```
+
+### Modified Files (Minimal Changes)
+
+```
+src/index.ts                            # Add exports for new mobile/telegram modules
+src/game/GameBuilder.ts                 # Add optional helper methods
+src/ui/index.ts                         # Export new mobile components
+index.html                              # Mobile viewport meta tag
+```
+
+### What WOULDN'T Change
+- ✅ All existing Actor/Component classes
+- ✅ Physics engine (Rapier)
+- ✅ Rendering system (THREE.js)  
+- ✅ Animation system
+- ✅ Navigation system
+- ✅ Multiplayer system
+- ✅ Core game loop architecture
+- ✅ Existing UI components
+- ✅ All existing games in `/games/` folder
+
+---
+
+## Usage Examples
+
+### Environment Detection Pattern
+```typescript
+const TelegramEnvironment = {
+  isAvailable: () => typeof window.Telegram?.WebApp !== 'undefined',
+  isMobile: () => /Android|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent),
+  
+  initialize: () => {
+    if (TelegramEnvironment.isAvailable()) {
+      window.Telegram.WebApp.ready();
+      window.Telegram.WebApp.expand();
+    }
+  }
+};
+```
+
+### Progressive Enhancement Pattern
+```typescript
+class MyTelegramGame extends ENGINE.BaseGameLoop {
+  protected override async postStart(): Promise<void> {
+    // Always works - normal game setup
+    ENGINE.GameBuilder.createDefaultLighting(this.world);
+    const { pawn, controller } = ENGINE.GameBuilder.createDefaultPawnWithPhysics(
+      this.world, 
+      ENGINE.CharacterMovementType.ThirdPerson
+    );
+
+    // Only add mobile controls if needed
+    if (TelegramEnvironment.isMobile()) {
+      await this.addMobileControls();
+    }
+
+    // Only use Telegram features if available
+    if (TelegramEnvironment.isAvailable()) {
+      this.initializeTelegramFeatures();
+    }
+  }
+}
+```
+
+### Existing Games (Zero Changes Required)
+```typescript
+// games/fps-demo.ts - continues to work exactly as before
+import * as ENGINE from '../src/index.js';
+
+class FPSDemo extends ENGINE.BaseGameLoop {
+  // No changes needed
+}
+```
+
+### New Games (Opt-in Support)
+```typescript
+// games/my-telegram-game.ts
+import * as ENGINE from '../src/index.js';
+import { TelegramSupport } from '../src/platforms/telegram/index.js';     // Optional
+import { MobileControls } from '../src/platforms/mobile/index.js';       // Optional
+
+class MyTelegramGame extends ENGINE.BaseGameLoop {
+  // Uses new optional features
+}
+```
+
+---
+
+## Benefits
+
+1. **Backward Compatibility**: Existing games work unchanged
+2. **Forward Compatibility**: Easy to add more platform-specific features later
+3. **Gradual Adoption**: Developers can opt-in to new features as needed
+4. **Clean Architecture**: Follows Genesys's modular, component-based design
+5. **Platform Agnostic**: Mobile features work in any mobile browser, not just Telegram
+6. **Social Gaming**: Opens up Telegram's social features for multiplayer and sharing
+
+---
+
+## Next Steps
+
+1. **Proof of Concept**: Create basic mobile controls as Genesys UI components
+2. **Platform Detection**: Implement robust environment detection utilities  
+3. **Touch Input Integration**: Connect touch events to existing InputManager system
+4. **Example Games**: Build demo games showcasing mobile and Telegram integration
+5. **Documentation**: Write comprehensive guides for mobile game development
+6. **Performance Testing**: Optimize for mobile devices and Telegram's WebView environment
+
+---
+
+## File Impact Summary
+- **New files**: ~15-20 (all optional)
+- **Modified files**: ~3-5 (minimal changes)
+- **Existing game files**: 0 changes required
+
+This approach maintains Genesys.js's core philosophy of being a powerful, modular game engine while opening up new possibilities for mobile and social gaming platforms. 

package/docs/deprecated/summary-2.md

@@ -0,0 +1,101 @@
+# High-Level Summary
+
+Genesys.js is a modern, feature-rich 3D game engine built with TypeScript and leveraging Three.js for rendering. It follows a robust, object-oriented design based on the popular **Actor-Component model**, which is similar in spirit to engines like Unreal Engine. The architecture promotes a clean separation of concerns, making it extensible and scalable. Key features include a swappable physics engine (with a Rapier implementation), a built-in multiplayer networking layer with client-side prediction, procedural geometry generation via CSG and noise, a state machine for complex animations, and a DOM-based UI system.
+
+The engine is designed with developer experience in mind, providing helper classes (`GameBuilder`), an in-game console (`ConsoleManager`), and extensive debugging utilities (`SceneGraphUtils`, debug renderers).
+
+---
+
+# Core Architectural Concepts
+
+The entire engine revolves around a few central concepts:
+
+1.  **`World`**: This is the main container for a scene. It holds all the actors, manages global systems (like physics, input, timers, and networking), and orchestrates the main game `tick` cycle. A `GameLoop` is responsible for creating and running the `World`.
+
+2.  **`Actor`**: The base class for any object that can be placed in the `World`. An Actor is essentially a container for Components. It doesn't have much logic on its own but gains functionality through the components attached to it. It has a transform (position, rotation, scale) which is anchored by its `rootComponent`.
+
+3.  **`Component`**: These are the building blocks of functionality that are attached to Actors. They come in two main flavors:
+    *   **`Component`**: The base class for non-visual components that add logic, like `CharacterStatsComponent` or `BehaviorTreeComponent`.
+    *   **`SceneComponent`**: Extends `THREE.Object3D` and is the base for any component that has a physical presence and transform in the scene. It can have other `SceneComponent`s as children, forming a hierarchy. Examples include `MeshComponent` and `LightComponent`.
+
+This structure allows for a highly compositional approach. For example, a "character" is an `Actor` with a `MeshComponent` (for visuals), a `CharacterMovementComponent` (for controls), and an `AnimationStateMachineComponent` (for animations).
+
+---
+
+# Module-by-Module Breakdown
+
+Here is an analysis of the key modules and their roles:
+
+## 1. Game Structure (`src/game/`)
+*   **`GameLoop.ts`**: The main entry point. It sets up the `requestAnimationFrame` loop, creates the `World`, and drives the entire simulation by calling `world.tick()` every frame.
+*   **`World.ts`**: The heart of the engine. It manages the collection of all `Actors`, owns the global `systems`, and orchestrates the pre-physics and post-physics update ticks for all objects.
+*   **`GameMode.ts`**: Defines the rules for a specific game or level. Its primary responsibility is to determine where players spawn by finding a `PlayerStart` actor.
+*   **`GameBuilder.ts`**: A static utility class with factory methods to quickly spawn common game objects like a default player, lighting, and a ground plane, simplifying scene setup.
+
+## 2. Actors (`src/actors/`)
+*   **`Actor.ts`**: The fundamental object. Handles its lifecycle, component management, serialization, and networking.
+*   **`Pawn.ts`**: A specialized, *controllable* `Actor`. It's designed to be "possessed" by a `PlayerController` and translates high-level commands (e.g., `addForwardInput`) into actions via its `MovementComponent`.
+*   **`PlayerController.ts`**: The brain of the player. It implements `IInputHandler` to receive raw input from the `InputManager` and directs the possessed `Pawn`.
+*   **`PlayerStart.ts`**: A simple marker actor used by `GameMode` for spawning.
+*   **`Projectile.ts`**: A self-contained actor for projectiles, managing its own movement, lifetime, and collision/damage logic.
+*   **`ThirdPersonCharacterPawn.ts`**: A pre-fabricated pawn that combines several components to create a ready-to-use animated character, showcasing the power of composition.
+
+## 3. Components (`src/components/`)
+This is the largest and most diverse module, defining the actual functionality of game objects.
+
+*   **Movement (`src/components/movement/`)**:
+    *   `BasePawnMovementComponent` is the abstract parent.
+    *   `CharacterMovementComponent` provides first/third-person walking/running/jumping, including integration with a physics character controller.
+    *   `AirplaneMovementComponent` and `TopDownMovementComponent` offer alternative control schemes.
+    *   `NpcMovementComponent` builds on `CharacterMovementComponent` to add pathfinding and actor-following capabilities for AI.
+
+*   **Visuals (`src/components/visual/`)**:
+    *   `MeshComponent` is a basic wrapper for a `THREE.Mesh`.
+    *   `GLTFMeshComponent` is crucial for loading and displaying complex 3D models from `.glb`/`.gltf` files.
+    *   `AnimationStateMachineComponent` is a sophisticated system for managing character animations with states, parameters, and transitions, driven by a JSON config.
+    *   `TerrainMeshComponent` procedurally generates terrain using Perlin noise.
+    *   `VoxelMeshComponent` and the `MagicaVoxelLoader` provide a full pipeline for rendering voxel art.
+
+
+*   **Lights (`src/components/lights/`)**: A clear hierarchy of components (`Ambient`, `Directional`, `Point`, `Spot`, etc.) that wrap their corresponding Three.js light types, making them part of the Actor-Component system.
+
+*   **Constructive Solid Geometry (CSG) (`src/components/csg/`)**:
+    *   `CSGShapes.ts` defines primitive shapes like cubes and cylinders.
+    *   `CSGCombiner.ts` takes these shapes as children and performs boolean operations (union, subtract, intersect) to create a single, complex mesh at runtime. This is powered by the `ManifoldWrapper` utility.
+
+*   **Gameplay (`src/components/gameplay/`)**:
+    *   `IEquipment` defines a contract for things that can be "fired".
+    *   `ProjectileWeaponComponent` is a concrete weapon that spawns `Projectile` actors.
+    *   `CharacterStatsComponent` manages health, damage, and other common character attributes.
+
+## 4. Systems (`src/systems/`)
+These are global singleton-like managers that provide core services to the `World`.
+
+*   **`ClassRegistry.ts`**: A vital system that maps string names to class constructors. This is the foundation for the serialization system, allowing objects to be created dynamically from saved data.
+*   **`WorldSerialization.ts`**: Handles the logic for converting the entire `World`, including Actors and Components, to and from a JSON format. It respects class hierarchies and component attachments.
+*   **`InputManager.ts`**: Centralizes all user input (keyboard, mouse, gamepad), managing event listeners and distributing events to registered handlers like `PlayerController` and `UIManager`.
+*   **`TimerSystem.ts`**: A robust `setTimeout`/`setInterval` implementation for the game world that respects the game's paused state and time scale (for slow-motion effects).
+*   **`CollisionConfig.ts`**: Manages how different types of objects interact. It defines collision channels (e.g., `Pawn`, `WorldStatic`) and profiles that specify responses (block, overlap, ignore) between them.
+
+## 5. Physics (`src/physics/`)
+*   The engine uses an abstraction layer (`IPhysicsEngine`) to decouple game logic from a specific physics library.
+*   The concrete implementation provided is **`RapierPhysicsEngine`**, which integrates the high-performance Rapier.rs physics engine (compiled to WebAssembly).
+*   It handles the creation of rigid bodies and colliders from `SceneComponent` data, steps the simulation, and reports collision events back to the components.
+*   It also includes a debug renderer to visualize collider shapes.
+
+## 6. Multiplayer (`src/multiplayer/`)
+*   The networking system is also built on an abstraction (`IGameSessionManager`, `IGameSession`).
+*   **`NetWorld.ts`** is the core client-side class that manages networked objects. It identifies "net relevant" objects and replicates their state to and from the game session.
+*   Two session manager implementations are provided:
+    *   **`MemoryGameSessionManager`**: An in-memory version for offline testing or single-player games.
+    *   **`WebSocketGameSessionManager`**: A full-fledged client for a WebSocket-based server, enabling true multiplayer.
+*   **`MovementPrediction.ts`**: Implements client-side prediction and interpolation to hide network latency and provide smooth movement for remote players.
+
+## 7. UI (`src/ui/`)
+*   A lightweight, DOM-based UI system managed by `UIManager`.
+*   **`UIElement`** and **`UILayout`** are wrappers around HTML elements and templates, allowing UI to be built programmatically or from HTML/CSS files loaded by `UIAssetLoader`.
+*   The module includes several pre-built, reusable UI components like `ProgressBar`, `InventoryGrid`, and `Minimap`.
+
+# Conclusion
+
+The Genesys.js engine is a well-architected and comprehensive game development framework. Its adherence to the Actor-Component model, clear separation of concerns, and powerful abstractions for core systems like physics and networking make it both flexible and easy to extend. The source code is clean, well-documented, and demonstrates a strong understanding of modern game engine design principles.

package/docs/engine-summary.md

@@ -0,0 +1,104 @@
+## Instruction
+You **MUST** read this doc to gain overall understanding of the engine.
+
+# High-Level Overview
+
+The Genesys engine is a modern, feature-rich 3D game engine built on top of **THREE.js**. It follows a design philosophy heavily inspired by established engines like Unreal Engine, employing an **Actor-Component model**. This architecture promotes creating complex game objects by composing smaller, reusable pieces of functionality.
+
+The engine is written in **TypeScript** and demonstrates strong software engineering principles, including clear abstraction layers, a robust serialization system, and advanced features for physics, animation, and networking.
+
+# Core Architectural Concepts
+
+The engine's structure revolves around a few central classes that manage the entire game state and lifecycle.
+
+1.  **`GameLoop` (The Driver):**
+    *   **Responsibility:** This is the main entry point of the application. It creates and owns the `World` and handles the `requestAnimationFrame` loop.
+    *   **Lifecycle:** It calculates `deltaTime`, calls `world.tick()` every frame, and manages the renderer. Subclasses like `BaseGameLoop` provide hooks (`preStart`, `postStart`) for setting up a default scene.
+
+2.  **`World` (The Container):**
+    *   **Responsibility:** The `World` is the central hub that contains everything in a level or scene. It owns the `THREE.Scene`, the list of all `Actors`, and manages global systems.
+    *   **Key Systems Owned by `World`:**
+        *   `InputManager`: Handles all raw keyboard, mouse, and gamepad input.
+        *   `TimerSystem`: Manages time-based events (`setTimeout`, `setInterval`).
+        *   `IPhysicsEngine`: The physics simulation instance (e.g., Rapier).
+        *   `INavigationServer`: The pathfinding instance (e.g., Recast).
+        *   `NetWorld`: The multiplayer and session management system.
+        *   `GameMode`: Defines the rules for the current game.
+
+3.  **`Actor` (The "What"):**
+    *   **Responsibility:** An `Actor` is any object that can be placed in the `World`. It serves as a container for `Component`s.
+    *   **Structure:** Every Actor has a `rootComponent` (a `SceneComponent`) which defines its position, rotation, and scale in the world. It can also have other `SceneComponent`s attached in a hierarchy, as well as non-transformable `Component`s.
+    *   **Examples:** `Pawn`, `PlayerController`, `Projectile`, `GLTFMeshActor`.
+
+4.  **`Component` (The "How"):**
+    *   **Responsibility:** `Component`s are the building blocks of `Actor`s, giving them behavior and functionality.
+    *   **Types:**
+        *   `Component`: The base class for non-spatial logic, like `CharacterStatsComponent` or `AnimationStateMachineComponent`.
+        *   `SceneComponent`: Extends `THREE.Object3D`, so it has a transform and can be part of the scene graph hierarchy. Almost all visual, audio, or physics-related components are `SceneComponent`s (e.g., `MeshComponent`, `LightComponent`, `SoundComponent`).
+
+5.  **Player Control Flow:**
+    *   The `InputManager` captures raw input.
+    *   A `PlayerController` (an `Actor`) is registered as an input handler. It translates raw input (e.g., 'W' key) into abstract commands (e.g., `addForwardInput`).
+    *   The `PlayerController` "possesses" a `Pawn` actor.
+    *   The `Pawn` actor receives the input commands and delegates them to its `MovementComponent` (e.g., `CharacterMovementComponent`).
+    *   The `MovementComponent` updates the transform of the `Pawn`'s root component, moving it in the world.
+
+---
+
+# Key Systems and Concepts
+
+## 1. Rendering & Scene Graph
+*   **Foundation:** Built on **THREE.js**. `SceneComponent` directly extends `THREE.Object3D`, making the engine's scene graph compatible with the THREE.js ecosystem.
+*   **Visuals:** `MeshComponent` is the basic renderable, while specialized versions like `GLTFMeshComponent`, `TerrainMeshComponent`, and `VoxelMeshComponent` handle more complex geometry.
+*   **Lighting:** A clean abstraction (`LightComponent`) wraps different THREE.js lights (`PointLightComponent`, `DirectionalLightComponent`, etc.), making them easy to add to Actors.
+*   **Camera:** Direct THREE.js camera integration allows cameras to be attached to any scene component, ideal for creating first-person, third-person, or cinematic cameras.
+*   **Extensions:** `ThreeJsExtensions.ts` cleverly patches the `THREE.Object3D.prototype` to add useful helper methods like `getWorldPosition` and `setWorldTransform`, simplifying transform manipulation significantly.
+
+## 2. Physics & Collision
+*   **Abstraction:** The `IPhysicsEngine` interface decouples the engine from a specific physics library. `BasePhysicsEngine` provides common logic for creating physics bodies from `SceneComponent` geometry.
+*   **Implementation:** The engine uses **Rapier** as its concrete physics implementation (`RapierPhysicsEngine`). It maps engine components to Rapier `RigidBody` and `Collider` objects.
+*   **Collision System:** A sophisticated collision system (`CollisionConfig`, `CollisionTypes`) allows for fine-grained control over interactions. It uses **channels** (e.g., Pawn, WorldStatic) and **profiles** to define responses (Block, Overlap, Ignore), similar to Unreal Engine.
+*   **Character Controller:** `CharacterMovementComponent` can use a built-in `KinematicCharacterController` from Rapier, enabling physically-correct movement with features like slope handling and auto-stepping.
+
+## 3. Animation
+*   **State Machine:** The `AnimationStateMachineComponent` is a powerful system for managing complex character animations. It uses a graph of states (e.g., "Idle", "Run", "Jump") and transitions between them based on parameters (e.g., `isRunning: true`, `isJumping: true`). This allows for dynamic, responsive animation that reacts to gameplay.
+*   **Caching:** `AnimationClipCache` is a singleton that prevents duplicate loading of animation data, which is crucial for performance when many instances of the same character are present.
+
+## 4. Serialization & Prefabs (`WorldSerialization`)
+*   **Core:** The engine has a robust serialization system capable of exporting the entire `World`, or individual `Actor`s, to a JSON format. This is the foundation for saving levels and creating prefabs.
+*   **Class Registry:** `ClassRegistry` maps class constructors to string names (e.g., `"ENGINE.ThirdPersonCharacterPawn"`). This allows the serializer to instantiate the correct classes when loading data. The `@EngineClass` decorator provides a clean registration mechanism.
+*   **Prefabs:** An actor can be created from a "prefab," which is a serialized `Actor` JSON file. The `GLTFMeshActor` is a good example of a simple prefab-like actor that just needs a model URL. `placePrefabs` shows how to spawn more complex, pre-configured actors.
+*   **Validation:** It uses the **Zod** library to define and validate the schema for serialized data, making the loading process safer and easier to debug.
+
+## 5. Multiplayer (`NetWorld`)
+*   **Architecture:** The networking system is designed around a central `NetWorld` that manages a `GameSession`. The session logic is abstracted via `IGameSession` and `IGameSessionManager`, with two provided implementations: `MemoryGameSession` (for local testing) and `WebSocketGameSession` (for real networking).
+*   **Replication:** Objects that need to be synchronized over the network must implement the `INetObject` interface.
+    *   `getNetConstructionData()`: Provides the data needed to create the object on a remote client (leveraging the serialization system).
+    *   `getNetDynamicState()` / `setNetDynamicState()`: Handle the frequent updates of properties like position and rotation. The system intelligently sends only changed data.
+*   **Movement Prediction:** `NetMovementPredictor` implements client-side prediction to hide latency. It buffers local and remote transforms and extrapolates the player's likely position, providing a smooth experience even with network delay.
+
+## 6. UI System
+*   **Foundation:** The UI system is DOM-based, managed by the `UIManager`. It creates an overlay on top of the game canvas.
+*   **Components:** `BaseUIComponent` is a powerful abstract class for creating reusable UI widgets (e.g., `ProgressBar`, `Minimap`, `InventoryGrid`). Each component can load its own HTML template and CSS styles from files, promoting a clean, modular structure.
+*   **Data-Driven:** UI components are designed to be data-driven. For example, you can call `progressBar.setValue(50)` rather than manually manipulating DOM element widths.
+
+## 7. Constructive Solid Geometry (CSG)
+*   **Powerful Tool:** The engine includes a CSG system for creating complex procedural geometry by adding, subtracting, and intersecting simpler shapes.
+*   **Implementation:** It uses the high-performance **Manifold 3D** library (via WebAssembly), which is lazily loaded to avoid increasing initial startup time.
+*   **User-Facing API:** `CSGCombiner` and `CSGShapes` (`CSGCubeComponent`, etc.) provide a component-based, user-friendly API. A developer can build a complex shape by simply adding CSG components as children to a `CSGCombiner` actor in the scene.
+
+# How to Build with Genesys: A Summary
+Based on the code, here's how a developer would typically use the engine:
+
+1.  **Setup the Game:** Create a class that extends `BaseGameLoop`. In its `preStart` or `postStart` methods, use `GameBuilder` helpers or custom code to add initial actors like a ground plane (`createDefaultGround`) and player start locations (`createPlayerStart`).
+2.  **Create a Player Character:** Extend `Pawn` (e.g., `ThirdPersonCharacterPawn`) or create a new one. Attach a `CharacterMovementComponent` to handle movement and a `GLTFMeshComponent` for the visual model. Attach an `AnimationStateMachineComponent` and configure its states (idle, walk, run, jump) to bring the character to life.
+3.  **Spawn the Player:** The `GameMode`'s `findPlayerStart` logic will determine where the player spawns. A `PlayerController` will be created, it will `possess` the player's `Pawn`, and the world's `InputManager` will route controls to it.
+4.  **Create Other Actors:**
+    *   For a simple static object, use `GLTFMeshActor` and provide a model URL.
+    *   For a weapon, create an `Actor`, attach a `ProjectileWeaponComponent`, and configure its `projectileClass` and `projectileOptions`.
+    *   For an enemy NPC, create an `Actor`, give it a `NpcMovementComponent` for pathfinding, and a `CharacterStatsComponent` for health.
+5.  **Build the Level:** Use the CSG tools (`CSGCombiner`) for procedural geometry, `TerrainMeshComponent` for landscapes, or place `GLTFMeshActor`s for static art.
+6.  **Add UI:** Use the `UIManager` to create UI components like a `ProgressBar` for health, an `AmmoCounter`, and a `Crosshair`. Bind these UI components to the data in the player's `CharacterStatsComponent` or `ProjectileWeaponComponent`.
+7.  **Go Multiplayer:** Set up a `WebSocketGameSessionManager`. Ensure important actors (`PlayerController`, `Pawn`) and components (`MovementComponent`) correctly implement `INetObject` to replicate their state across clients.
+
+Overall, the Genesys engine is a well-structured and powerful foundation for building 3D games, combining the flexibility of THREE.js with high-level architectural patterns from mature, commercial game engines.