@flare-engine/render 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,612 @@
+import { Rect, Vec2 } from '@flare-engine/math';
+import { SkImageLike, SpriteFrame } from '@flare-engine/assets';
+import { ComponentDef, World, Query } from '@flare-engine/ecs';
+
+/** A drawable item with a z-order for sorting. */
+interface Drawable {
+    /** Z-index for draw ordering. Higher values draw on top. */
+    z: number;
+}
+/**
+ * Sort an array of drawables by z-index (ascending = back to front).
+ * Uses insertion sort which is fast for nearly-sorted arrays
+ * (typical in game rendering where order rarely changes).
+ *
+ * Mutates the input array in place. Returns the same array.
+ *
+ * @param items The array to sort in place.
+ * @param length Optional upper bound — when provided, only sorts `items[0..length)`.
+ *               Use this when passing a pooled array that may hold stale tail entries.
+ */
+declare function sortByDrawOrder<T extends Drawable>(items: T[], length?: number): T[];
+/**
+ * Compare function for use with Array.sort when insertion sort isn't desired.
+ * Stable relative order for equal z values (returns 0).
+ */
+declare function drawOrderCompare(a: Drawable, b: Drawable): number;
+
+/** Camera follow smoothing options. */
+interface FollowOptions {
+    /** Smoothing factor (0 = instant, lower = faster, default 0.1). */
+    smoothing?: number;
+    /** Offset from target (e.g. look-ahead). */
+    offset?: Vec2;
+    /** Dead zone rect — camera won't move while target is inside. */
+    deadZone?: Rect;
+}
+/**
+ * Camera2D — 2D camera with position, zoom, rotation, follow, and shake.
+ * Pure data + methods — no Skia dependency. The renderer reads camera state
+ * to build the view transform.
+ */
+declare class Camera2D {
+    /** Camera position (world-space center). */
+    x: number;
+    y: number;
+    /** Zoom level (1 = 100%). */
+    zoom: number;
+    /** Rotation in radians. */
+    rotation: number;
+    /** Viewport width in pixels. */
+    viewportWidth: number;
+    /** Viewport height in pixels. */
+    viewportHeight: number;
+    /** Optional world bounds to clamp camera position. */
+    bounds: Rect | null;
+    private _follow;
+    private _shake;
+    private _shakePerlin;
+    private _shakeSeed;
+    private _shakePerlinSeed;
+    private _motionScale;
+    /** Set viewport dimensions. */
+    setViewport(width: number, height: number): void;
+    /** Start following a target position. */
+    follow(target: Vec2, options?: FollowOptions): void;
+    /** Stop following. */
+    unfollow(): void;
+    /**
+     * Global motion multiplier applied to subsequent `shake()` calls. Scales
+     * both amplitude and duration. Default 1 (no-op). 0 fully suppresses
+     * shake. Intended to be driven by `@flare-engine/a11y` reduced-motion so
+     * callers don't have to guard every shake site.
+     *
+     * Only affects future `shake()` calls — does not retroactively modify an
+     * in-flight shake.
+     *
+     * Clamped to `>= 0`.
+     */
+    setMotionScale(scale: number): void;
+    /** Current motion scale (default 1). */
+    get motionScale(): number;
+    /** Start camera shake. */
+    shake(intensity: number, duration: number): void;
+    /**
+     * Start a Perlin-noise-based camera shake. Overwrites any in-flight
+     * shakePerlin (same semantics as shake()). Respects motionScale.
+     */
+    shakePerlin(intensity: number, duration: number): void;
+    /**
+     * Update camera. Call once per frame.
+     * @param dt Delta time in seconds.
+     */
+    update(dt: number): void;
+    /** Get the effective camera X (including shake + shakePerlin offsets). */
+    get effectiveX(): number;
+    /** Get the effective camera Y (including shake + shakePerlin offsets). */
+    get effectiveY(): number;
+    /** Convert world coordinates to screen coordinates. */
+    worldToScreen(worldX: number, worldY: number): Vec2;
+    /** Zero-alloc variant — writes screen coordinates into `out`. */
+    worldToScreenInto(worldX: number, worldY: number, out: Vec2): Vec2;
+    /** Convert screen coordinates to world coordinates. */
+    screenToWorld(screenX: number, screenY: number): Vec2;
+    /** Zero-alloc variant — writes world coordinates into `out`. */
+    screenToWorldInto(screenX: number, screenY: number, out: Vec2): Vec2;
+    /** Get the visible world-space bounding rect (allocates a fresh Rect). */
+    getBounds(): Rect;
+    /** Zero-alloc variant — writes the visible bounds into `out`. */
+    getBoundsInto(out: Rect): Rect;
+    private _clampToBounds;
+}
+
+/** Minimal Skia Canvas-like interface for the Renderer. */
+interface CanvasLike {
+    save(): number;
+    restore(): void;
+    translate(x: number, y: number): void;
+    scale(sx: number, sy: number): void;
+    rotate(radians: number, cx: number, cy: number): void;
+    clear(color: number): void;
+}
+/** Stats tracked per frame. */
+interface RenderStats {
+    drawCalls: number;
+    batchCount: number;
+}
+/**
+ * Renderer — manages the Skia Canvas lifecycle for a frame.
+ * `begin()` to start, draw your content, `end()` to finish.
+ */
+declare class Renderer {
+    /** Current frame stats. */
+    readonly stats: RenderStats;
+    private _canvas;
+    private _inFrame;
+    /** Set the canvas to render to. Called once when canvas is available. */
+    setCanvas(canvas: CanvasLike): void;
+    /** Get the current canvas. Throws if not in a frame. */
+    get canvas(): CanvasLike;
+    /** Whether we are currently between begin() and end(). */
+    get inFrame(): boolean;
+    /**
+     * Begin a new frame. Clears the canvas and resets stats.
+     * @param clearColor 32-bit ARGB color to clear with (default black = 0xFF000000).
+     */
+    begin(clearColor?: number): void;
+    /**
+     * End the current frame. Restores canvas state.
+     */
+    end(): void;
+    /**
+     * Apply camera transform to the canvas.
+     * Call after begin() and before drawing.
+     */
+    applyCamera(cameraX: number, cameraY: number, zoom: number, rotation: number, viewportWidth: number, viewportHeight: number): void;
+    /** Increment draw call counter. Called by batching systems. */
+    recordDrawCall(): void;
+    /** Increment batch counter. */
+    recordBatch(): void;
+}
+
+/** Color as RGBA (0-1 per channel). */
+interface SpriteColor {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly a: number;
+}
+/** A sprite effect that can be applied during rendering. */
+interface SpriteEffect {
+    readonly type: string;
+}
+/** Tint effect — blend a color onto the sprite. */
+interface TintEffect extends SpriteEffect {
+    readonly type: 'tint';
+    readonly color: SpriteColor;
+    readonly amount: number;
+}
+/** Flash effect — overlay a solid color that decays. */
+interface FlashEffect extends SpriteEffect {
+    readonly type: 'flash';
+    readonly color: SpriteColor;
+    readonly duration: number;
+    readonly elapsed: number;
+}
+/** Grayscale effect — desaturate the sprite. */
+interface GrayscaleEffect extends SpriteEffect {
+    readonly type: 'grayscale';
+    readonly amount: number;
+}
+/** Outline effect — draw an outline around the sprite. */
+interface OutlineEffect extends SpriteEffect {
+    readonly type: 'outline';
+    readonly color: SpriteColor;
+    readonly width: number;
+}
+/**
+ * Opaque pre-compiled shader program. Typically a Skia `RuntimeEffect` built
+ * once at asset load time via `Skia.RuntimeEffect.Make(sksl)`. The render
+ * package stays Skia-agnostic; the `@flare-engine/react` layer narrows this to the
+ * concrete Skia type when applying the effect.
+ */
+type CompiledShader = object;
+/** Uniform values keyed by name. Scalars for floats, arrays for vec/mat. */
+type ShaderUniforms = Record<string, number | readonly number[]>;
+/** Custom shader effect — apply a pre-compiled runtime shader with uniforms. */
+interface CustomShaderEffect extends SpriteEffect {
+    readonly type: 'custom';
+    readonly shader: CompiledShader;
+    readonly uniforms: ShaderUniforms;
+}
+/** Water surface effect — animated UV-displaced sprite with foam crests. */
+interface WaterEffect extends SpriteEffect {
+    readonly type: 'water';
+    readonly color: SpriteColor;
+    readonly foamColor: SpriteColor;
+    readonly waveSpeed: number;
+    readonly waveAmplitude: number;
+}
+/** Fog / volumetric haze effect — animated FBM noise layered over a sprite. */
+interface FogEffect extends SpriteEffect {
+    readonly type: 'fog';
+    readonly color: SpriteColor;
+    readonly density: number;
+    readonly speed: number;
+    readonly scale: number;
+}
+/** Fire / flame effect — value-noise FBM flame rising upward from a sprite. */
+interface FireEffect extends SpriteEffect {
+    readonly type: 'fire';
+    readonly color: SpriteColor;
+    readonly tipColor: SpriteColor;
+    readonly speed: number;
+    readonly intensity: number;
+}
+/** Rooftop city skyline — AABB silhouettes via SDF hash fields. */
+interface RoofsCityEffect extends SpriteEffect {
+    readonly type: 'roofs-city';
+    readonly skyColor: SpriteColor;
+    readonly roofColor: SpriteColor;
+    readonly scrollOffsetY: number;
+    readonly density: number;
+    /** Destination render width in logical pixels — used as shader resolution.x. */
+    readonly resolutionW: number;
+    /** Destination render height in logical pixels — used as shader resolution.y. */
+    readonly resolutionH: number;
+}
+/** Forest canopy — value-noise tree line. */
+interface ForestCanopyEffect extends SpriteEffect {
+    readonly type: 'forest-canopy';
+    readonly skyColor: SpriteColor;
+    readonly leafColor: SpriteColor;
+    readonly scrollOffsetY: number;
+    readonly density: number;
+    readonly resolutionW: number;
+    readonly resolutionH: number;
+}
+/** River surface — 1D height-field wave with foam crests. */
+interface RiverWaveEffect extends SpriteEffect {
+    readonly type: 'river-wave';
+    readonly waterColor: SpriteColor;
+    readonly foamColor: SpriteColor;
+    readonly scrollOffsetY: number;
+    readonly waveScale: number;
+    readonly resolutionW: number;
+    readonly resolutionH: number;
+}
+/** Moon surface — polar-SDF craters on a flat disc. */
+interface MoonCraterEffect extends SpriteEffect {
+    readonly type: 'moon-crater';
+    readonly moonColor: SpriteColor;
+    readonly craterColor: SpriteColor;
+    readonly scrollOffsetY: number;
+    readonly craterCount: number;
+    readonly resolutionW: number;
+    readonly resolutionH: number;
+}
+/** Cave interior — stalactites hanging from the top edge. */
+interface CaveInteriorEffect extends SpriteEffect {
+    readonly type: 'cave-interior';
+    readonly caveColor: SpriteColor;
+    readonly glowColor: SpriteColor;
+    readonly scrollOffsetY: number;
+    readonly stalactiteCount: number;
+    readonly resolutionW: number;
+    readonly resolutionH: number;
+}
+/** Mountain / hill ridge — FBM height-field silhouette. */
+interface MountainHillsEffect extends SpriteEffect {
+    readonly type: 'mountain-hills';
+    readonly skyColor: SpriteColor;
+    readonly hillColor: SpriteColor;
+    readonly scrollOffsetY: number;
+    readonly ridgeScale: number;
+    readonly resolutionW: number;
+    readonly resolutionH: number;
+}
+/** Any concrete sprite effect. */
+type AnySpriteEffect = TintEffect | FlashEffect | GrayscaleEffect | OutlineEffect | CustomShaderEffect | WaterEffect | FogEffect | FireEffect | RoofsCityEffect | ForestCanopyEffect | RiverWaveEffect | MoonCraterEffect | CaveInteriorEffect | MountainHillsEffect;
+/** Create a tint effect. */
+declare function tint(color: SpriteColor, amount: number): TintEffect;
+/** Create a flash effect. */
+declare function flash(color: SpriteColor, durationSec: number): FlashEffect;
+/** Create a grayscale effect. */
+declare function grayscale(amount: number): GrayscaleEffect;
+/** Create an outline effect. */
+declare function outline(color: SpriteColor, width: number): OutlineEffect;
+/** Create a custom shader effect. `shader` must be pre-compiled; compiling
+ *  SkSL per frame is expensive. `uniforms` may be mutated externally between
+ *  frames to animate parameters. */
+declare function custom(shader: CompiledShader, uniforms: ShaderUniforms): CustomShaderEffect;
+/** Create a water surface effect. Time is passed to the renderer each frame
+ *  via `beginFrame(w, h, time)` — the effect itself is time-invariant. */
+declare function water(color: SpriteColor, foamColor: SpriteColor, waveSpeed: number, waveAmplitude: number): WaterEffect;
+/** Create a fog / volumetric haze effect. Time is passed to the renderer each
+ *  frame via `beginFrame(w, h, time)` — the effect itself is time-invariant. */
+declare function fog(color: SpriteColor, density?: number, speed?: number, scale?: number): FogEffect;
+/** Create a fire / flame effect. Time is passed to the renderer each
+ *  frame via `beginFrame(w, h, time)` — the effect itself is time-invariant. */
+declare function fire(opts: {
+    color: SpriteColor;
+    tipColor: SpriteColor;
+    speed?: number;
+    intensity?: number;
+}): FireEffect;
+/** Create a rooftop city skyline effect. */
+declare function roofsCity(opts: {
+    skyColor: SpriteColor;
+    roofColor: SpriteColor;
+    scrollOffsetY?: number;
+    density?: number;
+    resolutionW?: number;
+    resolutionH?: number;
+}): RoofsCityEffect;
+/** Create a forest canopy effect. */
+declare function forestCanopy(opts: {
+    skyColor: SpriteColor;
+    leafColor: SpriteColor;
+    scrollOffsetY?: number;
+    density?: number;
+    resolutionW?: number;
+    resolutionH?: number;
+}): ForestCanopyEffect;
+/** Create a river wave surface effect. */
+declare function riverWave(opts: {
+    waterColor: SpriteColor;
+    foamColor: SpriteColor;
+    scrollOffsetY?: number;
+    waveScale?: number;
+    resolutionW?: number;
+    resolutionH?: number;
+}): RiverWaveEffect;
+/** Create a moon crater surface effect. */
+declare function moonCrater(opts: {
+    moonColor: SpriteColor;
+    craterColor: SpriteColor;
+    scrollOffsetY?: number;
+    craterCount?: number;
+    resolutionW?: number;
+    resolutionH?: number;
+}): MoonCraterEffect;
+/** Create a cave interior effect. */
+declare function caveInterior(opts: {
+    caveColor: SpriteColor;
+    glowColor: SpriteColor;
+    scrollOffsetY?: number;
+    stalactiteCount?: number;
+    resolutionW?: number;
+    resolutionH?: number;
+}): CaveInteriorEffect;
+/** Create a mountain / hill ridge effect. */
+declare function mountainHills(opts: {
+    skyColor: SpriteColor;
+    hillColor: SpriteColor;
+    scrollOffsetY?: number;
+    ridgeScale?: number;
+    resolutionW?: number;
+    resolutionH?: number;
+}): MountainHillsEffect;
+/**
+ * Advance a time-based effect by `dt` seconds.
+ *
+ * Returns a new effect object if state changed (e.g. flash elapsed time
+ * advances), the same reference if the effect is time-invariant (tint,
+ * grayscale, outline, custom), or `null` if the effect has expired.
+ *
+ * Effects are immutable — callers must replace their reference with the
+ * returned value. Sharing an effect instance across entities is safe.
+ */
+declare function updateEffect(effect: AnySpriteEffect, dt: number): AnySpriteEffect | null;
+/**
+ * Get the current intensity of a flash effect (1 at start, 0 at end).
+ */
+declare function flashIntensity(effect: FlashEffect): number;
+
+/** A single sprite draw request in the batch. */
+interface SpriteDrawCommand {
+    /** Texture (Skia SkImage). */
+    image: SkImageLike;
+    /** Source rectangle in the texture. */
+    srcX: number;
+    srcY: number;
+    srcW: number;
+    srcH: number;
+    /** Destination position and size. */
+    dstX: number;
+    dstY: number;
+    dstW: number;
+    dstH: number;
+    /** Optional per-sprite effect. Shared by reference across commands in a
+     *  batch — the render adapter applies it once per batch. */
+    effect: AnySpriteEffect | undefined;
+    /** Per-instance alpha multiplier. Range [0, 1]. Default 1 (fully opaque).
+     *  Participates in the batch key — sprites with different alphas are
+     *  placed in separate batches so the renderer can apply each alpha once
+     *  per draw call without per-sprite overhead. */
+    alpha: number;
+    /** Rotation in radians, clockwise (Skia Y-down convention). Default 0.
+     *  Rotation is applied about the anchor point. */
+    rotation: number;
+    /** Anchor X fraction stored for the bridge rotation path. Range [0, 1]. */
+    anchorX: number;
+    /** Anchor Y fraction stored for the bridge rotation path. Range [0, 1]. */
+    anchorY: number;
+    /**
+     * When true, the sprite is drawn via `drawImageRect` so `dstW` and `dstH`
+     * are honored independently (non-uniform scale). A 256×256 source image
+     * will fill an arbitrary W×H destination rect.
+     *
+     * Default (false/absent): drawn via the batched `drawAtlas` path (uniform
+     * scale — dstW/srcW drives both axes). Stretched sprites are NOT batched
+     * with regular sprites; each is an independent `drawImageRect` call.
+     *
+     * Rotation is unsupported in stretch mode — the RSXform similarity-transform
+     * limit does not apply, but the bridge draws a plain axis-aligned rect.
+     * Combine with a zero rotation only.
+     */
+    stretch: boolean;
+}
+/**
+ * SpriteBatch — collects sprite draw commands and groups them by texture
+ * (and optionally by effect) for efficient batched rendering.
+ *
+ * Usage:
+ * 1. Call `draw()` for each sprite, optionally passing an effect
+ * 2. Call `flush()` with an atlas draw callback to execute all batched draws
+ * 3. Batching groups by texture identity, then by effect identity — so
+ *    sharing an effect instance across sprites maximizes batch size
+ *
+ * The actual Skia Atlas draw call is delegated to a callback so this module
+ * remains testable without Skia.
+ */
+declare class SpriteBatch {
+    private _commands;
+    private _pool;
+    private _batches;
+    /** Number of queued draw commands. */
+    get count(): number;
+    /** Queue a sprite draw from a frame.
+     *
+     *  `anchorX` / `anchorY` define the pivot point of the sprite as a
+     *  fraction of its destination size — `(0, 0)` = top-left (default),
+     *  `(0.5, 0.5)` = center, `(1, 1)` = bottom-right. `dstX` / `dstY`
+     *  then refer to the anchor point instead of the top-left corner.
+     *
+     *  `alpha` is a per-instance opacity multiplier in [0, 1]. Default 1. */
+    draw(image: SkImageLike, frame: SpriteFrame, dstX: number, dstY: number, dstW?: number, dstH?: number, effect?: AnySpriteEffect, anchorX?: number, anchorY?: number, alpha?: number, rotation?: number, stretch?: boolean): void;
+    /** Queue a raw sprite draw with explicit src/dst rects. `dstX` / `dstY`
+     *  refer to the anchor point — offset by `anchorX * dstW` / `anchorY * dstH`.
+     *
+     *  `alpha` is a per-instance opacity multiplier in [0, 1]. Default 1. */
+    drawRaw(image: SkImageLike, srcX: number, srcY: number, srcW: number, srcH: number, dstX: number, dstY: number, dstW: number, dstH: number, effect?: AnySpriteEffect, anchorX?: number, anchorY?: number, alpha?: number, rotation?: number, stretch?: boolean): void;
+    /**
+     * Flush all queued commands, grouped by (texture, effect, alpha) identity.
+     *
+     * @param drawAtlas Callback invoked once per batch. Receives
+     *   `(image, commands)` — all commands in a batch share the same texture,
+     *   the same effect (readable from `commands[0].effect`), and the same
+     *   alpha (readable from `commands[0].alpha`).
+     * @param renderer Optional renderer to record stats.
+     */
+    flush(drawAtlas: (image: SkImageLike, commands: SpriteDrawCommand[]) => void, renderer?: Renderer): void;
+    /** Clear all queued commands without drawing. */
+    clear(): void;
+    private _acquire;
+}
+
+declare const FIRE_SKSL = "\nuniform shader src;\nuniform float2 resolution;\nuniform float3 color;\nuniform float3 tipColor;\nuniform float speed;\nuniform float intensity;\nuniform float time;\n\nfloat hash(float2 p) { return fract(sin(dot(p, float2(127.1, 311.7))) * 43758.5453); }\n\nfloat vnoise(float2 p) {\n  float2 i = floor(p);\n  float2 f = fract(p);\n  float2 u = f * f * (3.0 - 2.0 * f);\n  float a = hash(i);\n  float b = hash(i + float2(1.0, 0.0));\n  float c = hash(i + float2(0.0, 1.0));\n  float d = hash(i + float2(1.0, 1.0));\n  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);\n}\n\nfloat fbm(float2 p) {\n  return 0.5 * vnoise(p) + 0.25 * vnoise(p * 2.0);\n}\n\nhalf4 main(float2 coord) {\n  half4 srcColor = src.eval(coord);\n  float2 uv = coord / max(resolution, float2(1.0));\n  float2 np = float2(uv.x * 4.0, uv.y * 6.0 - time * speed * 2.0);\n  float n = fbm(np);\n  float flameMask = smoothstep(0.0, intensity, n * (1.0 - uv.y));\n  float3 fireRgb = mix(color, tipColor, uv.y);\n  half4 fireColor = half4(fireRgb.r, fireRgb.g, fireRgb.b, flameMask);\n  return half4(fireColor.rgb, fireColor.a * srcColor.a);\n}\n";
+declare const FOG_SKSL = "\nuniform shader src;\nuniform float2 resolution;\nuniform float3 color;\nuniform float density;\nuniform float speed;\nuniform float scale;\nuniform float time;\n\nfloat hash(float2 p) {\n  return fract(sin(dot(p, float2(127.1, 311.7))) * 43758.5453);\n}\n\nfloat valueNoise(float2 p) {\n  float2 i = floor(p);\n  float2 f = fract(p);\n  float2 u = f * f * (3.0 - 2.0 * f);\n  float a = hash(i);\n  float b = hash(i + float2(1.0, 0.0));\n  float c = hash(i + float2(0.0, 1.0));\n  float d = hash(i + float2(1.0, 1.0));\n  return mix(mix(a, b, u.x), mix(c, d, u.x), u.y);\n}\n\nfloat fbm(float2 p) {\n  float value = 0.0;\n  float amplitude = 0.5;\n  for (int i = 0; i < 4; i++) {\n    value += amplitude * valueNoise(p);\n    p *= 2.0;\n    amplitude *= 0.5;\n  }\n  return value;\n}\n\nhalf4 main(float2 coord) {\n  float2 uv = coord / max(resolution, float2(1.0));\n  float2 drift = float2(time * speed, 0.3 * time * speed);\n  float n = clamp(fbm(uv * scale + drift), 0.0, 1.0);\n  half4 srcColor = src.eval(coord);\n  half3 blended = mix(srcColor.rgb, half3(color.r, color.g, color.b), half(density * n));\n  return half4(blended, srcColor.a);\n}\n";
+declare const WATER_SKSL = "\nuniform shader src;\nuniform float2 resolution;\nuniform float3 color;\nuniform float3 foamColor;\nuniform float waveSpeed;\nuniform float waveAmplitude;\nuniform float time;\n\nhalf4 main(float2 coord) {\n  float2 uv = coord / resolution;\n  float wave1 = sin(uv.x * 6.2832 * 3.0 + time * waveSpeed * 2.0) * waveAmplitude;\n  float wave2 = sin(uv.x * 6.2832 * 5.0 - time * waveSpeed * 1.3 + 1.5) * waveAmplitude * 0.5;\n  float totalWave = wave1 + wave2;\n  float2 displaced = float2(uv.x, uv.y + totalWave);\n  displaced = clamp(displaced, float2(0.0), float2(1.0));\n  half4 c = src.eval(displaced * resolution);\n  float waveDeriv = cos(uv.x * 6.2832 * 3.0 + time * waveSpeed * 2.0) * waveAmplitude * 2.0\n                  + cos(uv.x * 6.2832 * 5.0 - time * waveSpeed * 1.3 + 1.5) * waveAmplitude;\n  float foam = smoothstep(waveAmplitude * 0.6, waveAmplitude * 1.5, waveDeriv);\n  half3 tinted = mix(c.rgb, half3(color.r, color.g, color.b), half(0.35));\n  half3 final = mix(tinted, half3(foamColor.r, foamColor.g, foamColor.b), half(foam));\n  return half4(final, c.a);\n}\n";
+declare const ROOFS_CITY_SKSL = "\nuniform float2 resolution;\nuniform float3 skyColor;\nuniform float3 roofColor;\nuniform float scrollOffsetY;\nuniform float density;\n\nfloat hash(float x) { return fract(sin(x * 127.1) * 43758.5453); }\n\nfloat buildingTop(float2 uv, float density) {\n  float col = floor(uv.x * density);\n  float h = 0.35 + 0.35 * hash(col);\n  float w = 0.6 + 0.3 * hash(col + 7.3);\n  float edge = step(abs(fract(uv.x * density) - 0.5), w * 0.5);\n  return edge * step(uv.y, h);\n}\n\nhalf4 main(float2 coord) {\n  float2 uv = coord / max(resolution, float2(1.0));\n  uv.y = uv.y + scrollOffsetY / max(resolution.y, 1.0);\n  uv.y = fract(uv.y);\n  float buildings = buildingTop(uv, density);\n  half3 col = mix(half3(skyColor.r, skyColor.g, skyColor.b),\n                  half3(roofColor.r, roofColor.g, roofColor.b),\n                  half(buildings));\n  return half4(col, 1.0);\n}\n";
+declare const FOREST_CANOPY_SKSL = "\nuniform float2 resolution;\nuniform float3 skyColor;\nuniform float3 leafColor;\nuniform float scrollOffsetY;\nuniform float density;\n\nfloat hash(float2 p) { return fract(sin(dot(p, float2(127.1, 311.7))) * 43758.5453); }\n\nfloat valueNoise(float2 p) {\n  float2 i = floor(p);\n  float2 f = fract(p);\n  float2 u = f * f * (3.0 - 2.0 * f);\n  return mix(mix(hash(i), hash(i + float2(1.0, 0.0)), u.x),\n             mix(hash(i + float2(0.0, 1.0)), hash(i + float2(1.0, 1.0)), u.x), u.y);\n}\n\nhalf4 main(float2 coord) {\n  float2 uv = coord / max(resolution, float2(1.0));\n  uv.y = uv.y + scrollOffsetY / max(resolution.y, 1.0);\n  float n = valueNoise(float2(uv.x * density, uv.y * 3.0));\n  float treeLine = 0.55 + 0.25 * valueNoise(float2(uv.x * density * 0.5, 0.0));\n  float canopy = step(uv.y, treeLine) * smoothstep(0.3, 0.7, n);\n  half3 col = mix(half3(skyColor.r, skyColor.g, skyColor.b),\n                  half3(leafColor.r, leafColor.g, leafColor.b),\n                  half(canopy));\n  return half4(col, 1.0);\n}\n";
+declare const RIVER_WAVE_SKSL = "\nuniform float2 resolution;\nuniform float3 waterColor;\nuniform float3 foamColor;\nuniform float scrollOffsetY;\nuniform float waveScale;\n\nhalf4 main(float2 coord) {\n  float2 uv = coord / max(resolution, float2(1.0));\n  float scroll = scrollOffsetY / max(resolution.y, 1.0);\n  float2 p = float2(uv.x, uv.y + scroll);\n  float w1 = sin(p.x * 6.2832 * waveScale + p.y * 4.0) * 0.04;\n  float w2 = sin(p.x * 6.2832 * waveScale * 1.7 - p.y * 2.5 + 1.2) * 0.02;\n  float surface = 0.5 + w1 + w2;\n  float inWater = step(uv.y, surface);\n  float crest = smoothstep(surface - 0.015, surface, uv.y) * (1.0 - inWater) +\n                smoothstep(surface + 0.015, surface, uv.y) * inWater;\n  half3 base = mix(half3(foamColor.r, foamColor.g, foamColor.b),\n                   half3(waterColor.r, waterColor.g, waterColor.b),\n                   half(inWater));\n  half3 col = mix(base, half3(foamColor.r, foamColor.g, foamColor.b), half(crest * 0.6));\n  return half4(col, 1.0);\n}\n";
+declare const MOON_CRATER_SKSL = "\nuniform float2 resolution;\nuniform float3 moonColor;\nuniform float3 craterColor;\nuniform float scrollOffsetY;\nuniform float craterCount;\n\nfloat hash(float2 p) { return fract(sin(dot(p, float2(127.1, 311.7))) * 43758.5453); }\n\nfloat crater(float2 uv, float2 center, float r) {\n  float d = length(uv - center);\n  float rim = smoothstep(r, r * 0.85, d) - smoothstep(r * 0.85, r * 0.65, d);\n  float floor_ = smoothstep(r * 0.65, r * 0.4, d);\n  return rim * 0.6 + floor_ * 0.25;\n}\n\nhalf4 main(float2 coord) {\n  float2 uv = coord / max(resolution, float2(1.0));\n  uv.y = uv.y + scrollOffsetY / max(resolution.y, 1.0);\n  float c = 0.0;\n  for (int i = 0; i < 6; i++) {\n    float fi = float(i);\n    float2 center = float2(hash(float2(fi, 0.0)), hash(float2(fi, 1.0)));\n    float r = 0.04 + 0.07 * hash(float2(fi, 2.0));\n    c += crater(fract(uv), center, r) * step(fi, craterCount - 1.0);\n  }\n  c = clamp(c, 0.0, 1.0);\n  half3 col = mix(half3(moonColor.r, moonColor.g, moonColor.b),\n                  half3(craterColor.r, craterColor.g, craterColor.b),\n                  half(c));\n  return half4(col, 1.0);\n}\n";
+declare const CAVE_INTERIOR_SKSL = "\nuniform float2 resolution;\nuniform float3 caveColor;\nuniform float3 glowColor;\nuniform float scrollOffsetY;\nuniform float stalactiteCount;\n\nfloat hash(float x) { return fract(sin(x * 127.1) * 43758.5453); }\n\nfloat stalactite(float2 uv, float count) {\n  float col = floor(uv.x * count);\n  float tip = 0.1 + 0.2 * hash(col);\n  float w = 0.3 + 0.3 * hash(col + 5.0);\n  float dx = abs(fract(uv.x * count) - 0.5) / (w * 0.5);\n  float shape = step(dx, 1.0) * step(uv.y, tip * (1.0 - clamp(dx, 0.0, 1.0)));\n  return shape;\n}\n\nhalf4 main(float2 coord) {\n  float2 uv = coord / max(resolution, float2(1.0));\n  uv.y = 1.0 - uv.y;\n  uv.y = uv.y + scrollOffsetY / max(resolution.y, 1.0);\n  float stalac = stalactite(uv, stalactiteCount);\n  float glow = smoothstep(0.8, 1.0, uv.y) * (1.0 - stalac);\n  half3 col = mix(half3(caveColor.r, caveColor.g, caveColor.b),\n                  half3(glowColor.r, glowColor.g, glowColor.b),\n                  half(glow));\n  col = mix(col, half3(caveColor.r, caveColor.g, caveColor.b) * half(0.3), half(stalac));\n  return half4(col, 1.0);\n}\n";
+declare const MOUNTAIN_HILLS_SKSL = "\nuniform float2 resolution;\nuniform float3 skyColor;\nuniform float3 hillColor;\nuniform float scrollOffsetY;\nuniform float ridgeScale;\n\nfloat hash(float x) { return fract(sin(x * 127.1) * 43758.5453); }\n\nfloat heightField(float x, float scale) {\n  float h = 0.0;\n  float amp = 0.5;\n  float freq = scale;\n  for (int i = 0; i < 4; i++) {\n    float ix = floor(x * freq);\n    float fx = fract(x * freq);\n    fx = fx * fx * (3.0 - 2.0 * fx);\n    h += amp * mix(hash(ix), hash(ix + 1.0), fx);\n    freq *= 2.0;\n    amp *= 0.5;\n  }\n  return h;\n}\n\nhalf4 main(float2 coord) {\n  float2 uv = coord / max(resolution, float2(1.0));\n  float scroll = scrollOffsetY / max(resolution.y, 1.0);\n  float horizon = 0.4 + 0.3 * heightField(uv.x + scroll * 0.3, ridgeScale);\n  float mountains = step(uv.y, horizon);\n  half3 col = mix(half3(skyColor.r, skyColor.g, skyColor.b),\n                  half3(hillColor.r, hillColor.g, hillColor.b),\n                  half(mountains));\n  return half4(col, 1.0);\n}\n";
+
+/** A single glyph in a bitmap font. */
+interface Glyph {
+    /** Character code (Unicode). */
+    id: number;
+    /** Source rect in the font texture. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Draw offset. */
+    xOffset: number;
+    yOffset: number;
+    /** Horizontal advance after this glyph. */
+    xAdvance: number;
+}
+/** Kerning pair. */
+interface KerningPair {
+    first: number;
+    second: number;
+    amount: number;
+}
+/** Parsed bitmap font data. */
+interface BitmapFont {
+    /** Line height in pixels. */
+    lineHeight: number;
+    /** Baseline offset. */
+    base: number;
+    /** Glyph map by character code. */
+    glyphs: Map<number, Glyph>;
+    /** Kerning map. Key = `first << 16 | second`. */
+    kernings: Map<number, number>;
+}
+/**
+ * Parse BMFont JSON format (common output from tools like Hiero, BMFont, msdf-bmfont).
+ */
+declare function parseBMFontJSON(json: unknown): BitmapFont;
+/** Get kerning between two characters. */
+declare function getKerning(font: BitmapFont, first: number, second: number): number;
+/** Measure the width of a text string in pixels. */
+declare function measureText(font: BitmapFont, text: string): number;
+/**
+ * Draw text using a SpriteBatch.
+ * Characters are batched as individual sprites from the font texture.
+ */
+declare function drawText(batch: SpriteBatch, font: BitmapFont, image: SkImageLike, text: string, x: number, y: number, scale?: number): void;
+
+/** Position component data expected by the render system. */
+interface PositionData {
+    x: number;
+    y: number;
+}
+/** Sprite anchor as a fraction of the destination rect — `(0, 0)` is
+ *  top-left (default), `(0.5, 0.5)` is center, `(1, 1)` is bottom-right.
+ *  When present, `Position` refers to the anchor point rather than the
+ *  sprite's top-left corner. */
+interface SpriteAnchor {
+    x: number;
+    y: number;
+}
+/** Sprite component data expected by the render system. */
+interface SpriteData {
+    image: SkImageLike;
+    frame: SpriteFrame;
+    z: number;
+    width?: number;
+    height?: number;
+    /** Optional per-sprite effect (tint, flash, grayscale, outline, custom).
+     *  Shared instances are batched together — prefer reusing an effect
+     *  reference across entities that should render identically. */
+    effect?: AnySpriteEffect;
+    /** Optional pivot point for the sprite. Defaults to top-left `(0, 0)`. */
+    anchor?: SpriteAnchor;
+    /** Per-instance alpha multiplier. Range [0, 1]. Default 1 (fully opaque).
+     *  Mutate directly each frame — e.g. `sprite.alpha = lerp(1, 0, t)`.
+     *  Sprites with different alphas are placed in separate draw batches. */
+    alpha?: number;
+    /** Rotation in radians, clockwise (Skia Y-down convention). Default 0.
+     *  Applied about the sprite's anchor point. Non-uniform scale combined with
+     *  rotation is unsupported — scale is inferred uniformly from dstW/srcW. */
+    rotation?: number;
+    /**
+     * When true, draw via `drawImageRect` so `width` and `height` are honored
+     * independently (non-uniform scale). Use for background tiles or any sprite
+     * that must fill a non-square destination rect exactly.
+     *
+     * Default (absent/false): drawn via the batched `drawAtlas` uniform-scale
+     * path. Stretched sprites are NOT batched with regular sprites.
+     *
+     * Rotation is unsupported in stretch mode — combine only with `rotation = 0`.
+     */
+    stretch?: boolean;
+}
+/**
+ * Create a render system function.
+ *
+ * This is not a defineSystem() wrapper because it needs extra parameters
+ * (SpriteBatch) beyond what the ECS system interface provides. Instead,
+ * it returns a function to call in your game loop.
+ *
+ * The returned function only **queues** sprite draws into `batch` — it
+ * does not call `batch.flush()`. Flushing is owned by the frame owner
+ * (e.g. `<GameView>`) so that all draw sources (ECS, particles, custom)
+ * can contribute to a single flush at the render phase.
+ *
+ * @param world The ECS world.
+ * @param query Query that matches entities with Position + Sprite.
+ * @param positionDef ComponentDef for Position.
+ * @param spriteDef ComponentDef for Sprite.
+ * @param batch SpriteBatch instance to queue draws into.
+ */
+declare function createRenderSystem(world: World, query: Query, positionDef: ComponentDef<PositionData>, spriteDef: ComponentDef<SpriteData>, batch: SpriteBatch): () => void;
+/** Canonical Sprite component — queried by the render system alongside `Position`. */
+declare const Sprite: ComponentDef<SpriteData>;
+
+export { type AnySpriteEffect, type BitmapFont, CAVE_INTERIOR_SKSL, Camera2D, type CanvasLike, type CaveInteriorEffect, type CompiledShader, type CustomShaderEffect, type Drawable, FIRE_SKSL, FOG_SKSL, FOREST_CANOPY_SKSL, type FireEffect, type FlashEffect, type FogEffect, type FollowOptions, type ForestCanopyEffect, type Glyph, type GrayscaleEffect, type KerningPair, MOON_CRATER_SKSL, MOUNTAIN_HILLS_SKSL, type MoonCraterEffect, type MountainHillsEffect, type OutlineEffect, type PositionData, RIVER_WAVE_SKSL, ROOFS_CITY_SKSL, type RenderStats, Renderer, type RiverWaveEffect, type RoofsCityEffect, type ShaderUniforms, Sprite, type SpriteAnchor, SpriteBatch, type SpriteColor, type SpriteData, type SpriteDrawCommand, type SpriteEffect, type TintEffect, WATER_SKSL, type WaterEffect, caveInterior, createRenderSystem, custom, drawOrderCompare, drawText, fire, flash, flashIntensity, fog, forestCanopy, getKerning, grayscale, measureText, moonCrater, mountainHills, outline, parseBMFontJSON, riverWave, roofsCity, sortByDrawOrder, tint, updateEffect, water };