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(render): a render origin keeps a large world's meshes, lights and probes precise
yhh635e70fc3912
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1f0c60673..1d0d1564c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,7 @@ published separately; it ships inside the editor.### Added+- **A render origin for large worlds.** `setRenderOriginStep(step)` turns on drawing relative to a point near the camera: the origin is the camera's position rounded to `step` and moves only when the camera is further than `step` from it, the renderer takes every mesh, light, probe and shadow bound from it before the GPU sees them, and the camera's view-projection is built for the same origin, so a world tens of kilometres across stops jittering. It is off by default and changes nothing then. The first slice covers meshes, lights, probes, occluders and planar reflections; sprites, particles, trails, UI in the world, post-process height effects and terrain, water and foliage follow.- **A planet's ground has the layers' textures.** `Planet.layers` names up to four `.esterrainlayer` files, as on a flat terrain: each layer's albedo and normal map are read on the planes of the world's axes by how much the ground faces them, with a wider read mixed in far off so the repeat is lost. Without layers the ground is still the four colours.- **A planet's ground collides.** `Planet` takes `collision`, `collisionDistance`, `collisionLayer` and `friction` as flat terrain does: the finest nodes round every moving 3D body and character are built as collision geometry from the same samples the ground is drawn from, one chunk layer to each face of the cube.- **Height Fog by height above a planet.** `heightFog` takes `u_planetRadius` and the planet's centre (`u_planetX/Y/Z`): with a radius above 0 the fog thins with the height above the ground's sphere and not with world Y, so a round world is hazy at its horizon and clear from orbit.diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 956e2693f..c32f3472a 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 115,"beta": 171,- "experimental": 2545,+ "experimental": 2548,"deprecated": 3},- "total": 2831,+ "total": 2834,"subsystems": [{"id": "mobile-controls",diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 53ac26c06..2b2e76d72 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 159 beta · 1864 experimental · 3 deprecated+Symbols: 115 public · 159 beta · 1867 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -2099,6 +2099,7 @@ elapsed: numberregistry: { _cpp: CppRegistry; }renderPolicy: RenderResolution | undefinedrenderTarget: number | undefined+renderViewProjection: Float32Array<ArrayBufferLike> | undefinedviewProjection: Float32Array<ArrayBufferLike>viewportPixels: ViewportworldHeight: number | undefined@@ -7879,6 +7880,14 @@ static prototype: RemovedQueryInstance<any>'webgl2' | 'webgpu' | 'auto'```+## RenderOriginState — interface @experimental+```+step: number+x: number+y: number+z: number+```+## RenderParams — interface @experimental```clearColor: { x: number; y: number; z: number; w: number; } | undefined@@ -7995,7 +8004,7 @@ UIElement = 7## Renderer — const @experimental```-{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }+{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; setOrigin(x: number, y: number, z: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }```## ReplayReport — interface @experimental@@ -15261,6 +15270,11 @@ PrefabsPlugin(module: unknown, mesh: number, w: number, h: number): Promise<ImageData | null>```+## renderOrigin — function @experimental+```+(): Readonly<RenderOriginState>+```+## replay — function @experimental```(scope: SpeculationScope, body: (commands: CommandsInstance) => SpeculationOutcome): ReplayReport@@ -15611,6 +15625,11 @@ ServicesPlugin(active: boolean): void```+## setRenderOriginStep — function @experimental+```+(step: number): void+```+## setRetainedBudget — function @experimental```(bytes: number): voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 7741b72ba..b03abfc6b 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 164 beta · 1883 experimental · 3 deprecated+Symbols: 115 public · 164 beta · 1886 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -2099,6 +2099,7 @@ elapsed: numberregistry: { _cpp: CppRegistry; }renderPolicy: RenderResolution | undefinedrenderTarget: number | undefined+renderViewProjection: Float32Array<ArrayBufferLike> | undefinedviewProjection: Float32Array<ArrayBufferLike>viewportPixels: ViewportworldHeight: number | undefined@@ -8092,6 +8093,14 @@ static prototype: RemovedQueryInstance<any>'webgl2' | 'webgpu' | 'auto'```+## RenderOriginState — interface @experimental+```+step: number+x: number+y: number+z: number+```+## RenderParams — interface @experimental```clearColor: { x: number; y: number; z: number; w: number; } | undefined@@ -8208,7 +8217,7 @@ UIElement = 7## Renderer — const @experimental```-{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }+{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; setOrigin(x: number, y: number, z: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }```## ReplayReport — interface @experimental@@ -15524,6 +15533,11 @@ PrefabsPlugin(module: unknown, mesh: number, w: number, h: number): Promise<ImageData | null>```+## renderOrigin — function @experimental+```+(): Readonly<RenderOriginState>+```+## replay — function @experimental```(scope: SpeculationScope, body: (commands: CommandsInstance) => SpeculationOutcome): ReplayReport@@ -15874,6 +15888,11 @@ ServicesPlugin(active: boolean): void```+## setRenderOriginStep — function @experimental+```+(step: number): void+```+## setRetainedBudget — function @experimental```(bytes: number): voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex d0797729e..78391bccb 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 161 beta · 1863 experimental · 3 deprecated+Symbols: 115 public · 161 beta · 1866 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -2094,6 +2094,7 @@ elapsed: numberregistry: { _cpp: CppRegistry; }renderPolicy: RenderResolution | undefinedrenderTarget: number | undefined+renderViewProjection: Float32Array<ArrayBufferLike> | undefinedviewProjection: Float32Array<ArrayBufferLike>viewportPixels: ViewportworldHeight: number | undefined@@ -7874,6 +7875,14 @@ static prototype: RemovedQueryInstance<any>'webgl2' | 'webgpu' | 'auto'```+## RenderOriginState — interface @experimental+```+step: number+x: number+y: number+z: number+```+## RenderParams — interface @experimental```clearColor: { x: number; y: number; z: number; w: number; } | undefined@@ -7990,7 +7999,7 @@ UIElement = 7## Renderer — const @experimental```-{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }+{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; setOrigin(x: number, y: number, z: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }```## ReplayReport — interface @experimental@@ -15266,6 +15275,11 @@ PrefabsPlugin(module: unknown, mesh: number, w: number, h: number): Promise<ImageData | null>```+## renderOrigin — function @experimental+```+(): Readonly<RenderOriginState>+```+## replay — function @experimental```(scope: SpeculationScope, body: (commands: CommandsInstance) => SpeculationOutcome): ReplayReport@@ -15616,6 +15630,11 @@ ServicesPlugin(active: boolean): void```+## setRenderOriginStep — function @experimental+```+(step: number): void+```+## setRetainedBudget — function @experimental```(bytes: number): voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 2eb142101..b3d353c97 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 159 beta · 1885 experimental · 3 deprecated+Symbols: 115 public · 159 beta · 1888 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -2094,6 +2094,7 @@ elapsed: numberregistry: { _cpp: CppRegistry; }renderPolicy: RenderResolution | undefinedrenderTarget: number | undefined+renderViewProjection: Float32Array<ArrayBufferLike> | undefinedviewProjection: Float32Array<ArrayBufferLike>viewportPixels: ViewportworldHeight: number | undefined@@ -8167,6 +8168,14 @@ static prototype: RemovedQueryInstance<any>'webgl2' | 'webgpu' | 'auto'```+## RenderOriginState — interface @experimental+```+step: number+x: number+y: number+z: number+```+## RenderParams — interface @experimental```clearColor: { x: number; y: number; z: number; w: number; } | undefined@@ -8283,7 +8292,7 @@ UIElement = 7## Renderer — const @experimental```-{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }+{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; setOrigin(x: number, y: number, z: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }```## ReplayReport — interface @experimental@@ -15570,6 +15579,11 @@ PrefabsPlugin(module: unknown, mesh: number, w: number, h: number): Promise<ImageData | null>```+## renderOrigin — function @experimental+```+(): Readonly<RenderOriginState>+```+## replay — function @experimental```(scope: SpeculationScope, body: (commands: CommandsInstance) => SpeculationOutcome): ReplayReport@@ -15920,6 +15934,11 @@ ServicesPlugin(active: boolean): void```+## setRenderOriginStep — function @experimental+```+(step: number): void+```+## setRetainedBudget — function @experimental```(bytes: number): voiddiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 325716d70..d46783ff7 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -517,6 +517,7 @@ renderer_setDepthLayers: ((mask: number) => void) | undefinedrenderer_setEntityDrawOrder: ((registry: CppRegistry, entitiesPtr: number, count: number) => void) | undefinedrenderer_setLodPreview: ((view: number, entity: number, level: number) => void) | undefinedrenderer_setMeshEdgeBuffers: ((enabled: boolean) => void) | undefined+renderer_setOrigin: ((x: number, y: number, z: number) => void) | undefinedrenderer_setPlanarReflectionQuality: ((scale: number, maxSize: number, updatesPerSecond: number) => void) | undefinedrenderer_setQualityBudgets: ((atlasSize: number, cellSize: number, cascades: number, particleLimit: number) => void) | undefinedrenderer_setShadowDistance: ((distance: number) => void) | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 666d98163..83b45aa17 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 159 beta · 1876 experimental · 3 deprecated+Symbols: 115 public · 159 beta · 1879 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -2094,6 +2094,7 @@ elapsed: numberregistry: { _cpp: CppRegistry; }renderPolicy: RenderResolution | undefinedrenderTarget: number | undefined+renderViewProjection: Float32Array<ArrayBufferLike> | undefinedviewProjection: Float32Array<ArrayBufferLike>viewportPixels: ViewportworldHeight: number | undefined@@ -7881,6 +7882,14 @@ static prototype: RemovedQueryInstance<any>'webgl2' | 'webgpu' | 'auto'```+## RenderOriginState — interface @experimental+```+step: number+x: number+y: number+z: number+```+## RenderParams — interface @experimental```clearColor: { x: number; y: number; z: number; w: number; } | undefined@@ -7997,7 +8006,7 @@ UIElement = 7## Renderer — const @experimental```-{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }+{ init(width: number, height: number): void; resize(width: number, height: number): void; beginFrame(elapsedSec?: number): void; setOrigin(x: number, y: number, z: number): void; updateTransforms(registry: { _cpp: CppRegistry; }): void; begin(viewProjection: Float32Array, target?: RenderTargetHandle, clearFlags?: number, clearColor?: { x: number; y: number; z: number; w: number; }, clearRect?: { x: number; y: number; w: number; h: number; }): void; flush(): void; end(): void; endFrame(): void; hasScreenOverlay(): boolean; beginScreenOverlay(projection: Float32Array, vpX: number, vpY: number, vpW: number, vpH: number): void; submitScreenOverlay(registry: { _cpp: CppRegistry; }): void; endScreenOverlay(target?: RenderTargetHandle): void; submitAll(registry: { _cpp: CppRegistry; }, vpX: number, vpY: number, vpW: number, vpH: number): void; setStage(stage: RenderStage): void; createRenderTarget(width: number, height: number, flags?: number): RenderTargetHandle; releaseRenderTarget(handle: RenderTargetHandle): void; getTargetTexture(handle: RenderTargetHandle): number; getTargetDepthTexture(handle: RenderTargetHandle): number; setClearColor(r: number, g: number, b: number, a: number): void; setViewport(x: number, y: number, w: number, h: number): void; setYSortLayers(mask: number): void; setDepthLayers(mask: number): void; setCullingMask(mask: number): void; setViewId(view: number): void; lodInspect(view: number, entity: number): LodDecision | null; setLodPreview(view: number, entity: number, level: number | null): void; setViewShading(view: number, mode: ViewShading): void; setMeshEdgeBuffers(enabled: boolean): void; setViewSkinWeights(view: number, entity: number | null, joint?: number): void; lightStatus(entity: number): LightStatus | null; shadowStatus(entity: number): ShadowStatus | null; setTextureParams(textureId: number, minFilter: number, magFilter: number, wrapS: number, wrapT: number): void; measureBitmapText(fontHandle: number, text: string, fontSize: number, spacing: number): { width: number; height: number; }; getStats(): RenderStats; captureNextFrame(): void; getCapturedData(): FrameCaptureData | null; hasCapturedData(): boolean; replayToDrawCall(drawCallIndex: number): void; getSnapshotImageData(): Promise<ImageData | null>; snapshotMatchesCapture(): boolean; }```## ReplayReport — interface @experimental@@ -15297,6 +15306,11 @@ PrefabsPlugin(module: unknown, mesh: number, w: number, h: number): Promise<ImageData | null>```+## renderOrigin — function @experimental+```+(): Readonly<RenderOriginState>+```+## replay — function @experimental```(scope: SpeculationScope, body: (commands: CommandsInstance) => SpeculationOutcome): ReplayReport@@ -15647,6 +15661,11 @@ ServicesPlugin(active: boolean): void```+## setRenderOriginStep — function @experimental+```+(step: number): void+```+## setRetainedBudget — function @experimental```(bytes: number): voiddiff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.tsindex c94e46fe1..10dd57726 100644--- a/sdk/src/camera/CameraPlugin.ts+++ b/sdk/src/camera/CameraPlugin.ts@@ -25,13 +25,14 @@ import { uiLayoutRect, computeEffectiveOrthoSize, EDITOR_VIEW_ENTITY, type Canvaimport { EditorViewLighting, DEFAULT_EDITOR_VIEW_LIGHTING, pushEditorViewLighting } from './EditorViewLighting';import { EditorViewShading, DEFAULT_EDITOR_VIEW_SHADING, pushEditorViewShading, pushEditorViewWeights } from './EditorViewShading';import type { ViewShading } from '../render/renderer';-import { EditorView, DEFAULT_EDITOR_VIEW, editorViewStandoff, editorViewClipFar, editorViewClipNear, type EditorViewData } from './EditorView';+import { EditorView, DEFAULT_EDITOR_VIEW, editorViewStandoff, editorViewEye, editorViewClipFar, editorViewClipNear, type EditorViewData } from './EditorView';import { ScreenScaling, DEFAULT_SCREEN_SCALING, SCREEN_FIT_OFF } from './ScreenScaling';import { planPresent, viewportPixels, RenderResolution } from './presentPlan';import { CameraDirector, createDirectorState, resolveMainPOV } from './CameraDirector';import { RenderPipeline } from '../render/renderPipeline';import { renderTargetSize } from '../render/renderTexture';import { Renderer } from '../render/renderer';+import { followRenderOrigin, pushRenderOrigin, renderOrigin } from '../render/renderOrigin';import { platformNow, platformDevicePixelRatio } from '../platform';import { SceneManager } from '../scene/sceneManager';import {@@ -46,6 +47,8 @@ import {interface CameraInfo {entity: number;viewProjection: Float32Array;+ /** The same view-projection for the render origin (render/renderOrigin.ts): what the renderer is begun with. Equal to `viewProjection` while the origin is zero. */+ renderViewProjection: Float32Array;viewportRect: { x: number; y: number; w: number; h: number };clearFlags: number;priority: number;@@ -65,6 +68,7 @@ function acquireCameraInfo(pool: CameraInfo[], index: number): CameraInfo {const info: CameraInfo = {entity: 0,viewProjection: new Float32Array(16),+ renderViewProjection: new Float32Array(16),viewportRect: { x: 0, y: 0, w: 0, h: 0 },clearFlags: 0,priority: 0,@@ -336,6 +340,18 @@ export function buildCameraInfo(const cam = acquireCameraInfo(pool, index);cam.entity = pov.entity;cam.viewProjection.set(multiply(projection, view));+ const origin = renderOrigin();+ if (origin.x === 0 && origin.y === 0 && origin.z === 0) {+ cam.renderViewProjection.set(cam.viewProjection);+ } else {+ // The same view with the eye measured from the origin; the projection is the same.+ const near = pov.orbit+ ? invertViewOrbit(camX - origin.x, camY - origin.y, pov.orbit.focusZ - origin.z, pov.orbit.yaw, pov.orbit.pitch, pov.z)+ : pov.tilt+ ? invertViewQuat(camX - origin.x, camY - origin.y, pov.z - origin.z, pov.tilt.x, pov.tilt.y, pov.tilt.z, pov.tilt.w)+ : invertViewZ(camX - origin.x, camY - origin.y, pov.z - origin.z, Math.cos(pov.rotation), Math.sin(pov.rotation));+ cam.renderViewProjection.set(multiply(projection, near));+ }cam.viewportRect.x = pov.viewport.x;cam.viewportRect.y = pov.viewport.y;cam.viewportRect.w = pov.viewport.z;@@ -527,6 +543,7 @@ function resolveCameras(if (app.hasResource(EditorView)) {const view = app.getResource(EditorView);if (view.active && width > 0 && height > 0) {+ if (advance) { const eye = editorViewEye(view); followRenderOrigin(eye.x, eye.y, eye.z); }return [editorCameraInfo(view, width, height, pool)];}}@@ -542,6 +559,11 @@ function resolveCameras(const fullFrame = onScreen.filter((p) => isFullFrame(p.viewport));const overlays = onScreen.filter((p) => !isFullFrame(p.viewport)).sort((a, b) => a.priority - b.priority);+ // The origin follows the screen's own camera, before any view is built for it.+ if (advance) {+ const eye = fullFrame[0] ?? onScreen[0];+ if (eye) followRenderOrigin(eye.x, eye.y, eye.z);+ }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@@ -877,6 +899,8 @@ export function cameraPlugin(const cameras = app.measureFrameScope('render.resolveCameras', () =>resolveCameras(app, module, cppRegistry, width, height, app.world, activeScenes, cameraInfoPool, elapsed, true));+ pushRenderOrigin((x, y, z) => { Renderer.setOrigin(x, y, z); });+app.measureFrameScope('render.uiCameraSync', () =>syncUICameraInfo(app, module, cppRegistry, width, height, cameras));@@ -915,6 +939,7 @@ export function cameraPlugin(pipeline.renderCamera({registry: { _cpp: cppRegistry },viewProjection: cam.viewProjection,+ renderViewProjection: cam.renderViewProjection,viewportPixels: { x: px, y: py, w: pw, h: ph },clearFlags: cam.clearFlags,elapsed,@@ -1009,7 +1034,7 @@ export function renderCameraFrame(app: App, width: number, height: number, entitpipeline.beginScreenCapture();for (const cam of cameras) {const rect = viewportPixels(cam.viewportRect, width, height);- pipeline.renderCamera({ registry: { _cpp: registry }, viewProjection: cam.viewProjection,+ pipeline.renderCamera({ registry: { _cpp: registry }, viewProjection: cam.viewProjection, renderViewProjection: cam.renderViewProjection,viewportPixels: rect, clearFlags: cam.clearFlags, elapsed, cameraEntity: cam.entity,clearColor, cullingMask: cam.cullingMask, worldHeight: 2 * cam.halfH, renderPolicy: policy });}diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex ca62fafcc..4fb8fdbf3 100644--- a/sdk/src/core-render.ts+++ b/sdk/src/core-render.ts@@ -318,6 +318,7 @@ export {type RenderParams,type CameraRenderParams,} from './render/renderPipeline';+export { setRenderOriginStep, renderOrigin, type RenderOriginState } from './render/renderOrigin';// =============================================================================// Custom Draw Callbacksdiff --git a/sdk/src/ecs/bridge/nativeBindings.ts b/sdk/src/ecs/bridge/nativeBindings.tsindex e01066ba0..a7e2c69e1 100644--- a/sdk/src/ecs/bridge/nativeBindings.ts+++ b/sdk/src/ecs/bridge/nativeBindings.ts@@ -183,6 +183,8 @@ export const HOST_FLAGS = {* here and is called through the optional path.*/export const RENDERER_OPTIONAL_BINDINGS = {+ /** The render origin (render/renderOrigin.ts); a host predating it draws relative to zero. */+ setOrigin: 'es_renderer_setOrigin',/** 2.5D depth layers; hosts predating the feature simply stay painter-ordered. */setDepthLayers: 'es_renderer_setDepthLayers',/** Camera culling mask; hosts predating it draw every layer, as they always did. */diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex b4c524e04..f3cbd5ba6 100644--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts@@ -213,6 +213,7 @@ export interface NativeEngineApi {renderer_setEntityDrawOrder?(registry: unknown, entitiesPtr: number, count: number): void;renderer_setLodPreview?(view: number, entity: number, level: number): void;renderer_setMeshEdgeBuffers?(enabled: boolean): void;+ renderer_setOrigin?(x: number, y: number, z: number): void;renderer_setPlanarReflectionQuality?(scale: number, maxSize: number, updatesPerSecond: number): void;renderer_setQualityBudgets?(atlasSize: number, cellSize: number, cascades: number, particleLimit: number): void;renderer_setShadowDistance?(distance: number): void;@@ -538,6 +539,7 @@ export function createNativeEngineApi(bind('renderer_setEntityDrawOrder', 'es_renderer_setEntityDrawOrder', true);bind('renderer_setLodPreview', 'es_renderer_setLodPreview', false);bind('renderer_setMeshEdgeBuffers', 'es_renderer_setMeshEdgeBuffers', false);+ bind('renderer_setOrigin', 'es_renderer_setOrigin', false);bind('renderer_setPlanarReflectionQuality', 'es_renderer_setPlanarReflectionQuality', false);bind('renderer_setQualityBudgets', 'es_renderer_setQualityBudgets', false);bind('renderer_setShadowDistance', 'es_renderer_setShadowDistance', false);diff --git a/sdk/src/ecs/bridge/nativeRenderer.ts b/sdk/src/ecs/bridge/nativeRenderer.tsindex 559b5e6d4..a73bf659b 100644--- a/sdk/src/ecs/bridge/nativeRenderer.ts+++ b/sdk/src/ecs/bridge/nativeRenderer.ts@@ -80,6 +80,9 @@ export function createNativeRendererBackend(beginFrame: (elapsedSec): void => {hostCall(scope, RENDERER_BINDINGS.beginFrame, [elapsedSec]);},+ setOrigin: (x, y, z): void => {+ optional(scope, RENDERER_OPTIONAL_BINDINGS.setOrigin)?.(x, y, z);+ },updateTransforms: (_registry: CppRegistry): void => {hostCall(scope, RENDERER_BINDINGS.updateTransforms, []);},diff --git a/sdk/src/render/renderOrigin.ts b/sdk/src/render/renderOrigin.tsnew file mode 100644index 000000000..0a90f3995--- /dev/null+++ b/sdk/src/render/renderOrigin.ts@@ -0,0 +1,61 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file renderOrigin.ts+ * @brief The point a frame is drawn relative to, so a world far from zero keeps its precision on the GPU.+ *+ * @details Single floats hold a position well only near zero: at 50 km from it a step is 4 mm, and the vertices of a mesh there jitter as the+ * camera moves. The renderer takes every world position from an origin near the camera before it reaches the GPU, and the camera's+ * view-projection is built for the same origin, so the picture is the same and the numbers in it are small. The origin is the+ * camera's position rounded to `step`, and it stays where it is until the camera is further than `step` from it: shadow maps, the+ * light grid and other caches that are laid out on the world's grid step only when it does, not with every frame. Off (step 0) it is+ * zero, which changes nothing.+ */+export interface RenderOriginState {+ /** The grid the origin is rounded to, and how far the camera goes from it before it moves; 0 draws relative to the world's own zero. */+ step: number;+ x: number;+ y: number;+ z: number;+}++const state: RenderOriginState = { step: 0, x: 0, y: 0, z: 0 };+let pushed = { x: 0, y: 0, z: 0 };++/** The origin now. Read-only: it moves by {@link followRenderOrigin}. */+export function renderOrigin(): Readonly<RenderOriginState> {+ return state;+}++/** Turns the origin on (a step above 0, in world units) or off (0). Turning it off returns it to zero. */+export function setRenderOriginStep(step: number): void {+ state.step = Math.max(step, 0);+ if (state.step === 0) { state.x = 0; state.y = 0; state.z = 0; }+}++/**+ * Keeps the origin near the eye: it moves to the eye rounded to `step` once the eye is further than `step` from it. True if it moved.+ * Call it before the frame's cameras are built, with the eye the frame is drawn from.+ */+export function followRenderOrigin(eyeX: number, eyeY: number, eyeZ: number): boolean {+ const step = state.step;+ if (step <= 0) return false;+ if (Math.abs(eyeX - state.x) <= step && Math.abs(eyeY - state.y) <= step && Math.abs(eyeZ - state.z) <= step) return false;+ state.x = Math.round(eyeX / step) * step;+ state.y = Math.round(eyeY / step) * step;+ state.z = Math.round(eyeZ / step) * step;+ return true;+}++/** Hands the origin to the engine if it is not what the engine was last given. */+export function pushRenderOrigin(set: (x: number, y: number, z: number) => void): void {+ if (pushed.x === state.x && pushed.y === state.y && pushed.z === state.z) return;+ pushed = { x: state.x, y: state.y, z: state.z };+ set(state.x, state.y, state.z);+}++/** @internal Forgets what the engine was given (a new engine starts at zero). */+export function resetRenderOrigin(): void {+ state.step = 0; state.x = 0; state.y = 0; state.z = 0;+ pushed = { x: 0, y: 0, z: 0 };+}diff --git a/sdk/src/render/renderPipeline.ts b/sdk/src/render/renderPipeline.tsindex 6acf2491f..9b2593ebd 100644--- a/sdk/src/render/renderPipeline.ts+++ b/sdk/src/render/renderPipeline.ts@@ -47,6 +47,8 @@ export interface RenderParams {export interface CameraRenderParams {registry: { _cpp: CppRegistry };viewProjection: Float32Array;+ /** The view-projection for the render origin, which the renderer is begun with; absent, `viewProjection` (the origin is zero). */+ renderViewProjection?: Float32Array;viewportPixels: Viewport;clearFlags: number;elapsed: number;@@ -290,7 +292,7 @@ export class RenderPipeline {Renderer.setViewport(scene.x, scene.y, scene.w, scene.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, params.renderTarget ?? 0, clearFlags, params.clearColor, scene);+ Renderer.begin(params.renderViewProjection ?? viewProjection, params.renderTarget ?? 0, clearFlags, params.clearColor, scene);// Set after begin (which clears the draw list) and before the collect it gates.Renderer.setCullingMask(params.cullingMask ?? 0xFFFFFFFF);// The camera IS the view: a level picked from how big something looks isdiff --git a/sdk/src/render/renderer.ts b/sdk/src/render/renderer.tsindex 014ed7d4a..bef7b1295 100644--- a/sdk/src/render/renderer.ts+++ b/sdk/src/render/renderer.ts@@ -47,6 +47,8 @@ export interface RendererBackend {init(width: number, height: number): void;resize(width: number, height: number): void;beginFrame(elapsedSec: number): void;+ /** The point the frames are drawn relative to (render/renderOrigin.ts). A host predating it draws relative to zero. */+ setOrigin?(x: number, y: number, z: number): void;updateTransforms(registry: CppRegistry): void;begin(viewProjection: Float32Array, target: number, clearFlags: number,r: number, g: number, b: number, a: number,@@ -175,6 +177,7 @@ function wasmBackend(m: ESEngineModule): RendererBackend {init: (width, height) => m.renderer_init(width, height),resize: (width, height) => m.renderer_resize(width, height),beginFrame: (elapsedSec) => m.renderer_beginFrame(elapsedSec),+ setOrigin: (x, y, z) => { m.renderer_setOrigin?.(x, y, z); },updateTransforms: (registry) => {try {m.renderer_updateTransforms(registry);@@ -555,6 +558,10 @@ export const Renderer = {backend?.beginFrame(elapsedSec);},+ setOrigin(x: number, y: number, z: number): void {+ backend?.setOrigin?.(x, y, z);+ },+updateTransforms(registry: { _cpp: CppRegistry }): void {backend?.updateTransforms(registry._cpp);},diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex dff76dc54..2e8995c72 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -572,6 +572,7 @@ export interface ESEngineModule {renderer_init(width: number, height: number): void;renderer_resize(width: number, height: number): void;renderer_beginFrame(elapsedSec: number): void;+ renderer_setOrigin?(x: number, y: number, z: number): void;renderer_updateTransforms(registry: CppRegistry): void;/** Address of the transform composition's staleness counter, so a producer* stores into linear memory rather than calling across it. */diff --git a/sdk/tests/render-origin.test.ts b/sdk/tests/render-origin.test.tsnew file mode 100644index 000000000..09e576d43--- /dev/null+++ b/sdk/tests/render-origin.test.ts@@ -0,0 +1,60 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { afterEach, describe, expect, it } from 'vitest';+import { buildCameraInfo, type CameraPOV } from '../src/camera/CameraPlugin';+import { ProjectionType, ClearFlags } from '../src/ecs/component';+import { followRenderOrigin, pushRenderOrigin, renderOrigin, resetRenderOrigin, setRenderOriginStep } from '../src/render/renderOrigin';++const pov = (over: Partial<CameraPOV>): CameraPOV => ({+ entity: -1, isActive: true, x: 0, y: 0, z: 0, rotation: 0, projection: ProjectionType.Perspective, orthoSize: 10, fov: 60, near: 0.1, far: 100000,+ viewport: { x: 0, y: 0, z: 1, w: 1 }, clearFlags: ClearFlags.ColorAndDepth, priority: 0, pixelPerfect: false, ...over,+});++const clip = (m: Float32Array, p: [number, number, number]): [number, number, number, number] =>+ [0, 1, 2, 3].map((r) => m[r] * p[0] + m[4 + r] * p[1] + m[8 + r] * p[2] + m[12 + r]) as [number, number, number, number];++afterEach(resetRenderOrigin);++describe('the render origin', () => {+ it('is zero, and the render view is the view, while it is off', () => {+ const cam = buildCameraInfo(pov({ x: 5, y: 2, z: 9 }), 800, 600, null, [], 0);+ expect(Array.from(cam.renderViewProjection)).toEqual(Array.from(cam.viewProjection));+ expect(followRenderOrigin(1e6, 0, 0)).toBe(false);+ expect(renderOrigin()).toMatchObject({ x: 0, y: 0, z: 0 });+ });++ it('stays where it is until the eye is further than a step, then moves to the eye rounded to the step', () => {+ setRenderOriginStep(1000);+ expect(followRenderOrigin(900, -900, 300)).toBe(false);+ expect(followRenderOrigin(2600, 10, -4100)).toBe(true);+ expect(renderOrigin()).toMatchObject({ x: 3000, y: 0, z: -4000 });+ expect(followRenderOrigin(3400, 10, -4100)).toBe(false);+ });++ it('draws a point relative to the origin where the view draws it relative to the world', () => {+ setRenderOriginStep(1000);+ followRenderOrigin(40000, 30, 60000);+ const o = renderOrigin();+ for (const p of [+ pov({ x: 40000, y: 30, z: 60000 }),+ pov({ x: 40000, y: 30, z: 60000, tilt: { x: 0.1, y: 0.3, z: 0, w: 0.95 } }),+ pov({ x: 40000, y: 30, z: 20, orbit: { yaw: 0.4, pitch: 0.3, focusZ: 60000 } }),+ ]) {+ const cam = buildCameraInfo(p, 800, 600, null, [], 0);+ const world: [number, number, number] = [40003, 31, 59990];+ const a = clip(cam.viewProjection, world);+ const b = clip(cam.renderViewProjection, [world[0] - o.x, world[1] - o.y, world[2] - o.z]);+ for (let i = 0; i < 4; i++) expect(b[i]).toBeCloseTo(a[i]!, 1);+ }+ });++ it('is handed to the engine once for each place it stands', () => {+ const seen: number[][] = [];+ setRenderOriginStep(10);+ pushRenderOrigin((x, y, z) => seen.push([x, y, z]));+ followRenderOrigin(100, 0, 0);+ pushRenderOrigin((x, y, z) => seen.push([x, y, z]));+ pushRenderOrigin((x, y, z) => seen.push([x, y, z]));+ expect(seen).toEqual([[100, 0, 0]]);+ });+});diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex 115607a57..ac8af1c84 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -623,6 +623,11 @@ void renderer_resize(u32 width, u32 height) {g_renderFrame->resize(width, height);}+/// The point the next frames are drawn relative to (RenderOrigin.hpp); the view-projection they are begun with is built for the same one.+void renderer_setOrigin(f64 x, f64 y, f64 z) {+ setRenderOrigin(glm::dvec3(x, y, z));+}+void renderer_beginFrame(f32 elapsedSec) {// A render frame is not a mutation: composition is invalidated by the// producers that write transform inputs. A server has no frames, and onediff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hppindex c930d01c8..2b14baa75 100644--- a/src/esengine/bindings/RendererBindings.hpp+++ b/src/esengine/bindings/RendererBindings.hpp@@ -36,6 +36,7 @@ std::string renderer_getPlanarReflectionStatus(u32 view, u32 entity);void renderer_setViewLighting(u32 mode, f32 rotationDegrees, f32 keyIntensity, f32 fillIntensity,f32 skyIntensity, bool showSky);void renderer_beginFrame(f32 elapsedSec);+void renderer_setOrigin(f64 x, f64 y, f64 z);void renderer_begin(uintptr_t matrixPtr, u32 targetHandle, i32 clearFlags,f32 r, f32 g, f32 b, f32 a,i32 clearX, i32 clearY, u32 clearW, u32 clearH);diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex e9eb9c812..358434ecc 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -670,6 +670,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("renderer_init", &esengine::renderer_init);emscripten::function("renderer_resize", &esengine::renderer_resize);emscripten::function("renderer_beginFrame", &esengine::renderer_beginFrame);+ emscripten::function("renderer_setOrigin", &esengine::renderer_setOrigin);emscripten::function("renderer_begin", &esengine::renderer_begin);emscripten::function("renderer_flush", &esengine::renderer_flush);emscripten::function("renderer_end", &esengine::renderer_end);diff --git a/src/esengine/renderer/RenderOrigin.hpp b/src/esengine/renderer/RenderOrigin.hppnew file mode 100644index 000000000..5b1ab12e7--- /dev/null+++ b/src/esengine/renderer/RenderOrigin.hpp@@ -0,0 +1,31 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file RenderOrigin.hpp+ * @brief The point the frame is drawn relative to: a world far from zero loses precision in single floats, so positions go to the GPU as+ * offsets from a point near the camera.+ *+ * @details The view-projection a frame is begun with is built by the host for the same origin (the camera near zero), and every world position+ * the renderer hands the GPU is taken from it first, so the product on the GPU is the same and the numbers in it are small. Zero is+ * the default and changes nothing. One origin serves the whole frame, a shadow pass's draws included, so it is set between frames.+ */+#pragma once++#include <glm/glm.hpp>++namespace esengine {++/// The origin, in world units. A double, as the world positions it is taken from are far from zero.+inline glm::dvec3& renderOrigin() {+ static glm::dvec3 origin{0.0};+ return origin;+}++inline void setRenderOrigin(const glm::dvec3& origin) { renderOrigin() = origin; }++/// A world position as the frame draws it: from the origin.+inline glm::vec3 rebased(const glm::vec3& world) {+ return glm::vec3(glm::dvec3(world) - renderOrigin());+}++} // namespace esenginediff --git a/src/esengine/renderer/RenderTypePlugin.hpp b/src/esengine/renderer/RenderTypePlugin.hppindex faab2268a..da250d61f 100644--- a/src/esengine/renderer/RenderTypePlugin.hpp+++ b/src/esengine/renderer/RenderTypePlugin.hpp@@ -3,6 +3,7 @@#pragma once#include "../core/Types.hpp"+#include "./RenderOrigin.hpp"#include "./frame/RenderStage.hpp"#include "./frame/Frustum.hpp"#include "./frame/OcclusionView.hpp"@@ -389,7 +390,7 @@ inline glm::vec3 ribbonSide(const glm::vec3& tangent, const glm::vec3& worldPos,inline glm::vec3 parallaxedWorldPosition(ecs::Transform& transform, const glm::vec2& parallax,const CameraView& camera) {transform.ensureDecomposed();- glm::vec3 position = transform.worldPosition;+ glm::vec3 position = rebased(transform.worldPosition);position.x += camera.center.x * (1.0f - parallax.x);position.y += camera.center.y * (1.0f - parallax.y);return position;diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex 1e0c28482..feb0040c7 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -1361,7 +1361,7 @@ void RenderFrame::collectProbes(ecs::Registry& registry) {// solved on world axes, so a turned volume would be read along axes it// never had. Scale is not read for the same reason.const auto* transform = registry.tryGet<ecs::Transform>(entity);- const glm::vec3 centre = transform ? glm::vec3(transform->worldPosition) : glm::vec3(0.0f);+ const glm::vec3 centre = transform ? rebased(transform->worldPosition) : rebased(glm::vec3(0.0f));const glm::vec3 half = glm::abs(volume.halfExtents);probes.add(centre - half, centre + half, grid);}@@ -1387,7 +1387,7 @@ void RenderFrame::collectOccluders(ecs::Registry& registry) {// Scale is not read, matching every other authored extent and the box the// viewport draws: one value, two readers, and the picture an author places// the box by IS what the cull uses.- occlusion_.addBox(transform->worldPosition, transform->worldRotation,+ occlusion_.addBox(rebased(transform->worldPosition), transform->worldRotation,glm::abs(occluder.halfExtents));}occlusion_.finish();@@ -1411,7 +1411,7 @@ void RenderFrame::collectReflections(ecs::Registry& registry) {if (!probe.enabled || !probe.reflection.isValid()) continue;const auto* transform = registry.tryGet<ecs::Transform>(entity);if (!transform) continue;- const glm::vec3 centre = glm::vec3(transform->worldPosition);+ const glm::vec3 centre = rebased(transform->worldPosition);const glm::vec3 half = glm::abs(probe.halfExtents);store.add(centre - half, centre + half, probe.slot, probe.reflection.id());}@@ -1584,7 +1584,7 @@ void RenderFrame::collectLights(ecs::Registry& registry) {auto* transform = registry.tryGet<ecs::Transform>(entity);if (!transform) continue; // a positional light with no position casts nothingtransform->ensureDecomposed();- const glm::vec3 p = transform->worldPosition;+ const glm::vec3 p = rebased(transform->worldPosition);const f32 typeId = (type == ecs::LightType::Spot) ? 2.0f : 0.0f;gpu.posDir = glm::vec4(p.x, p.y, typeId, light.radius);// The height a surface with real geometry measures against. A sprite has no@@ -1795,7 +1795,7 @@ bool RenderFrame::meshWorldBounds(ecs::Registry& registry, glm::vec3& outMin, glauto& transform = meshes.get<ecs::Transform>(entity);transform.ensureDecomposed();glm::vec3 centre(0.0f), half(0.0f);- orientedWorldAabb(transform.worldPosition, transform.worldRotation, transform.worldScale,+ orientedWorldAabb(rebased(transform.worldPosition), transform.worldRotation, transform.worldScale,resident->localMin, resident->localMax, centre, half);outMin = any ? glm::min(outMin, centre - half) : centre - half;outMax = any ? glm::max(outMax, centre + half) : centre + half;@@ -1816,7 +1816,7 @@ bool RenderFrame::hairWorldBounds(ecs::Registry& registry, glm::vec3& outMin, glauto& transform = meshes.get<ecs::Transform>(entity);transform.ensureDecomposed();glm::vec3 centre(0.0f), half(0.0f);- orientedWorldAabb(transform.worldPosition, transform.worldRotation, transform.worldScale,+ orientedWorldAabb(rebased(transform.worldPosition), transform.worldRotation, transform.worldScale,resident->localMin, resident->localMax, centre, half);outMin = any ? glm::min(outMin, centre - half) : centre - half;outMax = any ? glm::max(outMax, centre + half) : centre + half;diff --git a/src/esengine/renderer/frame/RenderFramePlanar.cpp b/src/esengine/renderer/frame/RenderFramePlanar.cppindex 02cb53a18..e631c03c7 100644--- a/src/esengine/renderer/frame/RenderFramePlanar.cpp+++ b/src/esengine/renderer/frame/RenderFramePlanar.cpp@@ -46,14 +46,14 @@ void RenderFrame::declarePlanarReflection(ecs::Registry& registry) {auto& transform = surfaces.get<ecs::Transform>(entity);transform.ensureDecomposed();glm::vec3 centre, half;- orientedWorldAabb(transform.worldPosition, transform.worldRotation, transform.worldScale,+ orientedWorldAabb(rebased(transform.worldPosition), transform.worldRotation, transform.worldScale,geometry->localMin, geometry->localMax, centre, half);if (!frustum_.intersectsAABB(centre, half)) continue;const u32 axis = static_cast<u32>(surface.axis);if (axis > 2 || std::abs(transform.worldScale[axis]) < 1e-6f) continue;glm::vec3 normal(0.0f); normal[axis] = 1.0f;PlanarReflectionCamera candidate;- if (!planarReflectionCamera(view_projection_, transform.worldPosition,+ if (!planarReflectionCamera(view_projection_, rebased(transform.worldPosition),transform.worldRotation * normal, surface.clipOffset, candidate)) continue;++eligible;// A stable winner, independent of sparse-set iteration and camera movement.diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cppindex 4c8eaccaa..41a519244 100644--- a/src/esengine/renderer/plugins/MeshPlugin.cpp+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp@@ -117,7 +117,7 @@ u32 skinPose(ecs::Registry& registry, Entity entity, const Mesh& mesh,// draw is placed by — the cached matrix is the transform system's own// and is not guaranteed current for an entity nothing parents.joint->ensureDecomposed();- const glm::mat4 world = glm::translate(glm::mat4(1.0f), joint->worldPosition)+ const glm::mat4 world = glm::translate(glm::mat4(1.0f), rebased(joint->worldPosition))* glm::mat4_cast(joint->worldRotation)* glm::scale(glm::mat4(1.0f), joint->worldScale);out[i] = world * mesh.inverseBind[i];@@ -693,7 +693,7 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {// it, and its map is fitted to unshifted bounds: a caster stands where it is.transform.ensureDecomposed();const glm::vec3 position = shadowDepth- ? transform.worldPosition+ ? rebased(transform.worldPosition): parallaxedWorldPosition(transform, mesh.parallax, collect_ctx.camera);const auto& rotation = transform.worldRotation;const auto& scale = transform.worldScale;diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex aa4fc8e14..d94fe6ceb 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -2916,6 +2916,8 @@ export const NOTED = {{"note":"The editor's own eye shows the scene's post-processing."},"feat(terrain): the maths of ground on a cube sphere and the nodes drawn round an eye":{"internal":"The first layer of spherical terrain: pure maths and node selection, not yet drawn."},+ "feat(render): a render origin keeps a large world's meshes, lights and probes precise":+ {"note":"A render origin for large worlds."},"feat(terrain): a planet's ground is drawn with the layers' textures":{"note":"A planet's ground has the layers' textures."},"feat(terrain): a planet's ground collides":