@jts-studios/web-game-engine 0.1.0

package/src/core/state/AssetManifestLoader.js

@@ -0,0 +1,83 @@
+/**
+ * Resolves scene serializer asset manifests and optionally preloads URL assets.
+ */
+export class AssetManifestLoader {
+    resolve(manifest, { resolveTextureHandle = null } = {}) {
+        const textures = Array.isArray(manifest?.textures) ? manifest.textures : []
+        const resolved = []
+        const unresolved = []
+
+        for (let i = 0; i < textures.length; i++) {
+            const handle = textures[i]
+            if (!handle || typeof handle !== "object") {
+                continue
+            }
+
+            let url = null
+            if (handle.kind === "url" && typeof handle.value === "string") {
+                url = handle.value
+            } else if (typeof resolveTextureHandle === "function") {
+                url = resolveTextureHandle(handle) ?? null
+            }
+
+            if (typeof url === "string" && url.length > 0) {
+                resolved.push({ handle, url })
+            } else {
+                unresolved.push(handle)
+            }
+        }
+
+        return {
+            resolved,
+            unresolved,
+            total: textures.length,
+        }
+    }
+
+    async preloadUrls(urls, { onProgress = null, signal = null } = {}) {
+        const queue = Array.isArray(urls) ? urls.filter((url) => typeof url === "string" && url.length > 0) : []
+        let loaded = 0
+        const failed = []
+
+        for (let i = 0; i < queue.length; i++) {
+            if (signal?.aborted) {
+                return {
+                    status: "aborted",
+                    loaded,
+                    failed,
+                    total: queue.length,
+                }
+            }
+
+            const url = queue[i]
+            try {
+                const response = await fetch(url, {
+                    method: "GET",
+                    cache: "force-cache",
+                    signal: signal ?? undefined,
+                })
+                if (!response.ok) {
+                    failed.push({ url, status: response.status })
+                } else {
+                    loaded += 1
+                }
+            } catch (_error) {
+                failed.push({ url, status: 0 })
+            }
+
+            onProgress?.({
+                loaded,
+                total: queue.length,
+                failed: failed.length,
+                current: url,
+            })
+        }
+
+        return {
+            status: "ready",
+            loaded,
+            failed,
+            total: queue.length,
+        }
+    }
+}

package/src/core/state/AssetManifestLoader.test.js

@@ -0,0 +1,59 @@
+import test from "node:test"
+import assert from "node:assert/strict"
+
+import { AssetManifestLoader } from "./AssetManifestLoader.js"
+
+test("AssetManifestLoader resolves urls and unresolved handles", () => {
+    const loader = new AssetManifestLoader()
+    const result = loader.resolve(
+        {
+            textures: [
+                { kind: "url", value: "a.png" },
+                { kind: "asset", id: "hero" },
+                { kind: "asset", id: "missing" },
+            ],
+        },
+        {
+            resolveTextureHandle(handle) {
+                if (handle?.id === "hero") {
+                    return "hero.png"
+                }
+                return null
+            },
+        },
+    )
+
+    assert.equal(result.total, 3)
+    assert.equal(result.resolved.length, 2)
+    assert.equal(result.unresolved.length, 1)
+    assert.equal(result.resolved[0].url, "a.png")
+    assert.equal(result.resolved[1].url, "hero.png")
+})
+
+test("AssetManifestLoader preloadUrls reports failures and progress", async () => {
+    const loader = new AssetManifestLoader()
+    const progress = []
+
+    const originalFetch = globalThis.fetch
+    globalThis.fetch = async (url) => {
+        if (url === "ok.png") {
+            return { ok: true, status: 200 }
+        }
+        return { ok: false, status: 404 }
+    }
+
+    try {
+        const result = await loader.preloadUrls(["ok.png", "bad.png"], {
+            onProgress(entry) {
+                progress.push(entry)
+            },
+        })
+
+        assert.equal(result.status, "ready")
+        assert.equal(result.loaded, 1)
+        assert.equal(result.failed.length, 1)
+        assert.equal(progress.length, 2)
+    } finally {
+        globalThis.fetch = originalFetch
+    }
+})

