@directivegames/genesys.js 3.1.24

package/docs/guides/1-actors-and-components.md

@@ -0,0 +1,955 @@
+## Instruction
+Use this doc to learn how the Actor-Component Model works in Genesys.js and understand how Actors serve as world containers while Components provide reusable functionality for creating complex, modular game objects.
+
+# 1-actors-and-components.md
+
+## The Actor-Component Model in Genesys.js
+
+Welcome to Genesys.js! The core of all object-oriented design in the engine is the **Actor-Component Model**. This paradigm is fundamental to creating interactive, modular, and reusable game objects.
+
+*   **Actor**: An `Actor` is an object that can be placed into your game world. Think of it as a container or a blueprint. By itself, an actor only has a position, rotation, and scale. It doesn't *do* anything. Actors gain functionality by having **Components** attached to them. Examples of actors could be a character, a projectile, a door, or a trigger volume.
+
+*   **Component**: A `Component` is a reusable piece of functionality that can be added to any `Actor`. Components are what give actors their behaviors and properties. For example, a `MeshComponent` makes an actor visible, a `CharacterMovementComponent` makes it controllable, and a `SoundComponent` allows it to play audio.
+
+By combining different components, you can create complex game objects without writing monolithic classes. This guide will walk you through creating and using Actors and Components in Genesys.js.
+
+---
+
+## 1. Actors (`ENGINE.Actor`)
+
+The `ENGINE.Actor` class is the base class for all objects that can be placed in a `World`.
+
+### Creating a Basic Actor
+
+The simplest way to create an actor is to instantiate it and add it to the world. Every actor automatically gets a `rootComponent` (`ENGINE.SceneComponent`) which anchors its transform and any child components.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+// A simple game setup
+class MyGame extends ENGINE.BaseGameLoop {
+    protected override preStart(): void {
+        // Create an empty actor at position (0, 2, 0)
+        const myActor = new ENGINE.Actor({
+            position: new THREE.Vector3(0, 2, 0)
+        });
+
+        // Actors don't do anything until they are added to the world
+        this.world.addActors(myActor);
+
+        console.log(`Actor ${myActor.name} has been added to the world.`);
+    }
+}
+```
+
+### The Actor Lifecycle
+
+Actors follow a specific lifecycle managed by the `World`. You can hook into this lifecycle by overriding its methods in your custom actor classes.
+
+*   **`constructor()`**: Called when the actor is first created with `new`. This is where you should set up initial properties and add components.
+*   **`beginPlay()`**: Called once the actor has been added to a `World` and the game has started. This is the ideal place for initialization logic that requires access to the `World` or other actors.
+*   **`tickPrePhysics(deltaTime)`**: Called every frame *before* the physics simulation runs. Most game logic, such as input handling and movement calculations, should go here. `deltaTime` is the time in seconds since the last frame.
+*   **`tickPostPhysics(deltaTime)`**: Called every frame *after* the physics simulation. This is useful for logic that needs to react to physics results, like updating animations based on movement.
+*   **`endPlay()`**: Called when the actor is being removed from the `World` or the game is ending. Use this for cleanup tasks.
+
+Here's an example of a custom actor demonstrating the lifecycle hooks:
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+// Custom classes must be registered to be recognized by the engine, especially for serialization.
+@ENGINE.GameClass()
+class LifecycleActor extends ENGINE.Actor {
+    private tickCounter: number = 0;
+
+    constructor(options: ENGINE.ActorOptions) {
+        super(options);
+        console.log(`${this.name}: Constructor called!`);
+    }
+
+    // `beginPlay` is an ideal place for setup logic that depends on the world.
+    public override beginPlay(): void {
+        super.beginPlay(); // It's good practice to call the parent method.
+        console.log(`${this.name}: Begin Play! World is now available.`);
+        
+        // Example: Set a timer to destroy this actor after 5 seconds.
+        this.setLifeSpan(5); 
+    }
+
+    // `tickPrePhysics` is for frame-by-frame logic.
+    public override tickPrePhysics(deltaTime: number): void {
+        super.tickPrePhysics(deltaTime);
+        this.tickCounter++;
+        if (this.tickCounter % 60 === 0) { // Log every 60 frames
+            console.log(`${this.name}: Ticking... (deltaTime: ${deltaTime.toFixed(4)})`);
+        }
+    }
+
+    // `tickPostPhysics` is called after physics updates.
+    public override tickPostPhysics(deltaTime: number): void {
+        super.tickPostPhysics(deltaTime);
+    }
+
+    // `endPlay` is for cleanup.
+    public override endPlay(): void {
+        super.endPlay();
+        console.log(`${this.name}: End Play! This actor is being destroyed.`);
+    }
+}
+```
+
+### Essential Actor Methods
+
+*   `rootComponent`: Returns the root `SceneComponent` of the actor. All visual/spatial components are children of this component.
+*   `getWorld()`: Returns the `World` instance this actor belongs to. It's `null` until the actor is added to a world.
+*   `destroy()`: Schedules the actor for removal from the world. The actor and its components will be removed at the end of the current frame.
+*   `setWorldTransform(transform)`: Teleports the actor to a new position, rotation, or scale in world space.
+*   `getWorldTransform()`: Gets the actor's current world space transform.
+
+---
+
+## 2. Components (`ENGINE.Component` & `ENGINE.SceneComponent`)
+
+Components add functionality to actors. There are two base types:
+
+1.  **`ENGINE.Component`**: For non-spatial logic. These components don't have a transform (position/rotation/scale) and are not part of the scene graph hierarchy. They are perfect for managing data, stats, or abstract behaviors.
+2.  **`ENGINE.SceneComponent`**: For spatial logic. This component type extends `THREE.Object3D`, so it has a transform and can be part of the scene graph. Any component that needs to be visible, have a physical presence, or be positioned in the world should inherit from this.
+
+### Creating a Custom Component
+
+Let's create a simple component that logs a message. Since it has no spatial properties, we'll extend `ENGINE.Component`.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+@ENGINE.GameClass()
+class LoggingComponent extends ENGINE.Component<ENGINE.ComponentOptions> {
+    
+    public override beginPlay(): void {
+        super.beginPlay();
+        // this.getActor() will return the actor this component is attached to.
+        console.log(`LoggingComponent attached to ${this.getActor()?.name} has begun play.`);
+    }
+
+    public logMessage(message: string): void {
+        console.log(`[${this.getActor()?.name}] LOG: ${message}`);
+    }
+}
+```
+
+### Attaching Components to an Actor
+
+You can add components to an actor either during its construction or later on.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+// (Assuming LoggingComponent is defined as above)
+
+// --- Method 1: In the constructor ---
+@ENGINE.GameClass()
+class ActorWithLogger extends ENGINE.Actor {
+    public readonly logger: LoggingComponent;
+
+    constructor(options: ENGINE.ActorOptions) {
+        super({
+            ...options,
+            // You can add components directly via the actor options.
+            components: [ new LoggingComponent() ]
+        });
+        
+        // You can get a reference to the component for later use.
+        this.logger = this.getComponent(LoggingComponent)!;
+    }
+
+    public override beginPlay(): void {
+        super.beginPlay();
+        this.logger.logMessage("I am alive!");
+    }
+}
+
+// --- Method 2: After construction ---
+const myActor = new ENGINE.Actor({});
+const myLogger = new LoggingComponent();
+
+// Use the `addComponents` method to attach it.
+myActor.addComponents(myLogger);
+```
+
+### `SceneComponent` Hierarchy
+
+`SceneComponent`s form a hierarchy. Every actor has a `rootComponent`. You can add other `SceneComponent`s as children to this root, or to each other. This creates a parent-child relationship where child transforms are relative to their parent.
+
+This is how you build complex objects. For example, a character actor might have:
+*   A root `SceneComponent` at its feet.
+*   A `MeshComponent` (the character model) attached to the root.
+*   A Three.js camera attached to the mesh's head bone, so it follows the head's animation.
+*   A `LightComponent` attached to a hand bone to simulate a flashlight.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+// Create an actor
+const myActor = new ENGINE.Actor({});
+
+// Create a mesh component (a cube)
+const cubeMesh = new ENGINE.MeshComponent({
+    geometry: new THREE.BoxGeometry(1, 1, 1),
+    material: new THREE.MeshStandardMaterial({ color: 'red' })
+});
+
+// Create another mesh component (a small sphere)
+const sphereMesh = new ENGINE.MeshComponent({
+    geometry: new THREE.SphereGeometry(0.2),
+    material: new THREE.MeshStandardMaterial({ color: 'blue' }),
+    position: new THREE.Vector3(0, 1, 0) // Position relative to its parent
+});
+
+// Attach the cube to the actor's root
+myActor.rootComponent.add(cubeMesh);
+
+// Attach the sphere to the cube. Now, the sphere will move with the cube.
+cubeMesh.add(sphereMesh);
+
+// Add the actor to the world to make it visible
+// world.addActors(myActor);
+```
+
+---
+
+## 3. Full Example: Creating a Custom Rotating Actor
+
+Let's combine everything we've learned to create a reusable `RotatingCubeActor`.
+
+**Step 1: Create a `RotationComponent` for the logic.**
+
+This component will be responsible for rotating its owner. It's a non-spatial `Component`.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+@ENGINE.GameClass()
+class RotationComponent extends ENGINE.Component<ENGINE.ComponentOptions> {
+    public rotationSpeed: number = 1.0; // Radians per second
+
+    // We use tickPrePhysics to update the actor's state each frame.
+    public override tickPrePhysics(deltaTime: number): void {
+        super.tickPrePhysics(deltaTime);
+
+        // Get the actor this component is attached to.
+        const owner = this.getActor();
+        if (!owner) {
+            return;
+        }
+
+        // Get the actor's root component to apply rotation.
+        const root = owner.rootComponent;
+        
+        // Add rotation around the Y (up) axis.
+        root.addLocalRotation(new THREE.Euler(0, this.rotationSpeed * deltaTime, 0));
+    }
+}
+```
+
+**Step 2: Create the `RotatingCubeActor` class.**
+
+This actor will encapsulate a visual mesh and our rotation logic.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+// (Assuming RotationComponent is defined as above)
+
+@ENGINE.GameClass()
+class RotatingCubeActor extends ENGINE.Actor {
+    
+    public rotationComponent: RotationComponent;
+
+    constructor(options: ENGINE.ActorOptions) {
+        super({
+            // Pass along any options from the user.
+            ...options,
+            // Define the root component directly in the constructor.
+            // This is cleaner than adding it afterwards.
+            rootComponent: new ENGINE.MeshComponent({
+                geometry: new THREE.BoxGeometry(1, 1, 1),
+                material: new THREE.MeshStandardMaterial({ color: 'cyan' })
+            })
+        });
+
+        // Create and add our custom rotation component.
+        this.rotationComponent = new RotationComponent();
+        this.addComponents(this.rotationComponent);
+    }
+    
+    public setRotationSpeed(speed: number): void {
+        this.rotationComponent.rotationSpeed = speed;
+    }
+}
+```
+
+**Step 3: Spawn the actor in your game.**
+
+Now you can easily create instances of your new actor.
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+// (Assuming RotatingCubeActor is defined as above)
+
+class MyGame extends ENGINE.BaseGameLoop {
+    protected override preStart(): void {
+        // Create default lighting and a ground plane for context.
+        ENGINE.GameBuilder.createDefaultLighting(this.world);
+        ENGINE.GameBuilder.createDefaultGround(this.world);
+
+        // Spawn our custom actor at position (0, 1, -5).
+        const rotatingCube = new RotatingCubeActor({
+            position: new THREE.Vector3(0, 1, -5)
+        });
+        
+        // Let's make it a bit faster.
+        rotatingCube.setRotationSpeed(2.5);
+
+        // Spawn another one that's slower.
+        const rotatingCube2 = new RotatingCubeActor({
+            position: new THREE.Vector3(3, 1, -5)
+        });
+        rotatingCube2.setRotationSpeed(0.5);
+
+        // Add them to the world.
+        this.world.addActors(rotatingCube, rotatingCube2);
+    }
+}
+```
+
+This example demonstrates the power of the Actor-Component model. The `RotatingCubeActor` is a self-contained, reusable object, and the `RotationComponent` could be attached to *any* actor to make it rotate.
+
+---
+
+## 4. Extending Actor with Custom Options
+
+When creating custom actor classes, you often need to accept additional configuration options beyond the basic `ActorOptions`. Genesys.js provides a clean pattern for extending the options interface while maintaining type safety and proper inheritance.
+
+### Defining Custom Options
+
+To create custom options for your actor, extend the `ActorOptions` interface and define a `DEFAULT_OPTIONS` static getter:
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+// Define your custom options interface
+interface CustomActorOptions extends ENGINE.ActorOptions {
+    health?: number;
+    speed?: number;
+    color?: THREE.ColorRepresentation;
+    weaponType?: string;
+}
+
+@ENGINE.GameClass()
+class CustomActor extends ENGINE.Actor<CustomActorOptions> {
+    // Define default values for your custom options, inheriting from parent
+    static override get DEFAULT_OPTIONS(): CustomActorOptions {
+        return {
+            ...ENGINE.Actor.DEFAULT_OPTIONS,
+            health: 100,
+            speed: 5.0,
+            color: 0xff0000,
+            weaponType: 'sword'
+        };
+    }
+
+    public readonly health: number;
+    public readonly speed: number;
+    public readonly color: THREE.ColorRepresentation;
+    public readonly weaponType: string;
+
+    constructor(options: CustomActorOptions = {} as CustomActorOptions) {
+        super(options);
+        
+        // Merge user options with defaults
+        const mergedOptions = { ...CustomActor.DEFAULT_OPTIONS, ...options };
+        
+        this.health = mergedOptions.health!;
+        this.speed = mergedOptions.speed!;
+        this.color = mergedOptions.color!;
+        this.weaponType = mergedOptions.weaponType!;
+        
+        console.log(`Created ${this.name} with health: ${this.health}, speed: ${this.speed}`);
+    }
+}
+```
+
+### Using the `getDefaultOptions()` Method
+
+The Actor base class provides a `getDefaultOptions()` method that returns the default options for your actor class:
+
+```typescript
+constructor(options: CustomActorOptions = {} as CustomActorOptions) {
+    super(options);
+    
+    // Use the built-in method to get defaults
+    const defaults = this.getDefaultOptions();
+    const mergedOptions = { ...defaults, ...options };
+    
+    this.health = mergedOptions.health!;
+    this.speed = mergedOptions.speed!;
+    // ... etc
+}
+```
+
+### Practical Example: Configurable Enemy Actor
+
+Here's a complete example of a configurable enemy actor that demonstrates best practices:
+
+```typescript
+interface EnemyActorOptions extends ENGINE.ActorOptions {
+    enemyType?: 'grunt' | 'elite' | 'boss';
+    health?: number;
+    attackDamage?: number;
+    movementSpeed?: number;
+    detectionRadius?: number;
+    modelUrl?: string;
+    dropItems?: string[];
+}
+
+@ENGINE.GameClass()
+class EnemyActor extends ENGINE.Actor<EnemyActorOptions> {
+    static override get DEFAULT_OPTIONS(): EnemyActorOptions {
+        return {
+            ...ENGINE.Actor.DEFAULT_OPTIONS,
+            enemyType: 'grunt',
+            health: 50,
+            attackDamage: 10,
+            movementSpeed: 3.0,
+            detectionRadius: 10.0,
+            modelUrl: '@engine/assets/enemies/grunt.glb',
+            dropItems: ['coin']
+        };
+    }
+
+    // Presets for different enemy types
+    static readonly ENEMY_PRESETS: Record<string, Partial<EnemyActorOptions>> = {
+        grunt: {
+            health: 50,
+            attackDamage: 10,
+            movementSpeed: 3.0,
+            modelUrl: '@engine/assets/enemies/grunt.glb'
+        },
+        elite: {
+            health: 150,
+            attackDamage: 25,
+            movementSpeed: 4.0,
+            modelUrl: '@engine/assets/enemies/elite.glb',
+            dropItems: ['coin', 'gem']
+        },
+        boss: {
+            health: 500,
+            attackDamage: 50,
+            movementSpeed: 2.0,
+            detectionRadius: 20.0,
+            modelUrl: '@engine/assets/enemies/boss.glb',
+            dropItems: ['coin', 'gem', 'rare_item']
+        }
+    };
+
+    public readonly enemyConfig: Required<EnemyActorOptions>;
+    private healthComponent: HealthComponent;
+    private aiComponent: AIComponent;
+
+    constructor(options: EnemyActorOptions = {} as EnemyActorOptions) {
+        // Apply preset if enemyType is specified
+        const presetOptions = options.enemyType ? 
+            EnemyActor.ENEMY_PRESETS[options.enemyType] : {};
+        
+        const mergedOptions = {
+            ...EnemyActor.DEFAULT_OPTIONS,
+            ...presetOptions,
+            ...options
+        };
+
+        super(mergedOptions);
+        
+        this.enemyConfig = mergedOptions as Required<EnemyActorOptions>;
+        
+        this.setupComponents();
+    }
+    
+    private setupComponents(): void {
+        // Create health component
+        this.healthComponent = new HealthComponent({
+            maxHealth: this.enemyConfig.health,
+            currentHealth: this.enemyConfig.health
+        });
+        
+        // Create AI component
+        this.aiComponent = new AIComponent({
+            detectionRadius: this.enemyConfig.detectionRadius,
+            movementSpeed: this.enemyConfig.movementSpeed,
+            attackDamage: this.enemyConfig.attackDamage
+        });
+        
+        // Create visual component if model URL is provided
+        if (this.enemyConfig.modelUrl) {
+            const meshComponent = new ENGINE.MeshComponent({
+                // Load model from URL
+                // This would typically use a model loader
+            });
+            this.rootComponent.add(meshComponent);
+        }
+        
+        this.addComponents(this.healthComponent, this.aiComponent);
+    }
+    
+    public takeDamage(damage: number): void {
+        this.healthComponent.takeDamage(damage);
+        if (this.healthComponent.isDead()) {
+            this.dropItems();
+            this.destroy();
+        }
+    }
+    
+    private dropItems(): void {
+        this.enemyConfig.dropItems.forEach(itemType => {
+            // Spawn item at this actor's location
+            console.log(`Dropping ${itemType} at ${this.getWorldPosition()}`);
+        });
+    }
+}
+
+// Usage examples:
+class MyGame extends ENGINE.BaseGameLoop {
+    protected override preStart(): void {
+        // Create a basic grunt enemy
+        const grunt = new EnemyActor({
+            position: new THREE.Vector3(5, 0, 0),
+            enemyType: 'grunt'
+        });
+        
+        // Create a custom elite enemy with modified stats
+        const customElite = new EnemyActor({
+            position: new THREE.Vector3(-5, 0, 0),
+            enemyType: 'elite',
+            health: 200, // Override the preset health
+            dropItems: ['coin', 'gem', 'special_weapon']
+        });
+        
+        // Create a completely custom enemy
+        const customEnemy = new EnemyActor({
+            position: new THREE.Vector3(0, 0, 10),
+            health: 75,
+            attackDamage: 15,
+            movementSpeed: 6.0,
+            detectionRadius: 15.0,
+            dropItems: ['rare_coin']
+        });
+        
+        this.world.addActors(grunt, customElite, customEnemy);
+    }
+}
+```
+
+### Options Inheritance
+
+When extending actor classes, always inherit the `DEFAULT_OPTIONS` from the parent class using the spread operator:
+
+```typescript
+@ENGINE.GameClass()
+class ExtendedActor extends CustomActor {
+    static override get DEFAULT_OPTIONS() {
+        return {
+            ...CustomActor.DEFAULT_OPTIONS, // Inherit from parent
+            armor: 25,
+            magicPower: 50
+        };
+    }
+}
+```
+
+This ensures all parent options are preserved and available in child classes. The factory pattern (using static getters) ensures that default options are computed fresh each time they're accessed, which is important for object properties that shouldn't be shared between instances.
+
+### Key Benefits of Custom Options
+
+1. **Type Safety**: TypeScript ensures you can't pass invalid options or access undefined properties.
+2. **Default Values**: Sensible defaults make your actors easy to use while still being configurable.
+3. **Inheritance**: Options extend naturally when you create subclasses of your custom actors.
+4. **Serialization**: The engine's serialization system automatically handles your custom options.
+5. **Presets**: You can define common configurations that users can easily apply and modify.
+6. **Proper Inheritance**: Using the spread operator ensures all parent options are preserved.
+7. **Factory Pattern**: Using static getters prevents object reference sharing and ensures fresh default objects are created for each instance.
+
+This pattern makes your custom actors both powerful and easy to use, following the same conventions as the built-in Genesys.js classes.
+
+---
+
+## 5. Extending Components with Custom Options
+
+Just like Actors, Components and SceneComponents can be extended with custom options to create reusable, configurable functionality. The pattern is identical to what we use for Actors.
+
+### Extending Component with Custom Options
+
+For non-spatial components that manage data or abstract behaviors:
+
+```typescript
+import * as ENGINE from "genesys.js";
+
+// Define custom options interface
+interface HealthComponentOptions extends ENGINE.ComponentOptions {
+    maxHealth?: number;
+    currentHealth?: number;
+    regenerationRate?: number;
+    canRegenerate?: boolean;
+}
+
+@ENGINE.GameClass()
+class HealthComponent extends ENGINE.Component<HealthComponentOptions> {
+    static override get DEFAULT_OPTIONS(): HealthComponentOptions {
+        return {
+            ...ENGINE.Component.DEFAULT_OPTIONS,
+            maxHealth: 100,
+            currentHealth: 100,
+            regenerationRate: 5.0, // HP per second
+            canRegenerate: true
+        };
+    }
+
+    public maxHealth: number;
+    public currentHealth: number;
+    public regenerationRate: number;
+    public canRegenerate: boolean;
+
+    constructor(options: HealthComponentOptions = {} as HealthComponentOptions) {
+        super(options);
+        
+        const config = { ...this.getDefaultOptions(), ...options };
+        
+        this.maxHealth = config.maxHealth!;
+        this.currentHealth = config.currentHealth!;
+        this.regenerationRate = config.regenerationRate!;
+        this.canRegenerate = config.canRegenerate!;
+    }
+
+    public override tickPrePhysics(deltaTime: number): void {
+        super.tickPrePhysics(deltaTime);
+        
+        // Regenerate health if enabled and not at max
+        if (this.canRegenerate && this.currentHealth < this.maxHealth) {
+            this.currentHealth = Math.min(
+                this.maxHealth, 
+                this.currentHealth + this.regenerationRate * deltaTime
+            );
+        }
+    }
+
+    public takeDamage(damage: number): void {
+        this.currentHealth = Math.max(0, this.currentHealth - damage);
+    }
+
+    public heal(amount: number): void {
+        this.currentHealth = Math.min(this.maxHealth, this.currentHealth + amount);
+    }
+
+    public isDead(): boolean {
+        return this.currentHealth <= 0;
+    }
+}
+```
+
+### Extending SceneComponent with Custom Options
+
+For spatial components that need position, rotation, and physics:
+
+```typescript
+interface CustomMeshComponentOptions extends ENGINE.SceneComponentOptions {
+    geometry?: THREE.BufferGeometry;
+    material?: THREE.Material;
+    color?: THREE.ColorRepresentation;
+    wireframe?: boolean;
+    castShadow?: boolean;
+    receiveShadow?: boolean;
+}
+
+@ENGINE.GameClass()
+class CustomMeshComponent extends ENGINE.SceneComponent<CustomMeshComponentOptions> {
+    static override get DEFAULT_OPTIONS(): CustomMeshComponentOptions {
+        return {
+            ...ENGINE.SceneComponent.DEFAULT_OPTIONS,
+            color: 0xffffff,
+            wireframe: false,
+            castShadow: true,
+            receiveShadow: true
+        };
+    }
+
+    public readonly mesh: THREE.Mesh;
+
+    constructor(options: CustomMeshComponentOptions = {} as CustomMeshComponentOptions) {
+        super(options);
+        
+        const config = { ...this.getDefaultOptions(), ...options };
+        
+        // Create geometry (default to box if none provided)
+        const geometry = config.geometry || new THREE.BoxGeometry(1, 1, 1);
+        
+        // Create material with options
+        let material = config.material;
+        if (!material) {
+            material = new THREE.MeshStandardMaterial({
+                color: config.color,
+                wireframe: config.wireframe
+            });
+        }
+        
+        // Create and configure mesh
+        this.mesh = new THREE.Mesh(geometry, material);
+        this.mesh.castShadow = config.castShadow!;
+        this.mesh.receiveShadow = config.receiveShadow!;
+        
+        // Add mesh to this component
+        this.add(this.mesh);
+    }
+
+    public setColor(color: THREE.ColorRepresentation): void {
+        if (this.mesh.material instanceof THREE.MeshStandardMaterial) {
+            this.mesh.material.color.set(color);
+        }
+    }
+
+    public setWireframe(wireframe: boolean): void {
+        if (this.mesh.material instanceof THREE.MeshStandardMaterial) {
+            this.mesh.material.wireframe = wireframe;
+        }
+    }
+}
+```
+
+### Practical Example: Configurable Weapon Component
+
+Here's a complete example showing a weapon component with complex configuration:
+
+```typescript
+interface WeaponComponentOptions extends ENGINE.ComponentOptions {
+    weaponType?: 'sword' | 'bow' | 'staff';
+    damage?: number;
+    range?: number;
+    fireRate?: number;
+    ammoCapacity?: number;
+    reloadTime?: number;
+    projectileSpeed?: number;
+    effects?: {
+        muzzleFlash?: boolean;
+        sound?: string;
+        particles?: boolean;
+    };
+}
+
+@ENGINE.GameClass()
+class WeaponComponent extends ENGINE.Component<WeaponComponentOptions> {
+    static override get DEFAULT_OPTIONS(): WeaponComponentOptions {
+        return {
+            ...ENGINE.Component.DEFAULT_OPTIONS,
+            weaponType: 'sword',
+            damage: 25,
+            range: 10,
+            fireRate: 1.0,
+            ammoCapacity: 30,
+            reloadTime: 2.0,
+            projectileSpeed: 50,
+            effects: {
+                muzzleFlash: true,
+                sound: 'weapon_fire',
+                particles: true
+            }
+        };
+    }
+
+    // Weapon presets for different types
+    static readonly WEAPON_PRESETS: Record<string, Partial<WeaponComponentOptions>> = {
+        sword: {
+            damage: 50,
+            range: 2,
+            fireRate: 2.0,
+            ammoCapacity: 0, // Melee weapons don't use ammo
+            effects: { sound: 'sword_swing' }
+        },
+        bow: {
+            damage: 35,
+            range: 50,
+            fireRate: 1.5,
+            ammoCapacity: 20,
+            projectileSpeed: 75,
+            effects: { sound: 'bow_release' }
+        },
+        staff: {
+            damage: 40,
+            range: 30,
+            fireRate: 0.8,
+            ammoCapacity: 10,
+            reloadTime: 3.0,
+            projectileSpeed: 25,
+            effects: { muzzleFlash: true, particles: true, sound: 'magic_cast' }
+        }
+    };
+
+    public readonly config: Required<WeaponComponentOptions>;
+    private currentAmmo: number;
+    private lastFireTime: number = 0;
+    private isReloading: boolean = false;
+
+    constructor(options: WeaponComponentOptions = {} as WeaponComponentOptions) {
+        // Apply weapon preset if specified
+        const presetOptions = options.weaponType ? 
+            WeaponComponent.WEAPON_PRESETS[options.weaponType] : {};
+        
+        const mergedOptions = {
+            ...WeaponComponent.DEFAULT_OPTIONS,
+            ...presetOptions,
+            ...options,
+            // Deep merge effects
+            effects: {
+                ...WeaponComponent.DEFAULT_OPTIONS.effects,
+                ...presetOptions.effects,
+                ...options.effects
+            }
+        };
+
+        super(mergedOptions);
+        
+        this.config = mergedOptions as Required<WeaponComponentOptions>;
+        this.currentAmmo = this.config.ammoCapacity;
+    }
+
+    public canFire(): boolean {
+        const now = Date.now() / 1000;
+        const timeSinceLastFire = now - this.lastFireTime;
+        const fireInterval = 1.0 / this.config.fireRate;
+        
+        return !this.isReloading && 
+               timeSinceLastFire >= fireInterval && 
+               (this.config.ammoCapacity === 0 || this.currentAmmo > 0);
+    }
+
+    public fire(): boolean {
+        if (!this.canFire()) {
+            return false;
+        }
+
+        this.lastFireTime = Date.now() / 1000;
+        
+        // Consume ammo for ranged weapons
+        if (this.config.ammoCapacity > 0) {
+            this.currentAmmo--;
+        }
+
+        // Play effects
+        if (this.config.effects.sound) {
+            console.log(`Playing sound: ${this.config.effects.sound}`);
+        }
+        
+        if (this.config.effects.muzzleFlash) {
+            console.log('Showing muzzle flash');
+        }
+
+        console.log(`Fired ${this.config.weaponType} for ${this.config.damage} damage`);
+        return true;
+    }
+
+    public reload(): void {
+        if (this.config.ammoCapacity === 0 || this.isReloading) {
+            return;
+        }
+
+        this.isReloading = true;
+        console.log(`Reloading ${this.config.weaponType}...`);
+        
+        // Use timer system to handle reload delay
+        const world = this.getWorld();
+        if (world) {
+            world.timerSystem.setTimeout(() => {
+                this.currentAmmo = this.config.ammoCapacity;
+                this.isReloading = false;
+                console.log('Reload complete');
+            }, this.config.reloadTime * 1000);
+        }
+    }
+
+    public getAmmoCount(): number {
+        return this.currentAmmo;
+    }
+
+    public getMaxAmmo(): number {
+        return this.config.ammoCapacity;
+    }
+}
+
+// Usage example:
+class WeaponizedActor extends ENGINE.Actor {
+    private weaponComponent: WeaponComponent;
+
+    constructor(options: ENGINE.ActorOptions = {}) {
+        super(options);
+        
+        // Create a bow with custom settings
+        this.weaponComponent = new WeaponComponent({
+            weaponType: 'bow',
+            damage: 45, // Override preset damage
+            fireRate: 2.0, // Faster than default bow
+            effects: {
+                muzzleFlash: false, // Bows don't have muzzle flash
+                sound: 'custom_bow_sound',
+                particles: true
+            }
+        });
+        
+        this.addComponents(this.weaponComponent);
+    }
+    
+    public override tickPrePhysics(deltaTime: number): void {
+        super.tickPrePhysics(deltaTime);
+        
+        // Example: Auto-fire logic
+        if (this.weaponComponent.canFire()) {
+            this.weaponComponent.fire();
+        }
+    }
+}
+```
+
+### Component Options Inheritance
+
+Just like with Actors, component inheritance follows the same pattern:
+
+```typescript
+// Extend the weapon component
+interface MagicWeaponOptions extends WeaponComponentOptions {
+    manaCost?: number;
+    spellType?: string;
+    elementalDamage?: number;
+}
+
+@ENGINE.GameClass()
+class MagicWeaponComponent extends WeaponComponent {
+    static override get DEFAULT_OPTIONS(): MagicWeaponOptions {
+        return {
+            ...WeaponComponent.DEFAULT_OPTIONS, // Inherit parent options
+            manaCost: 10,
+            spellType: 'fireball',
+            elementalDamage: 15
+        };
+    }
+    
+    // Additional magic weapon functionality...
+}
+```
+
+This component extension pattern allows you to create highly configurable, reusable components that can be easily customized for different use cases while maintaining type safety and proper inheritance.
+
+## 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/game/GameLoop.ts}>
+<file path={src/game/GameBuilder.ts}>
+<file path={src/actors/Actor.ts}>
+```