Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(render): Billboard turns a mesh to each view that draws it, flat in the view plane or upright about world up, without writing its Transform

yhh19eaef162a01
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 80e96eb61..8cc4fbe44 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -32,7 +32,7 @@ env:
test_hierarchy_links test_entity_activity test_transform_traversal test_ui_tree test_tween_activity test_springbone
test_shader_device test_draw_params test_per_draw_blocks test_texture_fb test_buffer_device
test_compressed_format test_batch_builder test_skeletal_batch_color test_boundary_span test_webgpu_device
- test_clip_depth test_planar_reflection test_sort_key test_retained_text test_sprite_mask_range test_sprite_draw_mode test_shadow_atlas test_particle_shapes test_lod_selection test_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_view_shading test_mesh_edges test_hdr_format test_probe_store test_occlusion_view test_reflection_store test_tiled_lights test_light_layers test_shadow_channels
test_text_edit test_render_graph test_device_loss test_physics_interpolation
test_bitmap_font test_texture_cache test_material_shader_lifetime test_mesh_recovery test_aot_host test_aot_conformance
test_touch_stream
diff --git a/desktop b/desktop
index 6522a4a66..1b8e26f99 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 6522a4a66da1ae75b6ced024d5cb265513bfb7ee
+Subproject commit 1b8e26f99f516bbfa890a3edd2c1d89070b741d9
diff --git a/docs/astro/src/content/docs/graphics/drawing.mdx b/docs/astro/src/content/docs/graphics/drawing.mdx
index e39400550..15526db4a 100644
--- a/docs/astro/src/content/docs/graphics/drawing.mdx
+++ b/docs/astro/src/content/docs/graphics/drawing.mdx
@@ -154,6 +154,26 @@ automatically; to **mutate it at runtime**, go through the `MeshRenderers` resou
`getGeometry` / `clearGeometry` round it out. Direct writes to the `geometry`
field alone are not change-detected.
+### Cards that face the camera: `Billboard`
+
+A `Billboard` beside a MeshRenderer turns the mesh to each view that draws it: a sign, a sprite of a character in a 3D world, a
+distant tree drawn on a card, a lens glint.
+
+```typescript
+world.insert(card, MeshRenderer, { mesh: 'builtin:quad', texture: tree, lit: false });
+world.insert(card, Billboard, { mode: BillboardMode.Upright });
+```
+
+- **View plane** (the default) lies flat in the view, the way a particle does: every card in a view faces the same way.
+- **Upright** turns about world up only, so it stays standing as the camera looks down on it. It is the one for trees, signs and
+ characters, which would otherwise tip back as the camera rises.
+
+The mesh's +Z is turned toward the viewer and its +Y up, which is how `builtin:quad` stands. The rotation is worked out by each
+view as it draws, so two cameras each see the card face on, and the entity's Transform is never written: scripts, physics and the
+editor's gizmo read the rotation that was authored. A shadow map is a view too, so a card turns to the light there and casts its
+whole outline. A Billboard is not merged by [static batching](/docs/performance/static-batching/), and a set of placements
+(`MeshInstances`) is not turned.
+
## Custom geometry: the `Geometry` API
Where `MeshRenderer` is the *component* path, `Geometry` is the *immediate* one: it
diff --git a/docs/astro/src/content/docs/performance/static-batching.mdx b/docs/astro/src/content/docs/performance/static-batching.mdx
index b15b8ba70..58f3b1863 100644
--- a/docs/astro/src/content/docs/performance/static-batching.mdx
+++ b/docs/astro/src/content/docs/performance/static-batching.mdx
@@ -40,6 +40,7 @@ runs, and in the profiler's **Static batch** section.
| Skinned | One draw can only be in one pose. |
| Morphing | One draw can only be in one shape. |
| Level of detail | The renderer chooses among levels at run time. |
+| Billboard | It turns to each view, and a merged mesh stays where it was baked. |
| Blended | Its result depends on drawing order, and merging is the loss of order. |
| Moves | A dynamic body or a character controller: a batch bakes where a mesh stands. |
| Baked light | The scene has probes or a bake, and a merged mesh cannot keep each part's own. |
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx
index 217b3e5cf..256e861fd 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx
@@ -142,6 +142,20 @@ cmds.spawn()
`MeshRenderers` 资源——`setGeometry(entity, geometry)` 重新上传(索引在引擎侧校验),
另有 `getGeometry` / `clearGeometry`。只改 `geometry` 字段本身不会被变更检测。
+### 朝向相机的卡片:`Billboard`
+
+MeshRenderer 旁边的 `Billboard` 会把网格转向每个画它的视图:招牌、3D 世界里角色的精灵、画在卡片上的远处的树、镜头闪光。
+
+```typescript
+world.insert(card, MeshRenderer, { mesh: 'builtin:quad', texture: tree, lit: false });
+world.insert(card, Billboard, { mode: BillboardMode.Upright });
+```
+
+- **视平面**(默认)平躺在视图里,和粒子一样:同一视图里的卡片全都朝同一个方向。
+- **直立**只绕世界的上方向转,所以相机往下看时它仍然立着。树、招牌和角色用这个,否则相机升高时它们会向后倒。
+
+网格的 +Z 转向观察者,+Y 朝上,也就是 `builtin:quad` 本来立着的样子。旋转由每个视图在绘制时各自算出,所以两台相机都能正面看到卡片,而实体的 Transform 从不被写入:脚本、物理和编辑器的 Gizmo 读到的都是编辑时设的旋转。阴影贴图也是一个视图,所以卡片在那里会转向光源,投下完整的轮廓。Billboard 不会被[静态合并](/docs/zh-cn/performance/static-batching/)合进去,一组摆放实例(`MeshInstances`)也不会被转动。
+
## 自定义几何:`Geometry` API
`MeshRenderer` 是*组件*路径,`Geometry` 则是*即时*路径:它上传一个索引顶点缓冲,交回
diff --git a/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx b/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx
index e4c7f705e..25fda249f 100644
--- a/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx
+++ b/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx
@@ -38,6 +38,7 @@ world.insert(wall, StaticBatch, {});
| 带骨骼 | 一次绘制只能处于一个姿态。 |
| 带形变 | 一次绘制只能处于一个形状。 |
| 细节层级 | 渲染器在运行时选择用哪一级。 |
+| 公告牌 | 它朝每个视图转,合并后的网格却固定在烘焙时的位置。 |
| 半透明 | 结果取决于绘制顺序,而合并就是丢掉顺序。 |
| 会动 | 动态刚体或角色控制器:合并把网格站的位置烘进了顶点。 |
| 烘焙光照 | 场景有探针或烘焙,合并后的网格留不住每个部件各自的那一份。 |
diff --git a/docs/astro/src/data/componentDocs.ts b/docs/astro/src/data/componentDocs.ts
index f2b5c9a92..1cf309e10 100644
--- a/docs/astro/src/data/componentDocs.ts
+++ b/docs/astro/src/data/componentDocs.ts
@@ -111,6 +111,7 @@ export const COMPONENT_DOCS: Record<string, ComponentDoc> = {
Spline: { category: 'graphics', summary: 'A curve through points, each with a width, read by what follows it (a river\'s WaterBody on the same entity); measured by the distance along it.', doc: 'graphics/water', anchor: 'splines', anchorZh: '样条' },
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' },
LODGroup: { category: 'graphics', summary: 'Cheaper stand-in meshes for a MeshRenderer, chosen by how much of the screen the object covers.', doc: 'performance/level-of-detail', anchor: 'the-lodgroup-component', anchorZh: 'lodgroup-组件' },
ReflectionProbe: { category: 'graphics', summary: 'A box inside which reflections come from a bake rather than from the sky — the specular half of what a light probe volume answers.', doc: 'graphics/lighting', anchor: 'baked-light', anchorZh: '烘焙光照' },
PlanarReflection: { category: 'graphics', summary: 'Captures a mirrored view for flat lit surfaces, with layer filtering, capture quality and update controls.', doc: 'graphics/lighting' },
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index 23eb8331d..b31aaf837 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -259,6 +259,28 @@
}
]
},
+ {
+ "name": "Billboard",
+ "source": "cpp",
+ "fields": [
+ {
+ "key": "mode",
+ "type": "enum",
+ "default": "ViewPlane",
+ "doc": "View plane lies flat in the view, like a particle. Upright turns about world up only, so it stays standing as the camera looks down.",
+ "values": [
+ "ViewPlane",
+ "Upright"
+ ]
+ },
+ {
+ "key": "enabled",
+ "type": "boolean",
+ "default": "true",
+ "doc": "Off: the mesh keeps the entity's own rotation."
+ }
+ ]
+ },
{
"name": "BitmapText",
"source": "cpp",
@@ -6434,7 +6456,8 @@
"Not merged: alone in its group",
"Not merged: no mesh",
"Not merged: vertex layout",
- "Not merged: disabled"
+ "Not merged: disabled",
+ "Not merged: billboard"
],
"readonly": true
},
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index c234b213d..961605d61 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 · 161 beta · 2002 experimental · 3 deprecated
+Symbols: 115 public · 163 beta · 2003 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"790a68ffa2098d35"
+"04cb5f0f12687160"
```
## ANCHOR_AXES — const @experimental
@@ -1669,6 +1669,23 @@ p2x: number
p2y: number
```
+## Billboard — const @experimental
+```
+BuiltinComponentDef<BillboardData>
+```
+
+## BillboardData — interface @beta
+```
+enabled: boolean
+mode: BillboardMode
+```
+
+## BillboardMode — enum @beta
+```
+Upright = 1
+ViewPlane = 0
+```
+
## Binding — type @public
```
| { kind: 'key'; code: string }
@@ -10321,6 +10338,8 @@ static prototype: StaticBatchPlugin
| 'morph'
/** Chooses among levels of detail at run time, which a merged mesh cannot. */
| 'lod'
+ /** A billboard: it turns to each view, and a merged mesh is fixed where it was baked. */
+ | 'billboard'
/** Lit by a bake: its atlas patch belongs to the object, not to the batch. */
| 'baked'
/** Blended: its result depends on order, and merging is the loss of order. */
@@ -10343,7 +10362,7 @@ refused: Map<number, StaticBatchRefusal>
## StaticBatchState — const @experimental
```
-{ readonly Pending: 0; readonly Merged: 1; readonly Skinned: 2; readonly Morph: 3; readonly Lod: 4; readonly Blended: 5; readonly Moves: 6; readonly Baked: 7; readonly Alone: 8; readonly NoMesh: 9; readonly Layout: 10; readonly Disabled: 11; }
+{ readonly Pending: 0; readonly Merged: 1; readonly Skinned: 2; readonly Morph: 3; readonly Lod: 4; readonly Blended: 5; readonly Moves: 6; readonly Baked: 7; readonly Alone: 8; readonly NoMesh: 9; readonly Layout: 10; readonly Disabled: 11; readonly Billboard: 12; }
```
## StaticBatchSummary — interface @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 04d6527ff..4c059efe8 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 · 166 beta · 2021 experimental · 3 deprecated
+Symbols: 115 public · 168 beta · 2022 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"790a68ffa2098d35"
+"04cb5f0f12687160"
```
## ANCHOR_AXES — const @experimental
@@ -1669,6 +1669,23 @@ p2x: number
p2y: number
```
+## Billboard — const @experimental
+```
+BuiltinComponentDef<BillboardData>
+```
+
+## BillboardData — interface @beta
+```
+enabled: boolean
+mode: BillboardMode
+```
+
+## BillboardMode — enum @beta
+```
+Upright = 1
+ViewPlane = 0
+```
+
## Binding — type @public
```
| { kind: 'key'; code: string }
@@ -10534,6 +10551,8 @@ static prototype: StaticBatchPlugin
| 'morph'
/** Chooses among levels of detail at run time, which a merged mesh cannot. */
| 'lod'
+ /** A billboard: it turns to each view, and a merged mesh is fixed where it was baked. */
+ | 'billboard'
/** Lit by a bake: its atlas patch belongs to the object, not to the batch. */
| 'baked'
/** Blended: its result depends on order, and merging is the loss of order. */
@@ -10556,7 +10575,7 @@ refused: Map<number, StaticBatchRefusal>
## StaticBatchState — const @experimental
```
-{ readonly Pending: 0; readonly Merged: 1; readonly Skinned: 2; readonly Morph: 3; readonly Lod: 4; readonly Blended: 5; readonly Moves: 6; readonly Baked: 7; readonly Alone: 8; readonly NoMesh: 9; readonly Layout: 10; readonly Disabled: 11; }
+{ readonly Pending: 0; readonly Merged: 1; readonly Skinned: 2; readonly Morph: 3; readonly Lod: 4; readonly Blended: 5; readonly Moves: 6; readonly Baked: 7; readonly Alone: 8; readonly NoMesh: 9; readonly Layout: 10; readonly Disabled: 11; readonly Billboard: 12; }
```
## StaticBatchSummary — interface @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index a5a9e04d7..f28560fea 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 · 163 beta · 2001 experimental · 3 deprecated
+Symbols: 115 public · 165 beta · 2002 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1664,6 +1664,23 @@ p2x: number
p2y: number
```
+## Billboard — const @experimental
+```
+BuiltinComponentDef<BillboardData>
+```
+
+## BillboardData — interface @beta
+```
+enabled: boolean
+mode: BillboardMode
+```
+
+## BillboardMode — enum @beta
+```
+Upright = 1
+ViewPlane = 0
+```
+
## Binding — type @public
```
| { kind: 'key'; code: string }
@@ -10316,6 +10333,8 @@ static prototype: StaticBatchPlugin
| 'morph'
/** Chooses among levels of detail at run time, which a merged mesh cannot. */
| 'lod'
+ /** A billboard: it turns to each view, and a merged mesh is fixed where it was baked. */
+ | 'billboard'
/** Lit by a bake: its atlas patch belongs to the object, not to the batch. */
| 'baked'
/** Blended: its result depends on order, and merging is the loss of order. */
@@ -10338,7 +10357,7 @@ refused: Map<number, StaticBatchRefusal>
## StaticBatchState — const @experimental
```
-{ readonly Pending: 0; readonly Merged: 1; readonly Skinned: 2; readonly Morph: 3; readonly Lod: 4; readonly Blended: 5; readonly Moves: 6; readonly Baked: 7; readonly Alone: 8; readonly NoMesh: 9; readonly Layout: 10; readonly Disabled: 11; }
+{ readonly Pending: 0; readonly Merged: 1; readonly Skinned: 2; readonly Morph: 3; readonly Lod: 4; readonly Blended: 5; readonly Moves: 6; readonly Baked: 7; readonly Alone: 8; readonly NoMesh: 9; readonly Layout: 10; readonly Disabled: 11; readonly Billboard: 12; }
```
## StaticBatchSummary — interface @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 1cc304786..31f744323 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 · 161 beta · 2023 experimental · 3 deprecated
+Symbols: 115 public · 163 beta · 2024 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1664,6 +1664,23 @@ p2x: number
p2y: number
```
+## Billboard — const @experimental
+```
+BuiltinComponentDef<BillboardData>
+```
+
+## BillboardData — interface @beta
+```
+enabled: boolean
+mode: BillboardMode
+```
+
+## BillboardMode — enum @beta
+```
+Upright = 1
+ViewPlane = 0
+```
+
## Binding — type @public
```
| { kind: 'key'; code: string }
@@ -10611,6 +10628,8 @@ static prototype: StaticBatchPlugin
| 'morph'
/** Chooses among levels of detail at run time, which a merged mesh cannot. */
| 'lod'
+ /** A billboard: it turns to each view, and a merged mesh is fixed where it was baked. */
+ | 'billboard'
/** Lit by a bake: its atlas patch belongs to the object, not to the batch. */
| 'baked'
/** Blended: its result depends on order, and merging is the loss of order. */
@@ -10633,7 +10652,7 @@ refused: Map<number, StaticBatchRefusal>
## StaticBatchState — const @experimental
```
-{ readonly Pending: 0; readonly Merged: 1; readonly Skinned: 2; readonly Morph: 3; readonly Lod: 4; readonly Blended: 5; readonly Moves: 6; readonly Baked: 7; readonly Alone: 8; readonly NoMesh: 9; readonly Layout: 10; readonly Disabled: 11; }
+{ readonly Pending: 0; readonly Merged: 1; readonly Skinned: 2; readonly Morph: 3; readonly Lod: 4; readonly Blended: 5; readonly Moves: 6; readonly Baked: 7; readonly Alone: 8; readonly NoMesh: 9; readonly Layout: 10; readonly Disabled: 11; readonly Billboard: 12; }
```
## StaticBatchSummary — interface @experimental
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index f604560e3..b3881e705 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -14,6 +14,7 @@ shutdown: () => void
## CppRegistry — interface @experimental
```
activityEpoch: (() => number) | undefined
+addBillboard: (entity: Entity, component: Billboard) => void
addBitmapText: (entity: Entity, component: BitmapText) => void
addBoxCollider2D: (entity: Entity, component: BoxCollider2D) => void
addBoxCollider3D: (entity: Entity, component: BoxCollider3D) => void
@@ -73,6 +74,7 @@ delete: () => void
destroy: (entity: Entity) => void
destructionPending: ((entity: Entity) => boolean) | undefined
entityCount: () => number
+getBillboard: (entity: Entity) => Billboard
getBitmapText: (entity: Entity) => BitmapText
getBoxCollider2D: (entity: Entity) => BoxCollider2D
getBoxCollider3D: (entity: Entity) => BoxCollider3D
@@ -127,6 +129,7 @@ getUINode: (entity: Entity) => UINode
getUIScroll: (entity: Entity) => UIScroll
getUIVisual: (entity: Entity) => UIVisual
getVelocity: (entity: Entity) => Velocity
+hasBillboard: (entity: Entity) => boolean
hasBitmapText: (entity: Entity) => boolean
hasBoxCollider2D: (entity: Entity) => boolean
hasBoxCollider3D: (entity: Entity) => boolean
@@ -185,6 +188,7 @@ isEntityActive: ((entity: Entity) => boolean) | undefined
isEntityEnabled: ((entity: Entity) => boolean) | undefined
layoutEpoch: (() => number) | undefined
releaseDestruction: ((entity: Entity) => void) | undefined
+removeBillboard: (entity: Entity) => void
removeBitmapText: (entity: Entity) => void
removeBoxCollider2D: (entity: Entity) => void
removeBoxCollider3D: (entity: Entity) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 04ed520da..7782fcf3b 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 · 161 beta · 2014 experimental · 3 deprecated
+Symbols: 115 public · 163 beta · 2015 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -1664,6 +1664,23 @@ p2x: number
p2y: number
```
+## Billboard — const @experimental
+```
+BuiltinComponentDef<BillboardData>
+```
+
+## BillboardData — interface @beta
+```
+enabled: boolean
+mode: BillboardMode
+```
+
+## BillboardMode — enum @beta
+```
+Upright = 1
+ViewPlane = 0
+```
+
## Binding — type @public
```
| { kind: 'key'; code: string }
@@ -10323,6 +10340,8 @@ static prototype: StaticBatchPlugin
| 'morph'
/** Chooses among levels of detail at run time, which a merged mesh cannot. */
| 'lod'
+ /** A billboard: it turns to each view, and a merged mesh is fixed where it was baked. */
+ | 'billboard'
/** Lit by a bake: its atlas patch belongs to the object, not to the batch. */
| 'baked'
/** Blended: its result depends on order, and merging is the loss of order. */
@@ -10345,7 +10364,7 @@ refused: Map<number, StaticBatchRefusal>
## StaticBatchState — const @experimental
```
-{ readonly Pending: 0; readonly Merged: 1; readonly Skinned: 2; readonly Morph: 3; readonly Lod: 4; readonly Blended: 5; readonly Moves: 6; readonly Baked: 7; readonly Alone: 8; readonly NoMesh: 9; readonly Layout: 10; readonly Disabled: 11; }
+{ readonly Pending: 0; readonly Merged: 1; readonly Skinned: 2; readonly Morph: 3; readonly Lod: 4; readonly Blended: 5; readonly Moves: 6; readonly Baked: 7; readonly Alone: 8; readonly NoMesh: 9; readonly Layout: 10; readonly Disabled: 11; readonly Billboard: 12; }
```
## StaticBatchSummary — interface @experimental
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index 101b01a63..140c313d4 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -111,6 +111,9 @@ export {
TrailRenderer,
SpringBone,
SpringBoneCollider,
+ Billboard,
+ type BillboardData,
+ BillboardMode,
MeshRenderer,
type MeshRendererData,
type MeshRendererGeometry,
diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
index 5021c8584..a04479c02 100644
--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts
+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
@@ -9,6 +9,34 @@ interface Vec3 { x: number; y: number; z: number; }
interface Vec4 { x: number; y: number; z: number; w: number; }
interface Color { r: number; g: number; b: number; a: number; }
+export interface BillboardPtrData {
+ mode: number;
+ enabled: boolean;
+}
+
+export function fillBillboard(
+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,
+ ptr: number, out: BillboardPtrData,
+): void {
+ out.mode = u32[ptr >> 2] | 0;
+ out.enabled = u8[ptr + 4] !== 0;
+}
+
+export function writeBillboard(
+ f32: Float32Array, u32: Uint32Array, u8: Uint8Array,
+ ptr: number, data: BillboardPtrData,
+): void {
+ u32[ptr >> 2] = data.mode | 0;
+ u8[ptr + 4] = data.enabled ? 1 : 0;
+}
+
+export function createBillboardData(): BillboardPtrData {
+ return {
+ mode: 0,
+ enabled: false,
+ };
+}
+
export interface BitmapTextPtrData {
color: Color;
fontSize: number;
@@ -2804,6 +2832,7 @@ export interface PtrAccessor<T> {
}
export const PTR_ACCESSORS: Record<string, PtrAccessor<any>> = {
+ Billboard: { fill: fillBillboard, write: writeBillboard, create: createBillboardData },
BitmapText: { fill: fillBitmapText, write: writeBitmapText, create: createBitmapTextData },
BoxCollider2D: { fill: fillBoxCollider2D, write: writeBoxCollider2D, create: createBoxCollider2DData },
BoxCollider3D: { fill: fillBoxCollider3D, write: writeBoxCollider3D, create: createBoxCollider3DData },
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index ae5eefb3d..b06061bdb 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -7,7 +7,7 @@
import type { AssetFieldType } from '../scene/scene';
import type { FieldMeta } from './component';
import type { Color, Entity, Quat, Vec2, Vec3, Vec4 } from '../types';
-import type { AlignContent, AlignItems, AlignSelf, BodyType, CanvasScaleMode, ClearFlags, Dimension, EmitterShape, FlexDirection, FlexWrap, ForceFieldType, JustifyContent, LightType, MaskMode, Padding, ParticleCollisionFallback, ParticleCollisionMode, ParticleEasing, ParticleRenderMode, ProjectionType, ReflectionAxis, ReflectionQuality, ReflectionUpdate, ScrollMovement, ShapeType, SimulationSpace, SpringBoneShape, SpriteDrawMode, SpriteMaskInteraction, SubEmitterTrigger, TextAlign, TilemapOrientation, TilemapStaggerAxis, TilemapStaggerIndex, UIDisplay, UIFillMethod, UIFillOrigin, UIPointerEvents, UIPositionType, UIVisualFit, UIVisualType } from '../wasm/wasm.generated';
+import type { AlignContent, AlignItems, AlignSelf, BillboardMode, BodyType, CanvasScaleMode, ClearFlags, Dimension, EmitterShape, FlexDirection, FlexWrap, ForceFieldType, JustifyContent, LightType, MaskMode, Padding, ParticleCollisionFallback, ParticleCollisionMode, ParticleEasing, ParticleRenderMode, ProjectionType, ReflectionAxis, ReflectionQuality, ReflectionUpdate, ScrollMovement, ShapeType, SimulationSpace, SpringBoneShape, SpriteDrawMode, SpriteMaskInteraction, SubEmitterTrigger, TextAlign, TilemapOrientation, TilemapStaggerAxis, TilemapStaggerIndex, UIDisplay, UIFillMethod, UIFillOrigin, UIPointerEvents, UIPositionType, UIVisualFit, UIVisualType } from '../wasm/wasm.generated';
/**
* Single-source-of-truth hash of the C++/TS boundary ABI (component
@@ -15,7 +15,7 @@ import type { AlignContent, AlignItems, AlignSelf, BodyType, CanvasScaleMode, Cl
* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
* run on mismatch, because mismatched offsets read the wrong heap bytes.
*/
-export const ABI_LAYOUT_HASH = '790a68ffa2098d35';
+export const ABI_LAYOUT_HASH = '04cb5f0f12687160';
/**
* One asset-valued field of a component: which field, and what kind of
@@ -103,6 +103,20 @@ export interface ComponentMetaEntry {
}
export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
+ Billboard: {
+ defaults: {
+ mode: 0,
+ enabled: true,
+ },
+ assetFields: [],
+ entityFields: [],
+ colorFields: [],
+ animatableFields: [],
+ fields: {
+ mode: { enum: [{ label: 'ViewPlane', value: 0 }, { label: 'Upright', value: 1 }], tooltip: "View plane lies flat in the view, like a particle. Upright turns about world up only, so it stays standing as the camera looks down." },
+ enabled: { tooltip: "Off: the mesh keeps the entity's own rotation." },
+ },
+ },
BitmapText: {
defaults: {
text: '',
@@ -1423,6 +1437,17 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
// generated so the TS field types cannot drift from the C++ structs. A consumer
// adds any TS-only authoring field (e.g. Camera.showFrustum) by extending these.
+/**
+ * The fields of the engine's `Billboard` component, generated from
+ * the C++ struct so the two shapes cannot drift.
+ *
+ * @beta
+ */
+export interface BillboardData {
+ mode: BillboardMode;
+ enabled: boolean;
+}
+
export interface BitmapTextData {
text: string;
color: Color;
diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.ts
index e5d689863..38dd9999c 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,
+ TilemapLayerData, BitmapTextData, TrailRendererData, ParticleForceFieldData, SpringBoneData, SpringBoneColliderData, BillboardData,
CameraData as CameraDataCpp, ParticleEmitterData as ParticleEmitterDataCpp,
MeshRendererData as MeshRendererDataCpp,
} from './component.generated';
@@ -28,7 +28,7 @@ import type {
// C++ enum and the editor dropdowns derive from the same values. ScaleMode's
// canonical values come from CanvasScaleMode (only its Cocos-compat aliases
// ShowAll/NoBorder are TS-side).
-import { ProjectionType, ClearFlags, EmitterShape, SimulationSpace, SubEmitterTrigger, ForceFieldType, LightType, CanvasScaleMode, ShapeType, ParticleEasing, ParticleCollisionMode, ParticleCollisionFallback, ParticleRenderMode, ReflectionAxis, ReflectionQuality, ReflectionUpdate, SpriteMaskInteraction, SpriteDrawMode } from '../wasm/wasm.generated';
+import { ProjectionType, ClearFlags, EmitterShape, SimulationSpace, SubEmitterTrigger, ForceFieldType, LightType, CanvasScaleMode, ShapeType, ParticleEasing, ParticleCollisionMode, ParticleCollisionFallback, ParticleRenderMode, ReflectionAxis, ReflectionQuality, ReflectionUpdate, SpriteMaskInteraction, SpriteDrawMode, BillboardMode } from '../wasm/wasm.generated';
import { BlendMode } from '../render/blend';
import { getDefaultContext } from './context';
import type {
@@ -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,
+ TilemapLayerData, BitmapTextData, TrailRendererData, ParticleForceFieldData, SpringBoneData, SpringBoneColliderData, BillboardData,
};
export type LocalTransformData = TransformData;
@@ -1151,6 +1151,11 @@ export const SpringBoneCollider = defineBuiltin<SpringBoneColliderData>('SpringB
metaDefaults<SpringBoneColliderData>('SpringBoneCollider')
);
+// A card that faces the camera. The renderer turns the MeshRenderer beside it to each view as the view collects it; the Transform is not written.
+export const Billboard = defineBuiltin<BillboardData>('Billboard',
+ metaDefaults<BillboardData>('Billboard')
+);
+
// 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',
@@ -1203,7 +1208,7 @@ export const TilemapLayer = defineBuiltin<TilemapLayerData>('TilemapLayer',
// EmitterShape, SimulationSpace and ParticleEasing are re-exported from the
// generated module (see the import at the top) — single-sourced from their C++
// ES_ENUMs beside the component fields that serialize them.
-export { ParticleEasing, ParticleCollisionMode, ParticleCollisionFallback, ParticleRenderMode, ReflectionAxis, ReflectionQuality, ReflectionUpdate };
+export { ParticleEasing, ParticleCollisionMode, ParticleCollisionFallback, ParticleRenderMode, ReflectionAxis, ReflectionQuality, ReflectionUpdate, BillboardMode };
// =============================================================================
// ParticleEmitter Component
diff --git a/sdk/src/render/staticBatch.ts b/sdk/src/render/staticBatch.ts
index fa0a09a79..08f41e883 100644
--- a/sdk/src/render/staticBatch.ts
+++ b/sdk/src/render/staticBatch.ts
@@ -31,6 +31,8 @@ export type StaticBatchRefusal =
| 'morph'
/** Chooses among levels of detail at run time, which a merged mesh cannot. */
| 'lod'
+ /** A billboard: it turns to each view, and a merged mesh is fixed where it was baked. */
+ | 'billboard'
/** Lit by a bake: its atlas patch belongs to the object, not to the batch. */
| 'baked'
/** Blended: its result depends on order, and merging is the loss of order. */
diff --git a/sdk/src/render/staticBatchPlugin.ts b/sdk/src/render/staticBatchPlugin.ts
index 276a76662..93d7239f4 100644
--- a/sdk/src/render/staticBatchPlugin.ts
+++ b/sdk/src/render/staticBatchPlugin.ts
@@ -49,13 +49,14 @@ export const StaticBatchState = {
NoMesh: 9,
Layout: 10,
Disabled: 11,
+ Billboard: 12,
} as const;
const REFUSAL_STATE: Record<StaticBatchRefusal, number> = {
skinned: StaticBatchState.Skinned, morph: StaticBatchState.Morph, lod: StaticBatchState.Lod,
blended: StaticBatchState.Blended, moves: StaticBatchState.Moves, baked: StaticBatchState.Baked,
alone: StaticBatchState.Alone, 'no-mesh': StaticBatchState.NoMesh, layout: StaticBatchState.Layout,
- disabled: StaticBatchState.Disabled,
+ disabled: StaticBatchState.Disabled, billboard: StaticBatchState.Billboard,
};
/** The fields of the `StaticBatch` component. @experimental */
@@ -98,9 +99,10 @@ export const StaticBatch: ComponentDef<StaticBatchData> = defineComponent<Static
{ label: 'Not merged: no mesh', value: StaticBatchState.NoMesh },
{ label: 'Not merged: vertex layout', value: StaticBatchState.Layout },
{ label: 'Not merged: disabled', value: StaticBatchState.Disabled },
+ { label: 'Not merged: billboard', value: StaticBatchState.Billboard },
],
// Nothing to say before a pass has run, so the row stays out of the way in the editor.
- shownWhen: { field: 'state', values: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11] },
+ shownWhen: { field: 'state', values: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] },
},
batched: { label: 'Batched meshes', min: 0, shownWhen: { field: 'state', values: [1] } },
},
@@ -258,6 +260,7 @@ export class StaticBatchPlugin implements Plugin {
private async pass(app: App, state: StaticBatching, assets: ReturnType<App['getResource']> & any, entities: Entity[]): Promise<void> {
const world = app.world;
const lodDef = getComponent('LODGroup');
+ const billboardDef = getComponent('Billboard');
const skinDef = getComponent('MeshSkin');
const probeDef = getComponent('LightProbeVolume');
const bakedDef = getComponent('BakedLighting');
@@ -279,6 +282,7 @@ export class StaticBatchPlugin implements Plugin {
if (!mr.enabled) { this.refuse(app, state, e, 'disabled'); continue; }
if (!mr.opaque) { this.refuse(app, state, e, 'blended'); continue; }
if (lodDef && world.has(e, lodDef)) { this.refuse(app, state, e, 'lod'); continue; }
+ if (billboardDef && world.has(e, billboardDef) && (world.get(e, billboardDef) as { enabled: boolean }).enabled) { this.refuse(app, state, e, 'billboard'); continue; }
if (skinDef && world.has(e, skinDef)) { this.refuse(app, state, e, 'skinned'); continue; }
if ((characterDef && world.has(e, characterDef))
|| (bodyDef && world.has(e, bodyDef) && (world.get(e, bodyDef) as { bodyType: number }).bodyType !== BodyType.Static)) {
diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.ts
index c53451ae8..e3aa0dc8f 100644
--- a/sdk/src/wasm/ptrLayouts.generated.ts
+++ b/sdk/src/wasm/ptrLayouts.generated.ts
@@ -27,6 +27,13 @@ export interface PtrLayout {
}
export const PTR_LAYOUTS: Record<string, PtrLayout> = {
+ Billboard: {
+ ptrFn: 'getBillboardPtr',
+ fields: [
+ { name: 'mode', type: 'i32', offset: 0 },
+ { name: 'enabled', type: 'bool', offset: 4 },
+ ],
+ },
BitmapText: {
ptrFn: 'getBitmapTextPtr',
fields: [
diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.ts
index 8a02ed96e..f06074d36 100644
--- a/sdk/src/wasm/wasm.generated.ts
+++ b/sdk/src/wasm/wasm.generated.ts
@@ -55,6 +55,16 @@ export enum AlignSelf {
Stretch = 4,
}
+/**
+ * The engine's `BillboardMode`, generated from the C++ enum.
+ *
+ * @beta
+ */
+export enum BillboardMode {
+ ViewPlane = 0,
+ Upright = 1,
+}
+
export enum BodyType {
Static = 0,
Kinematic = 1,
@@ -457,6 +467,11 @@ export enum UIVisualType {
// Components
+export interface Billboard {
+ mode: number;
+ enabled: boolean;
+}
+
export interface BitmapText {
text: string;
color: Vec4;
@@ -1094,6 +1109,10 @@ export interface Registry {
/** Host-local component ID; -1 for an unknown name. */
componentTypeId?(name: string): number;
+ hasBillboard(entity: Entity): boolean;
+ getBillboard(entity: Entity): Billboard;
+ addBillboard(entity: Entity, component: Billboard): void;
+ removeBillboard(entity: Entity): void;
hasBitmapText(entity: Entity): boolean;
getBitmapText(entity: Entity): BitmapText;
addBitmapText(entity: Entity, component: BitmapText): void;
@@ -1325,6 +1344,7 @@ export interface ESEngineModule {
* the shipped SDK and the actual WASM module.
*/
getBuiltinComponentNames(): string[];
+ Billboard: new () => Billboard;
BitmapText: new () => BitmapText;
BoxCollider2D: new () => BoxCollider2D;
BoxCollider3D: new () => BoxCollider3D;
diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
index 0d8cd53c5..91719c9b5 100644
--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
@@ -2,6 +2,24 @@
exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapshot of every builtin with declared field metadata 1`] = `
{
+ "Billboard": {
+ "enabled": {
+ "tooltip": "Off: the mesh keeps the entity's own rotation.",
+ },
+ "mode": {
+ "enum": [
+ {
+ "label": "ViewPlane",
+ "value": 0,
+ },
+ {
+ "label": "Upright",
+ "value": 1,
+ },
+ ],
+ "tooltip": "View plane lies flat in the view, like a particle. Upright turns about world up only, so it stays standing as the camera looks down.",
+ },
+ },
"BitmapText": {
"align": {
"enum": [
diff --git a/src/esengine/aot/AotComponents.generated.cpp b/src/esengine/aot/AotComponents.generated.cpp
index 6cfc16f2d..84b6208c6 100644
--- a/src/esengine/aot/AotComponents.generated.cpp
+++ b/src/esengine/aot/AotComponents.generated.cpp
@@ -9,6 +9,7 @@
#include "esengine/ecs/Entity.hpp"
#include "esengine/ecs/Registry.hpp"
+#include "esengine/ecs/components/Billboard.hpp"
#include "esengine/ecs/components/BitmapText.hpp"
#include "esengine/ecs/components/Collider2D.hpp"
#include "esengine/ecs/components/RigidBody3D.hpp"
@@ -68,6 +69,11 @@ Candidates denseAsIds(std::span<const Entity> dense) {
} // namespace
ComponentAt engineComponentAt(ecs::Registry& registry, const char* name) {
+ if (std::strcmp(name, "Billboard") == 0) {
+ return [&registry](std::uint32_t raw) -> void* {
+ return registry.tryGet<esengine::ecs::Billboard>(Entity::fromRaw(raw));
+ };
+ }
if (std::strcmp(name, "BitmapText") == 0) {
return [&registry](std::uint32_t raw) -> void* {
return registry.tryGet<esengine::ecs::BitmapText>(Entity::fromRaw(raw));
@@ -337,6 +343,11 @@ ComponentAt engineComponentAt(ecs::Registry& registry, const char* name) {
}
CandidatesOf engineComponentCandidates(ecs::Registry& registry, const char* name) {
+ if (std::strcmp(name, "Billboard") == 0) {
+ return [&registry]() -> Candidates {
+ return denseAsIds(registry.entitiesWith<esengine::ecs::Billboard>());
+ };
+ }
if (std::strcmp(name, "BitmapText") == 0) {
return [&registry]() -> Candidates {
return denseAsIds(registry.entitiesWith<esengine::ecs::BitmapText>());
@@ -606,6 +617,7 @@ CandidatesOf engineComponentCandidates(ecs::Registry& registry, const char* name
}
bool isEngineComponent(const char* name) {
+ if (std::strcmp(name, "Billboard") == 0) return true;
if (std::strcmp(name, "BitmapText") == 0) return true;
if (std::strcmp(name, "BoxCollider2D") == 0) return true;
if (std::strcmp(name, "BoxCollider3D") == 0) return true;
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index aac13772f..644d7fdea 100644
--- a/src/esengine/bindings/EditorAPI.generated.cpp
+++ b/src/esengine/bindings/EditorAPI.generated.cpp
@@ -2,16 +2,17 @@
* @file EditorAPI.generated.cpp
* @brief Auto-generated editor API with string-dispatched component access
* @details Generated by EHT - DO NOT EDIT
- * @schema_hash f91ae5c2af80fca7
+ * @schema_hash e8915b5d31e26125
*/
-#define ES_EDITOR_API_SCHEMA_HASH "f91ae5c2af80fca7"
+#define ES_EDITOR_API_SCHEMA_HASH "e8915b5d31e26125"
#include <emscripten/bind.h>
#include <string>
#include <vector>
#include "../ecs/Registry.hpp"
#include "../animation/TweenData.hpp"
+#include "../ecs/components/Billboard.hpp"
#include "../ecs/components/BitmapText.hpp"
#include "../ecs/components/BodyType.hpp"
#include "../ecs/components/Camera.hpp"
@@ -70,6 +71,7 @@ inline glm::quat eulerDegToQuat(const glm::vec3& deg) {
std::vector<std::string> editor_getComponentNames() {
return {
+ "Billboard",
"BitmapText",
"BoxCollider2D",
"BoxCollider3D",
@@ -129,7 +131,12 @@ std::vector<std::string> editor_getComponentNames() {
// ── Component Schema (JSON) ──
std::string editor_getComponentSchema(const std::string& name) {
- if (name == "BitmapText") {
+ if (name == "Billboard") {
+ return R"JSON([
+ {"key":"mode","type":"int","group":"Billboard"},
+ {"key":"enabled","type":"bool","group":"Billboard"}
+ ])JSON";
+ } else if (name == "BitmapText") {
return R"JSON([
{"key":"text","type":"string","group":"BitmapText"},
{"key":"color.r","type":"color","group":"BitmapText"},
@@ -908,7 +915,10 @@ std::string editor_getComponentSchema(const std::string& name) {
bool editor_addComponent(Registry& reg, u32 e, const std::string& name) {
auto entity = static_cast<Entity>(e);
if (!reg.valid(entity)) return false;
- if (name == "BitmapText") {
+ if (name == "Billboard") {
+ if (!reg.has<esengine::ecs::Billboard>(entity)) reg.emplace<esengine::ecs::Billboard>(entity);
+ return true;
+ } else if (name == "BitmapText") {
if (!reg.has<esengine::ecs::BitmapText>(entity)) reg.emplace<esengine::ecs::BitmapText>(entity);
return true;
} else if (name == "BoxCollider2D") {
@@ -1072,7 +1082,9 @@ bool editor_addComponent(Registry& reg, u32 e, const std::string& name) {
bool editor_removeComponent(Registry& reg, u32 e, const std::string& name) {
auto entity = static_cast<Entity>(e);
if (!reg.valid(entity)) return false;
- if (name == "BitmapText") {
+ if (name == "Billboard") {
+ if (reg.has<esengine::ecs::Billboard>(entity)) { reg.remove<esengine::ecs::Billboard>(entity); return true; }
+ } else if (name == "BitmapText") {
if (reg.has<esengine::ecs::BitmapText>(entity)) { reg.remove<esengine::ecs::BitmapText>(entity); return true; }
} else if (name == "BoxCollider2D") {
if (reg.has<esengine::ecs::BoxCollider2D>(entity)) { reg.remove<esengine::ecs::BoxCollider2D>(entity); return true; }
@@ -1189,6 +1201,7 @@ bool editor_removeComponent(Registry& reg, u32 e, const std::string& name) {
bool editor_hasComponent(Registry& reg, u32 e, const std::string& name) {
auto entity = static_cast<Entity>(e);
if (!reg.valid(entity)) return false;
+ if (name == "Billboard") return reg.has<esengine::ecs::Billboard>(entity);
if (name == "BitmapText") return reg.has<esengine::ecs::BitmapText>(entity);
if (name == "BoxCollider2D") return reg.has<esengine::ecs::BoxCollider2D>(entity);
if (name == "BoxCollider3D") return reg.has<esengine::ecs::BoxCollider3D>(entity);
@@ -1251,6 +1264,7 @@ std::vector<std::string> editor_getComponents(Registry& reg, u32 e) {
auto entity = static_cast<Entity>(e);
std::vector<std::string> result;
if (!reg.valid(entity)) return result;
+ if (reg.has<esengine::ecs::Billboard>(entity)) result.push_back("Billboard");
if (reg.has<esengine::ecs::BitmapText>(entity)) result.push_back("BitmapText");
if (reg.has<esengine::ecs::BoxCollider2D>(entity)) result.push_back("BoxCollider2D");
if (reg.has<esengine::ecs::BoxCollider3D>(entity)) result.push_back("BoxCollider3D");
@@ -2479,7 +2493,13 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::st
bool editor_setInt(Registry& reg, u32 e, const std::string& comp, const std::string& field, i32 value) {
auto entity = static_cast<Entity>(e);
if (!reg.valid(entity)) return false;
- if (comp == "BitmapText") {
+ if (comp == "Billboard") {
+ if (!reg.has<esengine::ecs::Billboard>(entity)) return false;
+ auto& c = reg.get<esengine::ecs::Billboard>(entity);
+ if (field == "mode") { c.mode = static_cast<i32>(value); }
+ else { return false; }
+ return true;
+ } else if (comp == "BitmapText") {
if (!reg.has<esengine::ecs::BitmapText>(entity)) return false;
auto& c = reg.get<esengine::ecs::BitmapText>(entity);
if (field == "align") { c.align = static_cast<TextAlign>(value); }
@@ -2789,7 +2809,11 @@ bool editor_setInt(Registry& reg, u32 e, const std::string& comp, const std::str
i32 editor_getInt(Registry& reg, u32 e, const std::string& comp, const std::string& field) {
auto entity = static_cast<Entity>(e);
if (!reg.valid(entity)) return 0;
- if (comp == "BitmapText") {
+ if (comp == "Billboard") {
+ if (!reg.has<esengine::ecs::Billboard>(entity)) return 0;
+ const auto& c = reg.get<esengine::ecs::Billboard>(entity);
+ if (field == "mode") { return static_cast<i32>(c.mode); }
+ } else if (comp == "BitmapText") {
if (!reg.has<esengine::ecs::BitmapText>(entity)) return 0;
const auto& c = reg.get<esengine::ecs::BitmapText>(entity);
if (field == "align") { return static_cast<i32>(c.align); }
@@ -3027,7 +3051,13 @@ i32 editor_getInt(Registry& reg, u32 e, const std::string& comp, const std::stri
bool editor_setBool(Registry& reg, u32 e, const std::string& comp, const std::string& field, bool value) {
auto entity = static_cast<Entity>(e);
if (!reg.valid(entity)) return false;
- if (comp == "BitmapText") {
+ if (comp == "Billboard") {
+ if (!reg.has<esengine::ecs::Billboard>(entity)) return false;
+ auto& c = reg.get<esengine::ecs::Billboard>(entity);
+ if (field == "enabled") { c.enabled = value; }
+ else { return false; }
+ return true;
+ } else if (comp == "BitmapText") {
if (!reg.has<esengine::ecs::BitmapText>(entity)) return false;
auto& c = reg.get<esengine::ecs::BitmapText>(entity);
if (field == "enabled") { c.enabled = value; }
@@ -3331,7 +3361,11 @@ bool editor_setBool(Registry& reg, u32 e, const std::string& comp, const std::st
bool editor_getBool(Registry& reg, u32 e, const std::string& comp, const std::string& field) {
auto entity = static_cast<Entity>(e);
if (!reg.valid(entity)) return false;
- if (comp == "BitmapText") {
+ if (comp == "Billboard") {
+ if (!reg.has<esengine::ecs::Billboard>(entity)) return false;
+ const auto& c = reg.get<esengine::ecs::Billboard>(entity);
+ if (field == "enabled") { return c.enabled; }
+ } else if (comp == "BitmapText") {
if (!reg.has<esengine::ecs::BitmapText>(entity)) return false;
const auto& c = reg.get<esengine::ecs::BitmapText>(entity);
if (field == "enabled") { return c.enabled; }
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index 4e413cb45..aafa2a569 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -12,6 +12,7 @@
#include "../ui/UITypes.hpp"
#include "../animation/TweenData.hpp"
#include "../ecs/TransformSystem.hpp"
+#include "../ecs/components/Billboard.hpp"
#include "../ecs/components/BitmapText.hpp"
#include "../ecs/components/BodyType.hpp"
#include "../ecs/components/Camera.hpp"
@@ -122,6 +123,10 @@ EMSCRIPTEN_BINDINGS(esengine_enums) {
.value("End", esengine::ecs::AlignSelf::End)
.value("Stretch", esengine::ecs::AlignSelf::Stretch);
+ enum_<esengine::ecs::BillboardMode>("BillboardMode")
+ .value("ViewPlane", esengine::ecs::BillboardMode::ViewPlane)
+ .value("Upright", esengine::ecs::BillboardMode::Upright);
+
enum_<esengine::ecs::BodyType>("BodyType")
.value("Static", esengine::ecs::BodyType::Static)
.value("Kinematic", esengine::ecs::BodyType::Kinematic)
@@ -1835,6 +1840,10 @@ EMSCRIPTEN_BINDINGS(esengine_components) {
register_vector<f32>("VectorFloat");
+ value_object<esengine::ecs::Billboard>("Billboard")
+ .field("mode", &esengine::ecs::Billboard::mode)
+ .field("enabled", &esengine::ecs::Billboard::enabled);
+
value_object<BitmapTextJS>("BitmapText")
.field("text", &BitmapTextJS::text)
.field("color", &BitmapTextJS::color)
@@ -2440,6 +2449,7 @@ EMSCRIPTEN_BINDINGS(esengine_registry) {
.function("getBuiltinComponentNames", optional_override([](Registry& r, u32 e) {
const auto entity = static_cast<Entity>(e);
std::string names;
+ if (r.has<esengine::ecs::Billboard>(entity)) { if (!names.empty()) names += "|"; names += "Billboard"; }
if (r.has<esengine::ecs::BitmapText>(entity)) { if (!names.empty()) names += "|"; names += "BitmapText"; }
if (r.has<esengine::ecs::BoxCollider2D>(entity)) { if (!names.empty()) names += "|"; names += "BoxCollider2D"; }
if (r.has<esengine::ecs::BoxCollider3D>(entity)) { if (!names.empty()) names += "|"; names += "BoxCollider3D"; }
@@ -2497,6 +2507,7 @@ EMSCRIPTEN_BINDINGS(esengine_registry) {
}))
.function("componentTypeId", optional_override([](Registry&, const std::string& name) {
+ if (name == "Billboard") return static_cast<int>(componentTypeId<esengine::ecs::Billboard>());
if (name == "BitmapText") return static_cast<int>(componentTypeId<esengine::ecs::BitmapText>());
if (name == "BoxCollider2D") return static_cast<int>(componentTypeId<esengine::ecs::BoxCollider2D>());
if (name == "BoxCollider3D") return static_cast<int>(componentTypeId<esengine::ecs::BoxCollider3D>());
@@ -2553,6 +2564,27 @@ EMSCRIPTEN_BINDINGS(esengine_registry) {
return -1;
}))
+ // Billboard
+ .function("hasBillboard", optional_override([](Registry& r, u32 e) {
+ return r.has<esengine::ecs::Billboard>(static_cast<Entity>(e));
+ }))
+ .function("getBillboard", optional_override([](Registry& r, u32 e) -> esengine::ecs::Billboard& {
+ auto entity = static_cast<Entity>(e);
+ static esengine::ecs::Billboard s_dummy{};
+ if (!r.valid(entity) || !r.has<esengine::ecs::Billboard>(entity)) return s_dummy;
+ return r.get<esengine::ecs::Billboard>(entity);
+ }), allow_raw_pointers())
+ .function("addBillboard", optional_override([](Registry& r, u32 e, const esengine::ecs::Billboard& c) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity)) return;
+ r.emplaceOrReplace<esengine::ecs::Billboard>(entity, c);
+ }))
+ .function("removeBillboard", optional_override([](Registry& r, u32 e) {
+ auto entity = static_cast<Entity>(e);
+ if (!r.valid(entity) || !r.has<esengine::ecs::Billboard>(entity)) return;
+ r.remove<esengine::ecs::Billboard>(entity);
+ }))
+
// BitmapText
.function("hasBitmapText", optional_override([](Registry& r, u32 e) {
return r.has<esengine::ecs::BitmapText>(static_cast<Entity>(e));
@@ -3776,6 +3808,7 @@ emscripten::val esengineGetBuiltinComponentNames() {
using namespace emscripten;
auto arr = val::array();
size_t i = 0;
+ arr.set(i++, val(std::string("Billboard")));
arr.set(i++, val(std::string("BitmapText")));
arr.set(i++, val(std::string("BoxCollider2D")));
arr.set(i++, val(std::string("BoxCollider3D")));
@@ -3843,6 +3876,8 @@ EMSCRIPTEN_BINDINGS(esengine_reflection) {
// compiler layout matches. A failure here means the TS pointer accessors would
// read the wrong bytes -- fix the struct or regenerate EHT. DO NOT EDIT.
+static_assert(offsetof(esengine::ecs::Billboard, mode) == 0, "ABI offset drift: esengine::ecs::Billboard.mode (EHT expected 0)");
+static_assert(offsetof(esengine::ecs::Billboard, enabled) == 4, "ABI offset drift: esengine::ecs::Billboard.enabled (EHT expected 4)");
static_assert(offsetof(esengine::ecs::BitmapText, color) == 12, "ABI offset drift: esengine::ecs::BitmapText.color (EHT expected 12)");
static_assert(offsetof(esengine::ecs::BitmapText, fontSize) == 28, "ABI offset drift: esengine::ecs::BitmapText.fontSize (EHT expected 28)");
static_assert(offsetof(esengine::ecs::BitmapText, align) == 32, "ABI offset drift: esengine::ecs::BitmapText.align (EHT expected 32)");
@@ -4301,7 +4336,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "790a68ffa2098d35";
+static const char* kEsAbiLayoutHash = "04cb5f0f12687160";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/ecs/components/Billboard.hpp b/src/esengine/ecs/components/Billboard.hpp
new file mode 100644
index 000000000..70ff09649
--- /dev/null
+++ b/src/esengine/ecs/components/Billboard.hpp
@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Billboard.hpp
+ * @brief A mesh that turns to whoever looks at it.
+ *
+ * @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 {
+
+/// How a billboard is turned. ViewPlane lies flat in the view, like a particle; Upright turns about world up only, so a tree, a sign or a
+/// character drawn on a card stays standing as the camera looks down on it.
+ES_ENUM(stability=beta)
+enum class BillboardMode : i32 {
+ ViewPlane = 0,
+ Upright = 1,
+};
+
+/**
+ * @brief Turns the MeshRenderer beside it to face each view that draws it.
+ *
+ * @details The rotation is the VIEW's, worked out while the view collects what it draws, so two cameras each see the card face on and the
+ * entity's own Transform is never written: scripts, physics and the editor read the rotation that was authored. The mesh's +Z is
+ * turned toward the viewer and its +Y up, which is how a builtin quad stands; position and scale are the entity's. A shadow map
+ * is a view too, so a card turns to the light there and casts its whole outline.
+ */
+ES_COMPONENT(stability=beta)
+struct Billboard {
+ ES_PROPERTY(enum=BillboardMode, tooltip="View plane lies flat in the view, like a particle. Upright turns about world up only, so it stays standing as the camera looks down.")
+ i32 mode{static_cast<i32>(BillboardMode::ViewPlane)};
+
+ ES_PROPERTY(tooltip="Off: the mesh keeps the entity's own rotation.")
+ bool enabled{true};
+
+ Billboard() = default;
+};
+
+} // namespace esengine::ecs
diff --git a/src/esengine/renderer/draw/BillboardFacing.hpp b/src/esengine/renderer/draw/BillboardFacing.hpp
new file mode 100644
index 000000000..29a8bea93
--- /dev/null
+++ b/src/esengine/renderer/draw/BillboardFacing.hpp
@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file BillboardFacing.hpp
+ * @brief The rotation that turns a card to a view.
+ *
+ * @details Header-only and free of the renderer: a view-projection, the view's eye and where the card stands are the whole input, so the
+ * arithmetic can be held against its claims without a device.
+ */
+#pragma once
+
+#include "../../core/Types.hpp"
+#include "../../math/Math.hpp"
+
+#include <glm/gtc/quaternion.hpp>
+
+#include <cmath>
+
+namespace esengine::billboard {
+
+/** @brief The view's right, up and toward-the-viewer axes in the world, read off its view-projection. */
+struct ViewAxes {
+ glm::vec3 right{1.0f, 0.0f, 0.0f};
+ glm::vec3 up{0.0f, 1.0f, 0.0f};
+ glm::vec3 back{0.0f, 0.0f, 1.0f};
+};
+
+/**
+ * @brief The axes a view looks along.
+ *
+ * @details NDC x and y are the view's right and up scaled by the projection, so the first two rows of the view-projection point along them
+ * under both projections (a jittered or off-centre frustum leans them by its tiny skew, and the cross products below take that out).
+ * Toward the viewer is their cross product: the camera looks down its own -Z.
+ */
+inline ViewAxes viewAxes(const glm::mat4& viewProjection) {
+ const glm::vec3 row0(viewProjection[0][0], viewProjection[1][0], viewProjection[2][0]);
+ const glm::vec3 row1(viewProjection[0][1], viewProjection[1][1], viewProjection[2][1]);
+ ViewAxes axes;
+ if (glm::dot(row0, row0) < 1e-20f || glm::dot(row1, row1) < 1e-20f) return axes;
+ const glm::vec3 right = glm::normalize(row0);
+ const glm::vec3 back = glm::cross(right, glm::normalize(row1));
+ if (glm::dot(back, back) < 1e-12f) return axes;
+ axes.back = glm::normalize(back);
+ axes.right = right;
+ axes.up = glm::cross(axes.back, axes.right);
+ return axes;
+}
+
+/**
+ * @brief The rotation a card standing at @p position is drawn with in this view.
+ *
+ * @param mode 0 lies flat in the view plane; 1 turns about world up only.
+ * @param viewProjection The view's, which is where the view plane comes from.
+ * @param eye The view's eye in FrameConstants::camera's convention: a position when w = 1, the direction toward the viewer when
+ * w = 0 (an orthographic view, which has no position).
+ */
+inline glm::quat facing(i32 mode, const glm::mat4& viewProjection, const glm::vec4& eye, const glm::vec3& position) {
+ const ViewAxes axes = viewAxes(viewProjection);
+ if (mode != 1) {
+ // Columns are where the card's own +X, +Y and +Z go.
+ return glm::quat_cast(glm::mat3(axes.right, axes.up, axes.back));
+ }
+ // Upright: toward the viewer, flattened onto the ground. Straight overhead there is no such direction, and the view plane's own back,
+ // flattened, is what keeps the card from spinning as the camera passes over it.
+ glm::vec3 toward = eye.w > 0.5f ? glm::vec3(eye) - position : glm::vec3(eye);
+ toward.y = 0.0f;
+ if (glm::dot(toward, toward) < 1e-8f) {
+ toward = glm::vec3(axes.back.x, 0.0f, axes.back.z);
+ if (glm::dot(toward, toward) < 1e-8f) toward = -glm::vec3(axes.up.x, 0.0f, axes.up.z);
+ if (glm::dot(toward, toward) < 1e-8f) return glm::quat(1.0f, 0.0f, 0.0f, 0.0f);
+ }
+ const f32 yaw = std::atan2(toward.x, toward.z);
+ return glm::angleAxis(yaw, glm::vec3(0.0f, 1.0f, 0.0f));
+}
+
+} // namespace esengine::billboard
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index 04c119dbc..476f32035 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -12,6 +12,8 @@
#include "../../ecs/components/Transform.hpp"
#include "../../ecs/components/MeshRenderer.hpp"
#include "../../ecs/components/LODGroup.hpp"
+#include "../../ecs/components/Billboard.hpp"
+#include "../draw/BillboardFacing.hpp"
#include "../../resource/Mesh.hpp"
#include "../../resource/ShaderParser.hpp"
#include "../../core/Log.hpp"
@@ -704,7 +706,12 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
const glm::vec3 position = shadowDepth
? rebased(transform.worldPosition)
: parallaxedWorldPosition(transform, mesh.parallax, collect_ctx.camera);
- const auto& rotation = transform.worldRotation;
+ // A card turns to THIS view, whichever it is: the Transform keeps what was authored. Placements are each turned by their own
+ // record, so a set of them is left as it stands.
+ const ecs::Billboard* card = registry.tryGet<ecs::Billboard>(entity);
+ const glm::quat rotation = card && card->enabled && !registry.tryGet<ecs::MeshInstances>(entity)
+ ? billboard::facing(card->mode, ctx.view_projection, collect_ctx.camera.eye, position)
+ : transform.worldRotation;
const auto& scale = transform.worldScale;
tick(0);
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index b0b6dff3a..eaec7be6f 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -384,6 +384,14 @@ target_include_directories(test_lod_selection PRIVATE
)
add_test(NAME test_lod_selection COMMAND test_lod_selection)
+# How a Billboard is turned to a view: the view plane, upright about world up, an orthographic view. Header-only.
+add_executable(test_billboard_facing renderer/test_billboard_facing.cpp)
+target_include_directories(test_billboard_facing PRIVATE
+ ${CMAKE_SOURCE_DIR}/src
+ ${CMAKE_SOURCE_DIR}/third_party/glm
+)
+add_test(NAME test_billboard_facing COMMAND test_billboard_facing)
+
# How a view shades its meshes: Shaded unless it asked, and no entry left once it goes back.
add_executable(test_view_shading renderer/test_view_shading.cpp)
target_include_directories(test_view_shading PRIVATE
diff --git a/tests/aot/generated/conformance/handshake.h b/tests/aot/generated/conformance/handshake.h
index 3584a80cd..1fe5657f1 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 0x57b9f31fef78b5a7ULL
+#define ES_CONF_EXPECTED_CONTRACT_HASH 0x9f8d59a45b74ff12ULL
/* And which BUILD the artifact beside this one is. */
#define ES_CONF_EXPECTED_MODULE_CONTRACT 0xc3d0e057d5701a2eULL
diff --git a/tests/aot/generated/conformance/systems_decl.c b/tests/aot/generated/conformance/systems_decl.c
index 24bc0407b..bd810e84f 100644
--- a/tests/aot/generated/conformance/systems_decl.c
+++ b/tests/aot/generated/conformance/systems_decl.c
@@ -10,7 +10,7 @@
answer, it is a read of a different field. The address width belongs
to the MACHINE, so it mixes in here rather than in the compiler and a
32-bit artifact cannot load into a 64-bit host. */
-#define ES_ABI_ENGINE_DIGEST 0x57b9f31fef78b5a7ULL
+#define ES_ABI_ENGINE_DIGEST 0x9f8d59a45b74ff12ULL
ES_EXPORT const uint64_t es_abi_hash =
ES_ABI_ENGINE_DIGEST ^ (0x9e3779b97f4a7c15ULL * (uint64_t)sizeof(es_addr_t));
diff --git a/tests/renderer/test_billboard_facing.cpp b/tests/renderer/test_billboard_facing.cpp
new file mode 100644
index 000000000..b9da57eed
--- /dev/null
+++ b/tests/renderer/test_billboard_facing.cpp
@@ -0,0 +1,78 @@
+// The rotation a Billboard is drawn with, held against its claims without a device: a view-projection, an eye and where the card stands
+// are the whole input. A pixel gate can say a card looked wrong; only this can say which way it was turned.
+
+#include "esengine/renderer/draw/BillboardFacing.hpp"
+
+#include <glm/gtc/matrix_transform.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-3f) { return glm::length(a - b) < eps; }
+
+static glm::mat4 perspectiveFrom(const glm::vec3& eye, const glm::vec3& at) {
+ return glm::perspective(glm::radians(60.0f), 1.5f, 1.0f, 10000.0f) * glm::lookAt(eye, at, glm::vec3(0.0f, 1.0f, 0.0f));
+}
+
+/** Where the card's own +Z (its face) and +Y end up. */
+static glm::vec3 face(const glm::quat& q) { return q * glm::vec3(0.0f, 0.0f, 1.0f); }
+static glm::vec3 top(const glm::quat& q) { return q * glm::vec3(0.0f, 1.0f, 0.0f); }
+
+static void testViewPlane() {
+ // A camera up and to the side, looking down at the origin.
+ const glm::vec3 eye(300.0f, 400.0f, 500.0f);
+ const glm::mat4 vp = perspectiveFrom(eye, glm::vec3(0.0f));
+ const glm::quat q = billboard::facing(0, vp, glm::vec4(eye, 1.0f), glm::vec3(0.0f));
+ const glm::vec3 back = glm::normalize(eye); // the camera looks at the origin, so its back is toward the eye
+ CHECK(near(face(q), back), "view plane: the face points back along the view, toward the camera");
+ const glm::mat4 view = glm::lookAt(eye, glm::vec3(0.0f), glm::vec3(0.0f, 1.0f, 0.0f));
+ const glm::vec3 cameraUp(view[0][1], view[1][1], view[2][1]);
+ CHECK(near(top(q), cameraUp), "view plane: the card's top is the screen's top");
+ // Two cards in the same view are parallel, wherever they stand.
+ const glm::quat other = billboard::facing(0, vp, glm::vec4(eye, 1.0f), glm::vec3(-200.0f, 0.0f, 80.0f));
+ CHECK(near(face(other), face(q)), "view plane: every card in a view faces the same way");
+}
+
+static void testUpright() {
+ const glm::vec3 eye(300.0f, 400.0f, 500.0f);
+ const glm::mat4 vp = perspectiveFrom(eye, glm::vec3(0.0f));
+ const glm::vec3 at(100.0f, 0.0f, 0.0f);
+ const glm::quat q = billboard::facing(1, vp, glm::vec4(eye, 1.0f), at);
+ CHECK(near(top(q), glm::vec3(0.0f, 1.0f, 0.0f)), "upright: the card stays standing");
+ const glm::vec3 flat = glm::normalize(glm::vec3(eye.x - at.x, 0.0f, eye.z - at.z));
+ CHECK(near(face(q), flat), "upright: it turns about up to face the eye across the ground");
+ // Straight overhead the direction across the ground is gone; the card takes the view's and does not spin.
+ const glm::vec3 over(100.0f, 800.0f, 0.001f);
+ const glm::mat4 down = glm::perspective(glm::radians(60.0f), 1.5f, 1.0f, 10000.0f)
+ * glm::lookAt(over, at, glm::vec3(0.0f, 0.0f, -1.0f));
+ const glm::quat above = billboard::facing(1, down, glm::vec4(over, 1.0f), at + glm::vec3(0.0f, 0.0f, 0.001f));
+ CHECK(near(top(above), glm::vec3(0.0f, 1.0f, 0.0f)) && std::isfinite(above.w), "upright: overhead, still standing and finite");
+}
+
+static void testOrthographic() {
+ // An orthographic view has no eye position: the direction toward the viewer stands in for it.
+ const glm::mat4 vp = glm::ortho(-400.0f, 400.0f, -300.0f, 300.0f, 1.0f, 10000.0f)
+ * glm::lookAt(glm::vec3(0.0f, 0.0f, 1000.0f), glm::vec3(0.0f), glm::vec3(0.0f, 1.0f, 0.0f));
+ const glm::quat q = billboard::facing(1, vp, glm::vec4(0.0f, 0.0f, 1.0f, 0.0f), glm::vec3(250.0f, 0.0f, 0.0f));
+ CHECK(near(face(q), glm::vec3(0.0f, 0.0f, 1.0f)), "orthographic upright: faces the viewer direction, not a point");
+ const glm::quat p = billboard::facing(0, vp, glm::vec4(0.0f, 0.0f, 1.0f, 0.0f), glm::vec3(0.0f));
+ CHECK(near(face(p), glm::vec3(0.0f, 0.0f, 1.0f)) && near(top(p), glm::vec3(0.0f, 1.0f, 0.0f)),
+ "orthographic view plane: a head-on view leaves a quad as it is");
+}
+
+int main() {
+ testViewPlane();
+ testUpright();
+ testOrthographic();
+ std::printf(g_failures ? "\n%d FAILED\n" : "\nall passed\n", g_failures);
+ return g_failures ? 1 : 0;
+}
diff --git a/tools/check-corpus-authoring.mjs b/tools/check-corpus-authoring.mjs
index d7c572f1f..c5f117582 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'],
+ 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'],
// — owed: a creator-facing component nothing in the shipped corpus authors.