@directivegames/genesys.js 3.1.24

package/docs/guides/7-building-levels.md

@@ -0,0 +1,211 @@
+## Instruction
+Use this doc to learn how to build levels in Genesys.js and understand how to create game environments using primitive shapes for prototyping, GLTFMeshComponent for complex artist-created levels, and Constructive Solid Geometry (CSG) for procedural level generation.
+
+# 7-building-levels.md
+
+## Building Levels in Genesys.js
+
+A level is the environment where your game takes place. In Genesys.js, a level is composed of various `Actor`s that define the static geometry, lighting, player start points, and interactive elements. This guide covers techniques for building levels, from simple procedural geometry to complex shapes using Constructive Solid Geometry (CSG).
+
+---
+
+## 1. Creating Basic Level Geometry
+
+For prototyping and creating simple environments, you can use the built-in primitive shapes provided by the `World` and `GameBuilder`.
+
+### The Ground Plane
+
+Almost every level needs a floor. The `GameBuilder` has a convenient method for this.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+class MyGame extends ENGINE.BaseGameLoop {
+    protected override preStart(): void {
+        // Creates a large, static ground plane with physics enabled.
+        ENGINE.GameBuilder.createDefaultGround(this.world);
+    }
+}
+```
+
+This creates a `MeshComponent` with a `BoxGeometry` and sets up a static physics body, so other objects can collide with it.
+
+### Adding Primitive Shapes
+
+The `World` object has helper methods to quickly add basic shapes to your scene. These are great for creating walls, platforms, pillars, and other simple structures.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+class MyGame extends ENGINE.BaseGameLoop {
+    protected override preStart(): void {
+        ENGINE.GameBuilder.createDefaultGround(this.world);
+        ENGINE.GameBuilder.createDefaultLighting(this.world);
+        ENGINE.GameBuilder.createDefaultPawnWithPhysics(this.world, ENGINE.CharacterMovementType.FirstPerson);
+
+        // Add a solid wall. It will be a dynamic physics body by default.
+        this.world.addBox({
+            position: new THREE.Vector3(0, 1, -10),
+            width: 10,
+            height: 2,
+            depth: 0.5,
+            color: 'gray',
+            // Let's make it static so it doesn't move.
+            motionType: ENGINE.PhysicsMotionType.Static
+        });
+        
+        // Add a cylindrical pillar.
+        this.world.addCylinder({
+            position: new THREE.Vector3(-8, 2.5, -10),
+            radius: 0.5,
+            height: 5,
+            color: 'silver',
+            motionType: ENGINE.PhysicsMotionType.Static
+        });
+
+        // Add a floating platform.
+        this.world.addBox({
+            position: new THREE.Vector3(0, 5, -20),
+            width: 5,
+            height: 0.2,
+            depth: 5,
+            color: 'darkgreen',
+            motionType: ENGINE.PhysicsMotionType.Static
+        });
+    }
+}
+```
+
+These methods (`addBox`, `addSphere`, `addCylinder`, etc.) are shortcuts for creating an `Actor` with a `MeshComponent` and the specified geometry and physics properties.
+
+---
+
+## 2. Using `GLTFMeshComponent` for Level Meshes
+
+For complex, artist-created levels, the best approach is to model the level in software like Blender and export it as a single `.glb` file. You can then load it into your scene using a `GLTFMeshComponent`.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+// Create an actor to hold the entire level mesh.
+const levelActor = new ENGINE.Actor({
+    rootComponent: new ENGINE.GLTFMeshComponent({
+        modelUrl: '@engine/assets/levels/MyAwesomeLevel.glb',
+        physicsOptions: {
+            enabled: true,
+            motionType: ENGINE.PhysicsMotionType.Static,
+            // Use 'Trimesh' for complex, static geometry to ensure accurate collision.
+            collisionMeshType: ENGINE.CollisionMeshType.Trimesh
+        }
+    })
+});
+
+// Since the mesh will have shadows cast on it, we need to enable `receiveShadow`.
+// We do this by traversing the model after it loads.
+const levelMeshComponent = levelActor.rootComponent as ENGINE.GLTFMeshComponent;
+levelMeshComponent.onModelLoaded(() => {
+    levelMeshComponent.getModel()?.traverse((object) => {
+        if (object instanceof THREE.Mesh) {
+            object.receiveShadow = true;
+        }
+    });
+});
+
+// world.addActors(levelActor);
+```
+
+---
+
+## 3. Procedural Levels with Constructive Solid Geometry (CSG)
+
+CSG is a powerful technique that allows you to create complex shapes by combining simpler shapes using boolean operations (add, subtract, intersect). This is perfect for procedurally generating levels with doorways, windows, tunnels, and other features.
+
+The system relies on two main components:
+*   `CSGCombiner`: The root component that takes all its children and combines them into a single mesh.
+*   `CSGComponent`s (`CSGCubeComponent`, `CSGCylinderComponent`, etc.): The primitive shapes that will be combined.
+
+### How to use CSG:
+
+1.  Create an `Actor` with a `CSGCombiner` as its root component.
+2.  Add `CSGComponent`s as children to the combiner.
+3.  Each `CSGComponent` has an `operation` property (`'add'`, `'subtract'`, or `'intersect'`).
+4.  The combiner processes the children in order to produce the final mesh.
+
+### Example: Creating a Wall with a Doorway
+
+This example demonstrates how to subtract a cube (the doorway) from another cube (the wall).
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+// First, you must enable the Manifold CSG library in your world configuration.
+class MyCSGGame extends ENGINE.BaseGameLoop {
+    public override getWorldConfiguration(): ENGINE.WorldOptions {
+        return {
+            ...super.getWorldConfiguration(),
+            useManifold: true // This is essential!
+        };
+    }
+    
+    protected override async preStart(): Promise<void> {
+        ENGINE.GameBuilder.createDefaultLighting(this.world);
+        ENGINE.GameBuilder.createDefaultGround(this.world);
+        ENGINE.GameBuilder.createDefaultPawnWithPhysics(this.world, ENGINE.CharacterMovementType.FirstPerson);
+
+        // 1. Create the CSG Actor.
+        const wallWithDoorActor = new ENGINE.Actor({
+            position: new THREE.Vector3(0, 1.5, -15),
+            // The root is the CSGCombiner. It will generate a MeshComponent as its own child.
+            rootComponent: new ENGINE.csg.CSGCombiner({
+                // The final combined mesh will have these physics properties.
+                physicsOptions: {
+                    enabled: true,
+                    motionType: ENGINE.PhysicsMotionType.Static,
+                    collisionMeshType: ENGINE.CollisionMeshType.Trimesh
+                }
+            })
+        });
+
+        const combiner = wallWithDoorActor.rootComponent as ENGINE.csg.CSGCombiner;
+
+        // 2. Create the main wall shape (an "add" operation).
+        const wallShape = new ENGINE.csg.CSGCubeComponent({
+            operation: 'add',
+            dimensions: new THREE.Vector3(8, 3, 0.4),
+            material: new THREE.MeshStandardMaterial({ color: 'lightgray' })
+        });
+        
+        // 3. Create the doorway shape (a "subtract" operation).
+        const doorwayShape = new ENGINE.csg.CSGCubeComponent({
+            operation: 'subtract',
+            dimensions: new THREE.Vector3(1.5, 2.2, 1), // Make it thicker than the wall to ensure a clean cut
+        });
+        
+        // 4. Add the shapes as children to the combiner.
+        combiner.add(wallShape, doorwayShape);
+
+        // The CSGCombiner automatically processes on `beginPlay`.
+        this.world.addActors(wallWithDoorActor);
+    }
+}
+```
+When you run this code, Genesys will:
+1.  Initialize the Manifold WASM module.
+2.  The `CSGCombiner` will find its children.
+3.  It starts with the `wallShape`.
+4.  It then subtracts the `doorwayShape` from it.
+5.  It generates a new `THREE.Mesh` from the result and applies the physics properties.
+
+This procedural approach allows for dynamic and varied level generation directly within the engine. You can combine many shapes and operations to build incredibly complex and optimized level geometry at runtime.
+
+## Source Code
+Below are relevant engine source code you MUST digest in order to get complete understanding of the topic. Read them carefully.
+
+```
+<file path={src/game/World.ts}>
+<file path={src/components/visual/GLTFMeshComponent.ts}>
+<file path={src/components/visual/MeshComponent.ts}>
+<file path={src/actors/Actor.ts}>
+<file path={src/components/csg/CSGCombiner.ts}>
+<file path={src/components/csg/CSGShapes.ts}>
+```

