@jts-studios/web-game-engine 0.1.0

package/src/core/camera/CameraController.js

@@ -0,0 +1,119 @@
+export class CameraController {
+    constructor(camera, input, { moveSpeed = 500, zoomSpeed = 0.0015, minZoom = 0.15, maxZoom = 4 } = {}) {
+        this.camera = camera
+        this.input = input
+        this.moveSpeed = moveSpeed
+        this.zoomSpeed = zoomSpeed
+        this.minZoom = minZoom
+        this.maxZoom = maxZoom
+        this.followTarget = null
+        this.followSmoothing = 0.16
+        this.deadZone = { x: 36, y: 24 }
+        this.bounds = null
+    }
+
+    setFollowTarget(target) {
+        this.followTarget = target ?? null
+        return this
+    }
+
+    setFollowSmoothing(value) {
+        if (!Number.isFinite(value) || value <= 0) {
+            throw new TypeError("CameraController follow smoothing must be a positive number")
+        }
+
+        this.followSmoothing = value
+        return this
+    }
+
+    setDeadZone(width, height) {
+        if (!Number.isFinite(width) || width < 0 || !Number.isFinite(height) || height < 0) {
+            throw new TypeError("CameraController dead-zone dimensions must be non-negative numbers")
+        }
+
+        this.deadZone.x = width
+        this.deadZone.y = height
+        return this
+    }
+
+    setBounds(bounds = null) {
+        if (!bounds) {
+            this.bounds = null
+            return this
+        }
+
+        this.bounds = {
+            minX: Number.isFinite(bounds.minX) ? bounds.minX : -Infinity,
+            minY: Number.isFinite(bounds.minY) ? bounds.minY : -Infinity,
+            maxX: Number.isFinite(bounds.maxX) ? bounds.maxX : Infinity,
+            maxY: Number.isFinite(bounds.maxY) ? bounds.maxY : Infinity,
+        }
+        return this
+    }
+
+    update(deltaTime) {
+        const moveX = this.input.getAxis("KeyA", "KeyD") + this.input.getAxis("ArrowLeft", "ArrowRight")
+        const moveY = this.input.getAxis("KeyW", "KeyS") + this.input.getAxis("ArrowUp", "ArrowDown")
+
+        if (moveX !== 0 || moveY !== 0) {
+            const distance = (this.moveSpeed * deltaTime) / this.camera.zoom
+            this.camera.setPosition(this.camera.position.x + moveX * distance, this.camera.position.y + moveY * distance)
+        }
+
+        if (this.input.isPointerDragging()) {
+            const pointerDelta = this.input.consumePointerDelta()
+            this.camera.setPosition(
+                this.camera.position.x - pointerDelta.x / this.camera.zoom,
+                this.camera.position.y - pointerDelta.y / this.camera.zoom,
+            )
+        } else {
+            this.input.consumePointerDelta()
+        }
+
+        const wheelDelta = this.input.consumeWheelDelta()
+        if (wheelDelta !== 0) {
+            const targetZoom = this.camera.zoom * Math.exp(-wheelDelta * this.zoomSpeed)
+            const clampedZoom = Math.min(this.maxZoom, Math.max(this.minZoom, targetZoom))
+            this.camera.setZoom(clampedZoom)
+        }
+
+        this.#updateFollow(deltaTime)
+        this.#clampToBounds()
+    }
+
+    #updateFollow(deltaTime) {
+        const targetPosition = this.followTarget?.position
+        if (!targetPosition) {
+            return
+        }
+
+        const dx = targetPosition.x - this.camera.position.x
+        const dy = targetPosition.y - this.camera.position.y
+
+        const thresholdX = this.deadZone.x / this.camera.zoom
+        const thresholdY = this.deadZone.y / this.camera.zoom
+
+        const shouldMoveX = Math.abs(dx) > thresholdX
+        const shouldMoveY = Math.abs(dy) > thresholdY
+        if (!shouldMoveX && !shouldMoveY) {
+            return
+        }
+
+        const smoothing = 1 - Math.exp((-deltaTime * 60) / this.followSmoothing)
+        const nextX = shouldMoveX ? this.camera.position.x + dx * smoothing : this.camera.position.x
+        const nextY = shouldMoveY ? this.camera.position.y + dy * smoothing : this.camera.position.y
+        this.camera.setPosition(nextX, nextY)
+    }
+
+    #clampToBounds() {
+        if (!this.bounds) {
+            return
+        }
+
+        const clampedX = Math.min(this.bounds.maxX, Math.max(this.bounds.minX, this.camera.position.x))
+        const clampedY = Math.min(this.bounds.maxY, Math.max(this.bounds.minY, this.camera.position.y))
+        if (clampedX !== this.camera.position.x || clampedY !== this.camera.position.y) {
+            this.camera.setPosition(clampedX, clampedY)
+        }
+    }
+}

