@directivegames/genesys.js 3.1.24

package/src/components/lights/HemisphereLightComponent.ts

@@ -0,0 +1,132 @@
+/**
+ * HemisphereLightComponent models ambient lighting from sky and ground.
+ *
+ * It encapsulates a THREE.HemisphereLight and provides methods to adjust the
+ * sky and ground colors individually. A helper can be toggled on to visualize
+ * the light's influence and orientation. As with other lights derived from
+ * LightComponent, properties can be modified in the editor at runtime.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Use this light to simulate outdoor scenes where a simple ambient light is
+ *   insufficient.
+ * - Call `setSkyColor` and `setGroundColor` to fine tune the color balance.
+ */
+import * as THREE from 'three';
+
+import { EngineClass } from '../../systems/ClassRegistry.js';
+
+
+import { LightComponent } from './LightComponent.js';
+
+import type { LightComponentOptions } from './LightComponent.js';
+import type { EditorClassMeta } from '../../utils/EditorClassMeta.js';
+import type { EditorPropertyChangedResult } from '../../utils/EditorClassMeta.js';
+
+
+export interface HemisphereLightComponentOptions extends LightComponentOptions {
+  /** Color of the light from the sky */
+  skyColor?: THREE.ColorRepresentation;
+  /** Color of the light from the ground */
+  groundColor?: THREE.ColorRepresentation;
+}
+
+/**
+ * Component that wraps a THREE.HemisphereLight
+ * Provides functionality for a light that simulates an atmospheric light from the sky
+ */
+@EngineClass('HemisphereLightComponent')
+export class HemisphereLightComponent extends LightComponent<THREE.HemisphereLight, HemisphereLightComponentOptions> {
+  static override readonly EDITOR_CLASS_META: EditorClassMeta = {
+    ...LightComponent.EDITOR_CLASS_META,
+    skyColor: { type: THREE.Color },
+    groundColor: { type: THREE.Color },
+  } as const;
+
+  static override get DEFAULT_OPTIONS(): HemisphereLightComponentOptions {
+    return {
+      ...LightComponent.DEFAULT_OPTIONS,
+      skyColor: 0xffffff,
+      groundColor: 0x444444
+    };
+  }
+
+  /**
+     * Creates a new hemisphere light component with the specified options
+     * @param options Configuration options for the hemisphere light
+     */
+  constructor(options: HemisphereLightComponentOptions = {}) {
+    const skyColor = options.skyColor ?? HemisphereLightComponent.DEFAULT_OPTIONS.skyColor!;
+    const groundColor = options.groundColor ?? HemisphereLightComponent.DEFAULT_OPTIONS.groundColor!;
+
+    const hemisphereLight = new THREE.HemisphereLight(
+      skyColor,
+      groundColor,
+      options.intensity ?? HemisphereLightComponent.DEFAULT_OPTIONS.intensity!
+    );
+
+    super(hemisphereLight, options);
+  }
+
+  /**
+     * Sets the sky color of the hemisphere light
+     * @param color The new sky color
+     * @returns This component for method chaining
+     */
+  public setSkyColor(color: THREE.ColorRepresentation): this {
+    this.light.color.set(color);
+    return this;
+  }
+
+  /**
+     * Gets the current sky color of the hemisphere light
+     * @returns The THREE.Color for the sky
+     */
+  public getSkyColor(): THREE.Color {
+    return this.light.color;
+  }
+
+  /**
+     * Sets the ground color of the hemisphere light
+     * @param color The new ground color
+     * @returns This component for method chaining
+     */
+  public setGroundColor(color: THREE.ColorRepresentation): this {
+    this.light.groundColor.set(color);
+    return this;
+  }
+
+  /**
+     * Gets the current ground color of the hemisphere light
+     * @returns The THREE.Color for the ground
+     */
+  public getGroundColor(): THREE.Color {
+    return this.light.groundColor;
+  }
+
+  /**
+     * Configures shadow properties - no-op for hemisphere lights
+     * @returns This component for method chaining
+     */
+  public override configureShadow(): this {
+    // Hemisphere lights don't cast shadows, so this is a no-op
+    return this;
+  }
+
+  protected override createLightHelper(): THREE.Object3D | null {
+    return new THREE.HemisphereLightHelper(this.light, 1 /** Size */);
+  }
+
+  //====================================================================================================
+  // Editor Functions
+  //====================================================================================================
+
+  public override onEditorPropertyChanged(path: string, value: any, result: EditorPropertyChangedResult): void {
+    super.onEditorPropertyChanged(path, value, result);
+    if (path === 'skyColor') this.setSkyColor(value);
+    else if (path === 'groundColor') this.setGroundColor(value);
+  }
+
+  public override getEditorClassIcon(): string | null {
+    return 'Icon_Hemisphere';
+  }
+}

