@jts-studios/web-game-engine 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [0.1.0] - 2026-03-10
+
+### Added
+
+- First public package release for `@jts-studios/web-game-engine`.
+- Runtime loop foundation with `FixedStepClock` and `InputReplayTimeline`.
+- Plugin lifecycle support in `GameRuntime` with capability/dependency checks.
+- Scene snapshot utilities and asset preloading with `SceneSnapshotStore` and `AssetManifestLoader`.
+- Export verification and package verify script for release quality gates.

package/FALLBACK_STRATEGY.md

@@ -0,0 +1,21 @@
+# WebGPU Fallback Strategy
+
+`@jts-studios/web-game-engine` targets `@jts-studios/engine` WebGPU rendering.
+
+## Runtime Policy
+
+- Default policy: `warn`.
+- `strict`: throw when WebGPU is unavailable.
+- `warn`: enter degraded mode and emit diagnostics.
+- `silent`: enter degraded mode without warnings.
+
+## Degraded Mode
+
+When WebGPU is unavailable, gameplay systems continue updating while rendering is skipped.
+Use `runtime.getFallbackStatus()` to detect this mode.
+
+## Recommended App Behavior
+
+- Show a clear UI message in degraded mode.
+- Offer browser/device upgrade guidance.
+- Optionally expose a non-WebGPU renderer in the host app.

package/PLUGIN_API.md

@@ -0,0 +1,34 @@
+# Plugin API
+
+`GameRuntime.use(plugin)` accepts plugin objects that implement optional lifecycle hooks.
+
+## Required Shape
+
+- `name: string` recommended for diagnostics and dependency wiring.
+- `apiVersion?: number` defaults to runtime API version.
+- `capabilities?: string[]` any of: `render-hooks`, `update-hooks`, `scene-state`, `input-profile`.
+- `dependencies?: string[]` plugin names that must be registered first.
+- `priority?: number` lower values run first.
+- `enabled?: boolean` defaults to `true`.
+
+## Lifecycle Hooks
+
+- `onInit(runtime)` called once after runtime init.
+- `onUpdate(runtime, deltaTime)` called per fixed-step update.
+- `onRender(runtime, alpha)` called after render.
+- `onDestroy(runtime)` called during teardown.
+
+## Error Handling
+
+Hook exceptions are isolated and routed through `runtime.onPluginError(handler)`.
+Handlers receive:
+
+- `plugin`: plugin name
+- `hookName`: lifecycle hook identifier
+- `error`: original exception
+
+## Compatibility Guidance
+
+- Keep plugin behavior deterministic for replay-heavy projects.
+- Declare `dependencies` and `capabilities` explicitly.
+- Avoid mutating runtime internals not exposed by public APIs.

package/README.md

@@ -0,0 +1,49 @@
+# web-game-engine
+
+This package is a core game-framework layer built on top of `@jts-studios/engine`.
+
+`@jts-studios/engine` remains the rendering engine and GPU/rendering foundation.
+
+`@jts-studios/web-game-engine` provides reusable gameplay/runtime systems that compose that renderer.
+
+## Structure
+
+- `src/core/*`: reusable library systems (input, camera, state, loop).
+- `src/adapters/*`: integration glue to concrete runtimes (for example, browser runtime adapter).
+- `src/index.js`: public library entrypoint.
+- `src/app/*`: compatibility wrappers for older import paths.
+
+## Included Game Systems
+
+- Follow-camera controller with smoothing and dead-zone behavior.
+- Optional world-bounds clamping for camera movement.
+- Scene/state loop scaffolding intended for game-level orchestration.
+- Snapshot store and input profile catalog for runtime workflows.
+
+## Public API
+
+- `GameRuntime`
+- `CameraController`
+- `InputController`
+- `InputProfileCatalog`
+- `UpdateLoop`
+- `FixedStepClock`
+- `InputReplayTimeline`
+- `RuntimeBridge`
+- `SceneManager`
+- `SceneSnapshotStore`
+- `AssetManifestLoader`
+
+## Commands
+
+- `npm install`
+- `npm run dev`
+- `npm run build`
+- `npm run verify`
+- `npm run release:verify`
+
+## Separation Rule
+
+- Put rendering primitives and GPU systems in `web-engine`.
+- Put reusable gameplay/entity/physics/combat/quest systems in `web-game-engine`.
+- Put domain-specific implementations (for example, chess rules and chess assets) in their own sibling project folders, such as `chess`.

