@fairyhunter13/opentui-core 0.1.113 → 0.1.114

package/src/3d/SpriteResourceManager.ts

@@ -0,0 +1,286 @@
+import * as THREE from "three"
+import { TextureUtils } from "./TextureUtils.js"
+import type { Scene } from "three"
+
+export interface ResourceConfig {
+  imagePath: string
+  sheetNumFrames: number
+}
+
+export interface SheetProperties {
+  imagePath: string
+  sheetTilesetWidth: number
+  sheetTilesetHeight: number
+  sheetNumFrames: number
+}
+
+export interface InstanceManagerOptions {
+  maxInstances: number
+  renderOrder?: number
+  depthWrite?: boolean
+  name?: string
+  frustumCulled?: boolean
+  matrix?: THREE.Matrix4
+}
+
+export interface MeshPoolOptions {
+  geometry: () => THREE.BufferGeometry
+  material: THREE.Material
+  maxInstances: number
+  name?: string
+}
+
+const HIDDEN_MATRIX = new THREE.Matrix4().scale(new THREE.Vector3(0, 0, 0))
+
+export class MeshPool {
+  private pools: Map<string, THREE.InstancedMesh[]> = new Map()
+
+  public acquireMesh(poolId: string, options: MeshPoolOptions): THREE.InstancedMesh {
+    const poolArray = this.pools.get(poolId) ?? []
+    this.pools.set(poolId, poolArray)
+
+    if (poolArray.length > 0) {
+      const mesh = poolArray.pop()!
+      mesh.material = options.material
+      mesh.count = options.maxInstances
+      return mesh
+    }
+
+    const mesh = new THREE.InstancedMesh(options.geometry(), options.material, options.maxInstances)
+
+    if (options.name) {
+      mesh.name = options.name
+    }
+
+    return mesh
+  }
+
+  public releaseMesh(poolId: string, mesh: THREE.InstancedMesh): void {
+    const poolArray = this.pools.get(poolId) ?? []
+    poolArray.push(mesh)
+    this.pools.set(poolId, poolArray)
+  }
+
+  public fill(poolId: string, options: MeshPoolOptions, count: number): void {
+    const poolArray = this.pools.get(poolId) ?? []
+    this.pools.set(poolId, poolArray)
+
+    for (let i = 0; i < count; i++) {
+      const mesh = new THREE.InstancedMesh(options.geometry(), options.material, options.maxInstances)
+
+      if (options.name) {
+        mesh.name = `${options.name}_${i}`
+      }
+
+      poolArray.push(mesh)
+    }
+  }
+
+  public clearPool(poolId: string): void {
+    const poolArray = this.pools.get(poolId)
+    if (poolArray) {
+      poolArray.forEach((mesh) => {
+        mesh.geometry.dispose()
+        if (Array.isArray(mesh.material)) {
+          mesh.material.forEach((mat) => mat.dispose())
+        } else {
+          mesh.material.dispose()
+        }
+      })
+      poolArray.length = 0
+    }
+  }
+
+  public clearAllPools(): void {
+    for (const poolId of this.pools.keys()) {
+      this.clearPool(poolId)
+    }
+    this.pools.clear()
+  }
+}
+
+export class InstanceManager {
+  private scene: Scene
+  private instancedMesh: THREE.InstancedMesh
+  private material: THREE.Material
+  private maxInstances: number
+  private _freeIndices: number[] = []
+  private instanceCount: number = 0
+  private _matrix: THREE.Matrix4
+
+  constructor(scene: Scene, geometry: THREE.BufferGeometry, material: THREE.Material, options: InstanceManagerOptions) {
+    this.scene = scene
+    this.material = material
+    this.maxInstances = options.maxInstances
+    this._matrix = options.matrix ?? HIDDEN_MATRIX
+
+    this.instancedMesh = new THREE.InstancedMesh(geometry, material, this.maxInstances)
+    this.instancedMesh.renderOrder = options.renderOrder ?? 0
+    this.instancedMesh.frustumCulled = options.frustumCulled ?? false
+    this.instancedMesh.instanceMatrix.setUsage(THREE.DynamicDrawUsage)
+
+    if (options.name) {
+      this.instancedMesh.name = options.name
+    }
+
+    for (let i = 0; i < this.maxInstances; i++) {
+      this._freeIndices.push(i)
+      this.instancedMesh.setMatrixAt(i, this._matrix)
+    }
+    this.instancedMesh.instanceMatrix.needsUpdate = true
+
+    this.scene.add(this.instancedMesh)
+  }
+
+  acquireInstanceSlot(): number {
+    if (this._freeIndices.length === 0) {
+      throw new Error(`[InstanceManager] Max instances (${this.maxInstances}) reached. Cannot acquire slot.`)
+    }
+    const instanceIndex = this._freeIndices.pop()!
+    this.instanceCount++
+    return instanceIndex
+  }
+
+  releaseInstanceSlot(instanceIndex: number): void {
+    if (instanceIndex >= 0 && instanceIndex < this.maxInstances) {
+      this.instancedMesh.setMatrixAt(instanceIndex, this._matrix)
+      this.instancedMesh.instanceMatrix.needsUpdate = true
+
+      if (!this._freeIndices.includes(instanceIndex)) {
+        this._freeIndices.push(instanceIndex)
+        this._freeIndices.sort((a, b) => a - b)
+        this.instanceCount--
+      }
+    } else {
+      console.warn(`[InstanceManager] Attempted to release invalid instanceIndex ${instanceIndex}`)
+    }
+  }
+
+  getInstanceCount(): number {
+    return this.instanceCount
+  }
+
+  getMaxInstances(): number {
+    return this.maxInstances
+  }
+
+  get hasFreeIndices(): boolean {
+    return this._freeIndices.length > 0
+  }
+
+  get mesh(): THREE.InstancedMesh {
+    return this.instancedMesh
+  }
+
+  dispose(): void {
+    this.scene.remove(this.instancedMesh)
+    this.instancedMesh.geometry.dispose()
+    if (Array.isArray(this.material)) {
+      this.material.forEach((mat) => mat.dispose())
+    } else {
+      this.material.dispose()
+    }
+  }
+}
+
+export class SpriteResource {
+  private _texture: THREE.DataTexture
+  private _sheetProperties: SheetProperties
+  private scene: Scene
+  private _meshPool: MeshPool
+
+  constructor(texture: THREE.DataTexture, sheetProperties: SheetProperties, scene: Scene) {
+    this._texture = texture
+    this._sheetProperties = sheetProperties
+    this.scene = scene
+    this._meshPool = new MeshPool()
+  }
+
+  public get texture(): THREE.DataTexture {
+    return this._texture
+  }
+
+  public get sheetProperties(): SheetProperties {
+    return this._sheetProperties
+  }
+
+  public get meshPool(): MeshPool {
+    return this._meshPool
+  }
+
+  public createInstanceManager(
+    geometry: THREE.BufferGeometry,
+    material: THREE.Material,
+    options: InstanceManagerOptions,
+  ): InstanceManager {
+    const managerOptions = {
+      ...options,
+      name: options.name ?? `InstancedSprites_${this._sheetProperties.imagePath.replace(/[^a-zA-Z0-9_]/g, "_")}`,
+    }
+
+    return new InstanceManager(this.scene, geometry, material, managerOptions)
+  }
+
+  public get uvTileSize(): THREE.Vector2 {
+    const uvTileWidth = 1.0 / this._sheetProperties.sheetNumFrames
+    const uvTileHeight = 1.0
+    return new THREE.Vector2(uvTileWidth, uvTileHeight)
+  }
+
+  public dispose(): void {
+    this._meshPool.clearAllPools()
+  }
+}
+
+export class SpriteResourceManager {
+  private resources: Map<string, SpriteResource> = new Map()
+  private textureCache: Map<string, THREE.DataTexture> = new Map()
+  private scene: Scene
+
+  constructor(scene: Scene) {
+    this.scene = scene
+  }
+
+  private getResourceKey(sheetProps: SheetProperties): string {
+    return sheetProps.imagePath
+  }
+
+  public async getOrCreateResource(texture: THREE.DataTexture, sheetProps: SheetProperties): Promise<SpriteResource> {
+    const resourceKey = this.getResourceKey(sheetProps)
+    let resource = this.resources.get(resourceKey)
+
+    if (!resource) {
+      resource = new SpriteResource(texture, sheetProps, this.scene)
+      this.resources.set(resourceKey, resource)
+    }
+
+    return resource
+  }
+
+  public async createResource(config: ResourceConfig): Promise<SpriteResource> {
+    let texture = this.textureCache.get(config.imagePath)
+    if (!texture) {
+      const loadedTexture = await TextureUtils.fromFile(config.imagePath)
+      if (!loadedTexture) {
+        throw new Error(`[SpriteResourceManager] Failed to load texture for ${config.imagePath}`)
+      }
+      loadedTexture.needsUpdate = true
+      texture = loadedTexture
+      this.textureCache.set(config.imagePath, texture)
+    }
+
+    const sheetProps: SheetProperties = {
+      imagePath: config.imagePath,
+      sheetTilesetWidth: texture.image.width,
+      sheetTilesetHeight: texture.image.height,
+      sheetNumFrames: config.sheetNumFrames,
+    }
+
+    return await this.getOrCreateResource(texture, sheetProps)
+  }
+
+  public clearCache(): void {
+    this.resources.clear()
+    this.textureCache.clear()
+  }
+}