package/src/components/lights/LightComponent.ts

@@ -0,0 +1,351 @@
+/**
+ * LightComponent is the abstract base for all Genesys light wrappers.
+ *
+ * It encapsulates a THREE.Light object and exposes common properties such as
+ * color, intensity and shadow configuration. The component handles adding the
+ * underlying light to the scene graph and updating optional helpers on each
+ * tick. Editor metadata is provided so properties can be modified at runtime in
+ * the Genesys editor.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Extend this class when implementing new light types to ensure consistent
+ *   behavior.
+ * - Use `configureShadow` and helper methods in derived components to manage
+ *   visual debugging aids.
+ */
+import * as THREE from 'three';
+
+import { SceneComponent } from '../SceneComponent.js';
+
+import type { Actor } from '../../actors/Actor.js';
+import type { EditorClassMeta, EditorPropertyChangedResult } from '../../utils/EditorClassMeta.js';
+import type { SceneComponentOptions } from '../SceneComponent.js';
+
+
+export interface LightComponentOptions extends SceneComponentOptions {
+  /** Color of the light */
+  color?: THREE.ColorRepresentation;
+  /** Intensity of the light */
+  intensity?: number;
+  /** Whether the light casts shadows */
+  castShadow?: boolean;
+  /** Shadow map size */
+  shadowMapSize?: number;
+  /** Shadow bias */
+  shadowBias?: number;
+  /** Shadow normal bias - helps reduce shadow acne */
+  shadowNormalBias?: number;
+  /** Shadow near plane */
+  shadowNear?: number;
+  /** Shadow far plane */
+  shadowFar?: number;
+  /** Whether this light should be baked into lightmaps (default: true). If true, light is static (baked only). If false, light is dynamic (runtime only). */
+  bakeLightmaps?: boolean;
+}
+
+/**
+ * Base class for all light components in the engine
+ * Inherits from SceneComponent and wraps a THREE.Light
+ */
+export abstract class LightComponent<TLight extends THREE.Light, TLightOptions extends LightComponentOptions> extends SceneComponent<TLightOptions> {
+
+  static override readonly EDITOR_CLASS_META: EditorClassMeta = {
+    ...SceneComponent.EDITOR_CLASS_META,
+    color: { type: THREE.Color },
+  } as const;
+
+  static override get DEFAULT_OPTIONS(): LightComponentOptions {
+    return {
+      ...SceneComponent.DEFAULT_OPTIONS,
+      color: new THREE.Color(1, 1, 1),
+      intensity: 1,
+      castShadow: false,
+      shadowMapSize: 2048,        // Higher resolution for better quality
+      shadowBias: 0,              // Conservative negative bias (will be auto-adjusted)
+      shadowNormalBias: 0,        // Conservative normal bias (will be auto-adjusted)
+      shadowNear: 0.1,            // Closer near plane
+      shadowFar: 100,             // Farther far plane for larger scenes
+      bakeLightmaps: true,
+    };
+  }
+
+  /** The THREE.Light object managed by this component */
+  protected light: TLight;
+  protected lightHelper: THREE.Object3D | null = null;
+  protected cameraHelper: THREE.CameraHelper | null = null;
+
+  /**
+     * Creates a new light component with the specified options
+     * @param lightInstance The THREE.Light instance to use
+     * @param options Configuration options for the light component
+     */
+  constructor(lightInstance: TLight, options: TLightOptions = {} as TLightOptions) {
+    super(options);
+    this.light = lightInstance;
+    this.light.setTransient(true);
+
+    // clear the relative transform of the light so that the light component can be considered the same entity as the light itself
+    this.light.position.set(0, 0, 0);
+    this.light.rotation.set(0, 0, 0);
+    this.light.scale.set(1, 1, 1);
+
+    this.bindObject3DProperties(this.light, ['castShadow', 'receiveShadow']);
+
+    // Apply options to the light
+    if (options.color !== undefined) {
+      this.setColor(options.color);
+    }
+
+    if (options.intensity !== undefined) {
+      this.setIntensity(options.intensity);
+    }
+
+    if (options.castShadow !== undefined) {
+      this.castShadow = options.castShadow;
+    }
+
+    const defaultOptions = LightComponent.DEFAULT_OPTIONS;
+    this.configureShadow({
+      mapSize: options.shadowMapSize ?? defaultOptions.shadowMapSize,
+      bias: options.shadowBias ?? defaultOptions.shadowBias,
+      normalBias: options.shadowNormalBias ?? defaultOptions.shadowNormalBias,
+      near: options.shadowNear ?? defaultOptions.shadowNear,
+      far: options.shadowFar ?? defaultOptions.shadowFar
+    });
+
+    this.add(this.light);
+  }
+
+  /**
+     * Returns the THREE.Light object associated with this component
+     * @returns The THREE.Light instance
+     */
+  public getLight(): TLight {
+    return this.light;
+  }
+
+  /**
+     * Sets the color of the light
+     * @param color The new color for the light
+     * @returns This component for method chaining
+     */
+  public setColor(color: THREE.ColorRepresentation): this {
+    this.light.color.set(color);
+    return this;
+  }
+
+  /**
+     * Gets the current color of the light
+     * @returns The THREE.Color of the light
+     */
+  public getColor(): THREE.Color {
+    return this.light.color;
+  }
+
+  /**
+     * Sets the intensity of the light
+     * @param intensity The new intensity value
+     * @returns This component for method chaining
+     */
+  public setIntensity(intensity: number): this {
+    this.light.intensity = intensity;
+    return this;
+  }
+
+  /**
+     * Gets the current intensity of the light
+     * @returns The intensity value
+     */
+  public getIntensity(): number {
+    return this.light.intensity;
+  }
+
+  /**
+   * Sets whether this light should be baked into lightmaps
+   * @param baked Whether the light should be baked into lightmaps (true = baked, false = runtime only)
+   * @returns This component for method chaining
+   */
+  public setLightmapBaked(baked: boolean): this {
+    this.options.bakeLightmaps = baked;
+    return this;
+  }
+
+  /**
+   * Gets whether this light is baked into lightmaps
+   * @returns Whether the light is baked into lightmaps
+   */
+  public isLightmapBaked(): boolean {
+    return this.options.bakeLightmaps ?? LightComponent.DEFAULT_OPTIONS.bakeLightmaps!;
+  }
+
+  /**
+     * Configures shadow properties for the light
+     * @param options Shadow configuration options
+     * @returns This component for method chaining
+     */
+  public configureShadow(options: { mapSize?: number; bias?: number; normalBias?: number; near?: number; far?: number } = {}): this {
+    if (!this.light.shadow) return this;
+
+    const { mapSize, bias, normalBias, near, far } = options;
+
+    if (mapSize !== undefined) {
+      this.light.shadow.mapSize.width = mapSize;
+      this.light.shadow.mapSize.height = mapSize;
+    }
+
+    if (bias !== undefined) {
+      this.light.shadow.bias = bias;
+    }
+
+    if (normalBias !== undefined) {
+      this.light.shadow.normalBias = normalBias;
+    }
+
+    const camera = this.light.shadow.camera;
+
+    if (camera instanceof THREE.PerspectiveCamera || camera instanceof THREE.OrthographicCamera) {
+      if (near !== undefined) camera.near = near;
+      if (far !== undefined) camera.far = far;
+      camera.updateProjectionMatrix();
+    }
+
+    // Recreate camera helper if it's visible to reflect changes
+    // this.recreateCameraHelper();
+
+    return this;
+  }
+
+  /**
+     * Shows or hides a visual helper for the light
+     * This is a virtual method that derived classes should override
+     * @param show Whether to show the helper
+     * @returns This component for method chaining
+     */
+  public showHelper(show: boolean): this {
+    if (show === !!this.lightHelper) return this;
+    if (show) {
+      this.lightHelper = this.createLightHelper();
+    } else {
+      this.lightHelper?.removeFromParent();
+      this.lightHelper = null;
+    }
+    return this;
+  }
+
+  protected abstract createLightHelper(): THREE.Object3D | null;
+
+  /**
+     * Shows or hides a visual helper for the light's shadow camera
+     * @param show Whether to show the camera helper
+     * @returns This component for method chaining
+     */
+  public showCameraHelper(show: boolean): this {
+    if (show === !!this.cameraHelper) return this;
+    if (show && this.light.shadow) {
+      this.cameraHelper = new THREE.CameraHelper(this.light.shadow.camera);
+    } else {
+      this.cameraHelper?.removeFromParent();
+      this.cameraHelper = null;
+    }
+    return this;
+  }
+
+  /**
+     * Checks if the helper is currently visible
+     * This is a virtual method that derived classes should override
+     * @returns Whether the helper is currently shown
+     */
+  public isHelperVisible(): boolean {
+    return !!this.lightHelper;
+  }
+
+  /**
+     * Checks if the camera helper is currently visible
+     * @returns Whether the camera helper is currently shown
+     */
+  public isCameraHelperVisible(): boolean {
+    return !!this.cameraHelper;
+  }
+
+  /**
+     * Called after physics simulation each tick
+     * Updates light helpers if they exist
+     * @param deltaTime Time in seconds since the last tick
+     */
+  public override tickPrePhysics(deltaTime: number): void {
+    super.tickPrePhysics(deltaTime);
+    this.updateHelpers();
+  }
+
+  protected updateHelpers(): void {
+    // Update helper transform if helper is visible
+    if (this.lightHelper) {
+      this.lightHelper.visible = this.visible;
+      if (this.lightHelper.parent === null) {
+        // add the helper to the scene directly so it's not affected by the light component's transform
+        this.getWorld()?.scene.add(this.lightHelper);
+      }
+      this.lightHelper.updateMatrixWorld();
+      if (typeof (this.lightHelper as any).update === 'function') {
+        (this.lightHelper as any).update();
+      } else {
+        console.error('Light helper does not have an update method', this.lightHelper);
+      }
+    }
+
+    // Update camera helper if it exists
+    if (this.cameraHelper) {
+      this.cameraHelper.visible = this.visible && this.castShadow;
+      if (this.cameraHelper.parent === null) {
+        // add the helper to the scene directly so it's not affected by the light component's transform
+        this.getWorld()?.scene.add(this.cameraHelper);
+      }
+      this.cameraHelper.update();
+    }
+  }
+
+
+  protected recreateLightHelper(): void {
+    if (this.lightHelper) {
+      this.showHelper(false);
+      this.showHelper(true);
+    }
+  }
+
+  protected recreateCameraHelper(): void {
+    if (this.cameraHelper) {
+      this.showCameraHelper(false);
+      this.showCameraHelper(true);
+    }
+  }
+
+  //====================================================================================================
+  // Editor Functions
+  //====================================================================================================
+
+  public override onEditorSelectedChanged(isSelected: boolean, selectedActors: Actor[]): void {
+    super.onEditorSelectedChanged(isSelected, selectedActors);
+    this.showHelper(isSelected);
+    this.showCameraHelper(isSelected);
+    this.updateHelpers();
+  }
+
+  public override onEditorPropertyChanged(path: string, value: any, result: EditorPropertyChangedResult): void {
+    super.onEditorPropertyChanged(path, value, result);
+
+    if (path === 'color') this.setColor(value);
+    else if (path === 'intensity') this.setIntensity(value);
+    else if (path === 'bakeLightmaps') this.setLightmapBaked(value);
+    else if (path === 'shadowMapSize') this.configureShadow({ mapSize: value });
+    else if (path === 'shadowBias') this.configureShadow({ bias: value });
+    else if (path === 'shadowNormalBias') this.configureShadow({ normalBias: value });
+    else if (path === 'shadowNear') this.configureShadow({ near: value });
+    else if (path === 'shadowFar') this.configureShadow({ far: value });
+
+    this.updateHelpers();
+  }
+
+  public override getEditorClassIcon(): string | null {
+    return 'Icon_Light';
+  }
+}