package/src/core/state/SceneManager.js

@@ -0,0 +1,60 @@
+export class SceneManager {
+    constructor() {
+        this._states = new Map()
+        this._activeStateName = ""
+        this._activeState = null
+        this._inlineScene = null
+    }
+
+    registerState(name, state) {
+        if (typeof name !== "string" || name.length === 0) {
+            throw new TypeError("SceneManager.registerState requires a non-empty state name")
+        }
+        if (!state || typeof state !== "object") {
+            throw new TypeError("SceneManager.registerState requires a state object")
+        }
+
+        this._states.set(name, {
+            scene: state.scene ?? null,
+            onEnter: typeof state.onEnter === "function" ? state.onEnter : null,
+            onExit: typeof state.onExit === "function" ? state.onExit : null,
+            onUpdate: typeof state.onUpdate === "function" ? state.onUpdate : null,
+        })
+    }
+
+    setState(name, context = null) {
+        if (this._activeState?.onExit) {
+            this._activeState.onExit(context)
+        }
+
+        const state = this._states.get(name)
+        if (!state) {
+            throw new Error(`Scene state not found: ${name}`)
+        }
+
+        this._activeStateName = name
+        this._activeState = state
+
+        if (state.onEnter) {
+            state.onEnter(context)
+        }
+    }
+
+    setScene(scene) {
+        this._inlineScene = scene
+    }
+
+    update(deltaTime) {
+        if (this._activeState?.onUpdate) {
+            this._activeState.onUpdate(deltaTime)
+        }
+    }
+
+    getActiveScene() {
+        return this._activeState?.scene ?? this._inlineScene
+    }
+
+    getActiveStateName() {
+        return this._activeStateName
+    }
+}

package/src/core/state/SceneSnapshotStore.js

@@ -0,0 +1,98 @@
+import { SceneSerializer } from "@jts-studios/engine"
+
+/**
+ * Gameplay-layer scene snapshot store backed by renderer-scene serialization.
+ */
+export class SceneSnapshotStore {
+    constructor() {
+        this._snapshots = new Map()
+    }
+
+    save(name, scene) {
+        if (typeof name !== "string" || name.length === 0) {
+            throw new TypeError("SceneSnapshotStore.save requires a non-empty snapshot name")
+        }
+        const snapshot = SceneSerializer.serialize(scene)
+        const validation = SceneSerializer.validate(snapshot)
+        if (!validation.valid) {
+            throw new Error(`SceneSnapshotStore.save rejected invalid snapshot: ${validation.errors.join("; ")}`)
+        }
+        this._snapshots.set(name, snapshot)
+    }
+
+    load(name) {
+        const snapshot = this._snapshots.get(name)
+        if (!snapshot) {
+            return null
+        }
+        return SceneSerializer.deserialize(snapshot)
+    }
+
+    has(name) {
+        return this._snapshots.has(name)
+    }
+
+    validate(name, options = {}) {
+        const snapshot = this._snapshots.get(name)
+        if (!snapshot) {
+            return {
+                valid: false,
+                strict: !!options.strict,
+                errors: ["snapshot not found"],
+                warnings: [],
+                objectCount: 0,
+            }
+        }
+        return SceneSerializer.validate(snapshot, options)
+    }
+
+    getAssetManifest(name) {
+        const snapshot = this._snapshots.get(name)
+        if (!snapshot) {
+            return null
+        }
+        return SceneSerializer.extractAssetManifest(snapshot)
+    }
+
+    createPreloadPlan(name, { resolveTextureHandle = null } = {}) {
+        const manifest = this.getAssetManifest(name)
+        if (!manifest) {
+            return {
+                urls: [],
+                unresolved: [],
+                total: 0,
+            }
+        }
+
+        const urls = []
+        const unresolved = []
+        const textures = Array.isArray(manifest.textures) ? manifest.textures : []
+        for (let i = 0; i < textures.length; i++) {
+            const handle = textures[i]
+            if (handle?.kind === "url" && typeof handle.value === "string" && handle.value.length > 0) {
+                urls.push(handle.value)
+                continue
+            }
+
+            if (typeof resolveTextureHandle === "function") {
+                const resolved = resolveTextureHandle(handle)
+                if (typeof resolved === "string" && resolved.length > 0) {
+                    urls.push(resolved)
+                    continue
+                }
+            }
+
+            unresolved.push(handle)
+        }
+
+        return {
+            urls,
+            unresolved,
+            total: textures.length,
+        }
+    }
+
+    list() {
+        return Array.from(this._snapshots.keys())
+    }
+}