package/src/core/input/InputController.js

@@ -0,0 +1,207 @@
+export class InputController {
+    constructor({ element = null } = {}) {
+        this.element = element
+        this._keys = new Set()
+        this._wheelDelta = 0
+        this._dragging = false
+        this._pointerDeltaX = 0
+        this._pointerDeltaY = 0
+        this._lastPointerX = 0
+        this._lastPointerY = 0
+        this._actionProfile = null
+
+        this._onKeyDown = this.#onKeyDown.bind(this)
+        this._onKeyUp = this.#onKeyUp.bind(this)
+        this._onBlur = this.#onBlur.bind(this)
+        this._onWheel = this.#onWheel.bind(this)
+        this._onPointerDown = this.#onPointerDown.bind(this)
+        this._onPointerMove = this.#onPointerMove.bind(this)
+        this._onPointerUp = this.#onPointerUp.bind(this)
+    }
+
+    attach() {
+        window.addEventListener("keydown", this._onKeyDown)
+        window.addEventListener("keyup", this._onKeyUp)
+        window.addEventListener("blur", this._onBlur)
+        window.addEventListener("wheel", this._onWheel, { passive: false })
+
+        const target = this.element ?? window
+        target.addEventListener("pointerdown", this._onPointerDown)
+        window.addEventListener("pointermove", this._onPointerMove)
+        window.addEventListener("pointerup", this._onPointerUp)
+    }
+
+    detach() {
+        window.removeEventListener("keydown", this._onKeyDown)
+        window.removeEventListener("keyup", this._onKeyUp)
+        window.removeEventListener("blur", this._onBlur)
+        window.removeEventListener("wheel", this._onWheel)
+
+        const target = this.element ?? window
+        target.removeEventListener("pointerdown", this._onPointerDown)
+        window.removeEventListener("pointermove", this._onPointerMove)
+        window.removeEventListener("pointerup", this._onPointerUp)
+
+        this._keys.clear()
+        this._wheelDelta = 0
+        this._dragging = false
+        this._pointerDeltaX = 0
+        this._pointerDeltaY = 0
+    }
+
+    isKeyDown(code) {
+        return this._keys.has(code)
+    }
+
+    getAxis(negativeCode, positiveCode) {
+        const negative = this.isKeyDown(negativeCode) ? -1 : 0
+        const positive = this.isKeyDown(positiveCode) ? 1 : 0
+        return negative + positive
+    }
+
+    consumeWheelDelta() {
+        const delta = this._wheelDelta
+        this._wheelDelta = 0
+        return delta
+    }
+
+    consumePointerDelta() {
+        const deltaX = this._pointerDeltaX
+        const deltaY = this._pointerDeltaY
+        this._pointerDeltaX = 0
+        this._pointerDeltaY = 0
+        return { x: deltaX, y: deltaY }
+    }
+
+    isPointerDragging() {
+        return this._dragging
+    }
+
+    captureSnapshot() {
+        return {
+            keys: Array.from(this._keys),
+            pointerX: this._pointerX,
+            pointerY: this._pointerY,
+            pointerDeltaX: this._pointerDeltaX,
+            pointerDeltaY: this._pointerDeltaY,
+            dragging: this._dragging,
+        }
+    }
+
+    applySnapshot(snapshot) {
+        if (!snapshot || typeof snapshot !== "object") {
+            return this
+        }
+
+        this._keys.clear()
+        const keys = Array.isArray(snapshot.keys) ? snapshot.keys : []
+        for (let i = 0; i < keys.length; i++) {
+            if (typeof keys[i] === "string") {
+                this._keys.add(keys[i])
+            }
+        }
+
+        this._pointerX = Number.isFinite(snapshot.pointerX) ? snapshot.pointerX : this._pointerX
+        this._pointerY = Number.isFinite(snapshot.pointerY) ? snapshot.pointerY : this._pointerY
+        this._pointerDeltaX = Number.isFinite(snapshot.pointerDeltaX) ? snapshot.pointerDeltaX : this._pointerDeltaX
+        this._pointerDeltaY = Number.isFinite(snapshot.pointerDeltaY) ? snapshot.pointerDeltaY : this._pointerDeltaY
+        this._dragging = !!snapshot.dragging
+        return this
+    }
+
+    applyProfile(profile) {
+        this._actionProfile = profile && typeof profile === "object" ? JSON.parse(JSON.stringify(profile)) : null
+        return this
+    }
+
+    clearProfile() {
+        this._actionProfile = null
+        return this
+    }
+
+    isActionDown(actionName) {
+        if (!this._actionProfile || typeof actionName !== "string") {
+            return false
+        }
+
+        const bindings = this._actionProfile[actionName]
+        if (!Array.isArray(bindings)) {
+            return false
+        }
+
+        for (let i = 0; i < bindings.length; i++) {
+            const binding = bindings[i]
+            if (!binding || typeof binding !== "object") {
+                continue
+            }
+
+            if (binding.type === "keyboard") {
+                if (Array.isArray(binding.chord) && binding.chord.length > 0) {
+                    let chordPressed = true
+                    for (let c = 0; c < binding.chord.length; c++) {
+                        if (!this.isKeyDown(binding.chord[c])) {
+                            chordPressed = false
+                            break
+                        }
+                    }
+                    if (chordPressed) {
+                        return true
+                    }
+                    continue
+                }
+
+                if (typeof binding.code === "string" && this.isKeyDown(binding.code)) {
+                    return true
+                }
+            }
+        }
+
+        return false
+    }
+
+    #onKeyDown(event) {
+        this._keys.add(event.code)
+    }
+
+    #onKeyUp(event) {
+        this._keys.delete(event.code)
+    }
+
+    #onBlur() {
+        this._keys.clear()
+        this._dragging = false
+        this._wheelDelta = 0
+        this._pointerDeltaX = 0
+        this._pointerDeltaY = 0
+    }
+
+    #onWheel(event) {
+        this._wheelDelta += event.deltaY
+        event.preventDefault()
+    }
+
+    #onPointerDown(event) {
+        if (event.button !== 1 && event.button !== 0) {
+            return
+        }
+
+        this._dragging = true
+        this._lastPointerX = event.clientX
+        this._lastPointerY = event.clientY
+    }
+
+    #onPointerMove(event) {
+        if (!this._dragging) {
+            return
+        }
+
+        this._pointerDeltaX += event.clientX - this._lastPointerX
+        this._pointerDeltaY += event.clientY - this._lastPointerY
+        this._lastPointerX = event.clientX
+        this._lastPointerY = event.clientY
+    }
+
+    #onPointerUp() {
+        this._dragging = false
+    }
+}

