@jts-studios/engine

WebGPU-focused 2D rendering primitives for app and visualization workloads.

Overview

@jts-studios/engine is a pure rendering library, aiming to implement a modern, modular WebGPU rendering pipeline for 2D applications.

It is not a gameplay framework. It is a composable rendering foundation.

Install

npm install @jts-studios/engine

Quick Start

Add a canvas to your page:

<canvas id="gpu-canvas"></canvas>

Then initialize and render:

import { Camera, ColorRGBA, Scene, Sprite, Vec2, WebGPURenderer } from "@jts-studios/engine"

const canvas = document.getElementById("gpu-canvas")
const renderer = new WebGPURenderer({
    canvas,
    clearColor: new ColorRGBA(0.06, 0.07, 0.1, 1),
})

await renderer.init()

const scene = new Scene({
    backgroundColor: new ColorRGBA(0.06, 0.07, 0.1, 1),
})

const camera = new Camera({
    position: new Vec2(0, 0),
    zoom: 1,
})

scene.add(
    new Sprite({
        position: new Vec2(-48, -48),
        size: new Vec2(96, 96),
        color: new ColorRGBA(0.2, 0.75, 0.95, 1),
        layer: "world",
    }),
)

function resize() {
    renderer.setSize(window.innerWidth, window.innerHeight, window.devicePixelRatio || 1)
    camera.setViewport(canvas.width, canvas.height)
}

window.addEventListener("resize", resize)
resize()

function frame() {
    renderer.render(scene, camera)
    requestAnimationFrame(frame)
}

frame()

Concepts

• Scene and Object2D define renderable hierarchy and transforms.
• Camera controls world-to-screen view and culling bounds.
• WebGPURenderer is the recommended backend facade for applications.
• Render data is extracted and routed to opaque/transparent/UI passes.

Advanced Runtime Features

• renderer.getCapabilities() exposes runtime adapter/device limits and optional feature flags.
• renderer.renderIfDirty(scene, camera) renders only when the renderer was invalidated.
• renderer.setSize(width, height, pixelRatio) keeps canvas output in sync with viewport changes.
• renderer.setDebugOverlay(true) enables a lightweight runtime stats overlay.
• renderer.setPostProcessingPipeline(pipeline) applies user-configured post-processing effect stacks.
• renderer.createRenderTarget(...) and renderer.renderToTarget(scene, camera, target) enable render-to-texture workflows.
• renderer.setTextureStreamingProfile({ quality, preferMipmaps }) controls texture loading quality and mip preferences.
• renderer.getDiagnosticsSnapshot() returns a consolidated runtime object with stats, profiling, benchmarks, capabilities, and postfx state.
• renderer.getCapabilities() also includes HDR-readiness fields: colorWorkflow, supportsHdrCanvas, and preferredHdrCanvasFormat.

Profiling Payload

• renderer.getGpuProfiling() includes:
• gpuFrameMs, timestampDeltaNs when timestamp queries are available.
• cpuFrameMs and cpuPassMs (opaque, transparent, ui) as a fallback path.
• passTimingsMs as projected per-pass GPU timings when both GPU frame timing and CPU pass breakdown are available.

Post-Processing Runtime Notes

• PostProcessingPipeline is now execution-wired, not config-only.
• Active grading-style effects feed runtime uniforms (postFxRgb, postFxContrast, postFxSaturation, postFxGamma, postFxToneMapping) consumed by sprite and text shaders.
• Tone mapping modes: linear (default), reinhard, aces-approx.
• Example:

import { PostProcessingPipeline } from "@jts-studios/engine"

const postFx = new PostProcessingPipeline()
postFx.addEffect({
    id: "grade",
    type: "color-grade",
    intensity: 0.8,
    options: {
        tint: [1.1, 0.95, 0.9],
        contrast: 1.15,
    },
})

postFx.setToneMappingMode("reinhard")

renderer.setPostProcessingPipeline(postFx)

Primitives And Materials

• Material supports custom uniforms, texture slots, blend presets, and user parameters.
• Additional shape primitives include Circle and RoundedRect.

Shape Stroke Styling

• Dashed shape strokes support strokeDashLength, strokeGapLength, and strokeDashOffset.
• Stroke cap modes: butt, round, square.
• Stroke join modes: miter, round, bevel.
• Example:

import { RectStyle, RoundedRect } from "@jts-studios/engine"

const style = new RectStyle()
    .setStrokeWidth(6)
    .setStrokeDashLength(14)
    .setStrokeGapLength(8)
    .setStrokeCap("round")
    .setStrokeJoin("bevel")

const shape = new RoundedRect({ style, radius: 12 })

Scope

• @jts-studios/engine focuses on rendering and graphics infrastructure.
• Game-engine-specific systems (for example follow cameras, gameplay state orchestration) belong in web-game-engine.

Diagnostics Guide

• Detailed diagnostics snapshot reference: docs/renderer-diagnostics.md