package/docs/guides/8-user-interface.md

@@ -0,0 +1,291 @@
+## Instruction
+Use this doc to understand how the user interface system works in Genesys.js and learn how to create 2D interfaces using UIManager, UIElements for simple displays, UILayouts with HTML/CSS templates, and reusable BaseUIComponent classes.
+
+# 8-user-interface.md
+
+## User Interface (UI) in Genesys.js
+
+Genesys.js features a flexible, DOM-based UI system that allows you to create and manage 2D interfaces for your game. This system is built around the `UIManager`, which provides tools for creating layouts from HTML/CSS templates and managing individual UI elements.
+
+This approach lets you leverage the full power of HTML and CSS for styling and layout, which is often faster and more flexible than in-game 3D UI systems.
+
+---
+
+## 1. The `UIManager`
+
+The `UIManager` is a global system, owned by the `World`, that serves as the root for all UI elements. It creates a container `div` that sits on top of your game's canvas. You don't create a `UIManager` yourself; you access it through the `world` instance.
+
+```typescript
+const uiManager = this.world.uiManager;
+```
+
+---
+
+## 2. Core UI Concepts
+
+*   **`UIElement`**: A lightweight wrapper around a standard `HTMLElement`. It provides a fluent API for manipulating the element's style, classes, and content. You create these using `uiManager.createElement()`.
+
+*   **`UILayout`**: A more powerful object that represents a complete piece of UI, constructed from an HTML template and a CSS stylesheet. This is the recommended way to build complex UI components like HUDs, menus, or inventory screens. You create these with `uiManager.createLayout()`.
+
+*   **`UIAssetLoader`**: A static helper class for loading the `.html` and `.css` files needed by `UILayout`.
+
+---
+
+## 3. Creating a Simple UI Element
+
+For very simple UI, like a debug text display, you can create a `UIElement` directly.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+class MyGame extends ENGINE.BaseGameLoop {
+    private scoreDisplay: ENGINE.UIElement | null = null;
+    private score: number = 0;
+
+    protected override preStart(): void {
+        // Create a simple text element to show the score.
+        this.scoreDisplay = this.world.uiManager.createElement('score-display', {
+            // The tag can be any valid HTML tag.
+            tag: 'h2', 
+            textContent: 'Score: 0',
+            // Use CSS for positioning and styling.
+            style: {
+                position: 'absolute',
+                top: '20px',
+                left: '20px',
+                color: 'white',
+                fontFamily: 'Arial, sans-serif',
+                textShadow: '2px 2px 4px black'
+            }
+        });
+
+        // Set up a timer to increment the score every second.
+        this.world.timerSystem.setInterval(() => {
+            this.score++;
+            this.scoreDisplay?.setText(`Score: ${this.score}`);
+        }, 1);
+    }
+}
+```
+
+---
+
+## 4. Building with `UILayout` and Templates
+
+For anything more complex than a single label, `UILayout` is the way to go. This involves creating two files: an HTML template and a CSS stylesheet.
+
+**`/assets/ui/templates/health-bar.html`**:
+```html
+<div class="health-bar-container">
+    <div class="health-bar-label">HP</div>
+    <div class="health-bar">
+        <div class="health-bar-fill"></div>
+    </div>
+    <div class="health-value-text">{{currentHP}}/{{maxHP}}</div>
+</div>
+```
+*Notice the `{{handlebar}}` syntax for data interpolation.*
+
+**`/assets/ui/styles/health-bar.css`**:
+```css
+.health-bar-container {
+    position: absolute;
+    bottom: 20px;
+    left: 20px;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    background-color: rgba(0,0,0,0.5);
+    padding: 8px;
+    border-radius: 4px;
+    color: white;
+    font-family: sans-serif;
+}
+.health-bar {
+    width: 200px;
+    height: 20px;
+    background-color: #444;
+    border: 1px solid #666;
+    border-radius: 3px;
+}
+.health-bar-fill {
+    height: 100%;
+    background-color: #22c55e; /* Green */
+    width: 100%; /* Will be controlled by code */
+    transition: width 0.3s ease-out;
+}
+```
+
+Now, let's create a `UILayout` from these files.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+class MyGame extends ENGINE.BaseGameLoop {
+    protected override async postStart(): Promise<void> {
+        // 1. Load the assets.
+        const { template, styles } = await ENGINE.UIAssetLoader.loadUIAsset(
+            ENGINE.AssetPath.fromString('@engine/assets/ui/templates/health-bar.html'),
+            ENGINE.AssetPath.fromString('@engine/assets/ui/styles/health-bar.css')
+        );
+
+        // 2. Create the layout.
+        const healthBarLayout = this.world.uiManager.createLayout('player-hud', {
+            template,
+            styles,
+            // Provide initial data for the template placeholders.
+            data: {
+                currentHP: 100,
+                maxHP: 100
+            }
+        });
+
+        // 3. Interact with the layout's elements.
+        const fillElement = healthBarLayout.querySelector('.health-bar-fill') as HTMLElement;
+        const textElement = healthBarLayout.querySelector('.health-value-text') as HTMLElement;
+
+        // Example: Simulate taking damage.
+        this.world.timerSystem.setInterval(() => {
+            const currentHP = parseInt(textElement.innerText.split('/')[0]);
+            const newHP = Math.max(0, currentHP - 10);
+            
+            // Update the UI.
+            fillElement.style.width = `${(newHP / 100) * 100}%`;
+            textElement.textContent = `${newHP}/100`;
+
+        }, 2); // Take damage every 2 seconds.
+    }
+}
+```
+
+---
+
+## 5. Reusable UI Components
+
+To promote reusability and encapsulation, Genesys provides a `BaseUIComponent` class. You can extend this class to create self-contained UI components like a `ProgressBar`, `InventoryGrid`, or `Minimap`. The engine already includes several of these pre-built components.
+
+Using a pre-built component is much cleaner than managing templates and layouts manually.
+
+### Example: Using the `ProgressBar` Component
+
+Let's refactor our health bar example to use the built-in `ProgressBar` component.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+class MyGame extends ENGINE.BaseGameLoop {
+    private healthBar: ENGINE.ProgressBar | null = null;
+    private currentHealth: number = 100;
+    private maxHealth: number = 100;
+
+    protected override async postStart(): Promise<void> {
+        // 1. Create an instance of the ProgressBar component.
+        this.healthBar = new ENGINE.ProgressBar(this.world.uiManager, {
+            width: 250,
+            height: 25,
+            label: 'HEALTH',
+            // Use the 'health' theme for automatic coloring (green/orange/red).
+            theme: 'health', 
+            // Animate value changes smoothly.
+            animate: true,
+        });
+
+        // 2. Initialize the component (this loads its assets and creates the layout).
+        await this.healthBar.initialize();
+        
+        // 3. Position the component using setPosition() for precise control.
+        this.healthBar.setPosition({
+            position: 'absolute',
+            bottom: '20px',
+            left: '20px'
+        });
+        
+        // 4. Set its initial value.
+        this.healthBar.setValue(this.currentHealth);
+        this.healthBar.setMaxValue(this.maxHealth);
+
+        // 5. Simulate taking damage.
+        this.world.timerSystem.setInterval(() => {
+            this.currentHealth = Math.max(0, this.currentHealth - 15);
+            // The component handles the animation and text updates automatically.
+            this.healthBar?.setValue(this.currentHealth);
+        }, 2);
+    }
+
+    // Don't forget to clean up UI components when they're no longer needed.
+    public override destroy(): void {
+        this.healthBar?.destroy();
+        super.destroy();
+    }
+}
+```
+
+This approach is much cleaner and more maintainable. The component encapsulates all its HTML, CSS, and logic. You interact with it through a clear, high-level API (`setValue`, `setMaxValue`, etc.).
+
+### Positioning UI Components
+
+UI components can be positioned in two ways:
+
+1. **Using predefined positions** (via the `position` option in the constructor):
+   - `'top-left'`, `'top-center'`, `'top-right'`
+   - `'bottom-left'`, `'bottom-center'`, `'bottom-right'`
+   - `'center'`
+
+2. **Using custom positioning** (via the `.setPosition()` method for precise control):
+
+```typescript
+// Create a component without specifying position
+const healthBar = new ENGINE.ProgressBar(this.world.uiManager, {
+    width: 300,
+    height: 25,
+    label: 'HEALTH',
+    theme: 'health'
+});
+
+await healthBar.initialize();
+
+// Use setPosition() for precise positioning with CSS properties
+healthBar.setPosition({
+    position: 'absolute',
+    bottom: '20px',
+    right: '20px'
+});
+
+// You can also target specific child elements within the component
+healthBar.setPosition({
+    fontSize: '14px',
+    fontWeight: 'bold'
+}, '.progress-label'); // Target the label specifically
+```
+
+**Best Practice**: Use the `.setPosition()` method for precise control over UI positioning, especially when you need pixel-perfect placement or responsive positioning.
+
+The engine includes the following ready-to-use UI components in the `ENGINE` namespace:
+*   `ProgressBar`
+*   `AmmoCounter`
+*   `Crosshair`
+*   `InventoryBar`
+*   `InventoryGrid`
+*   `Minimap`
+*   `NumberDisplay`
+*   `ReloadIndicator`
+*   `ControlsPanel`
+
+## Source Code
+Below are relevant engine source code you MUST digest in order to get complete understanding of the topic. Read them carefully.
+
+```
+<file path={src/ui/UIManager.ts}>
+<file path={src/ui/components/AmmoCounter.ts}>
+<file path={src/ui/components/BaseUIComponent.ts}>
+<file path={src/ui/components/Compass.ts}>
+<file path={src/ui/components/ControlsPanel.ts}>
+<file path={src/ui/components/Crosshair.ts}>
+<file path={src/ui/components/InventoryBar.ts}>
+<file path={src/ui/components/InventoryGrid.ts}>
+<file path={src/ui/components/Minimap.ts}>
+<file path={src/ui/components/NumberDisplay.ts}>
+<file path={src/ui/components/ProgressBar.ts}>
+<file path={src/ui/components/ReloadIndicator.ts}>
+<file path={src/ui/ui-loader.ts}>
+```

package/docs/guides/9-multiplayer.md

@@ -0,0 +1,181 @@
+## Instruction
+Use this doc to understand how multiplayer and networking work in Genesys.js and learn how to implement server-authoritative multiplayer using IGameSession for shared state, INetObject interface for networked objects, and client-side prediction for smooth gameplay.
+
+# 9-multiplayer.md
+
+## Multiplayer and Networking in Genesys.js
+
+Genesys.js is designed with multiplayer in mind, featuring a built-in networking system that handles object replication and state synchronization. This guide provides a foundational understanding of how to create a multiplayer experience.
+
+The networking architecture is based on a server-authoritative model, but with a flexible client-side implementation. The core idea is that a **Game Session** acts as a central data store that all clients connect to.
+
+---
+
+## 1. Core Networking Concepts
+
+*   **`NetWorld`**: Every `World` has a `netWorld` property. This object is the bridge between your local game world and the remote game session. It's responsible for tracking networked objects and replicating their state.
+
+*   **`IGameSessionManager`**: An abstraction for connecting to and managing game sessions. Genesys provides two implementations:
+    *   `MemoryGameSessionManager`: An in-memory, local "server". Perfect for single-player testing or local multiplayer on the same machine. No data is sent over a network.
+    *   `WebSocketGameSessionManager`: A client that connects to a dedicated WebSocket server for true online multiplayer.
+
+*   **`IGameSession`**: Represents a connection to a single game room or session. Once connected, clients can add, update, and delete shared objects.
+
+*   **`INetObject`**: An interface that any `Actor` or `Component` must implement to be part of the networking system. It defines how an object is created on remote clients and how its state is synchronized.
+
+---
+
+## 2. Setting Up a Game Session
+
+Before any networking can happen, you must create or join a game session. This is typically done at the start of your game.
+
+### Example: Creating and Joining a Local Session
+
+For this example, we'll use the `MemoryGameSessionManager` for simplicity.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+class MyMultiplayerGame extends ENGINE.BaseGameLoop {
+    protected override async postStart(): Promise<void> {
+        // 1. Set the session manager on the NetWorld.
+        const netWorld = this.world.netWorld;
+        netWorld.setGameSessionManager(new ENGINE.multiplayer.MemoryGameSessionManager());
+
+        // 2. Try to join the first available session.
+        try {
+            const sessions = await netWorld.listSessions();
+            if (sessions.length > 0) {
+                console.log("Joining existing session...");
+                await netWorld.joinSession(sessions[0].sessionId);
+            } else {
+                console.log("No sessions found, creating a new one...");
+                await netWorld.createSession("My First Session");
+            }
+        } catch (error) {
+            console.error("Failed to start multiplayer session:", error);
+            return;
+        }
+
+        console.log("Successfully connected to session:", netWorld.getGameSession()?.getDescription());
+
+        // Now that we are in a session, we can spawn networked objects.
+        this.spawnPlayer();
+    }
+
+    private spawnPlayer(): void {
+        // The GameBuilder pawn is already a networked object.
+        ENGINE.GameBuilder.createDefaultAnimatedCharacter(this.world);
+    }
+}
+```
+
+To test this, you can open two browser tabs to the same game. The first tab will create the session, and the second tab will join it.
+
+---
+
+## 3. Networked Objects (`INetObject`)
+
+For an object to be synchronized across the network, its class (and the classes of its components) must implement the `INetObject` interface. The `Actor` and `Component` base classes already do this. The key methods you need to be aware of are:
+
+*   **`isNetRelevant()`**: Should this object be networked? Return `true` to enable networking. Player-controlled pawns are relevant by default. For other objects, you must explicitly make them relevant.
+*   **`getNetConstructionData()`**: Returns a JSON object with the necessary information to create this object on a remote client. For actors, this is usually their serialized data.
+*   **`getNetDynamicState()`**: Called every frame. Returns a JSON object containing the state that needs to be synchronized (e.g., position, health). If it returns `null`, no update is sent. The engine automatically optimizes this by comparing it to the last sent state.
+*   **`setNetDynamicState(state)`**: Called on remote clients when they receive a state update for this object. This is where you apply the received state (e.g., update the object's position).
+
+### Example: A Networked Spinning Cube
+
+Let's create a cube that spins on the "server" (the client that created it) and has its rotation synchronized to all other clients.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+@ENGINE.GameClass()
+class NetworkedCube extends ENGINE.Actor {
+    private rotationSpeed: number = 1.0;
+
+    constructor(options: ENGINE.ActorOptions) {
+        super({
+            ...options,
+            rootComponent: new ENGINE.MeshComponent({
+                geometry: new THREE.BoxGeometry(1, 1, 1),
+                material: new THREE.MeshStandardMaterial({ color: 'purple' })
+            })
+        });
+    }
+
+    // --- INetObject Implementation ---
+
+    // 1. Make this actor network-relevant.
+    public override isNetRelevant(): boolean {
+        return true;
+    }
+    
+    // 2. The default `getNetConstructionData` in Actor already serializes the
+    //    actor, so we don't need to override it for this simple case.
+
+    // 3. For the client that owns this cube, we'll handle the spinning logic.
+    //    Other clients will only receive updates.
+    public override tickPrePhysics(deltaTime: number): void {
+        // The NetWorld assigns a unique client ID. We can check if we are the owner.
+        if (this.getNetClientId() === this.world?.netWorld.clientId) {
+            // I am the owner, so I control the rotation.
+            this.rootComponent.addLocalRotation(
+                new THREE.Euler(0, this.rotationSpeed * deltaTime, 0)
+            );
+        }
+        
+        super.tickPrePhysics(deltaTime);
+    }
+    
+    // 4. The default `getNetDynamicState` in Actor already sends position,
+    //    rotation, and scale, which is exactly what we need.
+
+    // 5. The default `setNetDynamicState` in Actor applies the transform and
+    //    uses the `NetMovementPredictor` for smooth interpolation. We don't
+    //    need to override it.
+}
+```
+
+Now, in your game setup after connecting to a session:
+
+```typescript
+// Spawn the networked cube.
+const cube = new NetworkedCube({
+    position: new THREE.Vector3(5, 1, 0)
+});
+this.world.addActors(cube);
+```
+
+When you run this with two clients:
+*   The first client (the "owner") will create the cube. The cube's spinning logic will run locally. The `NetWorld` will send its creation data and continuous rotation updates to the session.
+*   The second client will receive the creation data, spawn a "remote" copy of the `NetworkedCube`. It will then receive the dynamic state updates (the new rotation) and apply them, making its cube spin in sync with the first client's cube.
+
+---
+
+## 4. Client-Side Prediction and Smoothing
+
+When you look at a remote player in a networked game, you are seeing a "ghost". If you just set its position directly from network updates, its movement would appear jerky due to network latency and packet loss.
+
+Genesys.js solves this with the **`NetMovementPredictor`**.
+
+*   For your **own** player character, your inputs are applied immediately, giving you instant feedback. The `BasePawnMovementComponent` sends your position and inputs to the session. If the server later sends a correction (e.g., you collided with something you didn't know about), your pawn will smoothly correct its position.
+*   For **remote** objects, `setNetDynamicState` doesn't just teleport the object. It feeds the incoming transform updates into the `NetMovementPredictor`. The predictor then uses interpolation and extrapolation to create a smooth visual path for the object, hiding network jitter.
+
+This entire system is enabled by default on `Actor` and `BasePawnMovementComponent`, so for most standard use cases, you get smooth multiplayer movement for free.
+
+## Next Steps
+
+This guide provides a basic overview. The multiplayer system is powerful and has more advanced features:
+*   **Custom Dynamic State**: You can override `getNetDynamicState` to send custom data beyond transforms, like `health` or `ammo`.
+*   **Remote Procedure Calls (RPCs)**: While not explicitly shown, you can implement RPCs by creating special networked objects that represent function calls and their arguments.
+*   **WebSocket Server**: To move beyond local testing, you will need to run the companion Genesys WebSocket server and use the `WebSocketGameSessionManager`. The server code is designed to be simple and stateless.
+
+## Source Code
+Below are relevant engine source code you MUST digest in order to get complete understanding of the topic. Read them carefully.
+
+```
+<file path={src/multiplayer/NetWorld.ts}>
+<file path={src/multiplayer/interface.ts}>
+<file path={src/multiplayer/MovementPrediction.ts}>
+```