@galfus/engine 0.0.0-stage → 0.31.0-alpha

package/src/realm3d/skinning.ts

@@ -0,0 +1,128 @@
+/**
+ * Skeletal skinning resolution system for Galfus Engine.
+ *
+ * Runs during the `preRender` stage after AnchorSolveSystem, reading world matrices
+ * directly from AnchorMatrixCache and uploading deformation matrices via realm3dUpdateBones.
+ */
+
+import type { GalfusEngine } from '@galfus/transport-types';
+import type { AnchorMatrixCache } from '../anchors/cache';
+import type { System } from '../ecs/system';
+import type { EcsWorld } from '../ecs/world';
+import { mat4, type Mat4 } from '../math/index';
+import { SpatialDirtyFlags } from '../spatial/flags';
+import type { Model3DComponent, Skin3DComponent } from './components';
+
+export class SkinningSolveSystem {
+  // Pre-allocated scratch matrices for zero-GC execution
+  private readonly _invModelMat: Mat4 = mat4.create();
+  private readonly _tempMat: Mat4 = mat4.create();
+  private readonly _skinMat: Mat4 = mat4.create();
+  private readonly _invBindMat: Mat4 = mat4.create();
+  private readonly _identityMat: Mat4 = mat4.create();
+
+  constructor(
+    readonly realmId: number,
+    readonly cache: AnchorMatrixCache
+  ) {}
+
+  /**
+   * Evaluates all active skins and submits bone matrices to the engine.
+   */
+  solve(world: EcsWorld, engine: GalfusEngine | null): void {
+    const skinEntities = world.query('Skin3D');
+    if (skinEntities.length === 0) return;
+
+    for (const skinEntityId of skinEntities) {
+      const skin = world.getComponent<Skin3DComponent>(skinEntityId, 'Skin3D');
+      if (!skin || skin.joints.length === 0) continue;
+
+      if (
+        !world.isAlive(skin.modelEntityId) ||
+        !world.getComponent<Model3DComponent>(skin.modelEntityId, 'Model3D')
+      ) {
+        world.destroyEntity(skinEntityId);
+        continue;
+      }
+
+      const model = world.getComponent<Model3DComponent>(skin.modelEntityId, 'Model3D');
+      if (!model) continue;
+
+      // Incremental optimization: skip re-computation and upload if model, joints, and skin are clean
+      const isModelDirty = (model.flags & SpatialDirtyFlags.WorldDirty) !== 0;
+      let isAnyJointDirty = false;
+      for (let j = 0; j < skin.joints.length; j++) {
+        const jointEntityId = skin.joints[j];
+        if (jointEntityId === undefined) continue;
+        const jointModel = world.getComponent<Model3DComponent>(jointEntityId, 'Model3D');
+        if (jointModel && (jointModel.flags & SpatialDirtyFlags.WorldDirty) !== 0) {
+          isAnyJointDirty = true;
+          break;
+        }
+      }
+
+      if (!skin.isDirty && !isModelDirty && !isAnyJointDirty) {
+        continue;
+      }
+
+      // 1. Get model world matrix (from model component or cache)
+      const modelWorld =
+        model.worldMatrix ?? this.cache.getWorld3D(skin.modelEntityId) ?? this._identityMat;
+
+      // 2. Invert model world matrix
+      if (!mat4.invert(this._invModelMat, modelWorld)) {
+        mat4.identity(this._invModelMat);
+      }
+
+      // 3. For each joint bone, compute: SkinMatrix = inv(ModelWorld) * JointWorld * InvBind
+      const jointCount = skin.joints.length;
+      for (let j = 0; j < jointCount; j++) {
+        const jointEntityId = skin.joints[j];
+        if (jointEntityId === undefined) continue;
+
+        const jointModel = world.getComponent<Model3DComponent>(jointEntityId, 'Model3D');
+        const jointWorld =
+          jointModel?.worldMatrix ?? this.cache.getWorld3D(jointEntityId) ?? this._identityMat;
+        const offset = j * 16;
+
+        // Copy 16 floats of the inverse bind matrix into scratch
+        for (let k = 0; k < 16; k++) {
+          this._invBindMat[k] = skin.inverseBindMatrices[offset + k] ?? (k % 5 === 0 ? 1 : 0);
+        }
+
+        // temp = JointWorld * InvBind
+        mat4.multiply(this._tempMat, jointWorld, this._invBindMat);
+
+        // skinMat = inv(ModelWorld) * temp
+        mat4.multiply(this._skinMat, this._invModelMat, this._tempMat);
+
+        // Store into pre-allocated jointMatrices buffer
+        for (let k = 0; k < 16; k++) {
+          skin.jointMatrices[offset + k] = this._skinMat[k] ?? 0;
+        }
+      }
+
+      // 4. Upload bone matrices to native core
+      if (engine) {
+        engine.realm3dUpdateBones(
+          this.realmId,
+          model.modelId,
+          skin.jointMatrices,
+          skin.jointMatrices.length
+        );
+      }
+
+      skin.isDirty = false;
+    }
+  }
+
+  /**
+   * Helper function creating an ECS System instance running this solver in `preRender`.
+   */
+  createSystem(getEngine: () => GalfusEngine | null): System<EcsWorld> {
+    return (world, context) => {
+      const engine = context.engine ?? getEngine();
+      this.solve(world, engine);
+    };
+  }
+}