package/src/components/lights/PointLightComponent.ts

@@ -0,0 +1,115 @@
+/**
+ * PointLightComponent emits light uniformly in all directions from a single
+ * point.
+ *
+ * This wrapper around THREE.PointLight exposes distance and decay properties
+ * and can display a helper for debugging placement. Because it inherits from
+ * LightComponent it also supports common color, intensity and shadow settings.
+ * Editor hooks allow real-time adjustment of these parameters when modifying
+ * scenes.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Use for localized light sources like torches or lamps.
+ * - Adjust `distance` and `decay` to control falloff and performance impact.
+ */
+import * as THREE from 'three';
+
+import { EngineClass } from '../../systems/ClassRegistry.js';
+
+
+import { LightComponent } from './LightComponent.js';
+
+import type { LightComponentOptions } from './LightComponent.js';
+import type { EditorPropertyChangedResult } from '../../utils/EditorClassMeta.js';
+
+
+export interface PointLightComponentOptions extends LightComponentOptions {
+  /** Distance at which the light's intensity falls to 0 */
+  distance?: number;
+  /** How quickly the light's intensity diminishes with distance */
+  decay?: number;
+}
+
+/**
+ * Component that wraps a THREE.PointLight
+ * Provides functionality for a light that emits from a single point in all directions
+ */
+@EngineClass('PointLightComponent')
+export class PointLightComponent extends LightComponent<THREE.PointLight, PointLightComponentOptions> {
+  static override get DEFAULT_OPTIONS(): PointLightComponentOptions {
+    return {
+      ...LightComponent.DEFAULT_OPTIONS,
+      distance: 0,
+      decay: 2
+    };
+  }
+
+  /**
+     * Creates a new point light component with the specified options
+     * @param options Configuration options for the point light
+     */
+  constructor(options: PointLightComponentOptions = {}) {
+    const pointLight = new THREE.PointLight(
+      options.color ?? PointLightComponent.DEFAULT_OPTIONS.color!,
+      options.intensity ?? PointLightComponent.DEFAULT_OPTIONS.intensity!,
+      options.distance ?? PointLightComponent.DEFAULT_OPTIONS.distance!,
+      options.decay ?? PointLightComponent.DEFAULT_OPTIONS.decay!
+    );
+    super(pointLight, options);
+  }
+
+  /**
+     * Sets the distance at which the light's intensity falls to 0
+     * @param distance Maximum distance the light reaches
+     * @returns This component for method chaining
+     */
+  public setDistance(distance: number): this {
+    this.light.distance = distance;
+    this.recreateLightHelper();
+    return this;
+  }
+
+  /**
+     * Gets the current maximum distance of the light
+     * @returns The distance value
+     */
+  public getDistance(): number {
+    return this.light.distance;
+  }
+
+  /**
+     * Sets how quickly the light's intensity diminishes with distance
+     * @param decay The decay factor
+     * @returns This component for method chaining
+     */
+  public setDecay(decay: number): this {
+    this.light.decay = decay;
+    return this;
+  }
+
+  /**
+     * Gets the current decay factor of the light
+     * @returns The decay value
+     */
+  public getDecay(): number {
+    return this.light.decay;
+  }
+
+  protected override createLightHelper(): THREE.Object3D | null {
+    return new THREE.PointLightHelper(this.light, this.light.distance);
+  }
+
+  //====================================================================================================
+  // Editor Functions
+  //====================================================================================================
+
+  public override onEditorPropertyChanged(path: string, value: any, result: EditorPropertyChangedResult): void {
+    super.onEditorPropertyChanged(path, value, result);
+    if (path === 'distance') this.setDistance(value);
+    else if (path === 'decay') this.setDecay(value);
+  }
+
+  public override getEditorClassIcon(): string | null {
+    return 'Icon_PointLight';
+  }
+}