kiwiengine 0.0.1-alpha → 0.5.2

package/src/renderer/renderer.ts

@@ -0,0 +1,180 @@
+import { EventMap } from '@webtaku/event-emitter'
+import { AutoDetectOptions, autoDetectRenderer, ColorSource, Container as PixiContainer, Renderer as PixiRenderer } from 'pixi.js'
+import { debugMode } from '../debug'
+import { setStyle } from '../dom/dom-utils'
+import { RenderableNode } from '../node/core/renderable'
+import { Camera } from './camera'
+import { RendererContainerManager } from './container-manager'
+import { FpsDisplay } from './fps-display'
+import { Layer } from './layer'
+import { Ticker } from './ticker'
+
+export type RendererOptions = {
+  logicalWidth?: number
+  logicalHeight?: number
+  backgroundColor?: ColorSource
+  backgroundAlpha?: number
+  layers?: { name: string; drawOrder: number }[]
+}
+
+export class Renderer extends RenderableNode<PixiContainer, {
+  resize: (width: number, height: number) => void
+}> {
+  #containerManager: RendererContainerManager
+  #ticker = new Ticker((dt) => this.#render(dt))
+  camera = new Camera()
+  fpsDisplay?: FpsDisplay
+
+  #logicalWidth?: number
+  #logicalHeight?: number
+  #backgroundColor?: ColorSource
+  #backgroundAlpha?: number
+
+  #pixiRenderer?: PixiRenderer
+  #layers: { [name: string]: Layer } = {}
+  _isSizeDirty = false
+
+  canvasWidth = 0
+  canvasHeight = 0
+  canvasLeft = 0
+  canvasTop = 0
+  viewportScale = 1
+  centerX = 0
+  centerY = 0
+
+  constructor(public container: HTMLElement, options?: RendererOptions) {
+    super(new PixiContainer({ sortableChildren: true }))
+    this.renderer = this
+
+    this.worldTransform.x.v = 0
+    this.worldTransform.y.v = 0
+    this.worldTransform.resetDirty()
+
+    this.#containerManager = new RendererContainerManager(container)
+    this.#containerManager.on('resize', (width, height) => this.#updateSize(width, height))
+
+    this.camera.on('positionChanged', () => this.#updatePosition())
+    this.camera.on('scaleChanged', () => this.#updatePosition())
+
+    if (options) {
+      if (options.logicalWidth !== undefined) this.#logicalWidth = options.logicalWidth
+      if (options.logicalHeight !== undefined) this.#logicalHeight = options.logicalHeight
+      if (options.backgroundColor !== undefined) this.#backgroundColor = options.backgroundColor
+      if (options.backgroundAlpha !== undefined) this.#backgroundAlpha = options.backgroundAlpha
+
+      if (options.layers) {
+        for (const layerOption of options.layers) {
+          const layer = new Layer(layerOption.drawOrder)
+          this._pixiContainer.addChild(layer._pixiContainer)
+          this.#layers[layerOption.name] = layer
+        }
+      }
+    }
+
+    if (debugMode) {
+      this.fpsDisplay = new FpsDisplay(container)
+    }
+
+    this.init()
+  }
+
+  private async init() {
+    const options: Partial<AutoDetectOptions> = {
+      eventMode: 'none',
+      resolution: window.devicePixelRatio,
+    }
+
+    if (this.#logicalWidth) options.width = this.#logicalWidth
+    if (this.#logicalHeight) options.height = this.#logicalHeight
+    if (this.#backgroundColor) options.backgroundColor = this.#backgroundColor
+    if (this.#backgroundAlpha) options.backgroundAlpha = this.#backgroundAlpha
+
+    const pr = await autoDetectRenderer(options)
+
+    setStyle(pr.canvas, {
+      position: 'absolute',
+      touchAction: 'auto',
+    })
+    this.container.appendChild(pr.canvas)
+
+    this.#pixiRenderer = pr
+
+    const cr = this.container.getBoundingClientRect()
+    this.#updateSize(cr.width, cr.height)
+  }
+
+  #updatePosition() {
+    const S = this.camera.scale
+    this._pixiContainer.scale = S
+    this._pixiContainer.position.set(
+      this.centerX - this.camera.x * S,
+      this.centerY - this.camera.y * S
+    )
+  }
+
+  #updateSize(containerWidth: number, containerHeight: number) {
+    const canvasWidth = this.#logicalWidth ?? containerWidth
+    const canvasHeight = this.#logicalHeight ?? containerHeight
+    this.canvasWidth = canvasWidth
+    this.canvasHeight = canvasHeight
+
+    this.centerX = canvasWidth / 2
+    this.centerY = canvasHeight / 2
+    this.#updatePosition()
+
+    const S = Math.min(containerWidth / canvasWidth, containerHeight / canvasHeight)
+    this.viewportScale = S
+
+    const displayWidth = canvasWidth * S
+    const displayHeight = canvasHeight * S
+
+    const canvasLeft = (containerWidth - displayWidth) / 2
+    const canvasTop = (containerHeight - displayHeight) / 2
+    this.canvasLeft = canvasLeft
+    this.canvasTop = canvasTop
+
+    if (this.#pixiRenderer) {
+      this.#pixiRenderer.resize(canvasWidth, canvasHeight)
+
+      setStyle(this.#pixiRenderer.canvas, {
+        width: `${displayWidth}px`,
+        height: `${displayHeight}px`,
+        left: `${canvasLeft}px`,
+        top: `${canvasTop}px`,
+      })
+
+      this.emit('resize', canvasWidth, canvasHeight)
+    }
+
+    this._isSizeDirty = true
+  }
+
+  #render(dt: number) {
+    this._isSizeDirty = false
+
+    this.update(dt)
+    this._updateWorldTransform()
+    this.#pixiRenderer?.render(this._pixiContainer)
+    this.fpsDisplay?.update()
+  }
+
+  _addToLayer(node: RenderableNode<PixiContainer, EventMap>, layerName: string) {
+    const layer = this.#layers[layerName]
+    if (!layer) throw new Error(`Layer ${layerName} does not exist.`)
+    layer._pixiContainer.addChild(node._pixiContainer)
+  }
+
+  override remove() {
+    this.#containerManager.remove()
+    this.#ticker.remove()
+    this.#pixiRenderer?.destroy()
+    this.fpsDisplay?.remove()
+    super.remove()
+  }
+
+  screenToWorld(screenX: number, screenY: number) {
+    const x = (screenX - this.canvasLeft) / this.viewportScale - this.canvasWidth / 2
+    const y = (screenY - this.canvasTop) / this.viewportScale - this.canvasHeight / 2
+    return { x, y }
+  }
+}

package/src/renderer/ticker.test.ts

@@ -0,0 +1,325 @@
+/** @jest-environment jsdom */
+
+/**
+ * Test Suite — Ticker (Jest)
+ * -------------------------------------------------------
+ * Goals
+ *  - Avoid floating-point pitfalls around fixed step boundaries
+ *  - Validate uncapped, capped via blur (6fps), long frame split,
+ *    focus/pageshow transitions, and remove()
+ *  - In this implementation: no setFixedFps; debugMode + focus/blur/pageshow control fps cap
+ *
+ * Principles
+ *  - Do not assert exactly at the boundary (e.g., prefer 170ms over ~166ms)
+ *  - Validate deltaTime using toBeCloseTo + loose call count checks
+ */
+
+/** ----------------------- Time & RAF harness ----------------------- **/
+
+// Local callback type to avoid depending on DOM lib typings.
+type FrameCb = (time: number) => void
+
+// Simulated monotonic clock (ms)
+let nowMs = 0
+
+// RAF callback registry: id -> cb
+const rafCallbacks = new Map<number, FrameCb>()
+let nextRafId = 1
+
+const installTimeAndRafMocks = () => {
+  jest.spyOn(performance, 'now').mockImplementation(() => nowMs)
+
+  jest
+    .spyOn(window, 'requestAnimationFrame')
+    .mockImplementation((cb: FrameCb) => {
+      const id = nextRafId++
+      rafCallbacks.set(id, cb)
+      return id as unknown as number
+    })
+
+  jest.spyOn(window, 'cancelAnimationFrame').mockImplementation((id: number) => {
+    rafCallbacks.delete(id)
+  })
+}
+
+const resetHarness = () => {
+  nowMs = 0
+  rafCallbacks.clear()
+  nextRafId = 1
+}
+
+/**
+ * Advance a single frame: move the clock by advanceMs and
+ * run only the currently registered RAF callbacks
+ * (callbacks registered during this step run on the next step).
+ */
+const step = (advanceMs: number) => {
+  nowMs += advanceMs
+  const cbs = [...rafCallbacks.values()]
+  rafCallbacks.clear()
+  for (const cb of cbs) cb(nowMs)
+}
+
+/** Advance multiple frames (helper) */
+const advance = (totalMs: number, stepMs = 16) => {
+  const n = Math.floor(totalMs / stepMs)
+  for (let i = 0; i < n; i++) step(stepMs)
+  const remain = totalMs - n * stepMs
+  if (remain > 0) step(remain)
+}
+
+/**
+ * Helper to (re)load Ticker with a specific debugMode value.
+ * Uses jest.resetModules + jest.doMock to inject the desired export.
+ */
+const loadTickerWithDebug = async (debug: boolean) => {
+  jest.resetModules()
+  jest.doMock('../debug', () => ({ debugMode: debug }), { virtual: true })
+  const mod = await import('./ticker')
+  return (mod as any).Ticker as new (onTick: (dt: number) => void) => { remove(): void }
+}
+
+/** Small helpers to read arguments cleanly */
+const argOf = (mockFn: jest.Mock, nthZeroBased: number) => mockFn.mock.calls[nthZeroBased][0] as number
+const lastArg = (mockFn: jest.Mock) => {
+  const i = mockFn.mock.calls.length - 1
+  return mockFn.mock.calls[i][0] as number
+}
+
+/** ----------------------- Lifecycle -------------------------- **/
+
+beforeEach(() => {
+  resetHarness()
+  jest.restoreAllMocks()
+  installTimeAndRafMocks()
+})
+
+afterEach(() => {
+  jest.restoreAllMocks()
+  resetHarness()
+})
+
+/** ----------------------- Tests ------------------------------ **/
+
+describe('uncapped mode (debugMode=false)', () => {
+  it('calls onTick once per frame with raw deltaTime (seconds)', async () => {
+    const Ticker = await loadTickerWithDebug(false)
+    const spy = jest.fn()
+    const ticker = new Ticker(spy) // default: uncapped
+
+    step(10) // 0.010
+    step(20) // 0.020
+    step(30) // 0.030
+
+    expect(spy).toHaveBeenCalledTimes(3)
+
+    // Assert shapes, then values
+    expect(spy).toHaveBeenNthCalledWith(1, expect.any(Number))
+    expect(spy).toHaveBeenNthCalledWith(2, expect.any(Number))
+    expect(spy).toHaveBeenNthCalledWith(3, expect.any(Number))
+
+    expect(argOf(spy, 0)).toBeCloseTo(0.010, 6)
+    expect(argOf(spy, 1)).toBeCloseTo(0.020, 6)
+    expect(argOf(spy, 2)).toBeCloseTo(0.030, 6)
+
+    ticker.remove()
+  })
+
+  it('does not call onTick when deltaTime <= 0', async () => {
+    const Ticker = await loadTickerWithDebug(false)
+    const spy = jest.fn()
+    const ticker = new Ticker(spy)
+
+    step(0)
+    expect(spy).not.toHaveBeenCalled()
+
+    step(5)
+    expect(spy).toHaveBeenCalledTimes(1)
+    expect(spy).toHaveBeenLastCalledWith(expect.any(Number))
+    expect(lastArg(spy)).toBeCloseTo(0.005, 6)
+
+    ticker.remove()
+  })
+})
+
+describe('capped mode via blur (debugMode=true -> 6fps)', () => {
+  it('accumulates lag and calls at fixed-step boundaries (avoid exact boundary)', async () => {
+    const Ticker = await loadTickerWithDebug(true)
+    jest.spyOn(document, 'hasFocus').mockReturnValue(true)
+
+    const spy = jest.fn()
+    const ticker = new Ticker(spy)
+
+    // Apply 6fps cap using blur (fixedStep ≈ 1/6 ≈ 0.1666667s)
+    window.dispatchEvent(new Event('blur'))
+
+    // 100 + 70 = 170ms -> crosses one boundary -> one call ≈ fixedStep
+    step(100)
+    step(70)
+    expect(spy).toHaveBeenCalledTimes(1)
+    expect(spy).toHaveBeenLastCalledWith(expect.any(Number))
+    expect(lastArg(spy)).toBeCloseTo(1 / 6, 6)
+
+    // Remaining lag ≈ 0.0033s
+    step(91) // still below another boundary
+    expect(spy).toHaveBeenCalledTimes(1)
+    step(80) // crosses again
+    expect(spy).toHaveBeenCalledTimes(2)
+    expect(spy).toHaveBeenLastCalledWith(expect.any(Number))
+    expect(lastArg(spy)).toBeCloseTo(1 / 6, 6)
+
+    ticker.remove()
+  })
+
+  it('long frame (delta >= 2*fixedStep) triggers two calls: fixedStep then raw delta; then lag resets', async () => {
+    const Ticker = await loadTickerWithDebug(true)
+    jest.spyOn(document, 'hasFocus').mockReturnValue(true)
+
+    const spy = jest.fn()
+    const ticker = new Ticker(spy)
+
+    window.dispatchEvent(new Event('blur')) // enable 6fps cap
+
+    // 500ms (0.5s) >= 2 * (1/6 ≈ 0.3333s)
+    step(500)
+    expect(spy).toHaveBeenCalledTimes(2)
+
+    expect(spy).toHaveBeenNthCalledWith(1, expect.any(Number))
+    expect(argOf(spy, 0)).toBeCloseTo(1 / 6, 6)
+
+    expect(spy).toHaveBeenNthCalledWith(2, expect.any(Number))
+    expect(argOf(spy, 1)).toBeCloseTo(0.5, 6)
+
+    // Repeat pattern
+    step(500)
+    expect(spy).toHaveBeenCalledTimes(4)
+
+    expect(spy).toHaveBeenNthCalledWith(3, expect.any(Number))
+    expect(argOf(spy, 2)).toBeCloseTo(1 / 6, 6)
+
+    expect(spy).toHaveBeenNthCalledWith(4, expect.any(Number))
+    expect(argOf(spy, 3)).toBeCloseTo(0.5, 6)
+
+    ticker.remove()
+  })
+})
+
+describe('runtime transitions via focus/pageshow (debugMode=true)', () => {
+  it('blur -> capped(6fps) / focus -> uncapped: after focus, raw delta behavior resumes', async () => {
+    const Ticker = await loadTickerWithDebug(true)
+    jest.spyOn(document, 'hasFocus').mockReturnValue(true)
+
+    const spy = jest.fn()
+    const ticker = new Ticker(spy)
+
+    // Enter capped mode and get one fixed-step call
+    window.dispatchEvent(new Event('blur'))
+    step(170)
+    expect(spy).toHaveBeenCalledTimes(1)
+    expect(spy).toHaveBeenLastCalledWith(expect.any(Number))
+    expect(lastArg(spy)).toBeCloseTo(1 / 6, 6)
+
+    // Back to uncapped
+    window.dispatchEvent(new Event('focus'))
+
+    spy.mockClear()
+    step(16)
+    step(33)
+    expect(spy).toHaveBeenCalledTimes(2)
+
+    expect(spy).toHaveBeenNthCalledWith(1, expect.any(Number))
+    expect(argOf(spy, 0)).toBeCloseTo(0.016, 6)
+
+    expect(spy).toHaveBeenNthCalledWith(2, expect.any(Number))
+    expect(argOf(spy, 1)).toBeCloseTo(0.033, 6)
+
+    ticker.remove()
+  })
+
+  it('pageshow(persisted=true) sets fpsCap to uncapped again', async () => {
+    const Ticker = await loadTickerWithDebug(true)
+    jest.spyOn(document, 'hasFocus').mockReturnValue(true)
+
+    const spy = jest.fn()
+    const ticker = new Ticker(spy)
+
+    window.dispatchEvent(new Event('blur'))
+    step(200) // > 1/6s => fixed-step call
+    expect(spy).toHaveBeenCalledTimes(1)
+    expect(spy).toHaveBeenLastCalledWith(expect.any(Number))
+    expect(lastArg(spy)).toBeCloseTo(1 / 6, 6)
+
+    // Create a pageshow event with persisted=true (jsdom lacks PageTransitionEvent)
+    const evt = new Event('pageshow') as Event & { persisted?: boolean }
+    Object.defineProperty(evt, 'persisted', { value: true })
+    window.dispatchEvent(evt)
+
+    spy.mockClear()
+    step(25)
+    step(40)
+    expect(spy).toHaveBeenCalledTimes(2)
+
+    expect(spy).toHaveBeenNthCalledWith(1, expect.any(Number))
+    expect(argOf(spy, 0)).toBeCloseTo(0.025, 6)
+
+    expect(spy).toHaveBeenNthCalledWith(2, expect.any(Number))
+    expect(argOf(spy, 1)).toBeCloseTo(0.040, 6)
+
+    ticker.remove()
+  })
+})
+
+describe('remove()', () => {
+  it('cancels next RAF and stops future ticks; also cleans up listeners', async () => {
+    const Ticker = await loadTickerWithDebug(true)
+
+    // Ensure the ticker starts in uncapped mode so the first small step triggers a tick.
+    jest.spyOn(document, 'hasFocus').mockReturnValue(true)
+
+    const spy = jest.fn()
+    const cancelSpy = jest.spyOn(window, 'cancelAnimationFrame')
+
+    const ticker = new Ticker(spy)
+
+    step(16) // ~0.016s -> should tick in uncapped mode
+    expect(spy).toHaveBeenCalledTimes(1)
+
+    ticker.remove()
+    expect(cancelSpy).toHaveBeenCalled()
+
+    spy.mockClear()
+    advance(200, 16)
+    expect(spy).not.toHaveBeenCalled()
+
+    // Listeners are cleaned up (dispatching events does nothing and does not throw)
+    expect(() => window.dispatchEvent(new Event('blur'))).not.toThrow()
+    expect(() => window.dispatchEvent(new Event('focus'))).not.toThrow()
+  })
+})
+
+describe('long-running sanity (ragged frames, capped=6fps)', () => {
+  it('produces a reasonable number of calls; includes fixedStep calls', async () => {
+    const Ticker = await loadTickerWithDebug(true)
+    jest.spyOn(document, 'hasFocus').mockReturnValue(true)
+
+    const spy = jest.fn()
+    const ticker = new Ticker(spy)
+
+    window.dispatchEvent(new Event('blur')) // 6fps -> fixedStep ≈ 0.1667
+
+    // Total ~1000ms with some long frames to trigger the split branch
+    const frames = [33, 33, 35, 201, 51, 61, 41, 201, 201, 251]
+    for (const ms of frames) step(ms)
+
+    const calls = spy.mock.calls.length
+    // With lag resets/rounding, tolerate a loose range
+    expect(calls).toBeGreaterThanOrEqual(5)
+    expect(calls).toBeLessThanOrEqual(9)
+
+    // At least one call should be exactly the fixed step (~1/6)
+    const hasFixedStep = spy.mock.calls.some(([dt]) => Math.abs((dt as number) - 1 / 6) < 1e-6)
+    expect(hasFixedStep).toBe(true)
+
+    ticker.remove()
+  })
+})

package/src/renderer/ticker.ts

@@ -0,0 +1,54 @@
+import { debugMode } from '../debug'
+
+export class Ticker {
+  #fpsCap?: number
+  #frameId = 0
+
+  constructor(onTick: (dt: number) => void) {
+    let prevTime = 0
+    let lagSeconds = 0
+
+    const step = (timestamp: number) => {
+      const dt = (timestamp - prevTime) / 1000
+      if (dt > 0) {
+        const fpsCap = this.#fpsCap
+        if (fpsCap !== undefined && fpsCap > 0) {
+          lagSeconds += dt
+          const fixedStep = 1 / fpsCap
+          if (lagSeconds >= fixedStep) {
+            onTick(fixedStep)
+            if (lagSeconds >= fixedStep * 2) { onTick(dt); lagSeconds = 0 }
+            else { lagSeconds -= fixedStep }
+          }
+        } else {
+          onTick(dt)
+        }
+        prevTime = timestamp
+      }
+      this.#frameId = requestAnimationFrame(step)
+    }
+    this.#frameId = requestAnimationFrame(step)
+
+    if (debugMode) {
+      if (!document.hasFocus()) this.#fpsCap = 6
+      window.addEventListener('blur', this.#blurListener)
+      window.addEventListener('focus', this.#focusListener)
+      window.addEventListener('pageshow', this.#pageshowListener)
+    }
+  }
+
+  #blurListener = () => { this.#fpsCap = 6 }
+  #focusListener = () => { this.#fpsCap = undefined }
+  #pageshowListener = (event: PageTransitionEvent) => {
+    if (event.persisted) {
+      this.#fpsCap = undefined
+    }
+  }
+
+  remove() {
+    cancelAnimationFrame(this.#frameId)
+    window.removeEventListener('blur', this.#blurListener)
+    window.removeEventListener('focus', this.#focusListener)
+    window.removeEventListener('pageshow', this.#pageshowListener)
+  }
+}

package/src/types/bitmap-font.ts

@@ -0,0 +1,19 @@
+import { Texture } from 'pixi.js'
+
+export type Char = {
+  x: number
+  y: number
+  width: number
+  height: number
+  xoffset: number
+  yoffset: number
+  xadvance: number
+}
+
+export type BitmapFont = {
+  src: string
+  chars: Record<number, Char>
+  texture: Texture
+  size: number
+  lineHeight: number
+}

package/src/utils/device.ts

@@ -0,0 +1 @@
+export const isMobile = /Android|iPhone|iPad|iPod/i.test(navigator.userAgent)

package/examples/test-dom/index.ts

@@ -1,21 +0,0 @@
-import { enableDebug, World, DomContainerObject } from '../../src';
-
-enableDebug();
-
-const world = new World({ width: 800, height: 600 });
-world.container.style.width = '100%';
-world.container.style.height = '100%';
-document.body.appendChild(world.container);
-
-const testEl = document.createElement('div');
-testEl.textContent = 'Hello World';
-testEl.style.color = 'red';
-testEl.onclick = () => alert('click');
-
-const go = new DomContainerObject({ el: testEl });
-go.alpha = 0.5;
-world.add(go);
-
-world.on('update', (dt) => {
-  go.rotation += dt;
-});