package/src/3d/SpriteUtils.ts

@@ -0,0 +1,70 @@
+import { TextureUtils } from "./TextureUtils.js"
+import { Sprite, SpriteMaterial, DataTexture, type SpriteMaterialParameters } from "three"
+
+export class SheetSprite extends Sprite {
+  private _frameIndex: number = 0
+  private _numFrames: number = 0
+
+  constructor(material: SpriteMaterial, numFrames: number) {
+    super(material)
+    this._numFrames = numFrames
+    this.setIndex(0)
+  }
+
+  setIndex = (index: number) => {
+    this._frameIndex = index
+    this.material.map?.repeat.set(1 / this._numFrames, 1)
+    this.material.map?.offset.set(this._frameIndex / this._numFrames, 0)
+  }
+}
+
+export class SpriteUtils {
+  static async fromFile(
+    path: string,
+    {
+      materialParameters = {
+        alphaTest: 0.1,
+        depthWrite: true,
+      },
+    }: {
+      materialParameters?: Omit<SpriteMaterialParameters, "map">
+    } = {},
+  ): Promise<Sprite> {
+    const texture = await TextureUtils.fromFile(path)
+    if (!texture) {
+      throw new Error(`Failed to load sprite texture from ${path}`)
+    }
+
+    const spriteMaterial = new SpriteMaterial({ map: texture, ...materialParameters })
+    const sprite = new Sprite(spriteMaterial)
+
+    const textureAspectRatio = texture.image.width / texture.image.height
+
+    sprite.updateMatrix = function () {
+      this.matrix.compose(this.position, this.quaternion, this.scale.clone().setX(this.scale.x * textureAspectRatio))
+    }
+
+    return sprite
+  }
+
+  static async sheetFromFile(path: string, numFrames: number): Promise<SheetSprite> {
+    const spriteTexture = await TextureUtils.fromFile(path)
+
+    if (!spriteTexture) {
+      throw new Error(`Failed to load sprite texture from ${path}`)
+    }
+
+    const spriteMaterial = new SpriteMaterial({ map: spriteTexture })
+    const sprite = new SheetSprite(spriteMaterial, numFrames)
+
+    const singleFrameWidth = spriteTexture.image.width / numFrames
+    const singleFrameHeight = spriteTexture.image.height
+    const frameAspectRatio = singleFrameWidth / singleFrameHeight
+
+    sprite.updateMatrix = function () {
+      this.matrix.compose(this.position, this.quaternion, this.scale.clone().setX(this.scale.x * frameAspectRatio))
+    }
+
+    return sprite
+  }
+}

