@directivegames/genesys.js 3.1.24

package/src/render/Renderer.ts

@@ -0,0 +1,310 @@
+/**
+ * Renderer encapsulates the THREE.WebGLRenderer used to display the scene.
+ *
+ * It sets up a WebGL renderer with shadow mapping enabled and automatically
+ * adjusts the canvas size when the window is resized. The class acts as a thin
+ * wrapper that forwards render calls to the active `World` instance while
+ * managing DOM integration for the canvas element.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Instantiate once with the HTML container element and optional renderer
+ *   parameters.
+ * - Call `render(world)` each frame from your game loop to draw the scene.
+ * - Use `getWindowSize` for cameras or UI that need the current output
+ *   resolution.
+ * - Invoke `destroy` when tearing down the engine to remove event listeners and
+ *   DOM nodes.
+ */
+
+import * as THREE from 'three';
+import { InstancedMesh } from 'three';
+
+import { MaterialUtils } from '../materials.js';
+import { CVarManager } from '../systems/ConsoleVariableManager.js';
+import { Stats } from '../systems/Stats.js';
+
+import type { World } from '../game/World';
+
+const cvarAutoInstancing = CVarManager.registerVariable({
+  name: 'r.AutoInstancing',
+  default: 0,
+  description: 'Enable auto instancing on the GenesysWebGLRenderer',
+});
+
+const cvarScreenPercentage = CVarManager.registerVariable({
+  name: 'r.ScreenPercentage',
+  default: 100,
+  description: 'Screen percentage for the GenesysWebGLRenderer',
+});
+
+type MeshInstances = Map<string, {
+  geometry: THREE.BufferGeometry,
+  material: THREE.Material,
+  objects: THREE.Mesh[]
+}>;
+
+export class GenesysWebGLRenderer extends THREE.WebGLRenderer {
+  instanceMeshes: Map<string, { mesh: THREE.InstancedMesh, capacity: number }> = new Map();
+  tempMatrix: THREE.Matrix4 = new THREE.Matrix4();
+  tempColor: THREE.Color = new THREE.Color();
+  minInstancingThreshold = 100;
+
+  constructor(options?: THREE.WebGLRendererParameters) {
+    super(options);
+
+    const originalRender = this.render.bind(this);
+    this.render = (scene: THREE.Scene, camera: THREE.Camera) => {
+      if (cvarAutoInstancing.get()) {
+        const instances = this.autoInstance(scene);
+        originalRender(scene, camera);
+        // restore the visibility flag
+        for (const { objects } of instances.values()) {
+          for (const obj of objects) {
+            obj.visible = true;
+          }
+        }
+      } else {
+        originalRender(scene, camera);
+      }
+    };
+
+    const originalRenderBufferDirect = this.renderBufferDirect.bind(this);
+    this.renderBufferDirect = (camera: THREE.Camera, scene: THREE.Scene, geometry: THREE.BufferGeometry, material: THREE.Material, object: THREE.Object3D, geometryGroup: any) => {
+      MaterialUtils.fixMaterialColorSpace(material);
+      originalRenderBufferDirect(camera, scene, geometry, material, object, geometryGroup);
+      Stats.addRenderBufferDirect(camera, scene, geometry, material, object, geometryGroup);
+    };
+  }
+
+  public beginRenderFrame() {
+    for (const { mesh } of this.instanceMeshes.values()) {
+      mesh.visible = false;
+    }
+  }
+
+  public endRenderFrame() {
+    // remove instance meshes that are no longer needed
+    for (const [key, { mesh }] of this.instanceMeshes.entries()) {
+      if (!mesh.visible) {
+        mesh.dispose();
+        mesh.removeFromParent();
+        this.instanceMeshes.delete(key);
+      }
+    }
+  }
+
+  private autoInstance(scene: THREE.Scene): MeshInstances {
+    const instances: MeshInstances = new Map();
+
+    // gather batchable instances
+    scene.traverseVisible((obj: THREE.Object3D) => {
+      if (!(obj instanceof THREE.Mesh)) return;
+      if (obj instanceof THREE.SkinnedMesh) return;
+      if (obj.userData.isAutoInstance) return;
+
+      const key = `${obj.geometry.uuid}_${obj.material.uuid}_${obj.castShadow}_${obj.receiveShadow}`;
+
+      if (!instances.has(key)) {
+        instances.set(key, {
+          geometry: obj.geometry,
+          material: obj.material,
+          objects: []
+        });
+      }
+      instances.get(key)!.objects.push(obj);
+    });
+
+    // Create or update InstancedMesh for each group
+    for (const [key, data] of instances) {
+      let numInstances = 0;
+      for (const obj of data.objects) {
+        if (obj instanceof THREE.InstancedMesh) {
+          numInstances += obj.count;
+        } else {
+          numInstances += 1;
+        }
+      }
+      if (numInstances < this.minInstancingThreshold) continue;
+      let { mesh, capacity } = this.instanceMeshes.get(key) ?? { mesh: undefined, capacity: 0 };
+
+      // Create new InstancedMesh if needed
+      if (!mesh || capacity < numInstances) {
+        if (mesh) {
+          mesh.dispose();
+          mesh.removeFromParent();
+        }
+        mesh = new InstancedMesh(
+          data.geometry,
+          data.material,
+          numInstances
+        );
+        mesh.userData.isAutoInstance = true;
+
+        // Per-instance culling not supported
+        mesh.frustumCulled = false;
+
+        // Copy shadow properties from the first object (assuming all objects in the batch have the same shadow settings)
+        const firstObj = data.objects[0];
+        mesh.castShadow = firstObj.castShadow;
+        mesh.receiveShadow = firstObj.receiveShadow;
+
+        this.instanceMeshes.set(key, { mesh, capacity: numInstances });
+        scene.add(mesh);
+      }
+
+      // Update instance count if needed
+      if (mesh.count !== numInstances) {
+        mesh.count = numInstances;
+      }
+
+      // Update instance transforms
+      let instanceIndex = 0;
+      for (const obj of data.objects) {
+        if (obj instanceof THREE.InstancedMesh) {
+          for (let index = 0; index < obj.count; ++index) {
+            obj.getMatrixAt(index, this.tempMatrix);
+            mesh.setMatrixAt(instanceIndex, this.tempMatrix.premultiply(obj.matrixWorld));
+            if (obj.instanceColor) {
+              obj.getColorAt(index, this.tempColor);
+              mesh.setColorAt(instanceIndex, this.tempColor);
+            }
+            instanceIndex += 1;
+          }
+
+        } else {
+          // Set instance matrix
+          mesh.setMatrixAt(instanceIndex, obj.matrixWorld);
+
+          // Optional: set per-instance color
+          if (obj.material instanceof THREE.MeshBasicMaterial && mesh.instanceColor) {
+            mesh.setColorAt(instanceIndex, obj.material.color);
+          }
+          instanceIndex += 1;
+        }
+
+        // Hide original object
+        obj.visible = false;
+      }
+
+      // Mark matrices as needing update
+      mesh.instanceMatrix.needsUpdate = true;
+      if (mesh.instanceColor) {
+        mesh.instanceColor.needsUpdate = true;
+      }
+
+      // Show the instanced mesh
+      mesh.visible = true;
+    }
+    return instances;
+  }
+}
+
+export class Renderer {
+  readonly renderer: GenesysWebGLRenderer;
+  private abortController = new AbortController();
+  private xrAnimationLoop: ((time: number) => void) | null = null;
+
+  /**
+   * Creates a new Renderer instance
+   * @param container - The HTML element to attach the renderer to
+   * @param options - Optional parameters for the renderer
+   */
+  constructor(protected container: HTMLElement, options?: THREE.WebGLRendererParameters) {
+    // hardcoded something decent to make it look good
+    this.renderer = new GenesysWebGLRenderer(options);
+    this.renderer.shadowMap.enabled = true;
+    this.renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+    this.renderer.toneMapping = THREE.NoToneMapping;
+
+    window.addEventListener('resize', this.onWindowResize.bind(this), { signal: this.abortController.signal });
+    this.onWindowResize();
+
+    this.container.appendChild(this.renderer.domElement);
+
+    cvarScreenPercentage.set(this.renderer.getPixelRatio() * 100);
+    cvarScreenPercentage.onValueChanged.add((oldValue, newValue) => {
+      this.renderer.setPixelRatio(newValue / 100);
+    });
+  }
+
+  /**
+   * Destroys the renderer instance
+   */
+  public destroy(): void {
+    this.renderer.domElement.remove();
+    this.abortController.abort();
+    this.renderer.dispose();
+  }
+
+  /**
+   * Gets the current window size
+   * @returns The current window size
+   */
+  public getWindowSize(): { width: number, height: number } {
+    return {
+      width: Math.floor(this.container.clientWidth || window.innerWidth),
+      height: Math.floor(this.container.clientHeight || window.innerHeight)
+    };
+  }
+
+  /**
+   * Renders the scene
+   * @param world - The world to render
+   */
+  public render(world: World): void {
+    this.renderer.beginRenderFrame();
+    world.renderScene(this.renderer, this.getWindowSize());
+    this.renderer.endRenderFrame();
+  }
+
+  /**
+   * Enables XR mode for the renderer
+   * @param referenceSpaceType The reference space type to use ('local', 'local-floor', 'bounded-floor', 'unbounded')
+   */
+  public enableXR(referenceSpaceType: XRReferenceSpaceType = 'local-floor'): void {
+    this.renderer.xr.enabled = true;
+    this.renderer.xr.setReferenceSpaceType(referenceSpaceType);
+    console.log(`WebXR enabled with reference space: ${referenceSpaceType}`);
+  }
+
+  /**
+   * Disables XR mode for the renderer
+   */
+  public disableXR(): void {
+    this.renderer.xr.enabled = false;
+    if (this.xrAnimationLoop) {
+      this.renderer.setAnimationLoop(null);
+      this.xrAnimationLoop = null;
+    }
+  }
+
+  /**
+   * Sets up XR animation loop for proper VR rendering
+   * @param tickCallback - The game loop's tick callback function
+   */
+  public setupXRAnimationLoop(tickCallback: (time: number) => void): void {
+    this.xrAnimationLoop = tickCallback;
+    this.renderer.setAnimationLoop(this.xrAnimationLoop);
+  }
+
+  /**
+   * Checks if XR is enabled
+   */
+  public isXREnabled(): boolean {
+    return this.renderer.xr.enabled;
+  }
+
+  /**
+   * Checks if currently presenting in XR
+   */
+  public isXRPresenting(): boolean {
+    return this.renderer.xr.isPresenting;
+  }
+
+  //====================================================================================================
+
+  protected onWindowResize(): void {
+    const windowSize = this.getWindowSize();
+    this.renderer.setSize(windowSize.width, windowSize.height);
+  }
+}