package/package.json

@@ -0,0 +1,37 @@
+{
+    "name": "@jts-studios/web-game-engine",
+    "private": false,
+    "version": "0.1.0",
+    "type": "module",
+    "main": "./src/index.js",
+    "module": "./src/index.js",
+    "types": "./src/index.d.ts",
+    "exports": {
+        ".": "./src/index.js"
+    },
+    "files": [
+        "src",
+        "README.md",
+        "CHANGELOG.md",
+        "PLUGIN_API.md",
+        "FALLBACK_STRATEGY.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "dev": "vite",
+        "build": "vite build",
+        "preview": "vite preview",
+        "test": "node --test \"src/**/*.test.js\"",
+        "check:exports": "node scripts/check-exports.mjs",
+        "verify": "npm run check:exports && npm run test && npm run build",
+        "release:verify": "npm run verify && npm pack --dry-run"
+    },
+    "dependencies": {
+        "@jts-studios/engine": "^1.5.0"
+    },
+    "devDependencies": {
+        "vite": "^7.3.1"
+    }
+}

package/src/adapters/runtime/GameRuntime.js

@@ -0,0 +1,446 @@
+import { Camera, ColorRGBA, Scene, WebGPURenderer2D } from "@jts-studios/engine"
+import { InputController } from "../../core/input/InputController.js"
+import { InputProfileCatalog } from "../../core/input/InputProfileCatalog.js"
+import { CameraController } from "../../core/camera/CameraController.js"
+import { UpdateLoop } from "../../core/loop/UpdateLoop.js"
+import { FixedStepClock } from "../../core/loop/FixedStepClock.js"
+import { InputReplayTimeline } from "../../core/loop/InputReplayTimeline.js"
+import { SceneManager } from "../../core/state/SceneManager.js"
+import { SceneSnapshotStore } from "../../core/state/SceneSnapshotStore.js"
+import { AssetManifestLoader } from "../../core/state/AssetManifestLoader.js"
+import { RuntimeBridge } from "../../core/runtime/RuntimeBridge.js"
+
+/**
+ * Runtime adapter that wires web-engine rendering with web-game-engine core systems.
+ */
+export class GameRuntime {
+    constructor({ canvas, fixedDelta = 1 / 60, maxSubSteps = 8, pluginApiVersion = 1, fallbackPolicy = "warn" } = {}) {
+        this.canvas = canvas
+        this.renderer = new WebGPURenderer2D({
+            canvas,
+            clearColor: new ColorRGBA(0.04, 0.06, 0.1, 1),
+        })
+        this.camera = new Camera({
+            position: { x: 0, y: 0 },
+            zoom: 1,
+        })
+        this.scene = new Scene({
+            backgroundColor: new ColorRGBA(0.04, 0.06, 0.1, 1),
+        })
+        this.sceneManager = new SceneManager()
+        this.sceneManager.setScene(this.scene)
+
+        this.input = new InputController({ element: canvas })
+        this.inputProfiles = new InputProfileCatalog()
+        this.cameraController = new CameraController(this.camera, this.input)
+        this.sceneSnapshots = new SceneSnapshotStore()
+        this.assetManifestLoader = new AssetManifestLoader()
+        this.updateLoop = new UpdateLoop()
+        this.updateLoop.add(this.cameraController)
+        this.clock = new FixedStepClock({ fixedDelta, maxSubSteps })
+        this.plugins = []
+        this.pluginApiVersion = Number.isFinite(pluginApiVersion) ? Math.max(1, Math.floor(pluginApiVersion)) : 1
+        this._pluginErrorHandlers = []
+        this._activeInputProfileName = ""
+        this.replay = new InputReplayTimeline()
+        this.bridge = new RuntimeBridge()
+        this.fallbackPolicy = fallbackPolicy === "strict" || fallbackPolicy === "silent" ? fallbackPolicy : "warn"
+        this._fallbackStatus = {
+            active: false,
+            reason: "",
+            policy: this.fallbackPolicy,
+        }
+
+        this._frameHandle = 0
+        this._running = false
+        this._frameInProgress = false
+        this._lastFrameTime = 0
+        this._onResize = this.#resize.bind(this)
+        this._onFrame = this.#frame.bind(this)
+    }
+
+    async init() {
+        try {
+            await this.renderer.init()
+            const capabilities = this.renderer.getCapabilities?.() ?? null
+            const hasWebGpu = capabilities?.supportsWebGPU !== false
+            if (!hasWebGpu) {
+                this.#activateFallback("webgpu-unavailable")
+            }
+        } catch (error) {
+            this.#activateFallback("renderer-init-failed")
+            if (this.fallbackPolicy === "strict") {
+                throw error
+            }
+        }
+
+        this.input.attach()
+        window.addEventListener("resize", this._onResize)
+        this.#resize()
+
+        await this.#invokePluginHookForAll("onInit", this)
+        this.bridge.emit("runtime:init", {
+            fallback: this.getFallbackStatus(),
+        })
+    }
+
+    setScene(scene) {
+        this.scene = scene
+        this.sceneManager.setScene(scene)
+    }
+
+    registerState(name, state) {
+        this.sceneManager.registerState(name, state)
+    }
+
+    setState(name, context = null) {
+        this.sceneManager.setState(name, context)
+    }
+
+    defineInputProfile(name, profile) {
+        this.inputProfiles.define(name, profile)
+        if (!this._activeInputProfileName) {
+            this.applyInputProfile(name)
+        }
+    }
+
+    getInputProfile(name) {
+        return this.inputProfiles.get(name)
+    }
+
+    listInputProfiles() {
+        return this.inputProfiles.list()
+    }
+
+    applyInputProfile(name) {
+        const profile = this.getInputProfile(name)
+        if (!profile) {
+            return false
+        }
+
+        this._activeInputProfileName = name
+        this.input.applyProfile(profile)
+        return true
+    }
+
+    getActiveInputProfileName() {
+        return this._activeInputProfileName ?? null
+    }
+
+    saveSceneSnapshot(name, scene = this.sceneManager.getActiveScene() ?? this.scene) {
+        this.sceneSnapshots.save(name, scene)
+    }
+
+    loadSceneSnapshot(name, { activate = true } = {}) {
+        const restored = this.sceneSnapshots.load(name)
+        if (!restored) {
+            return null
+        }
+
+        if (activate) {
+            this.setScene(restored)
+        }
+
+        return restored
+    }
+
+    listSceneSnapshots() {
+        return this.sceneSnapshots.list()
+    }
+
+    setCameraFollowTarget(target) {
+        this.cameraController.setFollowTarget(target)
+    }
+
+    setCameraBounds(bounds) {
+        this.cameraController.setBounds(bounds)
+    }
+
+    setCameraDeadZone(width, height) {
+        this.cameraController.setDeadZone(width, height)
+    }
+
+    use(plugin) {
+        if (!plugin || typeof plugin !== "object") {
+            throw new TypeError("GameRuntime.use requires a plugin object")
+        }
+
+        const pluginVersion = Number.isFinite(plugin.apiVersion) ? Math.floor(plugin.apiVersion) : this.pluginApiVersion
+        if (pluginVersion > this.pluginApiVersion) {
+            throw new Error(
+                `GameRuntime.use rejected plugin '${plugin.name ?? "anonymous"}' (apiVersion ${pluginVersion} > ${this.pluginApiVersion})`,
+            )
+        }
+
+        const capabilities = Array.isArray(plugin.capabilities) ? plugin.capabilities : []
+        const unsupported = capabilities.filter(
+            (capability) =>
+                capability !== "render-hooks" &&
+                capability !== "update-hooks" &&
+                capability !== "scene-state" &&
+                capability !== "input-profile",
+        )
+        if (unsupported.length > 0) {
+            throw new Error(`GameRuntime.use rejected plugin with unsupported capabilities: ${unsupported.join(", ")}`)
+        }
+
+        const pluginName =
+            typeof plugin.name === "string" && plugin.name.length > 0 ? plugin.name : `plugin-${this.plugins.length + 1}`
+        if (this.plugins.some((entry) => entry?.__pluginName === pluginName)) {
+            throw new Error(`GameRuntime.use rejected duplicate plugin name '${pluginName}'`)
+        }
+
+        const dependencies = Array.isArray(plugin.dependencies) ? plugin.dependencies : []
+        for (let i = 0; i < dependencies.length; i++) {
+            if (!this.plugins.some((entry) => entry?.__pluginName === dependencies[i])) {
+                throw new Error(`GameRuntime.use missing dependency '${dependencies[i]}' for plugin '${pluginName}'`)
+            }
+        }
+
+        const priority = Number.isFinite(plugin.priority) ? Math.floor(plugin.priority) : 0
+        const wrappedPlugin = {
+            ...plugin,
+            __pluginName: pluginName,
+            __enabled: plugin.enabled !== false,
+            __priority: priority,
+        }
+
+        this.plugins.push(wrappedPlugin)
+        this.plugins.sort((a, b) => (a.__priority ?? 0) - (b.__priority ?? 0))
+        return this
+    }
+
+    listPlugins() {
+        return this.plugins.map((plugin) => ({
+            name: plugin.__pluginName,
+            enabled: plugin.__enabled,
+            priority: plugin.__priority,
+            apiVersion: plugin.apiVersion ?? this.pluginApiVersion,
+        }))
+    }
+
+    setPluginEnabled(name, enabled = true) {
+        const plugin = this.plugins.find((entry) => entry.__pluginName === name)
+        if (!plugin) {
+            return false
+        }
+        plugin.__enabled = !!enabled
+        return true
+    }
+
+    onPluginError(handler) {
+        if (typeof handler === "function") {
+            this._pluginErrorHandlers.push(handler)
+        }
+        return this
+    }
+
+    startReplayRecording() {
+        this.replay.startRecording()
+        return this
+    }
+
+    stopReplayRecording() {
+        return this.replay.stopRecording()
+    }
+
+    startReplayPlayback(events) {
+        this.replay.startPlayback(events)
+        return this
+    }
+
+    stopReplayPlayback() {
+        this.replay.stopPlayback()
+        return this
+    }
+
+    getReplayDiagnostics(events = null) {
+        return this.replay.validate(events ?? this.replay.toJSON())
+    }
+
+    getFallbackStatus() {
+        return {
+            ...this._fallbackStatus,
+        }
+    }
+
+    onBridgeEvent(listener) {
+        return this.bridge.onEvent(listener)
+    }
+
+    registerBridgeCommand(name, handler) {
+        this.bridge.registerCommand(name, handler)
+        return this
+    }
+
+    executeBridgeCommand(name, payload = null) {
+        return this.bridge.execute(name, payload, this)
+    }
+
+    async preloadSnapshotAssets(name, { resolveTextureHandle = null, onProgress = null, signal = null } = {}) {
+        const plan = this.sceneSnapshots.createPreloadPlan(name, { resolveTextureHandle })
+        if (plan.urls.length === 0) {
+            return {
+                status: "ready",
+                loaded: 0,
+                failed: [],
+                unresolved: plan.unresolved,
+                total: plan.total,
+            }
+        }
+
+        const result = await this.assetManifestLoader.preloadUrls(plan.urls, {
+            onProgress,
+            signal,
+        })
+
+        return {
+            ...result,
+            unresolved: plan.unresolved,
+        }
+    }
+
+    start() {
+        if (this._running) {
+            return
+        }
+
+        this._running = true
+        this._frameInProgress = false
+        this._lastFrameTime = 0
+        this.clock.reset()
+        this._frameHandle = requestAnimationFrame(this._onFrame)
+    }
+
+    stop() {
+        if (!this._running) {
+            return
+        }
+
+        this._running = false
+        cancelAnimationFrame(this._frameHandle)
+        this._frameHandle = 0
+    }
+
+    destroy() {
+        this.stop()
+        this.input.detach()
+        this.updateLoop.clear()
+        void this.#invokePluginHookForAll("onDestroy", this)
+        window.removeEventListener("resize", this._onResize)
+        this.renderer.destroy()
+    }
+
+    #resize() {
+        this.renderer.setSize(window.innerWidth, window.innerHeight, window.devicePixelRatio || 1)
+        this.camera.setViewport(this.canvas.width, this.canvas.height)
+    }
+
+    async #frame(time) {
+        if (!this._running) {
+            return
+        }
+
+        if (this._frameInProgress) {
+            this._frameHandle = requestAnimationFrame(this._onFrame)
+            return
+        }
+
+        this._frameInProgress = true
+
+        try {
+            const deltaTime = this._lastFrameTime > 0 ? Math.max(0.0001, (time - this._lastFrameTime) * 0.001) : 1 / 60
+            this._lastFrameTime = time
+
+            const stepped = this.clock.consume(deltaTime)
+            for (let i = 0; i < stepped.steps.length; i++) {
+                const stepDelta = stepped.steps[i]
+
+                const replayEvents = this.replay.consume(stepDelta)
+                if (replayEvents.length > 0) {
+                    const latest = replayEvents[replayEvents.length - 1]
+                    if (latest?.snapshot) {
+                        this.input.applySnapshot(latest.snapshot)
+                    }
+                }
+
+                this.replay.record(stepDelta, this.input.captureSnapshot())
+
+                this.updateLoop.update(stepDelta)
+                this.sceneManager.update(stepDelta)
+                this.bridge.emit("runtime:update", {
+                    deltaTime: stepDelta,
+                })
+
+                await this.#invokePluginHookForAll("onUpdate", this, stepDelta)
+            }
+
+            const activeScene = this.sceneManager.getActiveScene() ?? this.scene
+            if (!this._fallbackStatus.active) {
+                await this.renderer.render(activeScene, this.camera)
+            }
+            await this.#invokePluginHookForAll("onRender", this, stepped.alpha)
+            this.bridge.emit("runtime:render", {
+                alpha: stepped.alpha,
+                fallbackActive: this._fallbackStatus.active,
+            })
+        } finally {
+            this._frameInProgress = false
+        }
+
+        if (!this._running) {
+            return
+        }
+
+        this._frameHandle = requestAnimationFrame(this._onFrame)
+    }
+
+    async #invokePluginHook(plugin, hookName, ...args) {
+        if (!plugin || typeof plugin !== "object") {
+            return
+        }
+
+        if (plugin.__enabled === false) {
+            return
+        }
+
+        const hook = plugin[hookName]
+        if (typeof hook !== "function") {
+            return
+        }
+
+        try {
+            await hook(...args)
+        } catch (error) {
+            for (let i = 0; i < this._pluginErrorHandlers.length; i++) {
+                try {
+                    this._pluginErrorHandlers[i]({
+                        plugin: plugin.__pluginName ?? plugin.name ?? "anonymous",
+                        hookName,
+                        error,
+                    })
+                } catch {
+                    // Avoid cascading plugin error handler failures.
+                }
+            }
+        }
+    }
+
+    async #invokePluginHookForAll(hookName, ...args) {
+        for (let i = 0; i < this.plugins.length; i++) {
+            await this.#invokePluginHook(this.plugins[i], hookName, ...args)
+        }
+    }
+
+    #activateFallback(reason) {
+        this._fallbackStatus = {
+            active: true,
+            reason,
+            policy: this.fallbackPolicy,
+        }
+
+        if (this.fallbackPolicy === "warn") {
+            console.warn(`[GameRuntime] Falling back to no-render mode: ${reason}`)
+        }
+    }
+}

package/src/app/GameApp.js

@@ -0,0 +1,6 @@
+import { GameRuntime } from "../adapters/runtime/GameRuntime.js"
+
+/**
+ * Backward-compatible alias. Prefer `GameRuntime` from `src/index.js`.
+ */
+export class GameApp extends GameRuntime {}

package/src/app/camera/CameraController.js

@@ -0,0 +1 @@
+export { CameraController } from "../../core/camera/CameraController.js"

package/src/app/input/InputController.js

@@ -0,0 +1 @@
+export { InputController } from "../../core/input/InputController.js"

package/src/app/input/InputProfileCatalog.js

@@ -0,0 +1 @@
+export { InputProfileCatalog } from "../../core/input/InputProfileCatalog.js"

package/src/app/loop/UpdateLoop.js

@@ -0,0 +1 @@
+export { UpdateLoop } from "../../core/loop/UpdateLoop.js"

package/src/app/state/SceneManager.js

@@ -0,0 +1 @@
+export { SceneManager } from "../../core/state/SceneManager.js"

package/src/app/state/SceneSnapshotStore.js

@@ -0,0 +1 @@
+export { SceneSnapshotStore } from "../../core/state/SceneSnapshotStore.js"