A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(camera): a camera can render into a texture
esenginef7de8a0cec1b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e5866aa47..bec3e0681 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,21 @@ published separately; it ships inside the editor.### Changed+- **A camera can render into a texture.** `Camera.renderTarget` takes a+ `RenderTexture` handle and that camera draws there instead of the screen — a+ minimap, a mirror, a portrait, the scene half of cache-as-bitmap. The engine+ could always open a pass on an offscreen target; what was missing is that no+ camera ever named one, so `Renderer.begin` was called with 0 every time. Such a+ camera does not compete to be the main view (a camera drawing elsewhere is not a+ candidate for the screen) and renders BEFORE the screen cameras, because what it+ draws is usually what they are about to sample. Its viewport fractions are of+ the target, whose own size sets the resolution, and a released target falls back+ to the screen rather than drawing nowhere.++ WebGL2 today. The WebGPU backend cannot yet adopt a device texture into the+ resource table (`importExternalTexture`), so the target a camera fills there+ cannot be handed to a `Sprite`.+- **Removed: 26 engine entry points no host called.** Five of them(`renderer_submitSprites` / `submitUIElements` / `submitBitmapText` /`submitShapes` / `submitParticles`) had bodies that were `(void)registry;` —@@ -193,6 +208,13 @@ published separately; it ships inside the editor.### Fixed+- **WebGPU reused one pipeline for two different colour formats.** The pipeline+ variant key mapped every 8-bit unorm format to one slot, so a pipeline built for+ the surface (`BGRA8Unorm`) was handed to a pass on a render target+ (`RGBA8Unorm`) — which WebGPU rejects outright, taking the whole command buffer+ with it. Nothing had drawn a scene into an offscreen target on that backend+ before, so nothing had asked.+- **The manual taught an import that does not exist.** `facingFromQuat` wasremoved when perception moved to a dot-product cone, and four pages went onimporting it — including a complete turret example a reader would copy. It isdiff --git a/docs/astro/src/content/docs/graphics/drawing.mdx b/docs/astro/src/content/docs/graphics/drawing.mdxindex 7a10fa3ad..e4e4ad9b6 100644--- a/docs/astro/src/content/docs/graphics/drawing.mdx+++ b/docs/astro/src/content/docs/graphics/drawing.mdx@@ -165,7 +165,15 @@ For minimaps, portraits, mirrors — and as the backing of[cache-as-bitmap](/docs/graphics/sprites/) — `RenderTexture` allocates an offscreenrender target. Wrap draw commands in `begin`/`end` to render into it; theresulting `texture` is an ordinary texture handle usable anywhere (a-`Sprite.texture`, `Draw.texture`, a material texture param):+`Sprite.texture`, `Draw.texture`, a material texture param).++A whole **scene** goes into one by pointing a camera at it: set+`Camera.renderTarget` to the target's handle and that camera draws there instead+of the screen, before the screen cameras and without competing to be the main+view. Its own sorting layers (`Camera.cullingMask`) decide what it sees, so a+minimap camera and the player's camera can look at the same world and show+different parts of it. On WebGL2 today; the WebGPU backend cannot yet hand a+render target's texture to a `Sprite`:```typescriptimport { RenderTexture, Draw } from 'esengine';diff --git a/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdxindex c8d8cf347..eaa2eba90 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx@@ -154,7 +154,13 @@ registerDrawCallback('custom-mesh', () => {小地图、头像、镜面——以及[位图缓存](/docs/zh-cn/graphics/sprites/)的底层——`RenderTexture` 分配一个离屏渲染目标。把绘制命令包在 `begin`/`end` 之间即渲染进去;得到的 `texture` 是普通纹理句柄,哪里都能用(`Sprite.texture`、-`Draw.texture`、材质纹理参数):+`Draw.texture`、材质纹理参数)。++要把**整个场景**画进去,让一台相机指向它:把 `Camera.renderTarget` 设成目标的句柄,+那台相机就画到那里而不是屏幕——在屏幕相机之前渲染,也不参与「谁是主视图」的竞争。+它看见什么由自己的排序层(`Camera.cullingMask`)决定,所以小地图相机和玩家相机可以+看同一个世界、显示不同的部分。目前仅 WebGL2:WebGPU 后端还不能把渲染目标的纹理+交给 `Sprite`:```typescriptimport { RenderTexture, Draw } from 'esengine';diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex cafe07962..6d7a07e88 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -402,6 +402,13 @@"default": "4294967295","doc": "Which sorting layers this camera renders."},+ {+ "key": "renderTarget",+ "type": "number",+ "default": "0",+ "doc": "Render into a RenderTexture instead of the screen (0 = screen). Set at run time.",+ "advanced": true+ },{"key": "showFrustum","type": "boolean",diff --git a/examples/render-texture/src/main.ts b/examples/render-texture/src/main.tsindex 634d10016..87e05ce9b 100644--- a/examples/render-texture/src/main.ts+++ b/examples/render-texture/src/main.ts@@ -9,9 +9,9 @@// 768×480 at a fixed display size — resize() returns a NEW handle whose// textureId the sprite must be re-pointed at.//-// RenderTexture is a low-level surface: a camera cannot target it, and it does-// not re-render the scene. It redirects Draw commands issued between begin()-// and end() into an offscreen target, under a view-projection you supply.+// RenderTexture is the low-level surface: Draw commands issued between begin()+// and end() go into an offscreen target under a view-projection you supply.+// A whole SCENE goes into one through Camera.renderTarget.import { addStartupSystem, addSystemToSchedule, Schedule } from 'esengine';import './components';diff --git a/fixtures/scenes/camera-target.esscene b/fixtures/scenes/camera-target.esscenenew file mode 100644index 000000000..b42828684--- /dev/null+++ b/fixtures/scenes/camera-target.esscene@@ -0,0 +1,136 @@+{+ "version": 2,+ "name": "CameraTarget",+ "entities": [+ {+ "id": 0,+ "name": "OffscreenCamera",+ "parent": null,+ "children": [],+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 10+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 100,+ "isActive": true,+ "priority": 0,+ "clearFlags": 3,+ "cullingMask": 2+ }+ }+ ],+ "visible": true+ },+ {+ "id": 1,+ "name": "RedFill",+ "parent": null,+ "children": [],+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "Sprite",+ "data": {+ "size": {+ "x": 400,+ "y": 400+ },+ "color": {+ "r": 1,+ "g": 0,+ "b": 0,+ "a": 1+ },+ "layer": 1+ }+ }+ ],+ "visible": true+ },+ {+ "id": 2,+ "name": "ScreenCamera",+ "parent": null,+ "children": [],+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 10+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 300,+ "isActive": true,+ "priority": 1,+ "clearFlags": 3,+ "cullingMask": 1+ }+ }+ ],+ "visible": true+ },+ {+ "id": 3,+ "name": "Screen",+ "parent": null,+ "children": [],+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "Sprite",+ "data": {+ "size": {+ "x": 300,+ "y": 300+ },+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "layer": 0+ }+ }+ ],+ "visible": true+ }+ ]+}diff --git a/fixtures/scenes/camera-target.textures.json b/fixtures/scenes/camera-target.textures.jsonnew file mode 100644index 000000000..0967ef424--- /dev/null+++ b/fixtures/scenes/camera-target.textures.json@@ -0,0 +1 @@+{}diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex c852b7b35..0b3dbf04b 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -5,7 +5,7 @@ Symbols: 113 public · 66 beta · 1507 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```-"43f91684e5f3d3fb"+"f4ba1e6b5d361dee"```## ANCHOR_AXES — const @experimental@@ -1535,6 +1535,7 @@ orthoSize: numberpixelPerfect: booleanpriority: numberprojectionType: number+renderTarget: numbershowFrustum: booleanviewport: Vec4```@@ -1582,6 +1583,7 @@ orthoSize: numberpixelPerfect: booleanpriority: numberprojectionType: number+renderTarget: number | undefinedviewport: { x: number; y: number; z: number; w: number; }```@@ -1599,6 +1601,7 @@ orthoSize: numberpixelPerfect: booleanpriority: numberprojection: number+renderTarget: numberrotation: numbertilt: { x: number; y: number; z: number; w: number; } | undefinedviewport: { x: number; y: number; z: number; w: number; }@@ -1615,6 +1618,7 @@ clearFlags: numbercullingMask: number | undefinedelapsed: numberregistry: { _cpp: CppRegistry; }+renderTarget: number | undefinedviewProjection: Float32Array<ArrayBufferLike>viewportPixels: Viewport```diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 7c6a34918..8956f141f 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -5,7 +5,7 @@ Symbols: 113 public · 71 beta · 1526 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```-"43f91684e5f3d3fb"+"f4ba1e6b5d361dee"```## ANCHOR_AXES — const @experimental@@ -1535,6 +1535,7 @@ orthoSize: numberpixelPerfect: booleanpriority: numberprojectionType: number+renderTarget: numbershowFrustum: booleanviewport: Vec4```@@ -1582,6 +1583,7 @@ orthoSize: numberpixelPerfect: booleanpriority: numberprojectionType: number+renderTarget: number | undefinedviewport: { x: number; y: number; z: number; w: number; }```@@ -1599,6 +1601,7 @@ orthoSize: numberpixelPerfect: booleanpriority: numberprojection: number+renderTarget: numberrotation: numbertilt: { x: number; y: number; z: number; w: number; } | undefinedviewport: { x: number; y: number; z: number; w: number; }@@ -1615,6 +1618,7 @@ clearFlags: numbercullingMask: number | undefinedelapsed: numberregistry: { _cpp: CppRegistry; }+renderTarget: number | undefinedviewProjection: Float32Array<ArrayBufferLike>viewportPixels: Viewport```diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex df4bb47ff..3d8824cbc 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1530,6 +1530,7 @@ orthoSize: numberpixelPerfect: booleanpriority: numberprojectionType: number+renderTarget: numbershowFrustum: booleanviewport: Vec4```@@ -1577,6 +1578,7 @@ orthoSize: numberpixelPerfect: booleanpriority: numberprojectionType: number+renderTarget: number | undefinedviewport: { x: number; y: number; z: number; w: number; }```@@ -1594,6 +1596,7 @@ orthoSize: numberpixelPerfect: booleanpriority: numberprojection: number+renderTarget: numberrotation: numbertilt: { x: number; y: number; z: number; w: number; } | undefinedviewport: { x: number; y: number; z: number; w: number; }@@ -1610,6 +1613,7 @@ clearFlags: numbercullingMask: number | undefinedelapsed: numberregistry: { _cpp: CppRegistry; }+renderTarget: number | undefinedviewProjection: Float32Array<ArrayBufferLike>viewportPixels: Viewport```diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 80ab93907..179cf5c80 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1530,6 +1530,7 @@ orthoSize: numberpixelPerfect: booleanpriority: numberprojectionType: number+renderTarget: numbershowFrustum: booleanviewport: Vec4```@@ -1577,6 +1578,7 @@ orthoSize: numberpixelPerfect: booleanpriority: numberprojectionType: number+renderTarget: number | undefinedviewport: { x: number; y: number; z: number; w: number; }```@@ -1594,6 +1596,7 @@ orthoSize: numberpixelPerfect: booleanpriority: numberprojection: number+renderTarget: numberrotation: numbertilt: { x: number; y: number; z: number; w: number; } | undefinedviewport: { x: number; y: number; z: number; w: number; }@@ -1610,6 +1613,7 @@ clearFlags: numbercullingMask: number | undefinedelapsed: numberregistry: { _cpp: CppRegistry; }+renderTarget: number | undefinedviewProjection: Float32Array<ArrayBufferLike>viewportPixels: Viewport```diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 57d4cb71f..b4fabf82b 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1530,6 +1530,7 @@ orthoSize: numberpixelPerfect: booleanpriority: numberprojectionType: number+renderTarget: numbershowFrustum: booleanviewport: Vec4```@@ -1577,6 +1578,7 @@ orthoSize: numberpixelPerfect: booleanpriority: numberprojectionType: number+renderTarget: number | undefinedviewport: { x: number; y: number; z: number; w: number; }```@@ -1594,6 +1596,7 @@ orthoSize: numberpixelPerfect: booleanpriority: numberprojection: number+renderTarget: numberrotation: numbertilt: { x: number; y: number; z: number; w: number; } | undefinedviewport: { x: number; y: number; z: number; w: number; }@@ -1610,6 +1613,7 @@ clearFlags: numbercullingMask: number | undefinedelapsed: numberregistry: { _cpp: CppRegistry; }+renderTarget: number | undefinedviewProjection: Float32Array<ArrayBufferLike>viewportPixels: Viewport```diff --git a/sdk/src/camera/CameraDirector.ts b/sdk/src/camera/CameraDirector.tsindex 114aebd2c..7c5e331cd 100644--- a/sdk/src/camera/CameraDirector.ts+++ b/sdk/src/camera/CameraDirector.ts@@ -60,6 +60,7 @@ export function lerpPOV(a: CameraPOV, b: CameraPOV, t: number): CameraPOV {priority: b.priority,pixelPerfect: t < 0.5 ? a.pixelPerfect : b.pixelPerfect, // discrete: flip at the midpointcullingMask: b.cullingMask, // discrete: the target camera decides what it shows+ renderTarget: b.renderTarget, // discrete: a blend cannot be half in a texture};}diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.tsindex c2945462e..94584696e 100644--- a/sdk/src/camera/CameraPlugin.ts+++ b/sdk/src/camera/CameraPlugin.ts@@ -22,6 +22,7 @@ import { EditorView, DEFAULT_EDITOR_VIEW, editorViewStandoff, editorViewClipFar,import { ScreenScaling, DEFAULT_SCREEN_SCALING, SCREEN_FIT_OFF } from './ScreenScaling';import { CameraDirector, createDirectorState, resolveMainPOV } from './CameraDirector';import { RenderPipeline } from '../render/renderPipeline';+import { renderTargetSize } from '../render/renderTexture';import { Renderer } from '../render/renderer';import { platformNow, platformDevicePixelRatio } from '../platform';import { SceneManager } from '../scene/sceneManager';@@ -45,6 +46,8 @@ interface CameraInfo {cameraX: number;cameraY: number;cullingMask: number;+ /** Offscreen target this camera draws into; 0 = the screen. */+ renderTarget: number;}function acquireCameraInfo(pool: CameraInfo[], index: number): CameraInfo {@@ -62,6 +65,7 @@ function acquireCameraInfo(pool: CameraInfo[], index: number): CameraInfo {cameraX: 0,cameraY: 0,cullingMask: 0xFFFFFFFF,+ renderTarget: 0,};pool.push(info);return info;@@ -174,6 +178,8 @@ export interface CameraPOV {pixelPerfect: boolean;/** Sorting layers this camera renders; bit i = layer i. */cullingMask: number;+ /** Offscreen target this camera draws into; 0 = the screen. */+ renderTarget: number;}/**@@ -206,6 +212,8 @@ export interface CameraFields {pixelPerfect: boolean;/** Absent on a core built before the field; that camera drew every layer. */cullingMask?: number;+ /** Absent on a core built before the field; that camera drew to the screen. */+ renderTarget?: number;}/**@@ -248,6 +256,7 @@ function readCameraPOV(pixelPerfect: camera.pixelPerfect,// A core built before the field answers undefined; that camera drew everything.cullingMask: camera.cullingMask ?? 0xFFFFFFFF,+ renderTarget: camera.renderTarget ?? 0,};}@@ -321,6 +330,7 @@ export function buildCameraInfo(cam.cameraX = camX;cam.cameraY = camY;cam.cullingMask = pov.cullingMask;+ cam.renderTarget = pov.renderTarget;return cam;}@@ -447,6 +457,7 @@ export function editorCameraInfo(// The editor's own eye is not a game camera: it shows every layer, so a// culled scene camera never hides content from authoring.cullingMask: 0xFFFFFFFF,+ renderTarget: 0,};return buildCameraInfo(pov, width, height, null, pool, 0);}@@ -506,10 +517,16 @@ function resolveCameras(const povs = collectCameraPOVs(module, cppRegistry, width, height, world, activeScenes);if (povs.length === 0) return [];const canvas = resolveFitSource(app, findCanvasData(module, cppRegistry, world, activeScenes));- const fullFrame = povs.filter((p) => isFullFrame(p.viewport));- const overlays = povs.filter((p) => !isFullFrame(p.viewport)).sort((a, b) => a.priority - b.priority);+ // A camera drawing into a texture is not a candidate for the screen: it does+ // not compete with the main view, and it renders BEFORE it, because what it+ // draws is usually what the main view is about to sample.+ const offscreen = povs.filter((p) => p.renderTarget !== 0).sort((a, b) => a.priority - b.priority);+ const onScreen = povs.filter((p) => p.renderTarget === 0);+ const fullFrame = onScreen.filter((p) => isFullFrame(p.viewport));+ const overlays = onScreen.filter((p) => !isFullFrame(p.viewport)).sort((a, b) => a.priority - b.priority);const out: CameraInfo[] = [];+ for (const p of offscreen) out.push(buildCameraInfo(p, width, height, canvas, pool, out.length));// The director resolves ONE main view from the full-frame candidates (active// camera + view-target blending); index 0 → it also drives screen<->world.if (fullFrame.length > 0 && app.hasResource(CameraDirector)) {@@ -685,10 +702,17 @@ export function cameraPlugin(pipeline.beginScreenCapture();for (const cam of cameras) {const vp = cam.viewportRect;- const px = Math.round(vp.x * width);- const py = Math.round((1 - vp.y - vp.h) * height);- const pw = Math.round(vp.w * width);- const ph = Math.round(vp.h * height);+ // A camera drawing into a texture is measured against+ // THAT surface: its viewport rect is a fraction, and+ // the fraction is of the target it draws to.+ const target = cam.renderTarget !== 0+ ? renderTargetSize(cam.renderTarget) : null;+ const w = target?.width ?? width;+ const h = target?.height ?? height;+ const px = Math.round(vp.x * w);+ const py = Math.round((1 - vp.y - vp.h) * h);+ const pw = Math.round(vp.w * w);+ const ph = Math.round(vp.h * h);pipeline.renderCamera({registry: { _cpp: cppRegistry },viewProjection: cam.viewProjection,@@ -698,6 +722,9 @@ export function cameraPlugin(cameraEntity: cam.entity,clearColor,cullingMask: cam.cullingMask,+ // A released target leaves the handle behind; drawing+ // to it would draw nowhere, so it falls to the screen.+ renderTarget: target ? cam.renderTarget : 0,});}pipeline.endScreenCapture();diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.tsindex 327b7c24b..70611af59 100644--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts@@ -170,6 +170,7 @@ export interface CameraPtrData {clearFlags: number;pixelPerfect: boolean;cullingMask: number;+ renderTarget: number;}export function fillCamera(@@ -188,6 +189,7 @@ export function fillCamera(out.clearFlags = u8[ptr + 48];out.pixelPerfect = u8[ptr + 49] !== 0;out.cullingMask = u32[(ptr + 52) >> 2];+ out.renderTarget = u32[(ptr + 56) >> 2];}export function writeCamera(@@ -206,6 +208,7 @@ export function writeCamera(u8[ptr + 48] = data.clearFlags;u8[ptr + 49] = data.pixelPerfect ? 1 : 0;u32[(ptr + 52) >> 2] = data.cullingMask;+ u32[(ptr + 56) >> 2] = data.renderTarget;}export function createCameraData(): CameraPtrData {@@ -222,6 +225,7 @@ export function createCameraData(): CameraPtrData {clearFlags: 0,pixelPerfect: false,cullingMask: 0,+ renderTarget: 0,};}diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.tsindex f12fb5e08..414edf4d0 100644--- a/sdk/src/ecs/component.generated.ts+++ b/sdk/src/ecs/component.generated.ts@@ -15,7 +15,7 @@ import type { Dimension, Padding } from '../wasm/wasm.generated';* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to* run on mismatch, because mismatched offsets read the wrong heap bytes.*/-export const ABI_LAYOUT_HASH = '43f91684e5f3d3fb';+export const ABI_LAYOUT_HASH = 'f4ba1e6b5d361dee';/*** One asset-valued field of a component: which field, and what kind of@@ -160,6 +160,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {clearFlags: 3,pixelPerfect: false,cullingMask: 4294967295,+ renderTarget: 0,},editorDefaults: {projectionType: 1,@@ -182,6 +183,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {clearFlags: { tooltip: "Which buffers to clear before rendering this camera." },pixelPerfect: { tooltip: "Snap the camera to the pixel grid for crisp pixel-art (Orthographic).", advanced: true, shownWhen: { field: "projectionType", values: [1] } },cullingMask: { tooltip: "Which sorting layers this camera renders.", bitmask: { source: "sortingLayers" } },+ renderTarget: { tooltip: "Render into a RenderTexture instead of the screen (0 = screen). Set at run time.", advanced: true },},},Canvas: {@@ -1112,6 +1114,7 @@ export interface CameraData {clearFlags: number;pixelPerfect: boolean;cullingMask: number;+ renderTarget: number;}export interface CanvasData {diff --git a/sdk/src/render/renderPipeline.ts b/sdk/src/render/renderPipeline.tsindex 0d663d2f3..855fec86a 100644--- a/sdk/src/render/renderPipeline.ts+++ b/sdk/src/render/renderPipeline.ts@@ -46,6 +46,8 @@ export interface CameraRenderParams {clearColor?: { x: number; y: number; z: number; w: number };/** Sorting layers this camera draws (`Camera.cullingMask`); omitted = all. */cullingMask?: number;+ /** Offscreen target to draw into; 0 (default) is the screen. */+ renderTarget?: number;}export class RenderPipeline {@@ -158,7 +160,7 @@ export class RenderPipeline {Renderer.setViewport(vp.x, vp.y, vp.w, vp.h);// The camera's clear rides begin as a region-scoped load-op — no scissor// dance, no sticky clear state at the boundary.- Renderer.begin(viewProjection, 0, clearFlags, params.clearColor, vp);+ Renderer.begin(viewProjection, params.renderTarget ?? 0, clearFlags, params.clearColor, vp);// Set after begin (which clears the draw list) and before the collect it gates.Renderer.setCullingMask(params.cullingMask ?? 0xFFFFFFFF);this.submitScene(registry, viewProjection, vp, elapsed);diff --git a/sdk/src/render/renderTexture.ts b/sdk/src/render/renderTexture.tsindex 2ba490772..a3c0a53c5 100644--- a/sdk/src/render/renderTexture.ts+++ b/sdk/src/render/renderTexture.ts@@ -27,6 +27,18 @@ export interface RenderTextureHandle {_filter: 'nearest' | 'linear';}+/**+ * Handle → the size of the target behind it. A `Camera.renderTarget` is a bare+ * handle (a component holds no object), and what decides that camera's+ * resolution is the target's own size — so the one place that knows it says so.+ */+const sizes = new Map<RenderTargetHandle, { width: number; height: number }>();++/** The size of a live render target, or null once it has been released. */+export function renderTargetSize(handle: RenderTargetHandle): { width: number; height: number } | null {+ return sizes.get(handle) ?? null;+}+export const RenderTexture = {create(options: RenderTextureOptions): RenderTextureHandle {const depth = options.depth ?? true;@@ -41,6 +53,7 @@ export const RenderTexture = {? getResourceManager()?.registerExternalTexture(textureId, options.width, options.height) ?? 0: 0;+ sizes.set(handle, { width: options.width, height: options.height });return {_handle: handle,textureId,@@ -54,6 +67,7 @@ export const RenderTexture = {release(rt: RenderTextureHandle): void {if (rt.texture !== 0) getResourceManager()?.releaseTexture(rt.texture);+ sizes.delete(rt._handle);Renderer.releaseRenderTarget(rt._handle);},diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.tsindex 42a5bd877..4510aa6c9 100644--- a/sdk/src/wasm/ptrLayouts.generated.ts+++ b/sdk/src/wasm/ptrLayouts.generated.ts@@ -79,6 +79,7 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {{ name: 'clearFlags', type: 'u8', offset: 48 },{ name: 'pixelPerfect', type: 'bool', offset: 49 },{ name: 'cullingMask', type: 'u32', offset: 52 },+ { name: 'renderTarget', type: 'u32', offset: 56 },],},Canvas: {diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.tsindex 7c070b3cb..aafcfce58 100644--- a/sdk/src/wasm/wasm.generated.ts+++ b/sdk/src/wasm/wasm.generated.ts@@ -263,6 +263,7 @@ export interface Camera {clearFlags: number;pixelPerfect: boolean;cullingMask: number;+ renderTarget: number;}export interface Canvas {diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snapindex 081bb1b19..a5f70b776 100644--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap@@ -109,6 +109,10 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho],"tooltip": "Orthographic (2D) or Perspective projection.",},+ "renderTarget": {+ "advanced": true,+ "tooltip": "Render into a RenderTexture instead of the screen (0 = screen). Set at run time.",+ },"showFrustum": {"advanced": true,"tooltip": "Draw this camera's whole view volume in the editor, not just what it frames on the content plane.",diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cppindex 4ae44dfd8..5728a4ad8 100644--- a/src/esengine/bindings/EditorAPI.generated.cpp+++ b/src/esengine/bindings/EditorAPI.generated.cpp@@ -2,10 +2,10 @@* @file EditorAPI.generated.cpp* @brief Auto-generated editor API with string-dispatched component access* @details Generated by EHT - DO NOT EDIT- * @schema_hash a430f15de6d510eb+ * @schema_hash 1bc8702f5edc3115*/-#define ES_EDITOR_API_SCHEMA_HASH "a430f15de6d510eb"+#define ES_EDITOR_API_SCHEMA_HASH "1bc8702f5edc3115"#include <emscripten/bind.h>#include <string>@@ -160,7 +160,8 @@ std::string editor_getComponentSchema(const std::string& name) {{"key":"viewport.w","type":"float","group":"Camera"},{"key":"clearFlags","type":"enum","group":"Camera","values":["Nothing","Color","Depth","ColorAndDepth"]},{"key":"pixelPerfect","type":"bool","group":"Camera"},- {"key":"cullingMask","type":"int","group":"Camera"}+ {"key":"cullingMask","type":"int","group":"Camera"},+ {"key":"renderTarget","type":"int","group":"Camera"}])JSON";} else if (name == "Canvas") {return R"JSON([@@ -1939,6 +1940,7 @@ bool editor_setInt(Registry& reg, u32 e, const std::string& comp, const std::strelse if (field == "priority") { c.priority = static_cast<i32>(value); }else if (field == "clearFlags") { c.clearFlags = static_cast<ClearFlags>(value); }else if (field == "cullingMask") { c.cullingMask = static_cast<u32>(value); }+ else if (field == "renderTarget") { c.renderTarget = static_cast<u32>(value); }else { return false; }return true;} else if (comp == "Canvas") {@@ -2168,6 +2170,7 @@ i32 editor_getInt(Registry& reg, u32 e, const std::string& comp, const std::strielse if (field == "priority") { return static_cast<i32>(c.priority); }else if (field == "clearFlags") { return static_cast<i32>(c.clearFlags); }else if (field == "cullingMask") { return static_cast<i32>(c.cullingMask); }+ else if (field == "renderTarget") { return static_cast<i32>(c.renderTarget); }} else if (comp == "Canvas") {if (!reg.has<esengine::ecs::Canvas>(entity)) return 0;const auto& c = reg.get<esengine::ecs::Canvas>(entity);diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cppindex e9f413f8b..127d24acc 100644--- a/src/esengine/bindings/WebBindings.generated.cpp+++ b/src/esengine/bindings/WebBindings.generated.cpp@@ -316,6 +316,7 @@ struct CameraJS {i32 clearFlags;bool pixelPerfect;u32 cullingMask;+ u32 renderTarget;};void cameraApplyJS(esengine::ecs::Camera& c, const CameraJS& js) {@@ -331,6 +332,7 @@ void cameraApplyJS(esengine::ecs::Camera& c, const CameraJS& js) {c.clearFlags = static_cast<ClearFlags>(js.clearFlags);c.pixelPerfect = js.pixelPerfect;c.cullingMask = js.cullingMask;+ c.renderTarget = js.renderTarget;}esengine::ecs::Camera cameraFromJS(const CameraJS& js) {@@ -353,6 +355,7 @@ CameraJS cameraToJS(const esengine::ecs::Camera& c) {js.clearFlags = static_cast<i32>(c.clearFlags);js.pixelPerfect = c.pixelPerfect;js.cullingMask = c.cullingMask;+ js.renderTarget = c.renderTarget;return js;}@@ -1336,7 +1339,8 @@ EMSCRIPTEN_BINDINGS(esengine_components) {.field("viewport", &CameraJS::viewport).field("clearFlags", &CameraJS::clearFlags).field("pixelPerfect", &CameraJS::pixelPerfect)- .field("cullingMask", &CameraJS::cullingMask);+ .field("cullingMask", &CameraJS::cullingMask)+ .field("renderTarget", &CameraJS::renderTarget);value_object<CanvasJS>("Canvas").field("designResolution", &CanvasJS::designResolution)@@ -2741,6 +2745,7 @@ static_assert(offsetof(esengine::ecs::Camera, viewport) == 32, "ABI offset driftstatic_assert(offsetof(esengine::ecs::Camera, clearFlags) == 48, "ABI offset drift: esengine::ecs::Camera.clearFlags (EHT expected 48)");static_assert(offsetof(esengine::ecs::Camera, pixelPerfect) == 49, "ABI offset drift: esengine::ecs::Camera.pixelPerfect (EHT expected 49)");static_assert(offsetof(esengine::ecs::Camera, cullingMask) == 52, "ABI offset drift: esengine::ecs::Camera.cullingMask (EHT expected 52)");+static_assert(offsetof(esengine::ecs::Camera, renderTarget) == 56, "ABI offset drift: esengine::ecs::Camera.renderTarget (EHT expected 56)");static_assert(offsetof(esengine::ecs::Canvas, designResolution) == 0, "ABI offset drift: esengine::ecs::Canvas.designResolution (EHT expected 0)");static_assert(offsetof(esengine::ecs::Canvas, pixelsPerUnit) == 8, "ABI offset drift: esengine::ecs::Canvas.pixelsPerUnit (EHT expected 8)");static_assert(offsetof(esengine::ecs::Canvas, scaleMode) == 12, "ABI offset drift: esengine::ecs::Canvas.scaleMode (EHT expected 12)");@@ -3065,7 +3070,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif// ABI Hash -- runtime handshake against the SDK bundle// =============================================================================-static const char* kEsAbiLayoutHash = "43f91684e5f3d3fb";+static const char* kEsAbiLayoutHash = "f4ba1e6b5d361dee";std::string esengineGetAbiLayoutHash() {return std::string(kEsAbiLayoutHash);diff --git a/src/esengine/ecs/components/Camera.hpp b/src/esengine/ecs/components/Camera.hppindex 68561cfbe..fb036c0bb 100644--- a/src/esengine/ecs/components/Camera.hpp+++ b/src/esengine/ecs/components/Camera.hpp@@ -121,6 +121,13 @@ struct Camera {ES_PROPERTY(bitmask_source=sortingLayers, tooltip="Which sorting layers this camera renders.")u32 cullingMask{0xFFFFFFFFu};+ /** @brief Offscreen target this camera draws into; 0 = the screen. A RenderTexture+ * handle, so it is created at run time and set from a script — a minimap,+ * a mirror, a portrait rendered once. The camera's viewport covers the+ * whole target, whose own size decides the resolution. */+ ES_PROPERTY(advanced, tooltip="Render into a RenderTexture instead of the screen (0 = screen). Set at run time.")+ u32 renderTarget{0};+Camera() = default;};diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cppindex 9656ec850..8e4d4ca9f 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp@@ -48,6 +48,7 @@ u32 colorVariantOf(WGPUTextureFormat format) {switch (format) {case WGPUTextureFormat_RGBA8UnormSrgb: return WebGPUDevice::kColorSrgb8;case WGPUTextureFormat_RGBA16Float: return WebGPUDevice::kColorRgba16f;+ case WGPUTextureFormat_BGRA8Unorm: return WebGPUDevice::kColorBgra8;default: return WebGPUDevice::kColorRgba8;}}diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hppindex 2792d9bfc..ae48d2562 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp@@ -49,8 +49,13 @@ public:enum DsVariant : u32 { kDsNone = 0, kDsDepthOnly = 1, kDsDepthStencil = 2, kDsVariantCount = 3 };/** @brief Color attachment format of a pass — like DsVariant, WebGPU- * validates the pipeline's color target format against the pass. */- enum ColorVariant : u32 { kColorRgba8 = 0, kColorSrgb8 = 1, kColorRgba16f = 2, kColorVariantCount = 3 };+ * validates the pipeline's color target format against the pass, and+ * BGRA is a DIFFERENT format from RGBA to that check even though both+ * are 8-bit unorm: a surface is usually the former, a render target+ * the latter, so they cannot share a slot. */+ enum ColorVariant : u32 {+ kColorRgba8 = 0, kColorBgra8 = 1, kColorSrgb8 = 2, kColorRgba16f = 3, kColorVariantCount = 4,+ };/** @brief @p device may be null for bookkeeping-only use (tests, bring-up).* @param instance The host's WGPUInstance to share. Web/emscripten passesdiff --git a/tools/render-host/host.ts b/tools/render-host/host.tsindex f817b7100..24e1b136b 100644--- a/tools/render-host/host.ts+++ b/tools/render-host/host.ts@@ -19,6 +19,7 @@ import {loadSceneData, Renderer, instantiatePrefab, writeFieldPath, Transform, Name,getComponent, DeviceStatus, getDeviceStatus, getDeviceLostReport, recoverDevice,finishDeviceRecovery, getContextLossGuardInfo, decodeImagePixels, captureFramePixels,+ RenderTexture, Camera, Sprite,} from 'esengine';import type { App, SceneData, PrefabData, RenderSurfaceSource } from 'esengine';import type { ESEngineModule } from 'esengine/wasm';@@ -490,6 +491,35 @@ window.__estellaHeadless = {if (!mesh?.handle) return 0;return m.meshRenderer_setMeshAll(registry, mesh.handle);},+ /**+ * Point a camera at an offscreen target and show that target on a sprite.+ * The whole claim in one hop: what the first camera drew has to arrive as the+ * second camera's texture, so the probe reads a colour that only exists+ * because a camera rendered somewhere other than the screen.+ */+ renderToTexture: (spec: { camera: number; sprite: number; width: number; height: number }) => {+ if (!app) return null;+ // By the order the scene lists them: a loaded entity's handle carries a+ // generation, so the ids in a scene file are not the World's.+ const loaded = [...app.world.getAllEntities()];+ const camEntity = loaded[spec.camera];+ const spriteEntity = loaded[spec.sprite];+ if (camEntity === undefined || spriteEntity === undefined) return { error: 'entity index out of range' };++ const rt = RenderTexture.create({ width: spec.width, height: spec.height, depth: true });+ const cam = app.world.get(camEntity, Camera) as { renderTarget: number };+ cam.renderTarget = rt._handle;+ app.world.insert(camEntity, Camera, cam as never);+ const sprite = app.world.get(spriteEntity, Sprite) as { texture: number };+ sprite.texture = rt.texture;+ app.world.insert(spriteEntity, Sprite, sprite as never);+ return {+ target: rt._handle,+ texture: rt.texture,+ appliedTarget: (app.world.get(camEntity, Camera) as { renderTarget: number }).renderTarget,+ appliedTexture: (app.world.get(spriteEntity, Sprite) as { texture: number }).texture,+ };+ },loadMaterialAsset: async (path: string) => {const assets = app?.getResource(Assets);const m = module as unknown as { meshRenderer_setMaterialAll?(registry: unknown, id: number): number } | null;diff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjsindex 2e8cdb1dd..ec14ba209 100644--- a/tools/render-host/run.mjs+++ b/tools/render-host/run.mjs@@ -183,6 +183,7 @@ app.whenReady().then(async () => {let deviceLoss = null;let meshResident = null;let meshAsset = null;+ let cameraTarget = null;let meshMaterial = null;let meshPrefab = null;let setField = null;@@ -282,6 +283,18 @@ app.whenReady().then(async () => {})()`);}+ // ESTELLA_VERIFY_CAMERA_TARGET={"camera","sprite","width","height"}: point a+ // camera at an offscreen texture and show that texture on a sprite. Nothing+ // else can produce the probe's colour, so it says the camera drew there.+ if (process.env.ESTELLA_VERIFY_CAMERA_TARGET) {+ const spec = JSON.parse(process.env.ESTELLA_VERIFY_CAMERA_TARGET);+ cameraTarget = await exec(`(async () => {+ const out = window.__estellaHeadless.renderToTexture(${JSON.stringify(spec)});+ await window.__estellaHeadless.api.step(3, 1 / 60);+ return out;+ })()`);+ }+// ESTELLA_VERIFY_SET_FIELD={"entity","component","key","value"} writes one// inspector field the way the editor's own door does, then waits: an asset// assigned after load is COLD, and reaching the World is an async load away.@@ -634,7 +647,7 @@ app.whenReady().then(async () => {};`);}- finish({ ok: true, entityCount, drawCalls, draws, capture, expect, resize, preview, meshPreview, grid, deviceLoss, meshResident, meshAsset, meshMaterial, meshPrefab, setField, pick }, server);+ finish({ ok: true, entityCount, drawCalls, draws, capture, expect, resize, preview, meshPreview, grid, deviceLoss, meshResident, meshAsset, meshMaterial, meshPrefab, setField, pick, cameraTarget }, server);} catch (e) {finish({ ok: false, error: String((e && e.stack) || e) }, server);}diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex bd6bc5a76..ec3fd4362 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -256,6 +256,10 @@ export const SCENES = [// and just outside it, so a box that collapsed or grew is caught without// asking a glyph to land on a given pixel.{ id: "ui-text-box", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/ui-text-uinode.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/ui-text-uinode.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.36,\"y\":0.36,\"rgb\":[46,51,71],\"tol\":20},{\"x\":0.64,\"y\":0.36,\"rgb\":[46,51,71],\"tol\":20},{\"x\":0.5,\"y\":0.7,\"rgb\":[0,0,0],\"tol\":15}]" } },+ // Red at the centre exists only if a camera rendered into a texture: the fill+ // sits on a layer the screen camera culls, and the screen sprite wears that+ // target. webgl2 only — WebGPU has no importExternalTexture yet.+ { id: "camera-render-target", tier: "pr", env: { ESTELLA_VERIFY_SCENE: "/scenes/camera-target.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/camera-target.textures.json", ESTELLA_VERIFY_CAMERA_TARGET: "{\"camera\":0,\"sprite\":3,\"width\":128,\"height\":128}", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":40}]" } },{ id: "material-lit", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-lit.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-lit.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":50}]" } },{ id: "material-lit-point", tier: "pr", webgpu: { ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,253,0],\"tol\":25},{\"x\":0.75,\"y\":0.5,\"rgb\":[0,52,0],\"tol\":25}]" }, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-lit-point.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-lit-point.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":50},{\"x\":0.75,\"y\":0.5,\"rgb\":[0,64,0],\"tol\":60}]" } },{ id: "material-lit-normal", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-lit-normal.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-lit-normal.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.333,\"y\":0.5,\"rgb\":[0,252,0],\"tol\":45},{\"x\":0.667,\"y\":0.5,\"rgb\":[0,36,0],\"tol\":50}]" } },