package/src/core/input/InputProfileCatalog.js

@@ -0,0 +1,29 @@
+/**
+ * Stores named input action profiles for gameplay integration.
+ */
+export class InputProfileCatalog {
+    constructor() {
+        this._profiles = new Map()
+    }
+
+    define(name, profile) {
+        if (typeof name !== "string" || name.length === 0) {
+            throw new TypeError("InputProfileCatalog.define requires a non-empty profile name")
+        }
+        if (!profile || typeof profile !== "object") {
+            throw new TypeError("InputProfileCatalog.define requires a profile object")
+        }
+
+        this._profiles.set(name, JSON.parse(JSON.stringify(profile)))
+        return this
+    }
+
+    get(name) {
+        const profile = this._profiles.get(name)
+        return profile ? JSON.parse(JSON.stringify(profile)) : null
+    }
+
+    list() {
+        return Array.from(this._profiles.keys())
+    }
+}

package/src/core/loop/FixedStepClock.js

@@ -0,0 +1,30 @@
+export class FixedStepClock {
+    constructor({ fixedDelta = 1 / 60, maxSubSteps = 8 } = {}) {
+        this.fixedDelta = Number.isFinite(fixedDelta) && fixedDelta > 0 ? fixedDelta : 1 / 60
+        this.maxSubSteps = Number.isFinite(maxSubSteps) ? Math.max(1, Math.floor(maxSubSteps)) : 8
+        this.accumulator = 0
+    }
+
+    reset() {
+        this.accumulator = 0
+    }
+
+    consume(deltaSeconds) {
+        const safeDelta = Number.isFinite(deltaSeconds) ? Math.max(0, deltaSeconds) : 0
+        this.accumulator += safeDelta
+
+        const steps = []
+        let subSteps = 0
+        while (this.accumulator >= this.fixedDelta && subSteps < this.maxSubSteps) {
+            steps.push(this.fixedDelta)
+            this.accumulator -= this.fixedDelta
+            subSteps += 1
+        }
+
+        const alpha = this.fixedDelta > 0 ? Math.min(1, this.accumulator / this.fixedDelta) : 0
+        return {
+            steps,
+            alpha,
+        }
+    }
+}

package/src/core/loop/InputReplayTimeline.js