package/src/3d/TextureUtils.ts

@@ -0,0 +1,196 @@
+import { readFile } from "node:fs/promises"
+import { Color, Texture, DataTexture, NearestFilter, ClampToEdgeWrapping, RGBAFormat, UnsignedByteType } from "three"
+import { Jimp } from "jimp"
+
+interface SimpleImageData {
+  data: Uint8ClampedArray
+  width: number
+  height: number
+}
+
+// Utility class for loading and generating THREE.Texture instances
+export class TextureUtils {
+  /**
+   * Loads a texture from a file path using sharp.
+   * Returns a THREE.Texture with ImageData attached to its .image property.
+   */
+  static async loadTextureFromFile(path: string): Promise<DataTexture | null> {
+    try {
+      const buffer = await readFile(path)
+      const image = await Jimp.read(buffer)
+
+      image.flip({ horizontal: false, vertical: true })
+
+      const texture = new DataTexture(
+        image.bitmap.data,
+        image.bitmap.width,
+        image.bitmap.height,
+        RGBAFormat,
+        UnsignedByteType,
+      )
+      texture.needsUpdate = true
+      texture.format = RGBAFormat
+      texture.magFilter = NearestFilter
+      texture.minFilter = NearestFilter
+      texture.wrapS = ClampToEdgeWrapping
+      texture.wrapT = ClampToEdgeWrapping
+      texture.flipY = false // Usually true for webGL, but our sampler flips V
+
+      return texture
+    } catch (error) {
+      console.error(`Failed to load texture from ${path}:`, error)
+      return null
+    }
+  }
+
+  /**
+   * Alias for loadTextureFromFile for convenience.
+   */
+  static async fromFile(path: string): Promise<DataTexture | null> {
+    return this.loadTextureFromFile(path)
+  }
+
+  /**
+   * Creates a THREE.Texture with a checkerboard pattern.
+   */
+  static createCheckerboard(
+    size: number = 256,
+    color1: Color = new Color(1.0, 1.0, 1.0),
+    color2: Color = new Color(0.0, 0.0, 0.0),
+    checkSize: number = 32,
+  ): Texture {
+    const data = new Uint8ClampedArray(size * size * 4)
+
+    for (let y = 0; y < size; y++) {
+      for (let x = 0; x < size; x++) {
+        const isEvenX = Math.floor(x / checkSize) % 2 === 0
+        const isEvenY = Math.floor(y / checkSize) % 2 === 0
+        const color = (isEvenX && isEvenY) || (!isEvenX && !isEvenY) ? color1 : color2
+
+        const index = (y * size + x) * 4
+        data[index] = Math.floor(color.r * 255)
+        data[index + 1] = Math.floor(color.g * 255)
+        data[index + 2] = Math.floor(color.b * 255)
+        data[index + 3] = 255 // Alpha
+      }
+    }
+
+    const imageData: SimpleImageData = { data, width: size, height: size }
+    const texture = new DataTexture(data, size, size, RGBAFormat, UnsignedByteType)
+    texture.needsUpdate = true
+    texture.format = RGBAFormat
+    texture.magFilter = NearestFilter
+    texture.minFilter = NearestFilter
+    texture.wrapS = ClampToEdgeWrapping
+    texture.wrapT = ClampToEdgeWrapping
+    texture.flipY = false
+
+    return texture
+  }
+
+  /**
+   * Creates a THREE.Texture with a gradient pattern.
+   */
+  static createGradient(
+    size: number = 256,
+    startColor: Color = new Color(1.0, 0.0, 0.0),
+    endColor: Color = new Color(0.0, 0.0, 1.0),
+    direction: "horizontal" | "vertical" | "radial" = "vertical",
+  ): Texture {
+    const data = new Uint8ClampedArray(size * size * 4)
+
+    for (let y = 0; y < size; y++) {
+      for (let x = 0; x < size; x++) {
+        let t = 0
+
+        if (direction === "horizontal") {
+          t = x / (size - 1)
+        } else if (direction === "vertical") {
+          t = y / (size - 1)
+        } else if (direction === "radial") {
+          const dx = x - size / 2
+          const dy = y - size / 2
+          t = Math.min(1, Math.sqrt(dx * dx + dy * dy) / (size / 2))
+        }
+
+        const r = startColor.r * (1 - t) + endColor.r * t
+        const g = startColor.g * (1 - t) + endColor.g * t
+        const b = startColor.b * (1 - t) + endColor.b * t
+
+        const index = (y * size + x) * 4
+        data[index] = Math.floor(r * 255)
+        data[index + 1] = Math.floor(g * 255)
+        data[index + 2] = Math.floor(b * 255)
+        data[index + 3] = 255 // Alpha
+      }
+    }
+
+    const imageData: SimpleImageData = { data, width: size, height: size }
+    const texture = new DataTexture(data, size, size, RGBAFormat, UnsignedByteType)
+    texture.needsUpdate = true
+    texture.format = RGBAFormat
+    texture.magFilter = NearestFilter
+    texture.minFilter = NearestFilter
+    texture.wrapS = ClampToEdgeWrapping
+    texture.wrapT = ClampToEdgeWrapping
+    texture.flipY = false
+
+    return texture
+  }
+
+  /**
+   * Creates a THREE.Texture with a procedural noise pattern.
+   */
+  static createNoise(
+    size: number = 256,
+    scale: number = 1,
+    octaves: number = 1,
+    color1: Color = new Color(1.0, 1.0, 1.0),
+    color2: Color = new Color(0.0, 0.0, 0.0),
+  ): Texture {
+    const data = new Uint8ClampedArray(size * size * 4)
+
+    for (let y = 0; y < size; y++) {
+      for (let x = 0; x < size; x++) {
+        let noise = 0
+        let amplitude = 1
+        let frequency = 1
+
+        for (let o = 0; o < octaves; o++) {
+          const nx = (x * frequency * scale) / size
+          const ny = (y * frequency * scale) / size
+          const sampleX = Math.sin(nx * 12.9898) * 43758.5453
+          const sampleY = Math.cos(ny * 78.233) * 43758.5453
+          const sample = Math.sin(sampleX + sampleY) * 0.5 + 0.5
+          noise += sample * amplitude
+          amplitude *= 0.5
+          frequency *= 2
+        }
+
+        noise = Math.min(1, Math.max(0, noise)) // Normalize
+
+        const r = color1.r * noise + color2.r * (1 - noise)
+        const g = color1.g * noise + color2.g * (1 - noise)
+        const b = color1.b * noise + color2.b * (1 - noise)
+
+        const index = (y * size + x) * 4
+        data[index] = Math.floor(r * 255)
+        data[index + 1] = Math.floor(g * 255)
+        data[index + 2] = Math.floor(b * 255)
+        data[index + 3] = 255 // Alpha
+      }
+    }
+
+    const imageData: SimpleImageData = { data, width: size, height: size }
+    const texture = new DataTexture(data, size, size, RGBAFormat, UnsignedByteType)
+    texture.needsUpdate = true
+    texture.format = RGBAFormat
+    texture.magFilter = NearestFilter
+    texture.minFilter = NearestFilter
+    texture.wrapS = ClampToEdgeWrapping
+    texture.wrapT = ClampToEdgeWrapping
+    texture.flipY = false
+
+    return texture
+  }
+}