A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(render): 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.ymlindex 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_springbonetest_shader_device test_draw_params test_per_draw_blocks test_texture_fb test_buffer_devicetest_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_channelstest_text_edit test_render_graph test_device_loss test_physics_interpolationtest_bitmap_font test_texture_cache test_material_shader_lifetime test_mesh_recovery test_aot_host test_aot_conformancetest_touch_streamdiff --git a/desktop b/desktopindex 1b8e26f99..5d374e754 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 1b8e26f99f516bbfa890a3edd2c1d89070b741d9+Subproject commit 5d374e7546374b3f193acb7645eb8e32aa35920bdiff --git a/docs/astro/src/content/docs/performance/level-of-detail.mdx b/docs/astro/src/content/docs/performance/level-of-detail.mdxindex 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 countwhich is the point — it is the mechanism that decides whether a field of tenthousand 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 streamingdiff --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.mdxindex 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.tsindex 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.jsonindex 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.mdindex 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): HttpBackendstatic prototype: HttpBackend```+## IMPOSTOR_BAKE_LAYER — const @experimental+```+31+```+## INTERACTION_CONTROLLER — const @experimental```"$interaction"@@ -5010,6 +5015,41 @@ valign: ImageValignwidth: 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): PackagedAssetIndexdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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): HttpBackendstatic prototype: HttpBackend```+## IMPOSTOR_BAKE_LAYER — const @experimental+```+31+```+## INTERACTION_CONTROLLER — const @experimental```"$interaction"@@ -5018,6 +5023,41 @@ valign: ImageValignwidth: 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): PackagedAssetIndexdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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): HttpBackendstatic prototype: HttpBackend```+## IMPOSTOR_BAKE_LAYER — const @experimental+```+31+```+## INTERACTION_CONTROLLER — const @experimental```"$interaction"@@ -5005,6 +5010,41 @@ valign: ImageValignwidth: 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): PackagedAssetIndexdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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): HttpBackendstatic prototype: HttpBackend```+## IMPOSTOR_BAKE_LAYER — const @experimental+```+31+```+## INTERACTION_CONTROLLER — const @experimental```"$interaction"@@ -5005,6 +5010,41 @@ valign: ImageValignwidth: 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): PackagedAssetIndexdiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex b3881e705..2c85293a4 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -31,6 +31,7 @@ addDraggable: (entity: Entity, component: Draggable) => voidaddDragonBonesAnimation: (entity: Entity, component: DragonBonesAnimation) => voidaddFlexContainer: (entity: Entity, component: FlexContainer) => voidaddGroupOpacity: (entity: Entity, component: GroupOpacity) => void+addImpostor: (entity: Entity, component: Impostor) => voidaddInteractable: (entity: Entity, component: Interactable) => voidaddLODGroup: (entity: Entity, component: LODGroup) => voidaddLight: (entity: Entity, component: Light) => void@@ -92,6 +93,7 @@ getDraggable: (entity: Entity) => DraggablegetDragonBonesAnimation: (entity: Entity) => DragonBonesAnimationgetFlexContainer: (entity: Entity) => FlexContainergetGroupOpacity: (entity: Entity) => GroupOpacity+getImpostor: (entity: Entity) => ImpostorgetInteractable: (entity: Entity) => InteractablegetLODGroup: (entity: Entity) => LODGroupgetLight: (entity: Entity) => Light@@ -146,6 +148,7 @@ hasDraggable: (entity: Entity) => booleanhasDragonBonesAnimation: (entity: Entity) => booleanhasFlexContainer: (entity: Entity) => booleanhasGroupOpacity: (entity: Entity) => boolean+hasImpostor: (entity: Entity) => booleanhasInactiveEntities: (() => boolean) | undefinedhasInteractable: (entity: Entity) => booleanhasLODGroup: (entity: Entity) => boolean@@ -205,6 +208,7 @@ removeDraggable: (entity: Entity) => voidremoveDragonBonesAnimation: (entity: Entity) => voidremoveFlexContainer: (entity: Entity) => voidremoveGroupOpacity: (entity: Entity) => void+removeImpostor: (entity: Entity) => voidremoveInteractable: (entity: Entity) => voidremoveLODGroup: (entity: Entity) => voidremoveLight: (entity: Entity) => void@@ -538,6 +542,7 @@ renderer_setCullingMask: ((mask: number) => void) | undefinedrenderer_setDepthLayers: ((mask: number) => void) | undefinedrenderer_setDepthPrepass: ((on: boolean) => void) | undefinedrenderer_setEntityDrawOrder: ((registry: CppRegistry, entitiesPtr: number, count: number) => void) | undefined+renderer_setImpostorAtlas: ((entity: number, texture: number, frames: number) => void) | undefinedrenderer_setLodPreview: ((view: number, entity: number, level: number) => void) | undefinedrenderer_setMeshEdgeBuffers: ((enabled: boolean) => void) | undefinedrenderer_setOrigin: ((x: number, y: number, z: number) => void) | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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): HttpBackendstatic prototype: HttpBackend```+## IMPOSTOR_BAKE_LAYER — const @experimental+```+31+```+## INTERACTION_CONTROLLER — const @experimental```"$interaction"@@ -5012,6 +5017,41 @@ valign: ImageValignwidth: 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): PackagedAssetIndexdiff --git a/sdk/src/app/pluginSets.ts b/sdk/src/app/pluginSets.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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 thosediff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.tsindex 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.tsindex 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.snapindex 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.tsnew file mode 100644index 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.cppindex 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 [®istry](std::uint32_t raw) -> void* {+ return registry.tryGet<esengine::ecs::Impostor>(Entity::fromRaw(raw));+ };+ }if (std::strcmp(name, "Interactable") == 0) {return [®istry](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* namereturn denseAsIds(registry.entitiesWith<esengine::ecs::GroupOpacity>());};}+ if (std::strcmp(name, "Impostor") == 0) {+ return [®istry]() -> Candidates {+ return denseAsIds(registry.entitiesWith<esengine::ecs::Impostor>());+ };+ }if (std::strcmp(name, "Interactable") == 0) {return [®istry]() -> 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.hindex 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 thattook 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.cppindex 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::sif (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::stif (!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::strelse 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::strielse 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::stif (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::stif (!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.cppindex 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.hppindex 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 throughdiff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cppindex 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 drifstatic_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.cppindex 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.hppnew file mode 100644index 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::ecsdiff --git a/src/esengine/renderer/draw/ImpostorFrames.hpp b/src/esengine/renderer/draw/ImpostorFrames.hppnew file mode 100644index 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::impostordiff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex 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.cppindex 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.txtindex 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 PRIVATEdiff --git a/tests/aot/generated/conformance/handshake.h b/tests/aot/generated/conformance/handshake.hindex 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 0xc3d0e057d5701a2eULLdiff --git a/tests/aot/generated/conformance/systems_decl.c b/tests/aot/generated/conformance/systems_decl.cindex 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 belongsto the MACHINE, so it mixes in here rather than in the compiler and a32-bit artifact cannot load into a 64-bit host. */-#define ES_ABI_ENGINE_DIGEST 0x9f8d59a45b74ff12ULL+#define ES_ABI_ENGINE_DIGEST 0xf32a5f990432930fULLES_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.cindex 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 belongsto the MACHINE, so it mixes in here rather than in the compiler and a32-bit artifact cannot load into a 64-bit host. */-#define ES_ABI_ENGINE_DIGEST 0x9f8d59a45b74ff12ULL+#define ES_ABI_ENGINE_DIGEST 0xf32a5f990432930fULLES_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.hindex 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 sidecarwritten with it has to carry too. */#define ES_EXPECTED_MODULE_CONTRACT 0x10bf77bb714ea1e3ULLdiff --git a/tests/renderer/test_impostor_frames.cpp b/tests/renderer/test_impostor_frames.cppnew file mode 100644index 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.mjsindex 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.mjsindex 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'],