@@ -0,0 +1,155 @@
+export class InputReplayTimeline {
+    constructor() {
+        this._events = []
+        this._recording = false
+        this._playing = false
+        this._cursor = 0
+        this._elapsed = 0
+    }
+
+    clear() {
+        this._events.length = 0
+        this._cursor = 0
+        this._elapsed = 0
+        return this
+    }
+
+    startRecording() {
+        this.clear()
+        this._recording = true
+        this._playing = false
+        return this
+    }
+
+    stopRecording() {
+        this._recording = false
+        return this.toJSON()
+    }
+
+    startPlayback(events = this._events) {
+        this._events = Array.isArray(events) ? events.map((entry) => ({ ...entry })) : []
+        this._events.sort((a, b) => (a.time ?? 0) - (b.time ?? 0))
+        this._recording = false
+        this._playing = true
+        this._cursor = 0
+        this._elapsed = 0
+        return this
+    }
+
+    stopPlayback() {
+        this._playing = false
+        this._cursor = 0
+        this._elapsed = 0
+        return this
+    }
+
+    record(deltaTime, snapshot, { checkpoint = false } = {}) {
+        if (!this._recording) {
+            return
+        }
+
+        this._elapsed += Number.isFinite(deltaTime) ? Math.max(0, deltaTime) : 0
+        const clonedSnapshot = snapshot && typeof snapshot === "object" ? JSON.parse(JSON.stringify(snapshot)) : null
+        this._events.push({
+            time: this._elapsed,
+            snapshot: clonedSnapshot,
+            hash: this.#hashSnapshot(clonedSnapshot),
+            checkpoint: !!checkpoint,
+        })
+    }
+
+    consume(deltaTime) {
+        if (!this._playing) {
+            return []
+        }
+
+        this._elapsed += Number.isFinite(deltaTime) ? Math.max(0, deltaTime) : 0
+        const emitted = []
+        while (this._cursor < this._events.length) {
+            const event = this._events[this._cursor]
+            if ((event?.time ?? 0) > this._elapsed) {
+                break
+            }
+            emitted.push(event)
+            this._cursor += 1
+        }
+
+        if (this._cursor >= this._events.length) {
+            this._playing = false
+        }
+
+        return emitted
+    }
+
+    toJSON() {
+        return this._events.map((entry) => ({
+            time: entry.time,
+            snapshot: entry.snapshot,
+            hash: entry.hash,
+            checkpoint: !!entry.checkpoint,
+        }))
+    }
+
+    validate(events = this._events) {
+        const list = Array.isArray(events) ? events : []
+        for (let i = 0; i < list.length; i++) {
+            const entry = list[i]
+            const expected = this.#hashSnapshot(entry?.snapshot ?? null)
+            if (typeof entry?.hash === "string" && entry.hash !== expected) {
+                return {
+                    valid: false,
+                    index: i,
+                    expected,
+                    actual: entry.hash,
+                }
+            }
+        }
+
+        return {
+            valid: true,
+            count: list.length,
+        }
+    }
+
+    compareWith(otherEvents) {
+        const a = this.toJSON()
+        const b = Array.isArray(otherEvents) ? otherEvents : []
+        const max = Math.max(a.length, b.length)
+        for (let i = 0; i < max; i++) {
+            const left = a[i]
+            const right = b[i]
+            if (!left || !right) {
+                return {
+                    equal: false,
+                    index: i,
+                    reason: "length-mismatch",
+                }
+            }
+
+            if (left.hash !== right.hash) {
+                return {
+                    equal: false,
+                    index: i,
+                    reason: "hash-mismatch",
+                    left: left.hash,
+                    right: right.hash,
+                }
+            }
+        }
+
+        return {
+            equal: true,
+            count: a.length,
+        }
+    }
+
+    #hashSnapshot(snapshot) {
+        const input = JSON.stringify(snapshot ?? null)
+        let hash = 2166136261
+        for (let i = 0; i < input.length; i++) {
+            hash ^= input.charCodeAt(i)
+            hash = Math.imul(hash, 16777619)
+        }
+        return `fnv1a-${(hash >>> 0).toString(16)}`
+    }
+}

package/src/core/loop/InputReplayTimeline.test.js