package/src/index.d.ts

@@ -0,0 +1,27 @@
+export type PluginCapability = "render-hooks" | "update-hooks" | "scene-state" | "input-profile"
+
+export interface GameRuntimePlugin {
+    name?: string
+    apiVersion?: number
+    capabilities?: PluginCapability[]
+    dependencies?: string[]
+    priority?: number
+    enabled?: boolean
+    onInit?(runtime: unknown): void | Promise<void>
+    onUpdate?(runtime: unknown, deltaTime: number): void | Promise<void>
+    onRender?(runtime: unknown, alpha: number): void | Promise<void>
+    onDestroy?(runtime: unknown): void | Promise<void>
+}
+
+export interface RuntimeBridgeEvent {
+    type: string
+    payload?: unknown
+    time: number
+}
+
+export declare class RuntimeBridge {
+    onEvent(listener: (event: RuntimeBridgeEvent) => void): () => void
+    emit(type: string, payload?: unknown): void
+    registerCommand(commandName: string, handler: (payload: unknown, context: unknown) => unknown): this
+    execute(commandName: string, payload?: unknown, context?: unknown): Promise<unknown>
+}

package/src/index.js

@@ -0,0 +1,11 @@
+export { CameraController } from "./core/camera/CameraController.js"
+export { InputController } from "./core/input/InputController.js"
+export { InputProfileCatalog } from "./core/input/InputProfileCatalog.js"
+export { UpdateLoop } from "./core/loop/UpdateLoop.js"
+export { FixedStepClock } from "./core/loop/FixedStepClock.js"
+export { InputReplayTimeline } from "./core/loop/InputReplayTimeline.js"
+export { RuntimeBridge } from "./core/runtime/RuntimeBridge.js"
+export { SceneManager } from "./core/state/SceneManager.js"
+export { SceneSnapshotStore } from "./core/state/SceneSnapshotStore.js"
+export { AssetManifestLoader } from "./core/state/AssetManifestLoader.js"
+export { GameRuntime } from "./adapters/runtime/GameRuntime.js"

package/src/main.js