package/src/render/Texture.ts

@@ -0,0 +1,140 @@
+/**
+ * UrlTexture loads an image from a URL and ties it into Genesys serialization.
+ *
+ * The class extends `THREE.Texture` but defers the actual image loading to a
+ * shared `TextureLoader`. Once loaded it copies the image and disposes of the
+ * temporary texture so memory usage stays low. All construction options are
+ * recorded so the texture can be recreated when a world is deserialized.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Pass the desired `UrlTextureOptions` when creating the texture, including
+ *   wrap and filter parameters.
+ * - Register it with `ClassRegistry` if you need to serialize textures as part
+ *   of a scene.
+ * - Call `export` during world save to capture the URL and sampler settings.
+ */
+
+import * as THREE from 'three';
+
+import { DISABLE_TEXTURE_FLIP } from '../const.js';
+import { AssetPath } from '../storage/storageProvider.js';
+import { ClassRegistry, EngineClass } from '../systems/ClassRegistry.js';
+import { resourceManager } from '../utils/ResourceManager.js';
+import { ISerializableObjectTag } from '../utils/serialization/serializable.js';
+import { omitIfDefault, overrideIfDefault } from '../utils/Utils.js';
+
+import type { ISerializable, SerializedObject, WorldSerializationContext } from '../systems/WorldSerialization.js';
+import type { Dumper, Loader } from '../utils/serialization/serializer.js';
+
+/**
+ * Options for the UrlTexture constructor
+ */
+export interface UrlTextureOptions {
+  url: string;
+  mapping?: THREE.Mapping;
+  wrapS?: THREE.Wrapping;
+  wrapT?: THREE.Wrapping;
+  magFilter?: THREE.MagnificationTextureFilter;
+  minFilter?: THREE.MinificationTextureFilter;
+  format?: THREE.PixelFormat;
+  type?: THREE.TextureDataType;
+  anisotropy?: number;
+  colorSpace?: THREE.ColorSpace;
+  repeat?: THREE.Vector2;
+  offset?: THREE.Vector2;
+  rotation?: number;
+}
+
+/**
+ * A texture that loads from a URL
+ */
+@EngineClass('UrlTexture')
+export class UrlTexture extends THREE.Texture implements ISerializable {
+  readonly [ISerializableObjectTag] = true;
+  private static defaultObject = new THREE.Texture();
+  public readonly loadPromise: Promise<THREE.Texture | null>;
+
+  constructor(protected options: UrlTextureOptions) {
+    super(undefined, options.mapping, options.wrapS, options.wrapT, options.magFilter, options.minFilter, options.format, options.type, options.anisotropy);
+
+    if (DISABLE_TEXTURE_FLIP) {
+      this.flipY = false;
+    }
+
+    this.loadPromise = resourceManager.loadTexture(AssetPath.fromString(options.url));
+    this.loadPromise.then((texture) => {
+      if (texture) {
+        this.image = texture.image;
+        this.needsUpdate = !!this.image;
+
+        // Initialize texture transform properties
+        this.mapping = overrideIfDefault(this.mapping, UrlTexture.defaultObject.mapping, options.mapping ?? texture.mapping);
+        this.wrapS = overrideIfDefault(this.wrapS, UrlTexture.defaultObject.wrapS, options.wrapS ?? texture.wrapS);
+        this.wrapT = overrideIfDefault(this.wrapT, UrlTexture.defaultObject.wrapT, options.wrapT ?? texture.wrapT);
+        this.magFilter = overrideIfDefault(this.magFilter, UrlTexture.defaultObject.magFilter, options.magFilter ?? texture.magFilter);
+        this.minFilter = overrideIfDefault(this.minFilter, UrlTexture.defaultObject.minFilter, options.minFilter ?? texture.minFilter);
+        this.format = overrideIfDefault(this.format, UrlTexture.defaultObject.format, options.format ?? texture.format);
+        this.type = overrideIfDefault(this.type, UrlTexture.defaultObject.type, options.type ?? texture.type);
+        this.anisotropy = overrideIfDefault(this.anisotropy, UrlTexture.defaultObject.anisotropy, options.anisotropy ?? texture.anisotropy);
+        this.colorSpace = overrideIfDefault(this.colorSpace, UrlTexture.defaultObject.colorSpace, options.colorSpace ?? texture.colorSpace);
+        this.repeat = overrideIfDefault(this.repeat, UrlTexture.defaultObject.repeat, options.repeat ?? texture.repeat);
+        this.offset = overrideIfDefault(this.offset, UrlTexture.defaultObject.offset, options.offset ?? texture.offset);
+        this.rotation = overrideIfDefault(this.rotation, UrlTexture.defaultObject.rotation, options.rotation ?? texture.rotation);
+      }
+    });
+  }
+
+  public getUrl(): string {
+    return this.options.url;
+  }
+
+  public export(context: WorldSerializationContext): SerializedObject {
+    return {
+      class: ClassRegistry.getClassNameChecked(this),
+      uuid: this.uuid,
+      ctor: {
+        url: this.options.url,
+        mapping: omitIfDefault(this.mapping, UrlTexture.defaultObject.mapping),
+        wrapS: omitIfDefault(this.wrapS, UrlTexture.defaultObject.wrapS),
+        wrapT: omitIfDefault(this.wrapT, UrlTexture.defaultObject.wrapT),
+        magFilter: omitIfDefault(this.magFilter, UrlTexture.defaultObject.magFilter),
+        minFilter: omitIfDefault(this.minFilter, UrlTexture.defaultObject.minFilter),
+        format: omitIfDefault(this.format, UrlTexture.defaultObject.format),
+        type: omitIfDefault(this.type, UrlTexture.defaultObject.type),
+        anisotropy: omitIfDefault(this.anisotropy, UrlTexture.defaultObject.anisotropy),
+        colorSpace: omitIfDefault(this.colorSpace, UrlTexture.defaultObject.colorSpace),
+        repeat: omitIfDefault(context.exportObject(this.repeat, false), UrlTexture.defaultObject.repeat),
+        offset: omitIfDefault(context.exportObject(this.offset, false), UrlTexture.defaultObject.offset),
+        rotation: omitIfDefault(this.rotation, UrlTexture.defaultObject.rotation),
+      }
+    };
+  }
+
+  public serialize(dumper: Dumper): void {
+    dumper.dumpValue('$uuid', this.uuid);
+    dumper.dumpCtorArgs([{
+      value: {
+        url: this.options.url,
+        mapping: omitIfDefault(this.mapping, UrlTexture.defaultObject.mapping),
+        wrapS: omitIfDefault(this.wrapS, UrlTexture.defaultObject.wrapS),
+        wrapT: omitIfDefault(this.wrapT, UrlTexture.defaultObject.wrapT),
+        magFilter: omitIfDefault(this.magFilter, UrlTexture.defaultObject.magFilter),
+        minFilter: omitIfDefault(this.minFilter, UrlTexture.defaultObject.minFilter),
+        format: omitIfDefault(this.format, UrlTexture.defaultObject.format),
+        type: omitIfDefault(this.type, UrlTexture.defaultObject.type),
+        anisotropy: omitIfDefault(this.anisotropy, UrlTexture.defaultObject.anisotropy),
+        colorSpace: omitIfDefault(this.colorSpace, UrlTexture.defaultObject.colorSpace),
+        repeat: omitIfDefault(this.repeat, UrlTexture.defaultObject.repeat),
+        offset: omitIfDefault(this.offset, UrlTexture.defaultObject.offset),
+        rotation: omitIfDefault(this.rotation, UrlTexture.defaultObject.rotation),
+      }
+    }]);
+
+    dumper.dumpProperties(this);
+  }
+
+  public deserialize(loader: Loader): void {
+    (this as any).uuid = loader.loadValue('$uuid') ?? this.uuid;
+    loader.loadProperties(this);
+  }
+}

package/src/render/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Consolidates rendering exports for easy consumption.
+ *
+ * This barrel file exposes the core `Renderer` and `UrlTexture` classes so that
+ * other modules can import from a single location. As additional render-related
+ * utilities are created they should be exported here to keep the public API
+ * tidy.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Import `Renderer` when bootstrapping the game and creating the rendering
+ *   context.
+ * - Use `UrlTexture` for any textures that need to participate in world
+ *   serialization.
+ */
+export * from './EdgeOutlineEffect.js';
+export * from './PostProcessManager.js';
+export * from './Renderer.js';
+export * from './Texture.js';
+
+export * from './lightmapping/index.js';
+export * from './postprocessing/index.js';
+