@@ -0,0 +1,43 @@
+import test from "node:test"
+import assert from "node:assert/strict"
+
+import { InputReplayTimeline } from "./InputReplayTimeline.js"
+
+test("InputReplayTimeline records hashes and validates deterministic payloads", () => {
+    const replay = new InputReplayTimeline()
+    replay.startRecording()
+    replay.record(1 / 60, { actions: { jump: true } }, { checkpoint: true })
+    const events = replay.stopRecording()
+
+    assert.equal(events.length, 1)
+    assert.equal(typeof events[0].hash, "string")
+    assert.equal(events[0].hash.startsWith("fnv1a-"), true)
+    assert.equal(events[0].checkpoint, true)
+
+    const diagnostics = replay.validate(events)
+    assert.equal(diagnostics.valid, true)
+})
+
+test("InputReplayTimeline validate detects tampered snapshots", () => {
+    const replay = new InputReplayTimeline()
+    replay.startRecording()
+    replay.record(1 / 60, { actions: { fire: false } })
+    const events = replay.stopRecording()
+    events[0].snapshot.actions.fire = true
+
+    const diagnostics = replay.validate(events)
+    assert.equal(diagnostics.valid, false)
+    assert.equal(diagnostics.index, 0)
+})
+
+test("InputReplayTimeline compareWith detects divergence", () => {
+    const replay = new InputReplayTimeline()
+    replay.startRecording()
+    replay.record(1 / 60, { actions: { left: true } })
+    const baseline = replay.stopRecording()
+
+    const modified = baseline.map((entry) => ({ ...entry, hash: `${entry.hash}-changed` }))
+    const comparison = replay.compareWith(modified)
+    assert.equal(comparison.equal, false)
+    assert.equal(comparison.reason, "hash-mismatch")
+})

package/src/core/loop/UpdateLoop.js

@@ -0,0 +1,28 @@
+export class UpdateLoop {
+    constructor() {
+        this._updatables = new Set()
+    }
+
+    add(updatable) {
+        if (!updatable || typeof updatable.update !== "function") {
+            throw new TypeError("UpdateLoop.add requires an object with update(deltaTime)")
+        }
+
+        this._updatables.add(updatable)
+        return updatable
+    }
+
+    remove(updatable) {
+        this._updatables.delete(updatable)
+    }
+
+    clear() {
+        this._updatables.clear()
+    }
+
+    update(deltaTime) {
+        for (const updatable of this._updatables) {
+            updatable.update(deltaTime)
+        }
+    }
+}

package/src/core/runtime/RuntimeBridge.js

@@ -0,0 +1,54 @@
+export class RuntimeBridge {
+    constructor() {
+        this._eventListeners = new Set()
+        this._commandHandlers = new Map()
+    }
+
+    onEvent(listener) {
+        if (typeof listener !== "function") {
+            return () => {}
+        }
+        this._eventListeners.add(listener)
+        return () => this._eventListeners.delete(listener)
+    }
+
+    emit(type, payload = null) {
+        if (typeof type !== "string" || type.length === 0) {
+            return
+        }
+
+        const event = {
+            type,
+            payload,
+            time: Date.now(),
+        }
+
+        for (const listener of this._eventListeners) {
+            try {
+                listener(event)
+            } catch {
+                // Bridge listeners are isolated from runtime execution.
+            }
+        }
+    }
+
+    registerCommand(commandName, handler) {
+        if (typeof commandName !== "string" || commandName.length === 0) {
+            throw new TypeError("RuntimeBridge.registerCommand requires a non-empty commandName")
+        }
+        if (typeof handler !== "function") {
+            throw new TypeError("RuntimeBridge.registerCommand requires a handler function")
+        }
+
+        this._commandHandlers.set(commandName, handler)
+        return this
+    }
+
+    async execute(commandName, payload = null, context = null) {
+        const handler = this._commandHandlers.get(commandName)
+        if (!handler) {
+            throw new Error(`RuntimeBridge.execute unknown command '${commandName}'`)
+        }
+        return await handler(payload, context)
+    }
+}

package/src/core/runtime/RuntimeBridge.test.js

@@ -0,0 +1,25 @@
+import test from "node:test"
+import assert from "node:assert/strict"
+
+import { RuntimeBridge } from "./RuntimeBridge.js"
+
+test("RuntimeBridge emits events to listeners", () => {
+    const bridge = new RuntimeBridge()
+    const events = []
+    const off = bridge.onEvent((event) => events.push(event))
+
+    bridge.emit("runtime:init", { ok: true })
+    off()
+    bridge.emit("runtime:update", { dt: 0.016 })
+
+    assert.equal(events.length, 1)
+    assert.equal(events[0].type, "runtime:init")
+})
+
+test("RuntimeBridge executes registered commands", async () => {
+    const bridge = new RuntimeBridge()
+    bridge.registerCommand("echo", async (payload) => payload)
+
+    const response = await bridge.execute("echo", { value: 42 })
+    assert.deepEqual(response, { value: 42 })
+})