@@ -0,0 +1,213 @@
+import { GameRuntime } from "./index.js"
+import { createBootstrapScene } from "./scenes/createBootstrapScene.js"
+
+function createDebugPanel(app) {
+    const panel = document.createElement("aside")
+    panel.style.position = "fixed"
+    panel.style.left = "14px"
+    panel.style.top = "14px"
+    panel.style.width = "320px"
+    panel.style.padding = "12px"
+    panel.style.border = "1px solid rgba(255, 255, 255, 0.18)"
+    panel.style.borderRadius = "10px"
+    panel.style.background = "rgba(8, 12, 28, 0.84)"
+    panel.style.backdropFilter = "blur(6px)"
+    panel.style.color = "#dfe9ff"
+    panel.style.font = "12px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
+    panel.style.zIndex = "1000"
+    panel.style.display = "grid"
+    panel.style.gap = "8px"
+
+    const title = document.createElement("div")
+    title.textContent = "Web Game Engine Debug"
+    title.style.fontWeight = "700"
+    title.style.letterSpacing = "0.04em"
+    panel.appendChild(title)
+
+    const snapshotRow = document.createElement("div")
+    snapshotRow.style.display = "grid"
+    snapshotRow.style.gridTemplateColumns = "1fr auto"
+    snapshotRow.style.gap = "6px"
+
+    const snapshotInput = document.createElement("input")
+    snapshotInput.type = "text"
+    snapshotInput.value = "bootstrap-initial"
+    snapshotInput.placeholder = "snapshot name"
+    snapshotInput.style.padding = "6px"
+    snapshotInput.style.background = "rgba(255,255,255,0.08)"
+    snapshotInput.style.border = "1px solid rgba(255,255,255,0.2)"
+    snapshotInput.style.borderRadius = "6px"
+    snapshotInput.style.color = "#fff"
+
+    const snapshotSaveButton = document.createElement("button")
+    snapshotSaveButton.type = "button"
+    snapshotSaveButton.textContent = "Save"
+    snapshotSaveButton.style.padding = "6px 10px"
+    snapshotSaveButton.style.cursor = "pointer"
+
+    snapshotRow.append(snapshotInput, snapshotSaveButton)
+    panel.appendChild(snapshotRow)
+
+    const snapshotControls = document.createElement("div")
+    snapshotControls.style.display = "grid"
+    snapshotControls.style.gridTemplateColumns = "1fr auto"
+    snapshotControls.style.gap = "6px"
+
+    const snapshotSelect = document.createElement("select")
+    snapshotSelect.style.padding = "6px"
+    snapshotSelect.style.background = "rgba(255,255,255,0.08)"
+    snapshotSelect.style.border = "1px solid rgba(255,255,255,0.2)"
+    snapshotSelect.style.borderRadius = "6px"
+    snapshotSelect.style.color = "#fff"
+
+    const snapshotLoadButton = document.createElement("button")
+    snapshotLoadButton.type = "button"
+    snapshotLoadButton.textContent = "Load"
+    snapshotLoadButton.style.padding = "6px 10px"
+    snapshotLoadButton.style.cursor = "pointer"
+
+    snapshotControls.append(snapshotSelect, snapshotLoadButton)
+    panel.appendChild(snapshotControls)
+
+    const profileRow = document.createElement("div")
+    profileRow.style.display = "grid"
+    profileRow.style.gridTemplateColumns = "1fr auto"
+    profileRow.style.gap = "6px"
+
+    const profileSelect = document.createElement("select")
+    profileSelect.style.padding = "6px"
+    profileSelect.style.background = "rgba(255,255,255,0.08)"
+    profileSelect.style.border = "1px solid rgba(255,255,255,0.2)"
+    profileSelect.style.borderRadius = "6px"
+    profileSelect.style.color = "#fff"
+
+    const profileCopyButton = document.createElement("button")
+    profileCopyButton.type = "button"
+    profileCopyButton.textContent = "Copy JSON"
+    profileCopyButton.style.padding = "6px 10px"
+    profileCopyButton.style.cursor = "pointer"
+
+    profileRow.append(profileSelect, profileCopyButton)
+    panel.appendChild(profileRow)
+
+    const info = document.createElement("pre")
+    info.style.margin = "0"
+    info.style.padding = "8px"
+    info.style.maxHeight = "170px"
+    info.style.overflow = "auto"
+    info.style.whiteSpace = "pre-wrap"
+    info.style.background = "rgba(255,255,255,0.05)"
+    info.style.borderRadius = "6px"
+    panel.appendChild(info)
+
+    const refreshUI = () => {
+        const snapshots = app.listSceneSnapshots()
+        const currentSnapshot = snapshotSelect.value
+        snapshotSelect.innerHTML = ""
+        for (let i = 0; i < snapshots.length; i++) {
+            const option = document.createElement("option")
+            option.value = snapshots[i]
+            option.textContent = snapshots[i]
+            snapshotSelect.appendChild(option)
+        }
+        if (snapshots.includes(currentSnapshot)) {
+            snapshotSelect.value = currentSnapshot
+        }
+
+        const profiles = app.listInputProfiles()
+        const currentProfile = profileSelect.value
+        profileSelect.innerHTML = ""
+        for (let i = 0; i < profiles.length; i++) {
+            const option = document.createElement("option")
+            option.value = profiles[i]
+            option.textContent = profiles[i]
+            profileSelect.appendChild(option)
+        }
+        if (profiles.includes(currentProfile)) {
+            profileSelect.value = currentProfile
+        }
+
+        const profile = profileSelect.value ? app.getInputProfile(profileSelect.value) : null
+        info.textContent = JSON.stringify(
+            {
+                snapshots,
+                profiles,
+                selectedProfile: profileSelect.value || null,
+                selectedProfileData: profile,
+                hint: "Save/Load snapshots + inspect input profiles",
+            },
+            null,
+            2,
+        )
+    }
+
+    snapshotSaveButton.addEventListener("click", () => {
+        const name = snapshotInput.value.trim()
+        if (!name) {
+            return
+        }
+        app.saveSceneSnapshot(name)
+        refreshUI()
+    })
+
+    snapshotLoadButton.addEventListener("click", () => {
+        const selected = snapshotSelect.value
+        if (!selected) {
+            return
+        }
+        app.loadSceneSnapshot(selected)
+    })
+
+    profileCopyButton.addEventListener("click", async () => {
+        const selected = profileSelect.value
+        if (!selected) {
+            return
+        }
+        const profile = app.getInputProfile(selected)
+        if (!profile) {
+            return
+        }
+
+        const text = JSON.stringify(profile, null, 2)
+        try {
+            await navigator.clipboard.writeText(text)
+        } catch {
+            // Clipboard API can be unavailable depending on browser permissions.
+        }
+        refreshUI()
+    })
+
+    profileSelect.addEventListener("change", refreshUI)
+    snapshotSelect.addEventListener("change", refreshUI)
+
+    refreshUI()
+    document.body.appendChild(panel)
+}
+
+async function boot() {
+    const canvas = document.getElementById("gpu-canvas")
+    const app = new GameRuntime({ canvas })
+    await app.init()
+    app.registerState("bootstrap", {
+        scene: createBootstrapScene(),
+    })
+    app.setState("bootstrap")
+
+    app.defineInputProfile("default", {
+        moveLeft: [{ type: "keyboard", code: "KeyA" }],
+        moveRight: [{ type: "keyboard", code: "KeyD" }],
+    })
+    app.defineInputProfile("camera-pan", {
+        pan: [{ type: "keyboard", chord: ["ShiftLeft", "Space"] }],
+        zoomIn: [{ type: "keyboard", code: "KeyQ" }],
+        zoomOut: [{ type: "keyboard", code: "KeyE" }],
+    })
+    app.saveSceneSnapshot("bootstrap-initial")
+    createDebugPanel(app)
+
+    app.start()
+}
+
+boot().catch((error) => {
+    console.error(error)
+})

package/src/scenes/createBootstrapScene.js

@@ -0,0 +1,17 @@
+import { ColorRGBA, Scene, Sprite, Vec2 } from "@jts-studios/engine"
+
+export function createBootstrapScene() {
+    const scene = new Scene({
+        backgroundColor: new ColorRGBA(0.04, 0.06, 0.1, 1),
+    })
+
+    scene.add(
+        new Sprite({
+            position: new Vec2(-40, -40),
+            size: new Vec2(80, 80),
+            color: new ColorRGBA(0.2, 0.8, 0.9, 1),
+        }),
+    )
+
+    return scene
+}