package/src/realm3d/sync.ts

@@ -0,0 +1,442 @@
+/**
+ * Realm 3D synchronization system syncing ECS state and resource registries with core GalfusEngine.
+ */
+
+import type { GalfusEngine, Model3DDesc, Transform3D } from '@galfus/transport-types';
+import type { AnchorMatrixCache } from '../anchors/cache';
+import type { EntityId } from '../ecs/entity';
+import type { EcsWorld } from '../ecs/world';
+import { mat4, quat, vec3 } from '../math/index';
+import { SpatialDirtyFlags } from '../spatial/flags';
+import type {
+  Camera3DComponent,
+  GeometryResourceEntry,
+  InstancedModel3DComponent,
+  Light3DComponent,
+  MaterialResourceEntry,
+  Mesh3DComponent,
+  Model3DComponent,
+  ParticleEmitter3DComponent,
+  Portal3DComponent,
+  Primitive3DKind
+} from './components';
+
+export interface Realm3DResourceProvider {
+  getGeometries(): Iterable<GeometryResourceEntry>;
+  getMaterials(): Iterable<MaterialResourceEntry>;
+}
+
+const scratchTrans = vec3.create();
+const scratchRot = quat.create();
+const scratchScale = vec3.create();
+
+export class Realm3DSyncSystem {
+  private readonly _syncedGeometries = new Set<number>();
+  private readonly _syncedMaterials = new Set<number>();
+  private readonly _syncedModels = new Set<number>();
+  private readonly _syncedCameras = new Set<number>();
+  private readonly _syncedLights = new Set<number>();
+  private readonly _syncedEmitters = new Set<number>();
+  private readonly _syncedPortals = new Set<number>();
+  private readonly _syncedInstancedModels = new Set<number>();
+  private readonly _transformCache = new Map<EntityId, Transform3D>();
+
+  constructor(
+    readonly realmId: number,
+    readonly cache: AnchorMatrixCache
+  ) {}
+
+  /**
+   * Extracts a Transform3D from the resolved model world matrix or cache.
+   */
+  getResolvedTransform(world: EcsWorld, id: EntityId): Transform3D {
+    let tf = this._transformCache.get(id);
+    if (!tf) {
+      tf = {
+        position: [0, 0, 0],
+        rotation: [0, 0, 0, 1],
+        scale: [1, 1, 1]
+      };
+      this._transformCache.set(id, tf);
+    }
+
+    const model = world.getComponent<Model3DComponent>(id, 'Model3D');
+    const mat = model ? model.worldMatrix : this.cache.getWorld3D(id);
+
+    if (mat) {
+      mat4.getTranslation(scratchTrans, mat);
+      mat4.getRotation(scratchRot, mat);
+      mat4.getScaling(scratchScale, mat);
+
+      const p = tf.position;
+      p[0] = scratchTrans[0]!;
+      p[1] = scratchTrans[1]!;
+      p[2] = scratchTrans[2]!;
+
+      const r = tf.rotation!;
+      r[0] = scratchRot[0]!;
+      r[1] = scratchRot[1]!;
+      r[2] = scratchRot[2]!;
+      r[3] = scratchRot[3]!;
+
+      const s = tf.scale!;
+      s[0] = scratchScale[0]!;
+      s[1] = scratchScale[1]!;
+      s[2] = scratchScale[2]!;
+    } else {
+      tf.position[0] = 0;
+      tf.position[1] = 0;
+      tf.position[2] = 0;
+    }
+
+    return tf;
+  }
+
+  private _uploadPrimitive(
+    engine: GalfusEngine,
+    geometryId: number,
+    primitive: Primitive3DKind
+  ): void {
+    switch (primitive.kind) {
+      case 'cube':
+        engine.realm3dCreateCube(this.realmId, geometryId, primitive.size);
+        break;
+      case 'plane':
+        engine.realm3dCreatePlane(this.realmId, geometryId, primitive.width, primitive.depth);
+        break;
+      case 'quad':
+        engine.realm3dCreateQuad(this.realmId, geometryId, primitive.width, primitive.height);
+        break;
+      case 'sphere':
+        engine.realm3dCreateSphere(
+          this.realmId,
+          geometryId,
+          primitive.radius,
+          primitive.rings,
+          primitive.sectors
+        );
+        break;
+      case 'cylinder':
+        engine.realm3dCreateCylinder(
+          this.realmId,
+          geometryId,
+          primitive.radius,
+          primitive.height,
+          primitive.sectors
+        );
+        break;
+      case 'capsule':
+        engine.realm3dCreateCapsule(
+          this.realmId,
+          geometryId,
+          primitive.radius,
+          primitive.cylinderHeight,
+          primitive.rings,
+          primitive.sectors
+        );
+        break;
+      case 'pyramid':
+        engine.realm3dCreatePyramid(
+          this.realmId,
+          geometryId,
+          primitive.width,
+          primitive.depth,
+          primitive.height
+        );
+        break;
+      case 'torus':
+        engine.realm3dCreateTorus(
+          this.realmId,
+          geometryId,
+          primitive.majorRadius,
+          primitive.minorRadius,
+          primitive.majorSegments,
+          primitive.minorSegments
+        );
+        break;
+      case 'custom':
+        engine.realm3dCreateGeometry(
+          this.realmId,
+          geometryId,
+          primitive.topology,
+          primitive.vertexData,
+          primitive.vertexData.byteLength,
+          primitive.indices,
+          primitive.indices.length
+        );
+        break;
+    }
+  }
+
+  /**
+   * Synchronizes all active 3D resources and ECS components to the engine driver.
+   */
+  sync(world: EcsWorld, engine: GalfusEngine, resourceProvider?: Realm3DResourceProvider): void {
+    // 1. Sync geometries from the resource registry
+    const currentGeometries = new Set<number>();
+    if (resourceProvider) {
+      for (const geo of resourceProvider.getGeometries()) {
+        currentGeometries.add(geo.geometryId);
+        if (!this._syncedGeometries.has(geo.geometryId) || geo.isDirty) {
+          this._uploadPrimitive(engine, geo.geometryId, geo.primitive);
+          if (geo.morphTargets) {
+            const { data, count } = geo.morphTargets;
+            engine.realm3dSetGeometryMorphTargets(
+              this.realmId,
+              geo.geometryId,
+              data,
+              data.byteLength,
+              count
+            );
+          }
+          this._syncedGeometries.add(geo.geometryId);
+          geo.isDirty = false;
+        }
+      }
+    }
+    for (const geoId of this._syncedGeometries) {
+      if (!currentGeometries.has(geoId)) {
+        engine.realm3dDestroyGeometry(this.realmId, geoId);
+        this._syncedGeometries.delete(geoId);
+      }
+    }
+
+    // 2. Sync materials from the resource registry
+    const currentMaterials = new Set<number>();
+    if (resourceProvider) {
+      for (const mat of resourceProvider.getMaterials()) {
+        currentMaterials.add(mat.materialId);
+        if (!this._syncedMaterials.has(mat.materialId) || mat.isDirty) {
+          engine.realm3dCreateMaterial(this.realmId, mat.materialId, mat.desc);
+          this._syncedMaterials.add(mat.materialId);
+          mat.isDirty = false;
+        }
+      }
+    }
+    for (const matId of this._syncedMaterials) {
+      if (!currentMaterials.has(matId)) {
+        engine.realm3dDestroyMaterial(this.realmId, matId);
+        this._syncedMaterials.delete(matId);
+      }
+    }
+
+    // 3. Sync Models & Meshes
+    const modelEntities = world.query('Model3D');
+    const currentModels = new Set<number>();
+    for (const id of modelEntities) {
+      const mesh = world.getComponent<Mesh3DComponent>(id, 'Mesh3D');
+      // If the entity has no mesh AND has a dedicated spatial component (Camera, Light, Emitter, Portal, InstancedModel),
+      // we do not register an empty Rust model for it.
+      if (
+        !mesh &&
+        (world.hasComponent(id, 'Camera3D') ||
+          world.hasComponent(id, 'Light3D') ||
+          world.hasComponent(id, 'ParticleEmitter3D') ||
+          world.hasComponent(id, 'Portal3D') ||
+          world.hasComponent(id, 'InstancedModel3D'))
+      ) {
+        continue;
+      }
+      const model = world.getComponent<Model3DComponent>(id, 'Model3D');
+      if (!model) continue;
+      currentModels.add(model.modelId);
+
+      const tf = this.getResolvedTransform(world, id);
+      const isRegistered = this._syncedModels.has(model.modelId);
+      const isSpatialDirty = (model.flags & SpatialDirtyFlags.WorldDirty) !== 0;
+      const isMeshDirty = mesh ? mesh.isDirty : false;
+
+      if (!isRegistered || isMeshDirty) {
+        const desc: Model3DDesc = {
+          geometryId: mesh ? mesh.geometryId : 0,
+          materialId: mesh ? mesh.materialId : 0,
+          castShadow: mesh ? mesh.castShadow : true,
+          receiveShadow: mesh ? mesh.receiveShadow : true,
+          castOutline: mesh ? mesh.castOutline : false,
+          outlineColor: mesh ? mesh.outlineColor : [1, 1, 1, 1],
+          active: mesh ? mesh.active : true,
+          boneOffset: mesh ? mesh.boneOffset : 0,
+          boneCount: mesh ? mesh.boneCount : 0
+        };
+        engine.realm3dCreateModel(this.realmId, model.modelId, desc, tf);
+        this._syncedModels.add(model.modelId);
+        if (mesh) mesh.isDirty = false;
+      } else if (isSpatialDirty) {
+        engine.realm3dSetModelTransform(this.realmId, model.modelId, tf);
+      }
+    }
+    for (const modelId of this._syncedModels) {
+      if (!currentModels.has(modelId)) {
+        engine.realm3dDestroyModel(this.realmId, modelId);
+        this._syncedModels.delete(modelId);
+        this._transformCache.delete(modelId);
+      }
+    }
+
+    // 4. Sync Cameras
+    const cameraEntities = world.query('Camera3D');
+    const currentCameras = new Set<number>();
+    for (const id of cameraEntities) {
+      const camera = world.getComponent<Camera3DComponent>(id, 'Camera3D');
+      if (!camera) continue;
+      currentCameras.add(camera.cameraId);
+
+      const model = world.getComponent<Model3DComponent>(id, 'Model3D');
+      const isSpatialDirty = model ? (model.flags & SpatialDirtyFlags.WorldDirty) !== 0 : false;
+      const tf = this.getResolvedTransform(world, id);
+      if (!this._syncedCameras.has(camera.cameraId) || camera.isDirty) {
+        engine.realm3dCreateCamera(this.realmId, camera.cameraId, camera.desc, tf);
+        this._syncedCameras.add(camera.cameraId);
+        camera.isDirty = false;
+      } else if (isSpatialDirty) {
+        engine.realm3dSetCameraTransform(this.realmId, camera.cameraId, tf);
+      }
+    }
+    for (const camId of this._syncedCameras) {
+      if (!currentCameras.has(camId)) {
+        engine.realm3dDestroyCamera(this.realmId, camId);
+        this._syncedCameras.delete(camId);
+      }
+    }
+
+    // 5. Sync Lights
+    const lightEntities = world.query('Light3D');
+    const currentLights = new Set<number>();
+    for (const id of lightEntities) {
+      const light = world.getComponent<Light3DComponent>(id, 'Light3D');
+      if (!light) continue;
+      currentLights.add(light.lightId);
+
+      const model = world.getComponent<Model3DComponent>(id, 'Model3D');
+      const isSpatialDirty = model ? (model.flags & SpatialDirtyFlags.WorldDirty) !== 0 : false;
+      const tf = this.getResolvedTransform(world, id);
+      if (!this._syncedLights.has(light.lightId) || light.isDirty) {
+        engine.realm3dCreateLight(this.realmId, light.lightId, light.desc, tf);
+        this._syncedLights.add(light.lightId);
+        light.isDirty = false;
+      } else if (isSpatialDirty) {
+        engine.realm3dSetLightTransform(this.realmId, light.lightId, tf);
+      }
+    }
+    for (const lightId of this._syncedLights) {
+      if (!currentLights.has(lightId)) {
+        engine.realm3dDestroyLight(this.realmId, lightId);
+        this._syncedLights.delete(lightId);
+      }
+    }
+
+    // 6. Sync Particle Emitters
+    const emitterEntities = world.query('ParticleEmitter3D');
+    const currentEmitters = new Set<number>();
+    for (const id of emitterEntities) {
+      const emitter = world.getComponent<ParticleEmitter3DComponent>(id, 'ParticleEmitter3D');
+      if (!emitter) continue;
+      currentEmitters.add(emitter.emitterId);
+
+      const model = world.getComponent<Model3DComponent>(id, 'Model3D');
+      const isSpatialDirty = model ? (model.flags & SpatialDirtyFlags.WorldDirty) !== 0 : false;
+      const tf = this.getResolvedTransform(world, id);
+      if (!this._syncedEmitters.has(emitter.emitterId) || emitter.isDirty) {
+        engine.realm3dCreateParticleEmitter(this.realmId, emitter.emitterId, emitter.desc, tf);
+        this._syncedEmitters.add(emitter.emitterId);
+        emitter.isDirty = false;
+      } else if (isSpatialDirty) {
+        engine.realm3dSetParticleEmitterTransform(this.realmId, emitter.emitterId, tf);
+      }
+    }
+    for (const emitterId of this._syncedEmitters) {
+      if (!currentEmitters.has(emitterId)) {
+        engine.realm3dDestroyParticleEmitter(this.realmId, emitterId);
+        this._syncedEmitters.delete(emitterId);
+      }
+    }
+
+    // 7. Sync Portals
+    const portalEntities = world.query('Portal3D');
+    const currentPortals = new Set<number>();
+    for (const id of portalEntities) {
+      const portal = world.getComponent<Portal3DComponent>(id, 'Portal3D');
+      if (!portal) continue;
+      currentPortals.add(portal.portalId);
+
+      if (!this._syncedPortals.has(portal.portalId) || portal.isDirty) {
+        engine.realm3dCreatePortal(this.realmId, portal.portalId, portal.desc);
+        this._syncedPortals.add(portal.portalId);
+        portal.isDirty = false;
+      }
+    }
+    for (const portalId of this._syncedPortals) {
+      if (!currentPortals.has(portalId)) {
+        engine.realm3dDestroyPortal(this.realmId, portalId);
+        this._syncedPortals.delete(portalId);
+      }
+    }
+
+    // 8. Sync Instanced Models
+    const instancedEntities = world.query('InstancedModel3D');
+    const currentInstanced = new Set<number>();
+    for (const id of instancedEntities) {
+      const instanced = world.getComponent<InstancedModel3DComponent>(id, 'InstancedModel3D');
+      if (!instanced) continue;
+      currentInstanced.add(instanced.instancedModelId);
+
+      if (!this._syncedInstancedModels.has(instanced.instancedModelId) || instanced.isDirty) {
+        engine.realm3dCreateInstancedModel(
+          this.realmId,
+          instanced.instancedModelId,
+          instanced.desc
+        );
+        this._syncedInstancedModels.add(instanced.instancedModelId);
+        instanced.isDirty = false;
+      }
+    }
+    for (const instancedId of this._syncedInstancedModels) {
+      if (!currentInstanced.has(instancedId)) {
+        engine.realm3dDestroyInstancedModel(this.realmId, instancedId);
+        this._syncedInstancedModels.delete(instancedId);
+      }
+    }
+
+    // 9. Clear WorldDirty for all Model3D entities after all Core sync steps are complete
+    for (const id of modelEntities) {
+      const model = world.getComponent<Model3DComponent>(id, 'Model3D');
+      if (model) {
+        model.flags &= ~SpatialDirtyFlags.WorldDirty;
+      }
+    }
+  }
+
+  isCameraSynced(cameraId: number): boolean {
+    return this._syncedCameras.has(cameraId);
+  }
+
+  isEmitterSynced(emitterId: number): boolean {
+    return this._syncedEmitters.has(emitterId);
+  }
+
+  /**
+   * Disposes all tracked IDs on the engine when the realm is destroyed.
+   */
+  dispose(engine: GalfusEngine | null): void {
+    if (engine) {
+      for (const id of this._syncedModels) engine.realm3dDestroyModel(this.realmId, id);
+      for (const id of this._syncedLights) engine.realm3dDestroyLight(this.realmId, id);
+      for (const id of this._syncedCameras) engine.realm3dDestroyCamera(this.realmId, id);
+      for (const id of this._syncedMaterials) engine.realm3dDestroyMaterial(this.realmId, id);
+      for (const id of this._syncedGeometries) engine.realm3dDestroyGeometry(this.realmId, id);
+      for (const id of this._syncedEmitters) engine.realm3dDestroyParticleEmitter(this.realmId, id);
+      for (const id of this._syncedPortals) engine.realm3dDestroyPortal(this.realmId, id);
+      for (const id of this._syncedInstancedModels)
+        engine.realm3dDestroyInstancedModel(this.realmId, id);
+    }
+    this._syncedModels.clear();
+    this._syncedLights.clear();
+    this._syncedCameras.clear();
+    this._syncedMaterials.clear();
+    this._syncedGeometries.clear();
+    this._syncedEmitters.clear();
+    this._syncedPortals.clear();
+    this._syncedInstancedModels.clear();
+    this._transformCache.clear();
+  }
+}

