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): 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.ymlindex 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_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_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_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 6522a4a66..1b8e26f99 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 6522a4a66da1ae75b6ced024d5cb265513bfb7ee+Subproject commit 1b8e26f99f516bbfa890a3edd2c1d89070b741d9diff --git a/docs/astro/src/content/docs/graphics/drawing.mdx b/docs/astro/src/content/docs/graphics/drawing.mdxindex 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` APIWhere `MeshRenderer` is the *component* path, `Geometry` is the *immediate* one: itdiff --git a/docs/astro/src/content/docs/performance/static-batching.mdx b/docs/astro/src/content/docs/performance/static-batching.mdxindex 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.mdxindex 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.mdxindex 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.tsindex 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.jsonindex 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.mdindex 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: numberp2y: 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 @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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: numberp2y: 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 @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: numberp2y: 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 @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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: numberp2y: 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 @experimentaldiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 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) => voidaddBitmapText: (entity: Entity, component: BitmapText) => voidaddBoxCollider2D: (entity: Entity, component: BoxCollider2D) => voidaddBoxCollider3D: (entity: Entity, component: BoxCollider3D) => void@@ -73,6 +74,7 @@ delete: () => voiddestroy: (entity: Entity) => voiddestructionPending: ((entity: Entity) => boolean) | undefinedentityCount: () => number+getBillboard: (entity: Entity) => BillboardgetBitmapText: (entity: Entity) => BitmapTextgetBoxCollider2D: (entity: Entity) => BoxCollider2DgetBoxCollider3D: (entity: Entity) => BoxCollider3D@@ -127,6 +129,7 @@ getUINode: (entity: Entity) => UINodegetUIScroll: (entity: Entity) => UIScrollgetUIVisual: (entity: Entity) => UIVisualgetVelocity: (entity: Entity) => Velocity+hasBillboard: (entity: Entity) => booleanhasBitmapText: (entity: Entity) => booleanhasBoxCollider2D: (entity: Entity) => booleanhasBoxCollider3D: (entity: Entity) => boolean@@ -185,6 +188,7 @@ isEntityActive: ((entity: Entity) => boolean) | undefinedisEntityEnabled: ((entity: Entity) => boolean) | undefinedlayoutEpoch: (() => number) | undefinedreleaseDestruction: ((entity: Entity) => void) | undefined+removeBillboard: (entity: Entity) => voidremoveBitmapText: (entity: Entity) => voidremoveBoxCollider2D: (entity: Entity) => voidremoveBoxCollider3D: (entity: Entity) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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: numberp2y: 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 @experimentaldiff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.tsindex 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.tsindex 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.tsindex 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.tsindex 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>('SpringBmetaDefaults<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 Componentdiff --git a/sdk/src/render/staticBatch.ts b/sdk/src/render/staticBatch.tsindex 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.tsindex 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.tsindex 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.tsindex 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.snapindex 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.cppindex 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) {} // namespaceComponentAt engineComponentAt(ecs::Registry& registry, const char* name) {+ if (std::strcmp(name, "Billboard") == 0) {+ return [®istry](std::uint32_t raw) -> void* {+ return registry.tryGet<esengine::ecs::Billboard>(Entity::fromRaw(raw));+ };+ }if (std::strcmp(name, "BitmapText") == 0) {return [®istry](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 [®istry]() -> Candidates {+ return denseAsIds(registry.entitiesWith<esengine::ecs::Billboard>());+ };+ }if (std::strcmp(name, "BitmapText") == 0) {return [®istry]() -> 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.cppindex 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::stbool 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::stri32 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::stribool 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::stbool 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.cppindex 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.hppnew file mode 100644index 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::ecsdiff --git a/src/esengine/renderer/draw/BillboardFacing.hpp b/src/esengine/renderer/draw/BillboardFacing.hppnew file mode 100644index 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::billboarddiff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cppindex 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.txtindex 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 PRIVATEdiff --git a/tests/aot/generated/conformance/handshake.h b/tests/aot/generated/conformance/handshake.hindex 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 0xc3d0e057d5701a2eULLdiff --git a/tests/aot/generated/conformance/systems_decl.c b/tests/aot/generated/conformance/systems_decl.cindex 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 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 0x57b9f31fef78b5a7ULL+#define ES_ABI_ENGINE_DIGEST 0x9f8d59a45b74ff12ULLES_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.cppnew file mode 100644index 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.mjsindex 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.