Skip to content

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.

feat(render): an Impostor stands a picture of its mesh in once it is small, taken from many directions by the engine's own cameras and drawn as one batched card per view

yhh19ddbcd42cb3
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 8cc4fbe44..074098119 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -32,7 +32,7 @@ env:
test_hierarchy_links test_entity_activity test_transform_traversal test_ui_tree test_tween_activity test_springbone
test_shader_device test_draw_params test_per_draw_blocks test_texture_fb test_buffer_device
test_compressed_format test_batch_builder test_skeletal_batch_color test_boundary_span test_webgpu_device
- test_clip_depth test_planar_reflection test_sort_key test_retained_text test_sprite_mask_range test_sprite_draw_mode test_shadow_atlas test_particle_shapes test_lod_selection test_billboard_facing test_view_shading test_mesh_edges test_hdr_format test_probe_store test_occlusion_view test_reflection_store test_tiled_lights test_light_layers test_shadow_channels
+ test_clip_depth test_planar_reflection test_sort_key test_retained_text test_sprite_mask_range test_sprite_draw_mode test_shadow_atlas test_particle_shapes test_lod_selection test_billboard_facing test_impostor_frames test_view_shading test_mesh_edges test_hdr_format test_probe_store test_occlusion_view test_reflection_store test_tiled_lights test_light_layers test_shadow_channels
test_text_edit test_render_graph test_device_loss test_physics_interpolation
test_bitmap_font test_texture_cache test_material_shader_lifetime test_mesh_recovery test_aot_host test_aot_conformance
test_touch_stream
diff --git a/desktop b/desktop
index 1b8e26f99..5d374e754 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 1b8e26f99f516bbfa890a3edd2c1d89070b741d9
+Subproject commit 5d374e7546374b3f193acb7645eb8e32aa35920b
diff --git a/docs/astro/src/content/docs/performance/level-of-detail.mdx b/docs/astro/src/content/docs/performance/level-of-detail.mdx
index 7df3814cb..4f2789460 100644
--- a/docs/astro/src/content/docs/performance/level-of-detail.mdx
+++ b/docs/astro/src/content/docs/performance/level-of-detail.mdx
@@ -126,6 +126,29 @@ CPU spent choosing, GPU saved drawing. The exchange rate improves with the count
which is the point — it is the mechanism that decides whether a field of ten
thousand props is shippable at all.
+## Impostors: a picture in place of a far mesh
+
+An `Impostor` beside a MeshRenderer stands a card in for the mesh once the object covers less than `screenSize` of the view.
+The card shows a picture of the mesh taken from the direction the view is looking from, so from far away it is the object, at
+two triangles.
+
+```typescript
+world.insert(tree, Impostor, { screenSize: 0.06, frames: 8, resolution: 1024 });
+```
+
+- **The pictures** are taken while the game runs, once per kind: `frames` x `frames` orthographic cameras of the engine's own look
+ at a copy of the mesh from the directions of the upper half of a sphere, each into its own cell of one atlas `resolution`
+ pixels on a side. They are ordinary cameras, so the pictures have the mesh's material, textures and the scene's light, on
+ every backend. Entities with the same mesh, material, texture and colour share one atlas; kinds are photographed one after
+ another, a frame or two each.
+- **The card** is drawn by the renderer in each view: the picture taken nearest that view's direction, on a square facing it.
+ Every card is drawn through the sprite batch, so cards whose atlases fit in one draw's texture slots are one draw. In the
+ `impostor` editor check, five objects of five kinds draw as one draw where their meshes, instanced by shape, drew as two.
+- **What it cannot do.** A picture keeps the light it was taken in, in the object's own frame: an object turned in the world is lit
+ as if the sun had turned with it, so impostors suit objects lit softly or not turned. The picture changes in steps as the view
+ goes round (more `frames` is smaller steps), a card casts no shadow and is not seen from below, and the pictures are taken in
+ Play and in a built game, not in the editor's own viewport.
+
## What this is not
`LODGroup` is about **one object at different sizes**. It is not a streaming
diff --git a/docs/astro/src/content/docs/zh-cn/performance/level-of-detail.mdx b/docs/astro/src/content/docs/zh-cn/performance/level-of-detail.mdx
index efb1dca9e..f2bc88e06 100644
--- a/docs/astro/src/content/docs/zh-cn/performance/level-of-detail.mdx
+++ b/docs/astro/src/content/docs/zh-cn/performance/level-of-detail.mdx
@@ -105,6 +105,18 @@ world.insert(rock, LODGroup, {
每一万个道具的选级大约花掉 0.2–0.3 ms 的 CPU,这就是那笔交易:花 CPU 去挑,省 GPU 去画。
数量越大,汇率越划算 —— 这正是重点,它决定了一万个道具的场地到底能不能发出去。
+## Impostor:用一张图代替远处的网格
+
+MeshRenderer 旁边的 `Impostor` 会在物体占视图高度小于 `screenSize` 时,用一张卡片代替网格。卡片上是从视图所在方向拍下的网格图像,所以远远看过去还是那个物体,只要两个三角形。
+
+```typescript
+world.insert(tree, Impostor, { screenSize: 0.06, frames: 8, resolution: 1024 });
+```
+
+- **拍图**在游戏运行时进行,每种只拍一次:`frames` x `frames` 台引擎自己的正交相机,从上半球的各个方向看一个网格副本,各自画进同一张图集(边长 `resolution` 像素)里属于自己的格子。它们就是普通相机,所以图里有网格的材质、贴图和场景的光照,所有后端都一样。网格、材质、贴图和颜色都相同的实体共用一张图集;不同种类依次拍,每种一两帧。
+- **卡片**由渲染器在每个视图里画:取离这个视图方向最近的那张图,画在一个朝向它的正方形上。所有卡片都走精灵批处理,图集能放进一次 draw 的贴图槽时,这些卡片就是一次 draw。在 `impostor` 编辑器检查里,五种物体各一个,画成卡片是 1 次 draw,画成网格(按形状实例化)是 2 次。
+- **它做不到的。** 图保留拍摄时的光照,而且是在物体自己的坐标系里:在世界里转过的物体,光照就像太阳也跟着转了,所以 Impostor 适合光线柔和或者没有旋转的物体。视角绕着转时图像是一级一级变的(`frames` 越多,每级越小);卡片不投影,不能从下方看;拍图在 Play 和打包后的游戏里进行,编辑器自己的视口里不拍。
+
## 它不做什么
`LODGroup` 讲的是**同一个物体在不同尺寸下**的事。它不是流式加载:每一级的网格都常驻,
diff --git a/docs/astro/src/data/componentDocs.ts b/docs/astro/src/data/componentDocs.ts
index 1cf309e10..5726b4d90 100644
--- a/docs/astro/src/data/componentDocs.ts
+++ b/docs/astro/src/data/componentDocs.ts
@@ -112,6 +112,7 @@ export const COMPONENT_DOCS: Record<string, ComponentDoc> = {
WaterBody: { category: 'graphics', summary: 'An ocean, a lake or a river: where the water is, how high its waves stand and how it flows; drawn as part of its zone\'s one surface.', doc: 'graphics/water', anchor: 'the-component', anchorZh: '组件' },
WaterZone: { category: 'graphics', summary: 'The region the bodies of water are baked over and drawn from as one surface: the waves they share, the material, the mesh and the ripples.', doc: 'graphics/water', anchor: 'the-zone', anchorZh: '水体区域' },
Billboard: { category: 'graphics', summary: 'Turns the MeshRenderer beside it to face each view that draws it: flat in the view plane, or upright about world up.', doc: 'graphics/drawing', anchor: 'cards-that-face-the-camera-billboard', anchorZh: '朝向相机的卡片billboard' },
+ Impostor: { category: 'graphics', summary: 'Stands a card showing a picture of the mesh in for the MeshRenderer once the object is small on screen; the pictures are taken from many directions while the game runs.', doc: 'performance/level-of-detail', anchor: 'impostors-a-picture-in-place-of-a-far-mesh', anchorZh: 'impostor用一张图代替远处的网格' },
LODGroup: { category: 'graphics', summary: 'Cheaper stand-in meshes for a MeshRenderer, chosen by how much of the screen the object covers.', doc: 'performance/level-of-detail', anchor: 'the-lodgroup-component', anchorZh: 'lodgroup-组件' },
ReflectionProbe: { category: 'graphics', summary: 'A box inside which reflections come from a bake rather than from the sky — the specular half of what a light probe volume answers.', doc: 'graphics/lighting', anchor: 'baked-light', anchorZh: '烘焙光照' },
PlanarReflection: { category: 'graphics', summary: 'Captures a mirrored view for flat lit surfaces, with layer filtering, capture quality and update controls.', doc: 'graphics/lighting' },
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index b31aaf837..c999eabd6 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -2687,6 +2687,39 @@
"cooldown"
]
},
+ {
+ "name": "Impostor",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "screenSize",
+ "type": "number",
+ "default": "0.06",
+ "doc": "Screen height fraction below which the card replaces the mesh.",
+ "range": "0–1"
+ },
+ {
+ "key": "frames",
+ "type": "number",
+ "default": "8",
+ "doc": "Pictures along each side of the atlas (frames x frames in all). More is smoother as the view goes round, and smaller each.",
+ "range": "2–16, step 1"
+ },
+ {
+ "key": "resolution",
+ "type": "number",
+ "default": "1024",
+ "doc": "The atlas's side in pixels; each picture is this divided by frames.",
+ "range": "128–4096, step 128"
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true",
+ "doc": "Off: the mesh is always drawn as itself."
+ }
+ ]
+ },
{
"name": "Interactable",
"source": "cpp",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 961605d61..52db98825 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,11 +1,11 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 163 beta · 2003 experimental · 3 deprecated
+Symbols: 115 public · 164 beta · 2014 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"04cb5f0f12687160"
+"0f608f110f54e807"
```
## ANCHOR_AXES — const @experimental
@@ -4953,6 +4953,11 @@ static new (options: HttpBackendOptions): HttpBackend
static prototype: HttpBackend
```
+## IMPOSTOR_BAKE_LAYER — const @experimental
+```
+31
+```
+
## INTERACTION_CONTROLLER — const @experimental
```
"$interaction"
@@ -5010,6 +5015,41 @@ valign: ImageValign
width: number
```
+## Impostor — const @experimental
+```
+BuiltinComponentDef<ImpostorData>
+```
+
+## ImpostorAtlases — class @experimental
+```
+given: Map<number, string>
+kinds: Map<string, ImpostorKind>
+ready: number
+static new (): ImpostorAtlases
+static prototype: ImpostorAtlases
+```
+
+## ImpostorAtlasesRes — const @experimental
+```
+ResourceDef<ImpostorAtlases>
+```
+
+## ImpostorData — interface @beta
+```
+enabled: boolean
+frames: number
+resolution: number
+screenSize: number
+```
+
+## ImpostorPlugin — class @experimental
+```
+build: (app: App) => void
+name: string
+static new (): ImpostorPlugin
+static prototype: ImpostorPlugin
+```
+
## InferParam — type @public
```
P extends QueryDescriptor<infer C> ? QueryInstance<C> :
@@ -15079,6 +15119,36 @@ Plugin
(flip: boolean): ImageBitmapOptions
```
+## impostorDecode — function @experimental
+```
+(u: number, v: number): Vec3
+```
+
+## impostorEncode — function @experimental
+```
+(d: Vec3): [number, number]
+```
+
+## impostorFrameDirection — function @experimental
+```
+(i: number, j: number, frames: number): Vec3
+```
+
+## impostorKindKey — function @experimental
+```
+(mr: MeshRendererData, imp: ImpostorData): string
+```
+
+## impostorPictureUp — function @experimental
+```
+(d: Vec3): Vec3
+```
+
+## impostorPlugin — const @experimental
+```
+Plugin
+```
+
## indexPackagedManifest — function @experimental
```
(manifest: AddressableManifest): PackagedAssetIndex
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 4c059efe8..115740b2f 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,11 +1,11 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 115 public · 168 beta · 2022 experimental · 3 deprecated
+Symbols: 115 public · 169 beta · 2033 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"04cb5f0f12687160"
+"0f608f110f54e807"
```
## ANCHOR_AXES — const @experimental
@@ -4961,6 +4961,11 @@ static new (options: HttpBackendOptions): HttpBackend
static prototype: HttpBackend
```
+## IMPOSTOR_BAKE_LAYER — const @experimental
+```
+31
+```
+
## INTERACTION_CONTROLLER — const @experimental
```
"$interaction"
@@ -5018,6 +5023,41 @@ valign: ImageValign
width: number
```
+## Impostor — const @experimental
+```
+BuiltinComponentDef<ImpostorData>
+```
+
+## ImpostorAtlases — class @experimental
+```
+given: Map<number, string>
+kinds: Map<string, ImpostorKind>
+ready: number
+static new (): ImpostorAtlases
+static prototype: ImpostorAtlases
+```
+
+## ImpostorAtlasesRes — const @experimental
+```
+ResourceDef<ImpostorAtlases>
+```
+
+## ImpostorData — interface @beta
+```
+enabled: boolean
+frames: number
+resolution: number
+screenSize: number
+```
+
+## ImpostorPlugin — class @experimental
+```
+build: (app: App) => void
+name: string
+static new (): ImpostorPlugin
+static prototype: ImpostorPlugin
+```
+
## InferParam — type @public
```
P extends QueryDescriptor<infer C> ? QueryInstance<C> :
@@ -15332,6 +15372,36 @@ Plugin
(flip: boolean): ImageBitmapOptions
```
+## impostorDecode — function @experimental
+```
+(u: number, v: number): Vec3
+```
+
+## impostorEncode — function @experimental
+```
+(d: Vec3): [number, number]
+```
+
+## impostorFrameDirection — function @experimental
+```
+(i: number, j: number, frames: number): Vec3
+```
+
+## impostorKindKey — function @experimental
+```
+(mr: MeshRendererData, imp: ImpostorData): string
+```
+
+## impostorPictureUp — function @experimental
+```
+(d: Vec3): Vec3
+```
+
+## impostorPlugin — const @experimental
+```
+Plugin
+```
+
## indexPackagedManifest — function @experimental
```
(manifest: AddressableManifest): PackagedAssetIndex
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index f28560fea..ae5fb4ae4 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 · 165 beta · 2002 experimental · 3 deprecated
+Symbols: 115 public · 166 beta · 2013 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4948,6 +4948,11 @@ static new (options: HttpBackendOptions): HttpBackend
static prototype: HttpBackend
```
+## IMPOSTOR_BAKE_LAYER — const @experimental
+```
+31
+```
+
## INTERACTION_CONTROLLER — const @experimental
```
"$interaction"
@@ -5005,6 +5010,41 @@ valign: ImageValign
width: number
```
+## Impostor — const @experimental
+```
+BuiltinComponentDef<ImpostorData>
+```
+
+## ImpostorAtlases — class @experimental
+```
+given: Map<number, string>
+kinds: Map<string, ImpostorKind>
+ready: number
+static new (): ImpostorAtlases
+static prototype: ImpostorAtlases
+```
+
+## ImpostorAtlasesRes — const @experimental
+```
+ResourceDef<ImpostorAtlases>
+```
+
+## ImpostorData — interface @beta
+```
+enabled: boolean
+frames: number
+resolution: number
+screenSize: number
+```
+
+## ImpostorPlugin — class @experimental
+```
+build: (app: App) => void
+name: string
+static new (): ImpostorPlugin
+static prototype: ImpostorPlugin
+```
+
## InferParam — type @public
```
P extends QueryDescriptor<infer C> ? QueryInstance<C> :
@@ -15074,6 +15114,36 @@ Plugin
(flip: boolean): ImageBitmapOptions
```
+## impostorDecode — function @experimental
+```
+(u: number, v: number): Vec3
+```
+
+## impostorEncode — function @experimental
+```
+(d: Vec3): [number, number]
+```
+
+## impostorFrameDirection — function @experimental
+```
+(i: number, j: number, frames: number): Vec3
+```
+
+## impostorKindKey — function @experimental
+```
+(mr: MeshRendererData, imp: ImpostorData): string
+```
+
+## impostorPictureUp — function @experimental
+```
+(d: Vec3): Vec3
+```
+
+## impostorPlugin — const @experimental
+```
+Plugin
+```
+
## indexPackagedManifest — function @experimental
```
(manifest: AddressableManifest): PackagedAssetIndex
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 31f744323..bae4a31e7 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 · 163 beta · 2024 experimental · 3 deprecated
+Symbols: 115 public · 164 beta · 2035 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4948,6 +4948,11 @@ static new (options: HttpBackendOptions): HttpBackend
static prototype: HttpBackend
```
+## IMPOSTOR_BAKE_LAYER — const @experimental
+```
+31
+```
+
## INTERACTION_CONTROLLER — const @experimental
```
"$interaction"
@@ -5005,6 +5010,41 @@ valign: ImageValign
width: number
```
+## Impostor — const @experimental
+```
+BuiltinComponentDef<ImpostorData>
+```
+
+## ImpostorAtlases — class @experimental
+```
+given: Map<number, string>
+kinds: Map<string, ImpostorKind>
+ready: number
+static new (): ImpostorAtlases
+static prototype: ImpostorAtlases
+```
+
+## ImpostorAtlasesRes — const @experimental
+```
+ResourceDef<ImpostorAtlases>
+```
+
+## ImpostorData — interface @beta
+```
+enabled: boolean
+frames: number
+resolution: number
+screenSize: number
+```
+
+## ImpostorPlugin — class @experimental
+```
+build: (app: App) => void
+name: string
+static new (): ImpostorPlugin
+static prototype: ImpostorPlugin
+```
+
## InferParam — type @public
```
P extends QueryDescriptor<infer C> ? QueryInstance<C> :
@@ -15380,6 +15420,36 @@ Plugin
(flip: boolean): ImageBitmapOptions
```
+## impostorDecode — function @experimental
+```
+(u: number, v: number): Vec3
+```
+
+## impostorEncode — function @experimental
+```
+(d: Vec3): [number, number]
+```
+
+## impostorFrameDirection — function @experimental
+```
+(i: number, j: number, frames: number): Vec3
+```
+
+## impostorKindKey — function @experimental
+```
+(mr: MeshRendererData, imp: ImpostorData): string
+```
+
+## impostorPictureUp — function @experimental
+```
+(d: Vec3): Vec3
+```
+
+## impostorPlugin — const @experimental
+```
+Plugin
+```
+
## indexPackagedManifest — function @experimental
```
(manifest: AddressableManifest): PackagedAssetIndex
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index b3881e705..2c85293a4 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -31,6 +31,7 @@ addDraggable: (entity: Entity, component: Draggable) => void
addDragonBonesAnimation: (entity: Entity, component: DragonBonesAnimation) => void
addFlexContainer: (entity: Entity, component: FlexContainer) => void
addGroupOpacity: (entity: Entity, component: GroupOpacity) => void
+addImpostor: (entity: Entity, component: Impostor) => void
addInteractable: (entity: Entity, component: Interactable) => void
addLODGroup: (entity: Entity, component: LODGroup) => void
addLight: (entity: Entity, component: Light) => void
@@ -92,6 +93,7 @@ getDraggable: (entity: Entity) => Draggable
getDragonBonesAnimation: (entity: Entity) => DragonBonesAnimation
getFlexContainer: (entity: Entity) => FlexContainer
getGroupOpacity: (entity: Entity) => GroupOpacity
+getImpostor: (entity: Entity) => Impostor
getInteractable: (entity: Entity) => Interactable
getLODGroup: (entity: Entity) => LODGroup
getLight: (entity: Entity) => Light
@@ -146,6 +148,7 @@ hasDraggable: (entity: Entity) => boolean
hasDragonBonesAnimation: (entity: Entity) => boolean
hasFlexContainer: (entity: Entity) => boolean
hasGroupOpacity: (entity: Entity) => boolean
+hasImpostor: (entity: Entity) => boolean
hasInactiveEntities: (() => boolean) | undefined
hasInteractable: (entity: Entity) => boolean
hasLODGroup: (entity: Entity) => boolean
@@ -205,6 +208,7 @@ removeDraggable: (entity: Entity) => void
removeDragonBonesAnimation: (entity: Entity) => void
removeFlexContainer: (entity: Entity) => void
removeGroupOpacity: (entity: Entity) => void
+removeImpostor: (entity: Entity) => void
removeInteractable: (entity: Entity) => void
removeLODGroup: (entity: Entity) => void
removeLight: (entity: Entity) => void
@@ -538,6 +542,7 @@ renderer_setCullingMask: ((mask: number) => void) | undefined
renderer_setDepthLayers: ((mask: number) => void) | undefined
renderer_setDepthPrepass: ((on: boolean) => void) | undefined
renderer_setEntityDrawOrder: ((registry: CppRegistry, entitiesPtr: number, count: number) => void) | undefined
+renderer_setImpostorAtlas: ((entity: number, texture: number, frames: number) => void) | undefined
renderer_setLodPreview: ((view: number, entity: number, level: number) => void) | undefined
renderer_setMeshEdgeBuffers: ((enabled: boolean) => void) | undefined
renderer_setOrigin: ((x: number, y: number, z: number) => void) | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 7782fcf3b..5771f2703 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 · 163 beta · 2015 experimental · 3 deprecated
+Symbols: 115 public · 164 beta · 2026 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -4948,6 +4948,11 @@ static new (options: HttpBackendOptions): HttpBackend
static prototype: HttpBackend
```
+## IMPOSTOR_BAKE_LAYER — const @experimental
+```
+31
+```
+
## INTERACTION_CONTROLLER — const @experimental
```
"$interaction"
@@ -5012,6 +5017,41 @@ valign: ImageValign
width: number
```
+## Impostor — const @experimental
+```
+BuiltinComponentDef<ImpostorData>
+```
+
+## ImpostorAtlases — class @experimental
+```
+given: Map<number, string>
+kinds: Map<string, ImpostorKind>
+ready: number
+static new (): ImpostorAtlases
+static prototype: ImpostorAtlases
+```
+
+## ImpostorAtlasesRes — const @experimental
+```
+ResourceDef<ImpostorAtlases>
+```
+
+## ImpostorData — interface @beta
+```
+enabled: boolean
+frames: number
+resolution: number
+screenSize: number
+```
+
+## ImpostorPlugin — class @experimental
+```
+build: (app: App) => void
+name: string
+static new (): ImpostorPlugin
+static prototype: ImpostorPlugin
+```
+
## InferParam — type @public
```
P extends QueryDescriptor<infer C> ? QueryInstance<C> :
@@ -15106,6 +15146,36 @@ Plugin
(flip: boolean): ImageBitmapOptions
```
+## impostorDecode — function @experimental
+```
+(u: number, v: number): Vec3
+```
+
+## impostorEncode — function @experimental
+```
+(d: Vec3): [number, number]
+```
+
+## impostorFrameDirection — function @experimental
+```
+(i: number, j: number, frames: number): Vec3
+```
+
+## impostorKindKey — function @experimental
+```
+(mr: MeshRendererData, imp: ImpostorData): string
+```
+
+## impostorPictureUp — function @experimental
+```
+(d: Vec3): Vec3
+```
+
+## impostorPlugin — const @experimental
+```
+Plugin
+```
+
## indexPackagedManifest — function @experimental
```
(manifest: AddressableManifest): PackagedAssetIndex
diff --git a/sdk/src/app/pluginSets.ts b/sdk/src/app/pluginSets.ts
index c9c59311c..e9f6e71c8 100644
--- a/sdk/src/app/pluginSets.ts
+++ b/sdk/src/app/pluginSets.ts
@@ -29,6 +29,7 @@ import { trailPlugin } from '../trail';
import { springBonePlugin } from '../springbone';
import { meshRendererPlugin } from '../render/meshRenderer';
import { staticBatchPlugin } from '../render/staticBatchPlugin';
+import { impostorPlugin } from '../render/impostor';
import { postProcessPlugin } from '../postprocess';
import { timerPlugin } from '../ecs/timer';
import { velocityPlugin } from '../velocity';
@@ -57,7 +58,7 @@ export const simulationBasePlugins = (): Plugin[] => [
/** What exists to be seen. Every entry drives the engine through `engineApi`. */
export const presentationBasePlugins = (): Plugin[] => [
- animationPlugin, videoPlugin, particlePlugin, trailPlugin, springBonePlugin, meshRendererPlugin, staticBatchPlugin,
+ animationPlugin, videoPlugin, particlePlugin, trailPlugin, springBonePlugin, meshRendererPlugin, staticBatchPlugin, impostorPlugin,
postProcessPlugin,
];
@@ -68,7 +69,7 @@ export const presentationBasePlugins = (): Plugin[] => [
*/
export const PLUGIN_BUILD_ORDER: readonly string[] = [
'Diagnostics', 'timer', 'velocity', 'lifecycle', 'animation', 'audio', 'video',
- 'particle', 'trail', 'springBone', 'meshRenderer', 'staticBatch', 'terrain', 'foliage', 'spline', 'water', 'floating', 'underwater', 'tilemap', 'postProcess', 'timeline',
+ 'particle', 'trail', 'springBone', 'meshRenderer', 'staticBatch', 'impostor', 'terrain', 'foliage', 'spline', 'water', 'floating', 'underwater', 'tilemap', 'postProcess', 'timeline',
'gameplay',
'perception', 'fsm', 'bt', 'scriptGraph', 'nav', 'eventBinding', 'replication',
'services',
@@ -94,7 +95,7 @@ export function inBuildOrder(plugins: readonly Plugin[]): Plugin[] {
export const webBasePlugins = (): Plugin[] => [
diagnosticsPlugin,
timerPlugin, velocityPlugin, lifecyclePlugin, animationPlugin, audioPlugin, videoPlugin,
- particlePlugin, trailPlugin, springBonePlugin, meshRendererPlugin, staticBatchPlugin, postProcessPlugin,
+ particlePlugin, trailPlugin, springBonePlugin, meshRendererPlugin, staticBatchPlugin, impostorPlugin, postProcessPlugin,
eventBindingPlugin,
servicesPlugin,
];
diff --git a/sdk/src/camera/CameraPlugin.ts b/sdk/src/camera/CameraPlugin.ts
index 50b3875e6..3f86efe34 100644
--- a/sdk/src/camera/CameraPlugin.ts
+++ b/sdk/src/camera/CameraPlugin.ts
@@ -33,6 +33,7 @@ import { RenderPipeline } from '../render/renderPipeline';
import { Input } from '../input/input';
import { pendingShaders } from '../render/shaderWarmup';
import { renderTargetSize } from '../render/renderTexture';
+import { cameraClearColor } from './cameraClear';
import { Renderer } from '../render/renderer';
import { followRenderOrigin, pushRenderOrigin, renderOrigin } from '../render/renderOrigin';
import { platformNow, platformDevicePixelRatio } from '../platform';
@@ -966,7 +967,7 @@ export function cameraPlugin(
clearFlags: cam.clearFlags,
elapsed,
cameraEntity: cam.entity,
- clearColor,
+ clearColor: cameraClearColor(cam.entity as Entity, clearColor),
cullingMask: cam.cullingMask,
// A released target leaves the handle behind; drawing
// to it would draw nowhere, so it falls to the screen.
diff --git a/sdk/src/camera/cameraClear.ts b/sdk/src/camera/cameraClear.ts
new file mode 100644
index 000000000..2a8da05ad
--- /dev/null
+++ b/sdk/src/camera/cameraClear.ts
@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cameraClear.ts
+ * @brief The colour a camera clears to when it is not the canvas's.
+ *
+ * @details Every camera clears to the canvas's background, which is right for a picture someone sees. A camera taking a picture for
+ * the engine's own use (an impostor's) wants the empty parts of it empty, and says so here. Engine-internal: a camera with
+ * no entry clears as it always has.
+ */
+import type { Entity } from '../types';
+
+type Rgba = { x: number; y: number; z: number; w: number };
+
+const overrides = new Map<Entity, Rgba>();
+
+/** Clear @p camera to @p colour instead of the canvas's background; null puts it back. @internal */
+export function setCameraClearColor(camera: Entity, colour: Rgba | null): void {
+ if (colour) overrides.set(camera, colour);
+ else overrides.delete(camera);
+}
+
+/** The colour @p camera clears to if it has its own, else @p fallback. @internal */
+export function cameraClearColor(camera: Entity, fallback: Rgba | undefined): Rgba | undefined {
+ return overrides.get(camera) ?? fallback;
+}
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 09249ad9d..f39f061eb 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -857,6 +857,10 @@ export {
mergeMeshes, planStaticBatches, STATIC_BATCH_DEFAULTS,
type StaticBatchGroup, type StaticBatchLimits, type StaticBatchRefusal, type StaticBatchReport,
} from './render/staticBatch';
+export {
+ ImpostorPlugin, impostorPlugin, ImpostorAtlases, ImpostorAtlasesRes, IMPOSTOR_BAKE_LAYER,
+ impostorEncode, impostorDecode, impostorFrameDirection, impostorPictureUp, impostorKindKey,
+} from './render/impostor';
export { drawBudgetReport, type DrawBudgetReport, type DrawPass, type DrawPassShare } from './render/drawBudget';
// =============================================================================
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index 140c313d4..8954b618c 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -114,6 +114,8 @@ export {
Billboard,
type BillboardData,
BillboardMode,
+ Impostor,
+ type ImpostorData,
MeshRenderer,
type MeshRendererData,
type MeshRendererGeometry,
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index eb4a3d3a1..c8133a120 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -221,6 +221,7 @@ export interface NativeEngineApi {
renderer_setDepthLayers?(mask: number): void;
renderer_setDepthPrepass?(on: boolean): void;
renderer_setEntityDrawOrder?(registry: unknown, entitiesPtr: number, count: number): void;
+ renderer_setImpostorAtlas?(entity: number, texture: number, frames: 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;
@@ -560,6 +561,7 @@ export function createNativeEngineApi(
bind('renderer_setDepthLayers', 'es_renderer_setDepthLayers', false);
bind('renderer_setDepthPrepass', 'es_renderer_setDepthPrepass', false);
bind('renderer_setEntityDrawOrder', 'es_renderer_setEntityDrawOrder', true);
+ bind('renderer_setImpostorAtlas', 'es_renderer_setImpostorAtlas', false);
bind('renderer_setLodPreview', 'es_renderer_setLodPreview', false);
bind('renderer_setMeshEdgeBuffers', 'es_renderer_setMeshEdgeBuffers', false);
bind('renderer_setOrigin', 'es_renderer_setOrigin', false);
diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
index a04479c02..21ba34d90 100644
--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts
+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
@@ -801,6 +801,42 @@ export function createGroupOpacityData(): GroupOpacityPtrData {
};
}
+export interface ImpostorPtrData {
+ screenSize: number;
+ frames: number;
+ resolution: number;
+ enabled: boolean;
+}
+
+export function fillImpostor(
+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,
+ ptr: number, out: ImpostorPtrData,
+): void {
+ out.screenSize = f32[ptr >> 2];
+ out.frames = u32[(ptr + 4) >> 2] | 0;
+ out.resolution = u32[(ptr + 8) >> 2] | 0;
+ out.enabled = u8[ptr + 12] !== 0;
+}
+
+export function writeImpostor(
+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,
+ ptr: number, data: ImpostorPtrData,
+): void {
+ f32[ptr >> 2] = data.screenSize;
+ u32[(ptr + 4) >> 2] = data.frames | 0;
+ u32[(ptr + 8) >> 2] = data.resolution | 0;
+ u8[ptr + 12] = data.enabled ? 1 : 0;
+}
+
+export function createImpostorData(): ImpostorPtrData {
+ return {
+ screenSize: 0,
+ frames: 0,
+ resolution: 0,
+ enabled: false,
+ };
+}
+
export interface InteractablePtrData {
enabled: boolean;
blockRaycast: boolean;
@@ -2848,6 +2884,7 @@ export const PTR_ACCESSORS: Record<string, PtrAccessor<any>> = {
DragonBonesAnimation: { fill: fillDragonBonesAnimation, write: writeDragonBonesAnimation, create: createDragonBonesAnimationData },
FlexContainer: { fill: fillFlexContainer, write: writeFlexContainer, create: createFlexContainerData },
GroupOpacity: { fill: fillGroupOpacity, write: writeGroupOpacity, create: createGroupOpacityData },
+ Impostor: { fill: fillImpostor, write: writeImpostor, create: createImpostorData },
Interactable: { fill: fillInteractable, write: writeInteractable, create: createInteractableData },
LODGroup: { fill: fillLODGroup, write: writeLODGroup, create: createLODGroupData },
Light: { fill: fillLight, write: writeLight, create: createLightData },
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index b06061bdb..ce9f1b51e 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -15,7 +15,7 @@ import type { AlignContent, AlignItems, AlignSelf, BillboardMode, BodyType, Canv
* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
* run on mismatch, because mismatched offsets read the wrong heap bytes.
*/
-export const ABI_LAYOUT_HASH = '04cb5f0f12687160';
+export const ABI_LAYOUT_HASH = '0f608f110f54e807';
/**
* One asset-valued field of a component: which field, and what kind of
@@ -461,6 +461,24 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
opacity: { min: 0, max: 1, step: 0.01, tooltip: "Opacity of this entity and everything under it, multiplied with the opacity of every group above it." },
},
},
+ Impostor: {
+ defaults: {
+ screenSize: 0.06,
+ frames: 8,
+ resolution: 1024,
+ enabled: true,
+ },
+ assetFields: [],
+ entityFields: [],
+ colorFields: [],
+ animatableFields: [],
+ fields: {
+ screenSize: { min: 0, max: 1, tooltip: "Screen height fraction below which the card replaces the mesh." },
+ frames: { min: 2, max: 16, step: 1, tooltip: "Pictures along each side of the atlas (frames x frames in all). More is smoother as the view goes round, and smaller each." },
+ resolution: { min: 128, max: 4096, step: 128, tooltip: "The atlas's side in pixels; each picture is this divided by frames." },
+ enabled: { tooltip: "Off: the mesh is always drawn as itself." },
+ },
+ },
Interactable: {
defaults: {
enabled: true,
@@ -1636,6 +1654,19 @@ export interface GroupOpacityData {
enabled: boolean;
}
+/**
+ * The fields of the engine's `Impostor` component, generated from
+ * the C++ struct so the two shapes cannot drift.
+ *
+ * @beta
+ */
+export interface ImpostorData {
+ screenSize: number;
+ frames: number;
+ resolution: number;
+ enabled: boolean;
+}
+
export interface InteractableData {
enabled: boolean;
blockRaycast: boolean;
diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.ts
index 38dd9999c..e37c6a3a3 100644
--- a/sdk/src/ecs/component.ts
+++ b/sdk/src/ecs/component.ts
@@ -19,7 +19,7 @@ import type {
SortingGroupData, GroupOpacityData, SpriteMaskData, LightProbeVolumeData, OccluderData,
ReflectionProbeData, PlanarReflectionData,
CanvasData, VelocityData, ParentData, ChildrenData, SpineAnimationData, DragonBonesAnimationData,
- TilemapLayerData, BitmapTextData, TrailRendererData, ParticleForceFieldData, SpringBoneData, SpringBoneColliderData, BillboardData,
+ TilemapLayerData, BitmapTextData, TrailRendererData, ParticleForceFieldData, SpringBoneData, SpringBoneColliderData, BillboardData, ImpostorData,
CameraData as CameraDataCpp, ParticleEmitterData as ParticleEmitterDataCpp,
MeshRendererData as MeshRendererDataCpp,
} from './component.generated';
@@ -846,7 +846,7 @@ export type {
SortingGroupData, GroupOpacityData, SpriteMaskData, LightProbeVolumeData, OccluderData,
ReflectionProbeData, PlanarReflectionData,
CanvasData, VelocityData, ParentData, ChildrenData, SpineAnimationData, DragonBonesAnimationData,
- TilemapLayerData, BitmapTextData, TrailRendererData, ParticleForceFieldData, SpringBoneData, SpringBoneColliderData, BillboardData,
+ TilemapLayerData, BitmapTextData, TrailRendererData, ParticleForceFieldData, SpringBoneData, SpringBoneColliderData, BillboardData, ImpostorData,
};
export type LocalTransformData = TransformData;
@@ -1156,6 +1156,11 @@ export const Billboard = defineBuiltin<BillboardData>('Billboard',
metaDefaults<BillboardData>('Billboard')
);
+// A picture of a mesh drawn in its place once it is small. The renderer draws the card; impostorPlugin takes the pictures.
+export const Impostor = defineBuiltin<ImpostorData>('Impostor',
+ metaDefaults<ImpostorData>('Impostor')
+);
+
// Particle force field. A scene-placed zone (wind, attractor, vortex, drag) that the
// C++ ParticleSystem folds into every nearby world-space particle's integration.
export const ParticleForceField = defineBuiltin<ParticleForceFieldData>('ParticleForceField',
diff --git a/sdk/src/render/impostor.ts b/sdk/src/render/impostor.ts
new file mode 100644
index 000000000..be1d24650
--- /dev/null
+++ b/sdk/src/render/impostor.ts
@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file impostor.ts
+ * @brief Takes the pictures an Impostor draws from: one atlas per kind of mesh, by cameras of the engine's own.
+ *
+ * @details The renderer draws an impostor's card (MeshPlugin); this takes its pictures. A copy of the mesh is set up out of the way on
+ * a layer nothing else is on, and `frames` x `frames` orthographic cameras look at it from the directions of a hemi-octahedral
+ * grid, each drawing into its own cell of one render target. They are ordinary cameras, so the pictures are the mesh as the
+ * scene's lights show it, with its material and textures, on every backend the engine draws with. One frame later the
+ * cameras and the copy go and the atlas is handed to every entity of that kind.
+ *
+ * The directions are the renderer's own (src/esengine/renderer/draw/ImpostorFrames.hpp); a test on each side holds the two to
+ * the same numbers.
+ */
+import type { App, Plugin } from '../app/app';
+import { defineSystem, Schedule } from '../ecs/system';
+import { defineResource } from '../ecs/resource';
+import { Camera, MeshRenderer, RuntimeOnly, Transform, getComponent, type MeshRendererData } from '../ecs/component';
+import { ClearFlags, ProjectionType } from '../wasm/wasm.generated';
+import { playModeOnly } from '../ecs/env';
+import { Assets } from '../asset/AssetPlugin';
+import { engineApi } from '../ecs/bridge/engineApi';
+import { RenderTexture, type RenderTextureHandle } from './renderTexture';
+import { setCameraClearColor } from '../camera/cameraClear';
+import type { Entity } from '../types';
+import type { ImpostorData } from '../ecs/component.generated';
+
+type Vec3 = [number, number, number];
+
+/** Where on the unit square a direction of the upper hemisphere folds to. Below the horizon is taken as on it. @experimental */
+export function impostorEncode(d: Vec3): [number, number] {
+ const y = Math.max(d[1], 0);
+ const s = Math.abs(d[0]) + y + Math.abs(d[2]);
+ if (s < 1e-12) return [0.5, 0.5];
+ const px = d[0] / s, pz = d[2] / s;
+ return [(px + pz) * 0.5 + 0.5, (px - pz) * 0.5 + 0.5];
+}
+
+/** The direction a point of the unit square unfolds to. @experimental */
+export function impostorDecode(u: number, v: number): Vec3 {
+ const qx = u * 2 - 1, qy = v * 2 - 1;
+ const px = (qx + qy) * 0.5, pz = (qx - qy) * 0.5;
+ const y = Math.max(1 - Math.abs(px) - Math.abs(pz), 0);
+ const l = Math.hypot(px, y, pz);
+ return [px / l, y / l, pz / l];
+}
+
+/** The direction, from the object toward the camera, that frame (i, j) of a `frames`-wide atlas is taken from. @experimental */
+export function impostorFrameDirection(i: number, j: number, frames: number): Vec3 {
+ const last = Math.max(frames, 2) - 1;
+ return impostorDecode(i / last, j / last);
+}
+
+/** The up a picture is taken with from `d`: world up laid flat across the view, and -Z straight overhead. @experimental */
+export function impostorPictureUp(d: Vec3): Vec3 {
+ const up: Vec3 = [-d[0] * d[1], 1 - d[1] * d[1], -d[2] * d[1]];
+ const l = Math.hypot(up[0], up[1], up[2]);
+ return l < 1e-4 ? [0, 0, -1] : [up[0] / l, up[1] / l, up[2] / l];
+}
+
+/** A rotation whose -Z looks along `-back` and whose +Y is `up`: how a camera looking back along `back` is turned. */
+export function lookRotation(back: Vec3, up: Vec3): { x: number; y: number; z: number; w: number } {
+ const right: Vec3 = [up[1] * back[2] - up[2] * back[1], up[2] * back[0] - up[0] * back[2], up[0] * back[1] - up[1] * back[0]];
+ // Columns right, up, back; the trace method.
+ const m00 = right[0], m01 = up[0], m02 = back[0];
+ const m10 = right[1], m11 = up[1], m12 = back[1];
+ const m20 = right[2], m21 = up[2], m22 = back[2];
+ const trace = m00 + m11 + m22;
+ if (trace > 0) {
+ const s = Math.sqrt(trace + 1) * 2;
+ return { w: s / 4, x: (m21 - m12) / s, y: (m02 - m20) / s, z: (m10 - m01) / s };
+ }
+ if (m00 > m11 && m00 > m22) {
+ const s = Math.sqrt(1 + m00 - m11 - m22) * 2;
+ return { w: (m21 - m12) / s, x: s / 4, y: (m01 + m10) / s, z: (m02 + m20) / s };
+ }
+ if (m11 > m22) {
+ const s = Math.sqrt(1 + m11 - m00 - m22) * 2;
+ return { w: (m02 - m20) / s, x: (m01 + m10) / s, y: s / 4, z: (m12 + m21) / s };
+ }
+ const s = Math.sqrt(1 + m22 - m00 - m11) * 2;
+ return { w: (m10 - m01) / s, x: (m02 + m20) / s, y: (m12 + m21) / s, z: s / 4 };
+}
+
+/** The sorting layer the pictures are taken on: nothing else is drawn by their cameras, and nothing else is put there. */
+export const IMPOSTOR_BAKE_LAYER = 31;
+/** Where the copy stands while its pictures are taken: up out of the way of what the scene's cameras look at. */
+const BAKE_ORIGIN: Vec3 = [0, 20000, 0];
+
+/** One kind of mesh's pictures: being taken, or taken. */
+interface ImpostorKind {
+ target: RenderTextureHandle | null;
+ frames: number;
+ /** While being taken: the cameras and the copy, and the frame they were set up on. */
+ cameras: Entity[];
+ copy: Entity | null;
+ since: number;
+ ready: boolean;
+}
+
+/** What the plugin has taken, by kind. @experimental */
+export class ImpostorAtlases {
+ readonly kinds = new Map<string, ImpostorKind>();
+ /** The entities handed an atlas, and by which kind. */
+ readonly given = new Map<Entity, string>();
+
+ /** How many kinds have their pictures. */
+ get ready(): number { let n = 0; for (const k of this.kinds.values()) if (k.ready) n++; return n; }
+}
+
+/** @experimental */
+export const ImpostorAtlasesRes = defineResource<ImpostorAtlases>(new ImpostorAtlases(), 'ImpostorAtlases');
+
+/** What makes two impostors share pictures: everything that decides how the mesh looks, and how the atlas is cut. */
+export function impostorKindKey(mr: MeshRendererData, imp: ImpostorData): string {
+ const c = mr.color;
+ return [mr.mesh, mr.material, mr.texture, mr.normalMap, c.r, c.g, c.b, c.a, mr.lit ? 1 : 0, imp.frames, imp.resolution].join('|');
+}
+
+/** @experimental */
+export class ImpostorPlugin implements Plugin {
+ name = 'impostor';
+
+ build(app: App): void {
+ const state = new ImpostorAtlases();
+ app.insertResource(ImpostorAtlasesRes, state);
+ const world = app.world;
+ let frame = 0;
+ // One kind at a time: every copy stands at the same place on the same layer, and two being photographed together would be
+ // in each other's pictures. It also spreads the cost of a scene with many kinds over its first frames.
+ let busy = false;
+
+ const handOver = (entity: Entity, kind: ImpostorKind | null): void => {
+ engineApi(app)?.renderer_setImpostorAtlas?.(entity as number, kind?.target?.textureId ?? 0, kind?.frames ?? 0);
+ };
+
+ const startBake = async (key: string, mr: MeshRendererData, imp: ImpostorData): Promise<void> => {
+ const kind: ImpostorKind = { target: null, frames: Math.max(2, Math.min(16, Math.round(imp.frames))), cameras: [], copy: null, since: -1, ready: false };
+ state.kinds.set(key, kind);
+ const mesh = app.hasResource(Assets) ? await app.getResource(Assets).readMeshData(mr.mesh) : null;
+ if (!mesh) { state.kinds.delete(key); busy = false; return; }
+ const centre: Vec3 = [(mesh.aabbMin[0] + mesh.aabbMax[0]) / 2, (mesh.aabbMin[1] + mesh.aabbMax[1]) / 2, (mesh.aabbMin[2] + mesh.aabbMax[2]) / 2];
+ const radius = Math.hypot(mesh.aabbMax[0] - mesh.aabbMin[0], mesh.aabbMax[1] - mesh.aabbMin[1], mesh.aabbMax[2] - mesh.aabbMin[2]) / 2;
+ if (!(radius > 0)) { state.kinds.delete(key); busy = false; return; }
+
+ const side = Math.max(128, Math.min(4096, Math.round(imp.resolution)));
+ kind.target = RenderTexture.create({ width: side, height: side, depth: true, filter: 'linear' });
+
+ // The copy: the mesh as it looks, alone on the bake layer, unturned and at its own size.
+ const copy = world.spawn();
+ world.insert(copy, RuntimeOnly);
+ world.insert(copy, Transform, { position: { x: BAKE_ORIGIN[0], y: BAKE_ORIGIN[1], z: BAKE_ORIGIN[2] } });
+ world.insert(copy, MeshRenderer, { ...mr, layer: IMPOSTOR_BAKE_LAYER, enabled: true });
+ kind.copy = copy;
+
+ const n = kind.frames;
+ const target: Vec3 = [BAKE_ORIGIN[0] + centre[0], BAKE_ORIGIN[1] + centre[1], BAKE_ORIGIN[2] + centre[2]];
+ for (let i = 0; i < n; i++) {
+ for (let j = 0; j < n; j++) {
+ const d = impostorFrameDirection(i, j, n);
+ const up = impostorPictureUp(d);
+ const cam = world.spawn();
+ world.insert(cam, RuntimeOnly);
+ world.insert(cam, Transform, {
+ position: { x: target[0] + d[0] * radius * 3, y: target[1] + d[1] * radius * 3, z: target[2] + d[2] * radius * 3 },
+ rotation: lookRotation(d, up),
+ });
+ world.insert(cam, Camera, {
+ projectionType: ProjectionType.Orthographic, orthoSize: radius, nearPlane: radius, farPlane: radius * 5,
+ isActive: true, priority: -100000, renderTarget: kind.target._handle,
+ // A viewport is placed from the top of its target and a texture is read from the bottom: row j of the
+ // atlas is the (n - 1 - j)th from the top.
+ viewport: { x: i / n, y: (n - 1 - j) / n, z: 1 / n, w: 1 / n },
+ cullingMask: (1 << IMPOSTOR_BAKE_LAYER) >>> 0, clearFlags: ClearFlags.ColorAndDepth,
+ });
+ setCameraClearColor(cam, { x: 0, y: 0, z: 0, w: 0 });
+ kind.cameras.push(cam);
+ }
+ }
+ kind.since = frame;
+ };
+
+ const finish = (kind: ImpostorKind): void => {
+ for (const cam of kind.cameras) { setCameraClearColor(cam, null); if (world.valid(cam)) world.despawn(cam); }
+ kind.cameras = [];
+ if (kind.copy !== null && world.valid(kind.copy)) world.despawn(kind.copy);
+ kind.copy = null;
+ kind.ready = true;
+ busy = false;
+ };
+
+ app.addSystemToSchedule(Schedule.PostUpdate, defineSystem([], () => {
+ frame++;
+ const def = getComponent('Impostor');
+ if (!def) return;
+ // Pictures set up two frames ago have been drawn: the cameras go, and the atlas is the kind's.
+ for (const kind of state.kinds.values()) {
+ if (!kind.ready && kind.since >= 0 && frame - kind.since >= 2) finish(kind);
+ }
+ const seen = new Set<Entity>();
+ for (const e of world.getEntitiesWithComponents([def, MeshRenderer])) {
+ const imp = world.get(e, def) as ImpostorData;
+ const mr = world.get(e, MeshRenderer) as MeshRendererData;
+ if (!imp.enabled || !mr.enabled || mr.mesh === 0 || world.has(e, RuntimeOnly)) continue;
+ seen.add(e);
+ const key = impostorKindKey(mr, imp);
+ const kind = state.kinds.get(key);
+ if (!kind) {
+ if (!busy) { busy = true; void startBake(key, mr, imp); }
+ continue;
+ }
+ if (!kind.ready) continue;
+ if (state.given.get(e) !== key) { handOver(e, kind); state.given.set(e, key); }
+ }
+ for (const [e] of state.given) {
+ if (seen.has(e)) continue;
+ if (world.valid(e)) handOver(e, null);
+ state.given.delete(e);
+ }
+ }, { name: 'ImpostorBakeSystem' }), { runIf: playModeOnly });
+ }
+}
+
+/** @experimental */
+export const impostorPlugin: Plugin = new ImpostorPlugin();
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 565b96182..e05411c79 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -686,6 +686,8 @@ export interface ESEngineModule {
renderer_getDrawCalls(): number;
/** Every draw the GPU was asked for in the last frame, every pass included. Optional: older engine builds do not carry it. */
renderer_getGpuDrawCalls?(): number;
+ /** Hand an entity's Impostor the atlas it draws from (0 takes it away). Optional: older engine builds do not carry it. */
+ renderer_setImpostorAtlas?(entity: number, texture: number, frames: number): void;
/**
* GPU objects the device has created and not destroyed, for the resource
* census. Null when no device is initialized — a census must record those
diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.ts
index e3aa0dc8f..35ba5c7ec 100644
--- a/sdk/src/wasm/ptrLayouts.generated.ts
+++ b/sdk/src/wasm/ptrLayouts.generated.ts
@@ -225,6 +225,15 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {
{ name: 'enabled', type: 'bool', offset: 4 },
],
},
+ Impostor: {
+ ptrFn: 'getImpostorPtr',
+ fields: [
+ { name: 'screenSize', type: 'f32', offset: 0 },
+ { name: 'frames', type: 'i32', offset: 4 },
+ { name: 'resolution', type: 'i32', offset: 8 },
+ { name: 'enabled', type: 'bool', offset: 12 },
+ ],
+ },
Interactable: {
ptrFn: 'getInteractablePtr',
fields: [
diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.ts
index f06074d36..e7d594a1e 100644
--- a/sdk/src/wasm/wasm.generated.ts
+++ b/sdk/src/wasm/wasm.generated.ts
@@ -642,6 +642,13 @@ export interface GroupOpacity {
enabled: boolean;
}
+export interface Impostor {
+ screenSize: number;
+ frames: number;
+ resolution: number;
+ enabled: boolean;
+}
+
export interface Interactable {
enabled: boolean;
blockRaycast: boolean;
@@ -1177,6 +1184,10 @@ export interface Registry {
getGroupOpacity(entity: Entity): GroupOpacity;
addGroupOpacity(entity: Entity, component: GroupOpacity): void;
removeGroupOpacity(entity: Entity): void;
+ hasImpostor(entity: Entity): boolean;
+ getImpostor(entity: Entity): Impostor;
+ addImpostor(entity: Entity, component: Impostor): void;
+ removeImpostor(entity: Entity): void;
hasInteractable(entity: Entity): boolean;
getInteractable(entity: Entity): Interactable;
addInteractable(entity: Entity, component: Interactable): void;
@@ -1361,6 +1372,7 @@ export interface ESEngineModule {
DragonBonesAnimation: new () => DragonBonesAnimation;
FlexContainer: new () => FlexContainer;
GroupOpacity: new () => GroupOpacity;
+ Impostor: new () => Impostor;
Interactable: new () => Interactable;
LODGroup: new () => LODGroup;
Light: new () => Light;
diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
index 91719c9b5..e4645dec7 100644
--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
@@ -242,6 +242,28 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho
"tooltip": "Opacity of this entity and everything under it, multiplied with the opacity of every group above it.",
},
},
+ "Impostor": {
+ "enabled": {
+ "tooltip": "Off: the mesh is always drawn as itself.",
+ },
+ "frames": {
+ "max": 16,
+ "min": 2,
+ "step": 1,
+ "tooltip": "Pictures along each side of the atlas (frames x frames in all). More is smoother as the view goes round, and smaller each.",
+ },
+ "resolution": {
+ "max": 4096,
+ "min": 128,
+ "step": 128,
+ "tooltip": "The atlas's side in pixels; each picture is this divided by frames.",
+ },
+ "screenSize": {
+ "max": 1,
+ "min": 0,
+ "tooltip": "Screen height fraction below which the card replaces the mesh.",
+ },
+ },
"Light": {
"aimFollowedSun": {
"advanced": true,
diff --git a/sdk/tests/impostor.test.ts b/sdk/tests/impostor.test.ts
new file mode 100644
index 000000000..de2874db5
--- /dev/null
+++ b/sdk/tests/impostor.test.ts
@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, expect, it } from 'vitest';
+import {
+ impostorDecode, impostorEncode, impostorFrameDirection, impostorPictureUp, impostorKindKey, lookRotation,
+} from '../src/render/impostor';
+
+const near = (a: number[], b: number[], eps = 1e-5): boolean => a.every((v, i) => Math.abs(v - b[i]!) < eps);
+const rotate = (q: { w: number; x: number; y: number; z: number }, v: number[]): number[] => {
+ const [x, y, z] = v as [number, number, number];
+ const tx = 2 * (q.y * z - q.z * y), ty = 2 * (q.z * x - q.x * z), tz = 2 * (q.x * y - q.y * x);
+ return [x + q.w * tx + (q.y * tz - q.z * ty), y + q.w * ty + (q.z * tx - q.x * tz), z + q.w * tz + (q.x * ty - q.y * tx)];
+};
+
+describe('the directions an impostor\'s pictures are taken from', () => {
+ it('are the renderer\'s own, to the numbers its test holds it to', () => {
+ // tests/renderer/test_impostor_frames.cpp prints and checks this one.
+ expect(near(impostorFrameDirection(2, 5, 8), [0, 0.8, -0.6])).toBe(true);
+ expect(near(impostorFrameDirection(0, 0, 8), [-1, 0, 0])).toBe(true);
+ expect(near(impostorDecode(0.5, 0.5), [0, 1, 0])).toBe(true);
+ });
+
+ it('fold and unfold to themselves over the upper hemisphere', () => {
+ for (let a = 0; a < 6.28; a += 0.37) {
+ for (let e = 0; e < 1.5; e += 0.29) {
+ const d = [Math.cos(a) * Math.cos(e), Math.sin(e), Math.sin(a) * Math.cos(e)] as [number, number, number];
+ const [u, v] = impostorEncode(d);
+ expect(near(impostorDecode(u, v), d, 1e-3)).toBe(true);
+ }
+ }
+ });
+
+ it('have an up across the view and toward the sky, and -z straight overhead', () => {
+ const d = [0.6, 0.48, 0.64] as [number, number, number];
+ const up = impostorPictureUp(d);
+ expect(Math.abs(up[0] * d[0] + up[1] * d[1] + up[2] * d[2])).toBeLessThan(1e-6);
+ expect(up[1]).toBeGreaterThan(0);
+ expect(near(impostorPictureUp([0, 1, 0]), [0, 0, -1])).toBe(true);
+ });
+});
+
+describe('a camera taking one of the pictures', () => {
+ it('looks back along its direction with the picture\'s up', () => {
+ for (const [i, j] of [[0, 0], [3, 4], [7, 7], [2, 5], [4, 4]]) {
+ const d = impostorFrameDirection(i!, j!, 8);
+ const q = lookRotation(d, impostorPictureUp(d));
+ // A camera looks down its own -Z: toward the object is -d.
+ expect(near(rotate(q, [0, 0, -1]), d.map((v) => -v), 1e-5)).toBe(true);
+ expect(near(rotate(q, [0, 1, 0]), impostorPictureUp(d), 1e-5)).toBe(true);
+ }
+ });
+});
+
+describe('which impostors share pictures', () => {
+ it('is everything that decides how the mesh looks, and how the atlas is cut', () => {
+ const mr = { mesh: 4, material: 0, texture: 2, normalMap: 0, color: { r: 1, g: 1, b: 1, a: 1 }, lit: true } as never;
+ const a = impostorKindKey(mr, { frames: 8, resolution: 1024, screenSize: 0.1, enabled: true });
+ expect(impostorKindKey(mr, { frames: 8, resolution: 1024, screenSize: 0.02, enabled: true })).toBe(a);
+ expect(impostorKindKey(mr, { frames: 12, resolution: 1024, screenSize: 0.1, enabled: true })).not.toBe(a);
+ expect(impostorKindKey({ ...(mr as object), texture: 3 } as never, { frames: 8, resolution: 1024, screenSize: 0.1, enabled: true })).not.toBe(a);
+ });
+});
diff --git a/src/esengine/aot/AotComponents.generated.cpp b/src/esengine/aot/AotComponents.generated.cpp
index 84b6208c6..c5d4d803b 100644
--- a/src/esengine/aot/AotComponents.generated.cpp
+++ b/src/esengine/aot/AotComponents.generated.cpp
@@ -21,6 +21,7 @@
#include "esengine/ecs/components/DragonBonesAnimation.hpp"
#include "esengine/ecs/components/FlexContainer.hpp"
#include "esengine/ecs/components/GroupOpacity.hpp"
+#include "esengine/ecs/components/Impostor.hpp"
#include "esengine/ecs/components/Interactable.hpp"
#include "esengine/ecs/components/LODGroup.hpp"
#include "esengine/ecs/components/Light.hpp"
@@ -154,6 +155,11 @@ ComponentAt engineComponentAt(ecs::Registry& registry, const char* name) {
return registry.tryGet<esengine::ecs::GroupOpacity>(Entity::fromRaw(raw));
};
}
+ if (std::strcmp(name, "Impostor") == 0) {
+ return [&registry](std::uint32_t raw) -> void* {
+ return registry.tryGet<esengine::ecs::Impostor>(Entity::fromRaw(raw));
+ };
+ }
if (std::strcmp(name, "Interactable") == 0) {
return [&registry](std::uint32_t raw) -> void* {
return registry.tryGet<esengine::ecs::Interactable>(Entity::fromRaw(raw));
@@ -428,6 +434,11 @@ CandidatesOf engineComponentCandidates(ecs::Registry& registry, const char* name
return denseAsIds(registry.entitiesWith<esengine::ecs::GroupOpacity>());
};
}
+ if (std::strcmp(name, "Impostor") == 0) {
+ return [&registry]() -> Candidates {
+ return denseAsIds(registry.entitiesWith<esengine::ecs::Impostor>());
+ };
+ }
if (std::strcmp(name, "Interactable") == 0) {
return [&registry]() -> Candidates {
return denseAsIds(registry.entitiesWith<esengine::ecs::Interactable>());
@@ -634,6 +645,7 @@ bool isEngineComponent(const char* name) {
if (std::strcmp(name, "DragonBonesAnimation") == 0) return true;
if (std::strcmp(name, "FlexContainer") == 0) return true;
if (std::strcmp(name, "GroupOpacity") == 0) return true;
+ if (std::strcmp(name, "Impostor") == 0) return true;
if (std::strcmp(name, "Interactable") == 0) return true;
if (std::strcmp(name, "LODGroup") == 0) return true;
if (std::strcmp(name, "Light") == 0) return true;
diff --git a/src/esengine/aot/EngineDigest.generated.h b/src/esengine/aot/EngineDigest.generated.h
index 647275b6e..fecaf98c5 100644
--- a/src/esengine/aot/EngineDigest.generated.h
+++ b/src/esengine/aot/EngineDigest.generated.h
@@ -6,7 +6,7 @@
/* One per address width, because the width is IN the digest: a host that
took the other one would refuse every module built for it. */
-#define ES_ENGINE_ABI_DIGEST_32 0xb535059db73b5e9eULL
-#define ES_ENGINE_ABI_DIGEST_64 0x9f8d59a45b74ff12ULL
+#define ES_ENGINE_ABI_DIGEST_32 0xb81a163f50f16233ULL
+#define ES_ENGINE_ABI_DIGEST_64 0xf32a5f990432930fULL
#define ES_ENGINE_ABI_DIGEST \
(sizeof(es_addr_t) == 8 ? ES_ENGINE_ABI_DIGEST_64 : ES_ENGINE_ABI_DIGEST_32)
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index 644d7fdea..94a905b0c 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 e8915b5d31e26125
+ * @schema_hash 6f0cd242105a26be
*/
-#define ES_EDITOR_API_SCHEMA_HASH "e8915b5d31e26125"
+#define ES_EDITOR_API_SCHEMA_HASH "6f0cd242105a26be"
#include <emscripten/bind.h>
#include <string>
@@ -24,6 +24,7 @@
#include "../ecs/components/FlexContainer.hpp"
#include "../ecs/components/GroupOpacity.hpp"
#include "../ecs/components/Hierarchy.hpp"
+#include "../ecs/components/Impostor.hpp"
#include "../ecs/components/Interactable.hpp"
#include "../ecs/components/LODGroup.hpp"
#include "../ecs/components/Light.hpp"
@@ -88,6 +89,7 @@ std::vector<std::string> editor_getComponentNames() {
"DragonBonesAnimation",
"FlexContainer",
"GroupOpacity",
+ "Impostor",
"Interactable",
"LODGroup",
"Light",
@@ -344,6 +346,13 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"opacity","type":"float","group":"GroupOpacity"},
{"key":"enabled","type":"bool","group":"GroupOpacity"}
])JSON";
+ } else if (name == "Impostor") {
+ return R"JSON([
+ {"key":"screenSize","type":"float","group":"Impostor"},
+ {"key":"frames","type":"int","group":"Impostor"},
+ {"key":"resolution","type":"int","group":"Impostor"},
+ {"key":"enabled","type":"bool","group":"Impostor"}
+ ])JSON";
} else if (name == "Interactable") {
return R"JSON([
{"key":"enabled","type":"bool","group":"Interactable"},
@@ -965,6 +974,9 @@ bool editor_addComponent(Registry& reg, u32 e, const std::string& name) {
} else if (name == "GroupOpacity") {
if (!reg.has<esengine::ecs::GroupOpacity>(entity)) reg.emplace<esengine::ecs::GroupOpacity>(entity);
return true;
+ } else if (name == "Impostor") {
+ if (!reg.has<esengine::ecs::Impostor>(entity)) reg.emplace<esengine::ecs::Impostor>(entity);
+ return true;
} else if (name == "Interactable") {
if (!reg.has<esengine::ecs::Interactable>(entity)) reg.emplace<esengine::ecs::Interactable>(entity);
return true;
@@ -1120,6 +1132,8 @@ bool editor_removeComponent(Registry& reg, u32 e, const std::string& name) {
if (reg.has<esengine::ecs::FlexContainer>(entity)) { reg.remove<esengine::ecs::FlexContainer>(entity); return true; }
} else if (name == "GroupOpacity") {
if (reg.has<esengine::ecs::GroupOpacity>(entity)) { reg.remove<esengine::ecs::GroupOpacity>(entity); return true; }
+ } else if (name == "Impostor") {
+ if (reg.has<esengine::ecs::Impostor>(entity)) { reg.remove<esengine::ecs::Impostor>(entity); return true; }
} else if (name == "Interactable") {
if (reg.has<esengine::ecs::Interactable>(entity)) { reg.remove<esengine::ecs::Interactable>(entity); return true; }
} else if (name == "LODGroup") {
@@ -1218,6 +1232,7 @@ bool editor_hasComponent(Registry& reg, u32 e, const std::string& name) {
if (name == "DragonBonesAnimation") return reg.has<esengine::ecs::DragonBonesAnimation>(entity);
if (name == "FlexContainer") return reg.has<esengine::ecs::FlexContainer>(entity);
if (name == "GroupOpacity") return reg.has<esengine::ecs::GroupOpacity>(entity);
+ if (name == "Impostor") return reg.has<esengine::ecs::Impostor>(entity);
if (name == "Interactable") return reg.has<esengine::ecs::Interactable>(entity);
if (name == "LODGroup") return reg.has<esengine::ecs::LODGroup>(entity);
if (name == "Light") return reg.has<esengine::ecs::Light>(entity);
@@ -1281,6 +1296,7 @@ std::vector<std::string> editor_getComponents(Registry& reg, u32 e) {
if (reg.has<esengine::ecs::DragonBonesAnimation>(entity)) result.push_back("DragonBonesAnimation");
if (reg.has<esengine::ecs::FlexContainer>(entity)) result.push_back("FlexContainer");
if (reg.has<esengine::ecs::GroupOpacity>(entity)) result.push_back("GroupOpacity");
+ if (reg.has<esengine::ecs::Impostor>(entity)) result.push_back("Impostor");
if (reg.has<esengine::ecs::Interactable>(entity)) result.push_back("Interactable");
if (reg.has<esengine::ecs::LODGroup>(entity)) result.push_back("LODGroup");
if (reg.has<esengine::ecs::Light>(entity)) result.push_back("Light");
@@ -1500,6 +1516,12 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::s
if (field == "opacity") { c.opacity = value; }
else { return false; }
return true;
+ } else if (comp == "Impostor") {
+ if (!reg.has<esengine::ecs::Impostor>(entity)) return false;
+ auto& c = reg.get<esengine::ecs::Impostor>(entity);
+ if (field == "screenSize") { c.screenSize = value; }
+ else { return false; }
+ return true;
} else if (comp == "LODGroup") {
if (!reg.has<esengine::ecs::LODGroup>(entity)) return false;
auto& c = reg.get<esengine::ecs::LODGroup>(entity);
@@ -2106,6 +2128,10 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::st
if (!reg.has<esengine::ecs::GroupOpacity>(entity)) return 0.0f;
const auto& c = reg.get<esengine::ecs::GroupOpacity>(entity);
if (field == "opacity") { return c.opacity; }
+ } else if (comp == "Impostor") {
+ if (!reg.has<esengine::ecs::Impostor>(entity)) return 0.0f;
+ const auto& c = reg.get<esengine::ecs::Impostor>(entity);
+ if (field == "screenSize") { return c.screenSize; }
} else if (comp == "LODGroup") {
if (!reg.has<esengine::ecs::LODGroup>(entity)) return 0.0f;
const auto& c = reg.get<esengine::ecs::LODGroup>(entity);
@@ -2574,6 +2600,13 @@ bool editor_setInt(Registry& reg, u32 e, const std::string& comp, const std::str
else if (field == "alignContent") { c.alignContent = static_cast<AlignContent>(value); }
else { return false; }
return true;
+ } else if (comp == "Impostor") {
+ if (!reg.has<esengine::ecs::Impostor>(entity)) return false;
+ auto& c = reg.get<esengine::ecs::Impostor>(entity);
+ if (field == "frames") { c.frames = static_cast<i32>(value); }
+ else if (field == "resolution") { c.resolution = static_cast<i32>(value); }
+ else { return false; }
+ return true;
} else if (comp == "LODGroup") {
if (!reg.has<esengine::ecs::LODGroup>(entity)) return false;
auto& c = reg.get<esengine::ecs::LODGroup>(entity);
@@ -2868,6 +2901,11 @@ i32 editor_getInt(Registry& reg, u32 e, const std::string& comp, const std::stri
else if (field == "justifyContent") { return static_cast<i32>(c.justifyContent); }
else if (field == "alignItems") { return static_cast<i32>(c.alignItems); }
else if (field == "alignContent") { return static_cast<i32>(c.alignContent); }
+ } else if (comp == "Impostor") {
+ if (!reg.has<esengine::ecs::Impostor>(entity)) return 0;
+ const auto& c = reg.get<esengine::ecs::Impostor>(entity);
+ if (field == "frames") { return static_cast<i32>(c.frames); }
+ else if (field == "resolution") { return static_cast<i32>(c.resolution); }
} else if (comp == "LODGroup") {
if (!reg.has<esengine::ecs::LODGroup>(entity)) return 0;
const auto& c = reg.get<esengine::ecs::LODGroup>(entity);
@@ -3145,6 +3183,12 @@ bool editor_setBool(Registry& reg, u32 e, const std::string& comp, const std::st
if (field == "enabled") { c.enabled = value; }
else { return false; }
return true;
+ } else if (comp == "Impostor") {
+ if (!reg.has<esengine::ecs::Impostor>(entity)) return false;
+ auto& c = reg.get<esengine::ecs::Impostor>(entity);
+ if (field == "enabled") { c.enabled = value; }
+ else { return false; }
+ return true;
} else if (comp == "Interactable") {
if (!reg.has<esengine::ecs::Interactable>(entity)) return false;
auto& c = reg.get<esengine::ecs::Interactable>(entity);
@@ -3429,6 +3473,10 @@ bool editor_getBool(Registry& reg, u32 e, const std::string& comp, const std::st
if (!reg.has<esengine::ecs::GroupOpacity>(entity)) return false;
const auto& c = reg.get<esengine::ecs::GroupOpacity>(entity);
if (field == "enabled") { return c.enabled; }
+ } else if (comp == "Impostor") {
+ if (!reg.has<esengine::ecs::Impostor>(entity)) return false;
+ const auto& c = reg.get<esengine::ecs::Impostor>(entity);
+ if (field == "enabled") { return c.enabled; }
} else if (comp == "Interactable") {
if (!reg.has<esengine::ecs::Interactable>(entity)) return false;
const auto& c = reg.get<esengine::ecs::Interactable>(entity);
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index d8d5235c8..5190d95d7 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -1338,6 +1338,11 @@ i32 renderer_lodInspect(u32 view, u32 entity, uintptr_t outPtr) {
return 1;
}
+void renderer_setImpostorAtlas(u32 entity, u32 texture, u32 frames) {
+ if (!g_renderFrame) return;
+ g_renderFrame->setImpostorAtlas(Entity::fromRaw(entity), texture, frames);
+}
+
void renderer_setLodPreview(u32 view, u32 entity, i32 level) {
if (!g_renderFrame) return;
const u8 held = level < 0 ? lod::kNoPreview : static_cast<u8>(level);
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index a2537a74e..a6f5a391f 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -297,6 +297,12 @@ i32 renderer_lodInspect(u32 view, u32 entity, uintptr_t outPtr);
*/
void renderer_setLodPreview(u32 view, u32 entity, i32 level);
+/**
+ * @brief Hand @p entity's Impostor the atlas it draws from: @p texture holds @p frames x @p frames pictures.
+ * @details A zero texture takes it away, and the mesh is drawn as itself at any size.
+ */
+void renderer_setImpostorAtlas(u32 entity, u32 texture, u32 frames);
+
/**
* @brief Shade a view's meshes as authored (0), as neutral clay (1) or as flat albedo (2).
* @details View state, like the LOD preview beside it: the same scene drawn through
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index aafa2a569..2407b3cce 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -24,6 +24,7 @@
#include "../ecs/components/FlexContainer.hpp"
#include "../ecs/components/GroupOpacity.hpp"
#include "../ecs/components/Hierarchy.hpp"
+#include "../ecs/components/Impostor.hpp"
#include "../ecs/components/Interactable.hpp"
#include "../ecs/components/LODGroup.hpp"
#include "../ecs/components/Light.hpp"
@@ -1998,6 +1999,12 @@ EMSCRIPTEN_BINDINGS(esengine_components) {
.field("opacity", &esengine::ecs::GroupOpacity::opacity)
.field("enabled", &esengine::ecs::GroupOpacity::enabled);
+ value_object<esengine::ecs::Impostor>("Impostor")
+ .field("screenSize", &esengine::ecs::Impostor::screenSize)
+ .field("frames", &esengine::ecs::Impostor::frames)
+ .field("resolution", &esengine::ecs::Impostor::resolution)
+ .field("enabled", &esengine::ecs::Impostor::enabled);
+
value_object<esengine::ecs::Interactable>("Interactable")
.field("enabled", &esengine::ecs::Interactable::enabled)
.field("blockRaycast", &esengine::ecs::Interactable::blockRaycast)
@@ -2466,6 +2473,7 @@ EMSCRIPTEN_BINDINGS(esengine_registry) {
if (r.has<esengine::ecs::DragonBonesAnimation>(entity)) { if (!names.empty()) names += "|"; names += "DragonBonesAnimation"; }
if (r.has<esengine::ecs::FlexContainer>(entity)) { if (!names.empty()) names += "|"; names += "FlexContainer"; }
if (r.has<esengine::ecs::GroupOpacity>(entity)) { if (!names.empty()) names += "|"; names += "GroupOpacity"; }
+ if (r.has<esengine::ecs::Impostor>(entity)) { if (!names.empty()) names += "|"; names += "Impostor"; }
if (r.has<esengine::ecs::Interactable>(entity)) { if (!names.empty()) names += "|"; names += "Interactable"; }
if (r.has<esengine::ecs::LODGroup>(entity)) { if (!names.empty()) names += "|"; names += "LODGroup"; }
if (r.has<esengine::ecs::Light>(entity)) { if (!names.empty()) names += "|"; names += "Light"; }
@@ -2524,6 +2532,7 @@ EMSCRIPTEN_BINDINGS(esengine_registry) {
if (name == "DragonBonesAnimation") return static_cast<int>(componentTypeId<esengine::ecs::DragonBonesAnimation>());
if (name == "FlexContainer") return static_cast<int>(componentTypeId<esengine::ecs::FlexContainer>());
if (name == "GroupOpacity") return static_cast<int>(componentTypeId<esengine::ecs::GroupOpacity>());
+ if (name == "Impostor") return static_cast<int>(componentTypeId<esengine::ecs::Impostor>());
if (name == "Interactable") return static_cast<int>(componentTypeId<esengine::ecs::Interactable>());
if (name == "LODGroup") return static_cast<int>(componentTypeId<esengine::ecs::LODGroup>());
if (name == "Light") return static_cast<int>(componentTypeId<esengine::ecs::Light>());
@@ -2940,6 +2949,27 @@ EMSCRIPTEN_BINDINGS(esengine_registry) {
r.remove<esengine::ecs::GroupOpacity>(entity);
}))
+ // Impostor
+ .function("hasImpostor", optional_override([](Registry& r, u32 e) {
+ return r.has<esengine::ecs::Impostor>(static_cast<Entity>(e));
+ }))
+ .function("getImpostor", optional_override([](Registry& r, u32 e) -> esengine::ecs::Impostor& {
+ auto entity = static_cast<Entity>(e);
+ static esengine::ecs::Impostor s_dummy{};
+ if (!r.valid(entity) || !r.has<esengine::ecs::Impostor>(entity)) return s_dummy;
+ return r.get<esengine::ecs::Impostor>(entity);
+ }), allow_raw_pointers())
+ .function("addImpostor", optional_override([](Registry& r, u32 e, const esengine::ecs::Impostor& c) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity)) return;
+ r.emplaceOrReplace<esengine::ecs::Impostor>(entity, c);
+ }))
+ .function("removeImpostor", optional_override([](Registry& r, u32 e) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity) || !r.has<esengine::ecs::Impostor>(entity)) return;
+ r.remove<esengine::ecs::Impostor>(entity);
+ }))
+
// Interactable
.function("hasInteractable", optional_override([](Registry& r, u32 e) {
return r.has<esengine::ecs::Interactable>(static_cast<Entity>(e));
@@ -3825,6 +3855,7 @@ emscripten::val esengineGetBuiltinComponentNames() {
arr.set(i++, val(std::string("DragonBonesAnimation")));
arr.set(i++, val(std::string("FlexContainer")));
arr.set(i++, val(std::string("GroupOpacity")));
+ arr.set(i++, val(std::string("Impostor")));
arr.set(i++, val(std::string("Interactable")));
arr.set(i++, val(std::string("LODGroup")));
arr.set(i++, val(std::string("Light")));
@@ -3994,6 +4025,10 @@ static_assert(offsetof(esengine::ecs::FlexContainer, gap) == 8, "ABI offset drif
static_assert(offsetof(esengine::ecs::FlexContainer, padding) == 16, "ABI offset drift: esengine::ecs::FlexContainer.padding (EHT expected 16)");
static_assert(offsetof(esengine::ecs::GroupOpacity, opacity) == 0, "ABI offset drift: esengine::ecs::GroupOpacity.opacity (EHT expected 0)");
static_assert(offsetof(esengine::ecs::GroupOpacity, enabled) == 4, "ABI offset drift: esengine::ecs::GroupOpacity.enabled (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::Impostor, screenSize) == 0, "ABI offset drift: esengine::ecs::Impostor.screenSize (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::Impostor, frames) == 4, "ABI offset drift: esengine::ecs::Impostor.frames (EHT expected 4)");
+static_assert(offsetof(esengine::ecs::Impostor, resolution) == 8, "ABI offset drift: esengine::ecs::Impostor.resolution (EHT expected 8)");
+static_assert(offsetof(esengine::ecs::Impostor, enabled) == 12, "ABI offset drift: esengine::ecs::Impostor.enabled (EHT expected 12)");
static_assert(offsetof(esengine::ecs::Interactable, enabled) == 0, "ABI offset drift: esengine::ecs::Interactable.enabled (EHT expected 0)");
static_assert(offsetof(esengine::ecs::Interactable, blockRaycast) == 1, "ABI offset drift: esengine::ecs::Interactable.blockRaycast (EHT expected 1)");
static_assert(offsetof(esengine::ecs::Interactable, raycastTarget) == 2, "ABI offset drift: esengine::ecs::Interactable.raycastTarget (EHT expected 2)");
@@ -4336,7 +4371,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "04cb5f0f12687160";
+static const char* kEsAbiLayoutHash = "0f608f110f54e807";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 30d691f31..1eb077d8d 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -807,6 +807,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("renderer_setViewId", &esengine::renderer_setViewId);
emscripten::function("renderer_lodInspect", &esengine::renderer_lodInspect);
emscripten::function("renderer_setLodPreview", &esengine::renderer_setLodPreview);
+ emscripten::function("renderer_setImpostorAtlas", &esengine::renderer_setImpostorAtlas);
emscripten::function("renderer_setViewShading", &esengine::renderer_setViewShading);
emscripten::function("renderer_setMeshEdgeBuffers", &esengine::renderer_setMeshEdgeBuffers);
emscripten::function("renderer_setViewSkinWeights", &esengine::renderer_setViewSkinWeights);
diff --git a/src/esengine/ecs/components/Impostor.hpp b/src/esengine/ecs/components/Impostor.hpp
new file mode 100644
index 000000000..6c43170e5
--- /dev/null
+++ b/src/esengine/ecs/components/Impostor.hpp
@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Impostor.hpp
+ * @brief A picture of a mesh, taken from many directions, drawn in its place once it is small.
+ *
+ * @author ESEngine Team
+ * @date 2026
+ *
+ * @copyright Copyright (c) 2026 ESEngine Team
+ * Licensed under the Apache License, Version 2.0.
+ */
+#pragma once
+
+#include "../../core/Types.hpp"
+#include "../../core/Reflection.hpp"
+
+namespace esengine::ecs {
+
+/**
+ * @brief Stands a card in for the MeshRenderer beside it once the object covers less than @ref screenSize of the view.
+ *
+ * @details The mesh is photographed from `frames` x `frames` directions over the upper half of a sphere into one atlas, as it is
+ * lit when the pictures are taken. Each view then draws the picture taken nearest its own direction to the object, on a
+ * card facing it, and every impostor that shares an atlas is drawn with the others: a forest on the horizon is a handful of
+ * draws. The atlas is shared by every entity with the same mesh, material, texture and colour.
+ *
+ * What it cannot do: the light is the light at the time of the pictures, the picture changes in steps as the view moves
+ * round, a card casts no shadow and is not seen from below.
+ */
+ES_COMPONENT(stability=beta)
+struct Impostor {
+ /** @brief Fraction of the viewport height below which the card replaces the mesh. */
+ ES_PROPERTY(min=0, max=1, tooltip="Screen height fraction below which the card replaces the mesh.")
+ f32 screenSize{0.06f};
+
+ /** @brief Directions along each side of the atlas: frames x frames pictures in all. */
+ ES_PROPERTY(min=2, max=16, step=1, tooltip="Pictures along each side of the atlas (frames x frames in all). More is smoother as the view goes round, and smaller each.")
+ i32 frames{8};
+
+ /** @brief The atlas's side in pixels. */
+ ES_PROPERTY(min=128, max=4096, step=128, tooltip="The atlas's side in pixels; each picture is this divided by frames.")
+ i32 resolution{1024};
+
+ ES_PROPERTY(tooltip="Off: the mesh is always drawn as itself.")
+ bool enabled{true};
+
+ Impostor() = default;
+};
+
+} // namespace esengine::ecs
diff --git a/src/esengine/renderer/draw/ImpostorFrames.hpp b/src/esengine/renderer/draw/ImpostorFrames.hpp
new file mode 100644
index 000000000..84326427f
--- /dev/null
+++ b/src/esengine/renderer/draw/ImpostorFrames.hpp
@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file ImpostorFrames.hpp
+ * @brief Which direction each picture of an impostor atlas is taken from, and which picture a view is shown.
+ *
+ * @details The pictures cover the upper half of a sphere on a hemi-octahedral grid: the square folds onto the hemisphere with its
+ * centre straight above and its edges round the horizon, so every grid point is a usable direction and the pictures are
+ * spread evenly. Frame (i, j) is taken from the grid point at (i, j) / (frames - 1), so the horizon is in the set. The SDK's
+ * bake places its cameras by the same rule (`impostorFrameDirection` in sdk/src/render/impostor.ts); the two are held to each
+ * other by tests on both sides.
+ *
+ * Header-only and free of the renderer: a direction and a frame count are the whole input.
+ */
+#pragma once
+
+#include "../../core/Types.hpp"
+#include "../../math/Math.hpp"
+
+#include <algorithm>
+#include <cmath>
+
+namespace esengine::impostor {
+
+/** @brief Where on the unit square a direction of the upper hemisphere folds to. Below the horizon is taken as on it. */
+inline glm::vec2 encode(glm::vec3 d) {
+ d.y = std::max(d.y, 0.0f);
+ const f32 s = std::abs(d.x) + std::abs(d.y) + std::abs(d.z);
+ if (s < 1e-12f) return glm::vec2(0.5f);
+ const f32 px = d.x / s, pz = d.z / s;
+ return glm::vec2((px + pz) * 0.5f + 0.5f, (px - pz) * 0.5f + 0.5f);
+}
+
+/** @brief The direction a point of the unit square unfolds to. */
+inline glm::vec3 decode(glm::vec2 uv) {
+ const f32 qx = uv.x * 2.0f - 1.0f, qy = uv.y * 2.0f - 1.0f;
+ const f32 px = (qx + qy) * 0.5f, pz = (qx - qy) * 0.5f;
+ const f32 y = 1.0f - std::abs(px) - std::abs(pz);
+ return glm::normalize(glm::vec3(px, std::max(y, 0.0f), pz));
+}
+
+/** @brief The direction, from the object toward the camera, that frame (@p i, @p j) is taken from. */
+inline glm::vec3 frameDirection(u32 i, u32 j, u32 frames) {
+ const f32 last = static_cast<f32>(std::max(frames, 2u) - 1u);
+ return decode(glm::vec2(static_cast<f32>(i) / last, static_cast<f32>(j) / last));
+}
+
+/** @brief The frame taken nearest @p d, a direction from the object toward the viewer in the object's own space. */
+inline glm::uvec2 nearestFrame(const glm::vec3& d, u32 frames) {
+ const glm::vec2 uv = encode(d);
+ const f32 last = static_cast<f32>(std::max(frames, 2u) - 1u);
+ const u32 i = static_cast<u32>(std::clamp(std::lround(uv.x * last), 0L, static_cast<long>(last)));
+ const u32 j = static_cast<u32>(std::clamp(std::lround(uv.y * last), 0L, static_cast<long>(last)));
+ return {i, j};
+}
+
+/**
+ * @brief The up a picture is taken with from @p d: world up laid flat across the view.
+ *
+ * @details Straight overhead there is no such thing, and -Z stands in (the bake's camera looks down with the object's -Z at the
+ * top of the picture). The card is drawn with the same rule, so a picture and its card agree on which way is up.
+ */
+inline glm::vec3 pictureUp(const glm::vec3& d) {
+ glm::vec3 up = glm::vec3(0.0f, 1.0f, 0.0f) - d * d.y;
+ if (glm::dot(up, up) < 1e-8f) return glm::vec3(0.0f, 0.0f, -1.0f);
+ return glm::normalize(up);
+}
+
+} // namespace esengine::impostor
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index 368b4e8ba..23347070d 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -120,6 +120,20 @@ public:
/// (a tiled one), the second pass is geometry paid for twice.
void setDepthPrepass(bool on) { depth_prepass_ = on; }
void setPlanarQuality(f32 scale, u32 maxSize, f32 updatesPerSecond);
+ /** @brief An impostor's pictures: the atlas texture and how many frames along its side. */
+ struct ImpostorAtlas {
+ u32 texture = 0;
+ u32 frames = 0;
+ };
+ /** @brief Hand @p entity the atlas its Impostor draws from; a zero texture takes it away. */
+ void setImpostorAtlas(Entity entity, u32 texture, u32 frames) {
+ if (texture == 0 || frames < 2) { impostor_atlases_.erase(entity.raw); return; }
+ impostor_atlases_[entity.raw] = {texture, frames};
+ }
+ const ImpostorAtlas* impostorAtlas(Entity entity) const {
+ const auto it = impostor_atlases_.find(entity.raw);
+ return it == impostor_atlases_.end() ? nullptr : &it->second;
+ }
u32 planarTextureFor(Entity entity) const {
return entity == planar_receiver_ ? planar_texture_ : 0;
}
@@ -739,6 +753,8 @@ private:
f32 planar_rate_ = 0;
Entity planar_receiver_ = INVALID_ENTITY;
u32 planar_texture_ = 0;
+ /// Each impostor's atlas, by raw entity id: set by the SDK's bake, read by the mesh collect.
+ std::unordered_map<u32, ImpostorAtlas> impostor_atlases_;
PlanarConstants planar_constants_;
glm::vec4 scene_clear_{0.0f, 0.0f, 0.0f, 1.0f};
rg::ResourceId planar_resource_ = rg::kNoResource;
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index 476f32035..2cfdb23ae 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -14,6 +14,9 @@
#include "../../ecs/components/LODGroup.hpp"
#include "../../ecs/components/Billboard.hpp"
#include "../draw/BillboardFacing.hpp"
+#include "../draw/ImpostorFrames.hpp"
+#include "../draw/BatchBuilder.hpp"
+#include "../../ecs/components/Impostor.hpp"
#include "../../resource/Mesh.hpp"
#include "../../resource/ShaderParser.hpp"
#include "../../core/Log.hpp"
@@ -553,6 +556,50 @@ void MeshPlugin::trackPose(const RenderFrameContext& ctx, Entity entity, const g
}
namespace {
+/**
+ * @brief The card an impostor draws: the picture taken nearest this view's direction to the object, on a square facing that way.
+ *
+ * @details The card is turned as its picture was taken, in the object's own space: from the frame's direction, with that picture's
+ * up. A view between two frames sees the card a few degrees off square, which is the price of not blending two pictures.
+ * Every impostor sharing an atlas shares this key but for its depth, so a crowd of them merges into a few draws.
+ */
+void emitImpostorCard(RenderCollectContext& collect, const RenderFrame::ImpostorAtlas& atlas, const ecs::MeshRenderer& mesh,
+ Entity entity, const glm::vec3& centre, f32 radius, const glm::quat& rotation) {
+ const glm::vec4 eye = collect.camera.eye;
+ glm::vec3 toward = eye.w > 0.5f ? glm::vec3(eye) - centre : glm::vec3(eye);
+ if (glm::dot(toward, toward) < 1e-12f) return;
+ const glm::vec3 local = glm::inverse(rotation) * glm::normalize(toward);
+ const glm::uvec2 frame = impostor::nearestFrame(local, atlas.frames);
+ const glm::vec3 d = impostor::frameDirection(frame.x, frame.y, atlas.frames);
+ const glm::vec3 upLocal = impostor::pictureUp(d);
+ const glm::vec3 up = rotation * upLocal * radius;
+ const glm::vec3 right = rotation * glm::cross(upLocal, d) * radius;
+ const f32 n = static_cast<f32>(atlas.frames);
+ const f32 u0 = static_cast<f32>(frame.x) / n, u1 = static_cast<f32>(frame.x + 1u) / n;
+ const f32 v0 = static_cast<f32>(frame.y) / n, v1 = static_cast<f32>(frame.y + 1u) / n;
+ const BatchVertex quad[4] = {
+ {centre - right - up, 0xFFFFFFFFu, {u0, v0}},
+ {centre + right - up, 0xFFFFFFFFu, {u1, v0}},
+ {centre + right + up, 0xFFFFFFFFu, {u1, v1}},
+ {centre - right + up, 0xFFFFFFFFu, {u0, v1}},
+ };
+ // Blended over what is behind it, the picture's empty corners being transparent, and depth-tested so a nearer wall hides it.
+ BatchDrawKey key{
+ .stage = RenderStage::Transparent,
+ .layer = mesh.layer,
+ .shaderId = collect.frame_context.batch_shader_id,
+ .blend = BlendMode::Normal,
+ .textureId = atlas.texture,
+ .depth = collect.camera.viewDepth(centre),
+ .y = centre.y,
+ .entity = entity,
+ .type = RenderType::Mesh,
+ };
+ key.depthTest = true;
+ key.depthWrite = false;
+ appendQuad(collect.buffer_pool, collect.draw_list, collect.clip_state, quad, key);
+}
+
/**
* @brief Writes the placements of a MeshInstances as instances of one draw per level of detail.
*
@@ -748,6 +795,23 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
}
}
tick(1);
+ // Small enough, and an impostor with its pictures taken: a card facing this view stands in for the mesh. Only the scene's own
+ // views draw one: a card casts no shadow, and a picture has no motion to write.
+ if (ctx.purpose == RenderPurpose::Scene && resident && !placements && ctx.frame) {
+ const auto* stand = registry.tryGet<ecs::Impostor>(entity);
+ const RenderFrame::ImpostorAtlas* atlas = stand && stand->enabled ? ctx.frame->impostorAtlas(entity) : nullptr;
+ if (atlas) {
+ glm::vec3 centre;
+ f32 radius = 0.0f;
+ lod::boundingSphere(position, transform.worldRotation, scale, resident->localMin, resident->localMax, centre, radius);
+ if (radius > 0.0f && lod::screenRelativeSize(ctx.view_projection, centre, radius) < stand->screenSize) {
+ if (collect_ctx.frustum.intersectsAABB(centre, glm::vec3(radius))) {
+ emitImpostorCard(collect_ctx, *atlas, mesh, entity, centre, radius, transform.worldRotation);
+ }
+ continue;
+ }
+ }
+ }
// A set of placements is bounded by where they stand, grown by how far the mesh reaches from its origin at the greatest scale.
const glm::vec3 reach = (placements ? glm::max(glm::abs(resident->localMin), glm::abs(resident->localMax)) * placements->maxScale
: glm::vec3(0.0f));
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index eaec7be6f..b1d172bfa 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -392,6 +392,14 @@ target_include_directories(test_billboard_facing PRIVATE
)
add_test(NAME test_billboard_facing COMMAND test_billboard_facing)
+# Which direction each picture of an impostor atlas is taken from, and which a view is shown. Header-only.
+add_executable(test_impostor_frames renderer/test_impostor_frames.cpp)
+target_include_directories(test_impostor_frames PRIVATE
+ ${CMAKE_SOURCE_DIR}/src
+ ${CMAKE_SOURCE_DIR}/third_party/glm
+)
+add_test(NAME test_impostor_frames COMMAND test_impostor_frames)
+
# How a view shades its meshes: Shaded unless it asked, and no entry left once it goes back.
add_executable(test_view_shading renderer/test_view_shading.cpp)
target_include_directories(test_view_shading PRIVATE
diff --git a/tests/aot/generated/conformance/handshake.h b/tests/aot/generated/conformance/handshake.h
index 1fe5657f1..eeb514b7a 100644
--- a/tests/aot/generated/conformance/handshake.h
+++ b/tests/aot/generated/conformance/handshake.h
@@ -1,5 +1,5 @@
/* GENERATED by sdk/tests/aot-conformance.test.ts — do not edit. */
/* The contract half of the handshake. The width half is the harness. */
-#define ES_CONF_EXPECTED_CONTRACT_HASH 0x9f8d59a45b74ff12ULL
+#define ES_CONF_EXPECTED_CONTRACT_HASH 0xf32a5f990432930fULL
/* And which BUILD the artifact beside this one is. */
#define ES_CONF_EXPECTED_MODULE_CONTRACT 0xc3d0e057d5701a2eULL
diff --git a/tests/aot/generated/conformance/systems_decl.c b/tests/aot/generated/conformance/systems_decl.c
index bd810e84f..1cf7585b7 100644
--- a/tests/aot/generated/conformance/systems_decl.c
+++ b/tests/aot/generated/conformance/systems_decl.c
@@ -10,7 +10,7 @@
answer, it is a read of a different field. The address width belongs
to the MACHINE, so it mixes in here rather than in the compiler and a
32-bit artifact cannot load into a 64-bit host. */
-#define ES_ABI_ENGINE_DIGEST 0x9f8d59a45b74ff12ULL
+#define ES_ABI_ENGINE_DIGEST 0xf32a5f990432930fULL
ES_EXPORT const uint64_t es_abi_hash =
ES_ABI_ENGINE_DIGEST ^ (0x9e3779b97f4a7c15ULL * (uint64_t)sizeof(es_addr_t));
diff --git a/tests/aot/generated/move_system_decl.c b/tests/aot/generated/move_system_decl.c
index 920e42a30..721c80f69 100644
--- a/tests/aot/generated/move_system_decl.c
+++ b/tests/aot/generated/move_system_decl.c
@@ -10,7 +10,7 @@
answer, it is a read of a different field. The address width belongs
to the MACHINE, so it mixes in here rather than in the compiler and a
32-bit artifact cannot load into a 64-bit host. */
-#define ES_ABI_ENGINE_DIGEST 0x9f8d59a45b74ff12ULL
+#define ES_ABI_ENGINE_DIGEST 0xf32a5f990432930fULL
ES_EXPORT const uint64_t es_abi_hash =
ES_ABI_ENGINE_DIGEST ^ (0x9e3779b97f4a7c15ULL * (uint64_t)sizeof(es_addr_t));
diff --git a/tests/aot/generated/move_system_hash.h b/tests/aot/generated/move_system_hash.h
index f79827c33..3f1e66d56 100644
--- a/tests/aot/generated/move_system_hash.h
+++ b/tests/aot/generated/move_system_hash.h
@@ -1,6 +1,6 @@
/* GENERATED by @estella/compiler — do not edit. */
/* The contract half of the handshake. The width half is the harness. */
-#define ES_EXPECTED_CONTRACT_HASH 0x9f8d59a45b74ff12ULL
+#define ES_EXPECTED_CONTRACT_HASH 0xf32a5f990432930fULL
/* And which BUILD the artifact beside this one is, which the sidecar
written with it has to carry too. */
#define ES_EXPECTED_MODULE_CONTRACT 0x10bf77bb714ea1e3ULL
diff --git a/tests/renderer/test_impostor_frames.cpp b/tests/renderer/test_impostor_frames.cpp
new file mode 100644
index 000000000..4c36f4225
--- /dev/null
+++ b/tests/renderer/test_impostor_frames.cpp
@@ -0,0 +1,65 @@
+// Which direction each picture of an impostor atlas is taken from, and which a view is shown, held against their claims without a
+// device. The SDK's bake places its cameras by the same rule; sdk/tests/impostor.test.ts holds it to the same numbers.
+
+#include "esengine/renderer/draw/ImpostorFrames.hpp"
+
+#include <cmath>
+#include <cstdio>
+
+using namespace esengine;
+
+static int g_failures = 0;
+#define CHECK(cond, msg) \
+ do { \
+ if (!(cond)) { std::printf("FAIL: %s\n", msg); ++g_failures; } \
+ else { std::printf("ok: %s\n", msg); } \
+ } while (0)
+
+static bool near(const glm::vec3& a, const glm::vec3& b, f32 eps = 1e-4f) { return glm::length(a - b) < eps; }
+
+static void testFolding() {
+ CHECK(near(impostor::decode(glm::vec2(0.5f)), glm::vec3(0.0f, 1.0f, 0.0f)), "the centre of the square is straight above");
+ CHECK(near(impostor::decode(glm::vec2(0.0f, 0.0f)), glm::vec3(-1.0f, 0.0f, 0.0f)), "a corner is on the horizon (-x)");
+ CHECK(near(impostor::decode(glm::vec2(1.0f, 0.0f)), glm::vec3(0.0f, 0.0f, 1.0f)), "the next corner is on the horizon (+z)");
+ bool round = true;
+ for (f32 a = 0.0f; a < 6.28f; a += 0.37f) {
+ for (f32 e = 0.0f; e < 1.5f; e += 0.29f) {
+ const glm::vec3 d(std::cos(a) * std::cos(e), std::sin(e), std::sin(a) * std::cos(e));
+ round = round && near(impostor::decode(impostor::encode(d)), glm::normalize(d), 1e-3f);
+ }
+ }
+ CHECK(round, "every direction of the upper hemisphere folds and unfolds to itself");
+ CHECK(near(impostor::decode(impostor::encode(glm::vec3(1.0f, -0.5f, 0.0f))), glm::vec3(1.0f, 0.0f, 0.0f)),
+ "below the horizon is taken as on it");
+}
+
+static void testFrames() {
+ const u32 n = 8;
+ CHECK(near(impostor::frameDirection(0, 0, n), glm::vec3(-1.0f, 0.0f, 0.0f)), "frame (0, 0) is taken from the horizon");
+ bool own = true;
+ for (u32 i = 0; i < n; ++i) for (u32 j = 0; j < n; ++j) {
+ const glm::uvec2 f = impostor::nearestFrame(impostor::frameDirection(i, j, n), n);
+ own = own && f.x == i && f.y == j;
+ }
+ CHECK(own, "a view from a frame's own direction is shown that frame");
+ // The numbers the TypeScript bake is held to.
+ const glm::vec3 d = impostor::frameDirection(2, 5, n);
+ std::printf(" frame (2, 5) of 8: %.6f %.6f %.6f\n", d.x, d.y, d.z);
+ CHECK(near(d, glm::normalize(glm::vec3(0.0f, 0.571429f, -0.428571f))),
+ "frame (2, 5) of 8 is where the SDK's bake puts its camera");
+}
+
+static void testUp() {
+ const glm::vec3 side = glm::normalize(glm::vec3(1.0f, 0.3f, 0.2f));
+ const glm::vec3 up = impostor::pictureUp(side);
+ CHECK(std::abs(glm::dot(up, side)) < 1e-5f && up.y > 0.0f, "a picture's up is across the view and toward the sky");
+ CHECK(near(impostor::pictureUp(glm::vec3(0.0f, 1.0f, 0.0f)), glm::vec3(0.0f, 0.0f, -1.0f)), "straight overhead, -z is up");
+}
+
+int main() {
+ testFolding();
+ testFrames();
+ testUp();
+ std::printf(g_failures ? "\n%d FAILED\n" : "\nall passed\n", g_failures);
+ return g_failures ? 1 : 0;
+}
diff --git a/tools/check-corpus-authoring.mjs b/tools/check-corpus-authoring.mjs
index c5f117582..a33773539 100644
--- a/tools/check-corpus-authoring.mjs
+++ b/tools/check-corpus-authoring.mjs
@@ -140,6 +140,7 @@ const DISPOSITION = {
Ragdoll: ['owed', 'no example carries a skinned character that is knocked down yet; the first one with a rigged enemy goes into one'],
RagdollJoint: ['owed', 'arrives with the first example that has a Ragdoll, which is the only place a bone needs a say of its own'],
TerrainBand2D: ['owed', 'no example draws a 2D ground from a spline yet; the first side-scroller built on one carries it'],
+ Impostor: ['owed', 'no example has far objects small enough to stand a picture in for yet; an open 3D world with distant props is the first to'],
Billboard: ['owed', 'no example draws a card that faces the camera yet; a 3D scene with signs or far trees on cards is the first to'],
Replicated: ['code-only', 'multiplayer-arena declares its replicated set beside the server systems that own it; the wire table is a contract both ends compile against, not scene content'],
diff --git a/tools/check-gizmo-coverage.mjs b/tools/check-gizmo-coverage.mjs
index 59cb8e52e..412c12cb4 100644
--- a/tools/check-gizmo-coverage.mjs
+++ b/tools/check-gizmo-coverage.mjs
@@ -126,6 +126,7 @@ const DISPOSITION = {
'Terrain.sizeX': ['renders', 'the ground drawn at it is the outline'],
'Terrain.sizeZ': ['renders', 'the ground drawn at it is the outline'],
'Terrain.height': ['renders', 'the ground drawn at it is the outline'],
+ 'Impostor.screenSize': ['not-world', 'a fraction of the view\'s height below which the card replaces the mesh, as LODGroup\'s sizes are'],
'Terrain.dirtHeight': ['not-world', 'a share of the height of the terrain, 0 to 1'],
'Terrain.snowHeight': ['not-world', 'a share of the height of the terrain, 0 to 1'],
'Footsteps.width': ['no-place', 'how far apart the left and right feet land, a spacing between steps and not a region of the walker'],