package/src/realm3d/utils/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Realm 3D math and spatial utilities.
+ */
+
+import { vec3 } from '../../math/index';
+import type { Vec3 } from '../../math/vec3';
+
+export interface BoundingSphere3D {
+  center: [number, number, number];
+  radius: number;
+}
+
+export function createBoundingSphere3D(
+  center: [number, number, number] | Vec3,
+  radius: number
+): BoundingSphere3D {
+  return {
+    center: [center[0], center[1], center[2]],
+    radius
+  };
+}
+
+export function intersectsSphere3D(a: BoundingSphere3D, b: BoundingSphere3D): boolean {
+  const d = vec3.distance(a.center, b.center);
+  return d <= a.radius + b.radius;
+}

package/src/resources/index.ts

@@ -0,0 +1,4 @@
+/**
+ * Subpath export for GPU shared resources subsystem.
+ */
+export * from './manager';

package/src/resources/manager.ts

@@ -0,0 +1,92 @@
+/**
+ * ResourceManager manages allocation and GPU binding for shared textures.
+ */
+
+import type { GalfusEngine, GpuTextureDesc, TextureUpdateDesc } from '@galfus/transport-types';
+import { IdAllocator, type TextureId } from '../types';
+
+export interface LoadTextureOptions {
+  /** Debug label for the GPU texture resource */
+  label?: string;
+  /** Whether pixels represent sRGB color (defaults to true; set false for normal/data maps) */
+  srgb?: boolean;
+}
+
+export class ResourceManager {
+  private _engine: GalfusEngine | null = null;
+  private readonly _idAllocator = new IdAllocator<TextureId>(1);
+  private readonly _textures = new Set<TextureId>();
+
+  bindEngine(engine: GalfusEngine): void {
+    this._engine = engine;
+  }
+
+  /**
+   * Loads raw image bytes (PNG, JPEG, WebP, ICO) directly into a tracked GPU texture.
+   * Auto-detection and decoding are handled natively inside the Galfus core.
+   * Follows payload-first convention: (data, options?).
+   *
+   * @param data Encoded image file bytes (PNG, JPEG, WebP, ICO).
+   * @param options Configuration options (sRGB color space, debug label).
+   * @returns The allocated logical TextureId.
+   */
+  loadTexture(data: Uint8Array, options?: LoadTextureOptions): TextureId {
+    const srgb = options?.srgb ?? true;
+    return this.createTexture(data, {
+      label: options?.label ?? 'image-texture',
+      width: 0,
+      height: 0,
+      format: srgb ? 'rgba8UnormSrgb' : 'rgba8Unorm'
+    });
+  }
+
+  /**
+   * Creates a shared GPU texture from raw byte data under a tracked logical TextureId.
+   * If `data` contains encoded image container bytes (PNG, JPEG, WebP, ICO), the Galfus core
+   * automatically decodes it into RGBA8 and derives width/height.
+   *
+   * Follows payload-first convention: (data, desc).
+   */
+  createTexture(data: Uint8Array, desc: GpuTextureDesc): TextureId {
+    const textureId = this._idAllocator.allocate('TextureId');
+    if (this._engine) {
+      this._engine.resourceCreateTexture(textureId, desc, data, data.byteLength);
+    }
+    this._textures.add(textureId);
+    return textureId;
+  }
+
+  /**
+   * Updates a sub-rectangle of an existing GPU texture.
+   * Follows payload-first convention: (textureId, data, rect).
+   */
+  updateTexture(textureId: TextureId, data: Uint8Array, rect: TextureUpdateDesc): void {
+    if (this._engine) {
+      this._engine.resourceUpdateTexture(textureId, rect, data, data.byteLength);
+    }
+  }
+
+  /**
+   * Disposes a GPU texture and frees its logical ID.
+   */
+  disposeTexture(textureId: TextureId): void {
+    if (!this._textures.has(textureId)) return;
+    if (this._engine) {
+      this._engine.resourceDisposeTexture(textureId);
+    }
+    this._textures.delete(textureId);
+  }
+
+  /**
+   * Disposes all active textures.
+   */
+  dispose(): void {
+    if (this._engine) {
+      for (const textureId of this._textures) {
+        this._engine.resourceDisposeTexture(textureId);
+      }
+    }
+    this._textures.clear();
+    this._engine = null;
+  }
+}