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(decal): a projector you can place, and a bake that prints it
esenginee4177be77cf9
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 0a598ee25..9793678dd 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -97,6 +97,22 @@ published separately; it ships inside the editor.Per-instance, not per-object-record, because the record was out of room at thetime. The entry below is the change that moved it.+- **Decals you can place.** Put a `DecalProjector` on an entity, point its box at+ something, and Bake Decal cuts what it covers into a mesh on that same entity —+ drawn with the decal's own material, won on depth by that material's bias. The+ box IS the entity's transform, so a decal is placed, turned and sized with the+ gizmo everything else uses.++ The example ships one: a target printed across a floor and up onto the step+ beside it, at two different heights — which is what says it CONFORMS. A quad+ hovering in front of a wall cannot do that, and the check reads it off the+ written mesh rather than off a picture of it.++ Looking at the picture found a bug nothing else would have: the mesh was minted,+ the ref stored, and nothing drew — the registry had not indexed the file yet, so+ a freshly baked decal appeared only after the scene was opened again. The ref is+ stored after the index knows the file now.+- **A decal's geometry, cut.** What a projector produces here is not a stickerhovering in front of a wall — it is the wall, cut to the projector's box anddrawn again with the decal's own material, won on depth by that material'sdiff --git a/desktop b/desktopindex 5eebbe685..31b8113f8 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 5eebbe6853f2edabc23742978df8899249fdd21d+Subproject commit 31b8113f8e9c6eceeb3875af6cde6affa69183aediff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 47b188cb4..c657adf9f 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -3,10 +3,10 @@"counts": {"public": 114,"beta": 101,- "experimental": 1985,+ "experimental": 1988,"deprecated": 3},- "total": 2200,+ "total": 2203,"subsystems": [{"id": "ecs",diff --git a/docs/astro/src/data/componentDocs.ts b/docs/astro/src/data/componentDocs.tsindex 5a4f10edb..a0e3309c0 100644--- a/docs/astro/src/data/componentDocs.ts+++ b/docs/astro/src/data/componentDocs.ts@@ -78,6 +78,7 @@ export const COMPONENT_DOCS: Record<string, ComponentDoc> = {MeshLightmap: { category: 'graphics', summary: 'Where a MeshRenderer\'s baked light comes from — the atlas, and the rectangle of it this object occupies.', doc: 'graphics/lighting', anchor: 'baked-light', anchorZh: '烘焙光照' },LightProbeVolume: { category: 'graphics', summary: 'A box of baked irradiance on a grid — what lights the things a lightmap cannot hold still, characters included.', doc: 'graphics/lighting', anchor: 'baked-light', anchorZh: '烘焙光照' },BakedLighting: { category: 'graphics', summary: 'How this scene is baked — atlas size, density, bounces — and a record of what the last bake read.', doc: 'graphics/lighting', anchor: 'baked-light', anchorZh: '烘焙光照' },+ DecalProjector: { category: 'graphics', summary: 'Prints this entity\'s material onto what its box covers — the surface is cut to the box and drawn again, so a decal is lit and shadowed as the surface under it.', doc: 'graphics/lighting', anchor: 'baked-light', anchorZh: '烘焙光照' },StreamedWorld: { category: 'world', summary: 'Declares the scene a streamed world and how big the cook cuts its cells.', doc: 'world/streaming', anchor: 'declaring-a-streamed-world', anchorZh: '声明一个流送世界' },WorldPersistent: { category: 'world', summary: 'Keeps an entity\'s whole subtree out of the partition — it belongs to the persistent world.', doc: 'world/streaming', anchor: 'declaring-a-streamed-world', anchorZh: '声明一个流送世界' },WorldStreamingSource: { category: 'world', summary: 'Asks for the places near it to exist; several sources are unioned.', doc: 'world/streaming', anchor: 'asking-for-places-streaming-sources', anchorZh: '请求地方存在流送源' },diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex 4ccacfc51..b9b6cbca8 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -1036,6 +1036,29 @@}]},+ {+ "name": "DecalProjector",+ "source": "ts",+ "fields": [+ {+ "key": "facing",+ "type": "number",+ "default": "0.2",+ "doc": "How squarely a surface must face the projector to take the decal.",+ "range": "-1–1, step 0.05"+ },+ {+ "key": "bakedFrom",+ "type": "string",+ "default": "empty",+ "doc": "What the last cut read.",+ "advanced": true+ }+ ],+ "animatable": [+ "facing"+ ]+ },{"name": "Disabled","source": "ts",diff --git a/examples/physics-3d/assets/materials/decal-target.esmaterial b/examples/physics-3d/assets/materials/decal-target.esmaterialnew file mode 100644index 000000000..aeac760d7--- /dev/null+++ b/examples/physics-3d/assets/materials/decal-target.esmaterial@@ -0,0 +1,12 @@+{+ "version": "1.0",+ "type": "material",+ "shader": "decal-target.esshader",+ "blendMode": 0,+ "depthTest": true,+ "depthWrite": true,+ "depthBias": -8,+ "properties": {+ "u_tint": { "r": 1, "g": 0.32, "b": 0.12, "a": 1 }+ }+}diff --git a/examples/physics-3d/assets/materials/decal-target.esmaterial.meta b/examples/physics-3d/assets/materials/decal-target.esmaterial.metanew file mode 100644index 000000000..bfff8d06f--- /dev/null+++ b/examples/physics-3d/assets/materials/decal-target.esmaterial.meta@@ -0,0 +1,6 @@+{+ "uuid": "32c1e256-5ad2-4e05-958c-b17d17e1d3b3",+ "version": "2.0",+ "type": "material",+ "importer": {}+}diff --git a/examples/physics-3d/assets/materials/decal-target.esshader b/examples/physics-3d/assets/materials/decal-target.esshadernew file mode 100644index 000000000..2e38dfc48--- /dev/null+++ b/examples/physics-3d/assets/materials/decal-target.esshader@@ -0,0 +1,225 @@+#pragma shader "DecalTarget"+#pragma version 300 es+#pragma domain Lit+#pragma param u_tint color default(1,0.32,0.12,1)++#pragma fragment+precision mediump float;++in vec4 v_color;+in vec2 v_texCoord;++out vec4 fragColor;++void main() {+ // A target: the SHAPE is what says the decal took the projector's+ // coordinates, which a solid patch of colour would not.+ vec2 d = v_texCoord - vec2(0.5);+ float r = length(d) * 2.0;+ float ring = step(0.62, r) * step(r, 0.86);+ float bar = max(step(abs(d.x), 0.035), step(abs(d.y), 0.035)) * step(r, 0.95);+ if (max(ring, bar) < 0.5) discard;+ fragColor = vec4(u_tint.rgb, 1.0);+}+#pragma end++#pragma vertex wgsl full+// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.+// Regenerate after changing the GLSL stages above.+// source-hash: 144f76db1f5f521a+// assembled-hash: d26e42f84f30beec+struct gl_PerVertex {+ @builtin(position) gl_Position: vec4<f32>,+ gl_PointSize: f32,+}++struct FrameConstants {+ u_projection: mat4x4<f32>,+ u_camera: vec4<f32>,+ u_inverseViewProjection: mat4x4<f32>,+}++struct TimeConstants {+ u_time: vec4<f32>,+ u_viewport: vec4<f32>,+}++struct MaterialConstants {+ u_tint: vec4<f32>,+}++struct InstanceConstants {+ u_instanceBase: vec4<u32>,+}++struct VertexOutput {+ @location(1) member: vec4<f32>,+ @builtin(position) gl_Position: vec4<f32>,+ @location(2) member_1: vec2<f32>,+ @location(6) member_2: vec2<f32>,+ @location(0) @interpolate(flat) member_3: f32,+}++var<private> a_position_1: vec3<f32>;+var<private> v_color: vec4<f32>;+var<private> a_color_1: vec4<f32>;+var<private> unnamed: gl_PerVertex = gl_PerVertex(vec4<f32>(0f, 0f, 0f, 1f), 1f);+@group(0) @binding(0)+var<uniform> unnamed_1: FrameConstants;+var<private> v_texCoord: vec2<f32>;+var<private> a_texCoord_1: vec2<f32>;+var<private> v_worldPos: vec2<f32>;+var<private> v_probeSlot: f32;+var<private> gl_InstanceIndex_1: i32;+@group(0) @binding(3)+var<uniform> unnamed_2: TimeConstants;+@group(0) @binding(1)+var<uniform> unnamed_3: MaterialConstants;+@group(0) @binding(8)+var<uniform> unnamed_4: InstanceConstants;+@group(1) @binding(23)+var u_instanceData_est: texture_2d<f32>;+@group(1) @binding(31)+var u_instanceData_ess: sampler;++fn main_1() {+ var world: vec4<f32>;++ let _e18 = a_position_1;+ world = vec4<f32>(_e18.x, _e18.y, _e18.z, 1f);+ let _e23 = a_color_1;+ v_color = _e23;+ let _e25 = unnamed_1.u_projection;+ let _e26 = world;+ unnamed.gl_Position = (_e25 * _e26);+ let _e29 = a_texCoord_1;+ v_texCoord = _e29;+ let _e30 = world;+ v_worldPos = _e30.xy;+ let _e32 = gl_InstanceIndex_1;+ v_probeSlot = f32(_e32);+ return;+}++@vertex+fn vs_main(@location(0) a_position: vec3<f32>, @location(1) a_color: vec4<f32>, @location(2) a_texCoord: vec2<f32>, @builtin(instance_index) gl_InstanceIndex: u32) -> VertexOutput {+ a_position_1 = a_position;+ a_color_1 = a_color;+ a_texCoord_1 = a_texCoord;+ gl_InstanceIndex_1 = i32(gl_InstanceIndex);+ main_1();+ let _e15 = v_color;+ let _e16 = unnamed.gl_Position;+ let _e17 = v_texCoord;+ let _e18 = v_worldPos;+ let _e19 = v_probeSlot;+ return VertexOutput(_e15, _e16, _e17, _e18, _e19);+}+#pragma end++#pragma fragment wgsl full+// GENERATED by tools/gen-shader-twins.mjs (glslang + naga) - do not edit.+// Regenerate after changing the GLSL stages above.+// source-hash: 144f76db1f5f521a+// assembled-hash: d26e42f84f30beec+struct MaterialConstants {+ u_tint: vec4<f32>,+}++struct FrameConstants {+ u_projection: mat4x4<f32>,+ u_camera: vec4<f32>,+ u_inverseViewProjection: mat4x4<f32>,+}++struct TimeConstants {+ u_time: vec4<f32>,+ u_viewport: vec4<f32>,+}++struct Light {+ posDir: vec4<f32>,+ color: vec4<f32>,+ spot: vec4<f32>,+ shadow: vec4<f32>,+ shadowMap: vec4<f32>,+ falloff: vec4<f32>,+}++struct LightConstants {+ u_ambient: vec4<f32>,+ u_lights: array<Light, 16>,+ u_mask2DRect: vec4<f32>,+ u_shadowMatrix: array<mat4x4<f32>, 16>,+ u_shadowTile: array<vec4<f32>, 16>,+ u_shadowParams: vec4<f32>,+ u_envIrradiance: array<vec4<f32>, 9>,+ u_envParams: vec4<f32>,+ u_envTint: vec4<f32>,+}++struct ProbeConstants {+ u_probeIrradiance: array<vec4<f32>, 900>,+}++var<private> v_texCoord_1: vec2<f32>;+var<private> fragColor: vec4<f32>;+@group(0) @binding(1)+var<uniform> unnamed: MaterialConstants;+@group(0) @binding(0)+var<uniform> unnamed_1: FrameConstants;+@group(0) @binding(3)+var<uniform> unnamed_2: TimeConstants;+@group(0) @binding(2)+var<uniform> unnamed_3: LightConstants;+@group(0) @binding(7)+var<uniform> unnamed_4: ProbeConstants;+var<private> v_probeSlot_1: f32;+@group(1) @binding(7)+var u_shadow2D_est: texture_2d<f32>;+@group(1) @binding(15)+var u_shadow2D_ess: sampler;+@group(1) @binding(6)+var u_lightShape2D_est: texture_2d<f32>;+@group(1) @binding(14)+var u_lightShape2D_ess: sampler;+var<private> v_color_1: vec4<f32>;++fn main_1() {+ var d: vec2<f32>;+ var r: f32;+ var ring: f32;+ var bar: f32;++ let _e32 = v_texCoord_1;+ d = (_e32 - vec2<f32>(0.5f, 0.5f));+ let _e34 = d;+ r = (length(_e34) * 2f);+ let _e37 = r;+ let _e39 = r;+ ring = (step(0.62f, _e37) * step(_e39, 0.86f));+ let _e43 = d[0u];+ let _e47 = d[1u];+ let _e51 = r;+ bar = (max(step(abs(_e43), 0.035f), step(abs(_e47), 0.035f)) * step(_e51, 0.95f));+ let _e54 = ring;+ let _e55 = bar;+ if (max(_e54, _e55) < 0.5f) {+ discard;+ }+ let _e59 = unnamed.u_tint;+ let _e60 = _e59.xyz;+ fragColor = vec4<f32>(_e60.x, _e60.y, _e60.z, 1f);+ return;+}++@fragment+fn fs_main(@location(2) v_texCoord: vec2<f32>, @location(0) @interpolate(flat) v_probeSlot: f32, @location(1) v_color: vec4<f32>) -> @location(0) vec4<f32> {+ v_texCoord_1 = v_texCoord;+ v_probeSlot_1 = v_probeSlot;+ v_color_1 = v_color;+ main_1();+ let _e7 = fragColor;+ return _e7;+}+#pragma enddiff --git a/examples/physics-3d/assets/materials/decal-target.esshader.meta b/examples/physics-3d/assets/materials/decal-target.esshader.metanew file mode 100644index 000000000..ed37e46a9--- /dev/null+++ b/examples/physics-3d/assets/materials/decal-target.esshader.meta@@ -0,0 +1,6 @@+{+ "uuid": "6ec2ef28-3eb7-4f0f-b5f4-612c5ea27bbf",+ "version": "2.0",+ "type": "shader",+ "importer": {}+}diff --git a/examples/physics-3d/assets/scenes/main.esscene b/examples/physics-3d/assets/scenes/main.essceneindex e10a4c43e..70fbf3304 100644--- a/examples/physics-3d/assets/scenes/main.esscene+++ b/examples/physics-3d/assets/scenes/main.esscene@@ -1,6 +1,6 @@{"version": 4,- "name": "Main",+ "name": "3D Physics","entities": [{"id": 0,@@ -1558,6 +1558,61 @@}}]+ },+ {+ "id": 51,+ "name": "TargetDecal",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 270,+ "y": 30,+ "z": 0+ },+ "rotation": {+ "x": -0.7071067811865476,+ "y": 0,+ "z": 0,+ "w": 0.7071067811865476+ },+ "scale": {+ "x": 300,+ "y": 300,+ "z": 240+ }+ }+ },+ {+ "type": "DecalProjector",+ "data": {+ "facing": 0.2,+ "bakedFrom": "assets/scenes/main_decal_51.esmesh"+ }+ },+ {+ "type": "MeshRenderer",+ "data": {+ "mesh": "@uuid:1608694e-bdef-4fba-9769-23872d62f45e",+ "lit": true,+ "opaque": true,+ "cullBackfaces": true,+ "color": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 1+ },+ "layer": 0,+ "enabled": true,+ "material": "assets/materials/decal-target.esmaterial"+ }+ }+ ]}]}diff --git a/examples/physics-3d/assets/scenes/main_decal_51.esmesh b/examples/physics-3d/assets/scenes/main_decal_51.esmeshnew file mode 100644index 000000000..b92637fc3Binary files /dev/null and b/examples/physics-3d/assets/scenes/main_decal_51.esmesh differdiff --git a/examples/physics-3d/assets/scenes/main_decal_51.esmesh.meta b/examples/physics-3d/assets/scenes/main_decal_51.esmesh.metanew file mode 100644index 000000000..d0f40abcc--- /dev/null+++ b/examples/physics-3d/assets/scenes/main_decal_51.esmesh.meta@@ -0,0 +1,6 @@+{+ "uuid": "1608694e-bdef-4fba-9769-23872d62f45e",+ "version": "2.0",+ "type": "mesh",+ "importer": {}+}diff --git a/pipeline/bin/estella.mjs b/pipeline/bin/estella.mjsindex 92a1eabe9..48df393b9 100644--- a/pipeline/bin/estella.mjs+++ b/pipeline/bin/estella.mjs@@ -229,7 +229,10 @@ async function bakeScene(baker, sceneFile, check) {spacing: volume.data?.spacing ?? 100,});}- if (mesh && mesh.data?.enabled !== false) {+ // A decal is not a lightmap receiver: what it prints on was baked already,+ // and baking the overlay too would light the same surface twice.+ const isDecal = !!bakeComponent(entity, 'DecalProjector');+ if (mesh && mesh.data?.enabled !== false && !isDecal) {const ref = typeof mesh.data?.mesh === 'string' ? mesh.data.mesh : '';const builtin = ref.startsWith('builtin:') ? ref : undefined;const file = builtin ? '' : resolveRef(ref);diff --git a/pipeline/src/assets/decalBake.ts b/pipeline/src/assets/decalBake.tsnew file mode 100644index 000000000..695c30dc7--- /dev/null+++ b/pipeline/src/assets/decalBake.ts@@ -0,0 +1,86 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Decal bake: the surfaces under a projector become one mesh asset.+ *+ * The same shape as the lightmap bake beside it — the computation is the SDK's+ * and this reads the files it needs. What comes out is ordinary geometry, so+ * nothing downstream of it has to know a decal was involved.+ */+import { readFileSync } from 'node:fs';+import {+ bakeDecalMesh, receiverFromMesh, decodeMesh, encodeMesh, builtinMeshTemplate,+ type DecalReceiver, type MeshData,+} from 'esengine';++/** One placed object the projector may print on. */+export interface DecalBakeSurface {+ /** Absolute path of the `.esmesh` it draws, or '' when {@link builtinRef} names it. */+ meshFile: string;+ /** `builtin:<id>` for stock geometry, which is built from code. */+ builtinRef?: string;+ /** How it is named where a warning has to be readable. */+ label: string;+ /** Column-major 4x4 world transform. */+ transform: number[];+}++export interface DecalBakeInput {+ /** Column-major 4x4 world transform of the projector. Its unit cube is the box. */+ projector: number[];+ surfaces: DecalBakeSurface[];+ /** How squarely a surface must face the projector. @see DEFAULT_FACING_COSINE */+ facing?: number;+}++export interface DecalBakeResult {+ /** The decal's geometry in the projector's space, or null when it covers nothing. */+ mesh: MeshData | null;+ /** Encoded `.esmesh` bytes for {@link mesh}, or null with it. */+ bytes: Uint8Array | null;+ /** How many surfaces contributed, and what could not be read. */+ received: number;+ warnings: string[];+}++/** Stock geometry, built once per ref rather than per surface that names it. */+function builtinGeometry(ref: string, cache: Map<string, MeshData | null>): MeshData | null {+ if (!cache.has(ref)) cache.set(ref, builtinMeshTemplate(ref)?.build() ?? null);+ return cache.get(ref) ?? null;+}++/** Cut the surfaces to the projector's box. */+export function bakeSceneDecal(input: DecalBakeInput): DecalBakeResult {+ const warnings: string[] = [];+ const receivers: DecalReceiver[] = [];+ const builtins = new Map<string, MeshData | null>();++ for (const s of input.surfaces) {+ let mesh: MeshData | null = null;+ try {+ mesh = s.builtinRef ? builtinGeometry(s.builtinRef, builtins)+ : decodeMesh(new Uint8Array(readFileSync(s.meshFile)));+ } catch (err) {+ warnings.push(`${s.label}: ${(err as Error).message}`);+ continue;+ }+ if (!mesh) {+ warnings.push(`${s.label}: "${s.builtinRef}" is not stock geometry this build has`);+ continue;+ }+ const receiver = receiverFromMesh(mesh, s.transform);+ if (!receiver) {+ warnings.push(`${s.label}: its geometry carries no positions`);+ continue;+ }+ receivers.push(receiver);+ }++ const mesh = bakeDecalMesh(receivers, input.projector, { facing: input.facing });+ return {+ mesh,+ bytes: mesh ? encodeMesh(mesh) : null,+ received: receivers.length,+ warnings,+ };+}diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 347e74fe9..7b49b8cc2 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 114 public · 94 beta · 1824 experimental · 3 deprecated+Symbols: 114 public · 94 beta · 1827 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -2888,6 +2888,17 @@ Int4 = 8facing: number | undefined```+## DecalProjector — const @experimental+```+ComponentDef<DecalProjectorData>+```++## DecalProjectorData — interface @experimental+```+bakedFrom: string+facing: number+```+## DecalReceiver — interface @experimental```indices: Uint32Array<ArrayBufferLike>@@ -13628,6 +13639,11 @@ PrefabsPlugin(entities: ProcessedEntity[]): void```+## receiverFromMesh — function @experimental+```+(mesh: MeshData, transform: ArrayLike<number>): DecalReceiver | null+```+## recordSceneOrigins — function @experimental```(app: App, entityMap: ReadonlyMap<number, Entity>): voiddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex bc3810122..27d1ba207 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 114 public · 99 beta · 1843 experimental · 3 deprecated+Symbols: 114 public · 99 beta · 1846 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```@@ -2896,6 +2896,17 @@ Int4 = 8facing: number | undefined```+## DecalProjector — const @experimental+```+ComponentDef<DecalProjectorData>+```++## DecalProjectorData — interface @experimental+```+bakedFrom: string+facing: number+```+## DecalReceiver — interface @experimental```indices: Uint32Array<ArrayBufferLike>@@ -13871,6 +13882,11 @@ PrefabsPlugin(entities: ProcessedEntity[]): void```+## receiverFromMesh — function @experimental+```+(mesh: MeshData, transform: ArrayLike<number>): DecalReceiver | null+```+## recordSceneOrigins — function @experimental```(app: App, entityMap: ReadonlyMap<number, Entity>): voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 38e48502d..6a23120ad 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: 114 public · 96 beta · 1823 experimental · 3 deprecated+Symbols: 114 public · 96 beta · 1826 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -2883,6 +2883,17 @@ Int4 = 8facing: number | undefined```+## DecalProjector — const @experimental+```+ComponentDef<DecalProjectorData>+```++## DecalProjectorData — interface @experimental+```+bakedFrom: string+facing: number+```+## DecalReceiver — interface @experimental```indices: Uint32Array<ArrayBufferLike>@@ -13633,6 +13644,11 @@ PrefabsPlugin(entities: ProcessedEntity[]): void```+## receiverFromMesh — function @experimental+```+(mesh: MeshData, transform: ArrayLike<number>): DecalReceiver | null+```+## recordSceneOrigins — function @experimental```(app: App, entityMap: ReadonlyMap<number, Entity>): voiddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex d62eb04ed..be45934ea 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: 114 public · 94 beta · 1845 experimental · 3 deprecated+Symbols: 114 public · 94 beta · 1848 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -2883,6 +2883,17 @@ Int4 = 8facing: number | undefined```+## DecalProjector — const @experimental+```+ComponentDef<DecalProjectorData>+```++## DecalProjectorData — interface @experimental+```+bakedFrom: string+facing: number+```+## DecalReceiver — interface @experimental```indices: Uint32Array<ArrayBufferLike>@@ -13892,6 +13903,11 @@ PrefabsPlugin(entities: ProcessedEntity[]): void```+## receiverFromMesh — function @experimental+```+(mesh: MeshData, transform: ArrayLike<number>): DecalReceiver | null+```+## recordSceneOrigins — function @experimental```(app: App, entityMap: ReadonlyMap<number, Entity>): voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 13578be03..869769d4e 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: 114 public · 94 beta · 1835 experimental · 3 deprecated+Symbols: 114 public · 94 beta · 1838 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -2883,6 +2883,17 @@ Int4 = 8facing: number | undefined```+## DecalProjector — const @experimental+```+ComponentDef<DecalProjectorData>+```++## DecalProjectorData — interface @experimental+```+bakedFrom: string+facing: number+```+## DecalReceiver — interface @experimental```indices: Uint32Array<ArrayBufferLike>@@ -13656,6 +13667,11 @@ PrefabsPlugin(entities: ProcessedEntity[]): void```+## receiverFromMesh — function @experimental+```+(mesh: MeshData, transform: ArrayLike<number>): DecalReceiver | null+```+## recordSceneOrigins — function @experimental```(app: App, entityMap: ReadonlyMap<number, Entity>): voiddiff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 7c3cdd62d..85638b6a4 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -173,7 +173,9 @@ export {* @experimental Pre-1.0: the cut follows what an authoring panel needs.*/export {- bakeDecalMesh, clipToProjector, projectorUV, DEFAULT_FACING_COSINE, CLIP_EPSILON,+ DecalProjector, type DecalProjectorData,+ bakeDecalMesh, receiverFromMesh, clipToProjector, projectorUV,+ DEFAULT_FACING_COSINE, CLIP_EPSILON,type DecalReceiver, type DecalBakeOptions, type ClipVertex, type ClipTriangle,} from './decal';/**diff --git a/sdk/src/decal/bake.ts b/sdk/src/decal/bake.tsindex cb7a1d3ef..ad8a01291 100644--- a/sdk/src/decal/bake.ts+++ b/sdk/src/decal/bake.ts@@ -25,6 +25,71 @@ export interface DecalReceiver {indices: Uint32Array;}+/**+ * One mesh, placed, as surfaces a projector can print on.+ *+ * Here and not in each caller because it is the same knowledge the cut needs:+ * which channel is which, and that a transform moves a position one way and a+ * normal the other.+ */+export function receiverFromMesh(mesh: MeshData, transform: ArrayLike<number>): DecalReceiver | null {+ const pos = mesh.channels.find((c) => c.semantic === MeshChannel.Position);+ const nrm = mesh.channels.find((c) => c.semantic === MeshChannel.Normal);+ if (!pos || pos.type !== MeshChannelType.Float32) return null;+ const m = transform;+ const view = new DataView(mesh.vertices.buffer, mesh.vertices.byteOffset, mesh.vertices.byteLength);+ const positions = new Float32Array(mesh.vertexCount * 3);+ const normals = new Float32Array(mesh.vertexCount * 3);+ // The inverse-transpose a normal takes, for the usual reason: under a+ // non-uniform scale the position transform tilts a normal off its surface.+ const nm = normalMatrixOf(m);+ for (let v = 0; v < mesh.vertexCount; ++v) {+ const b = v * mesh.vertexStride + pos.offset;+ const x = view.getFloat32(b, true);+ const y = view.getFloat32(b + 4, true);+ const z = pos.components >= 3 ? view.getFloat32(b + 8, true) : 0;+ positions[v * 3] = m[0]! * x + m[4]! * y + m[8]! * z + m[12]!;+ positions[v * 3 + 1] = m[1]! * x + m[5]! * y + m[9]! * z + m[13]!;+ positions[v * 3 + 2] = m[2]! * x + m[6]! * y + m[10]! * z + m[14]!;+ // Geometry with no normal channel faces the viewer, as a flat surface+ // does everywhere else here — and then only a head-on projector prints.+ let nx = 0, ny = 0, nz = 1;+ if (nrm && nrm.type === MeshChannelType.Float32) {+ const nb = v * mesh.vertexStride + nrm.offset;+ nx = view.getFloat32(nb, true);+ ny = view.getFloat32(nb + 4, true);+ nz = view.getFloat32(nb + 8, true);+ }+ const wx = nm[0]! * nx + nm[3]! * ny + nm[6]! * nz;+ const wy = nm[1]! * nx + nm[4]! * ny + nm[7]! * nz;+ const wz = nm[2]! * nx + nm[5]! * ny + nm[8]! * nz;+ const len = Math.hypot(wx, wy, wz) || 1;+ normals[v * 3] = wx / len;+ normals[v * 3 + 1] = wy / len;+ normals[v * 3 + 2] = wz / len;+ }+ return { positions, normals, indices: mesh.indices };+}++/** The 3x3 inverse-transpose of a column-major 4x4, column-major. */+function normalMatrixOf(m: ArrayLike<number>): number[] {+ const a = [m[0]!, m[1]!, m[2]!, m[4]!, m[5]!, m[6]!, m[8]!, m[9]!, m[10]!];+ const det = a[0]! * (a[4]! * a[8]! - a[5]! * a[7]!)+ - a[3]! * (a[1]! * a[8]! - a[2]! * a[7]!)+ + a[6]! * (a[1]! * a[5]! - a[2]! * a[4]!);+ if (Math.abs(det) < 1e-12) return [1, 0, 0, 0, 1, 0, 0, 0, 1];+ const inv = 1 / det;+ // Cofactors, transposed twice — which is the cofactor matrix itself.+ return [+ (a[4]! * a[8]! - a[5]! * a[7]!) * inv, (a[5]! * a[6]! - a[3]! * a[8]!) * inv,+ (a[3]! * a[7]! - a[4]! * a[6]!) * inv,+ (a[2]! * a[7]! - a[1]! * a[8]!) * inv, (a[0]! * a[8]! - a[2]! * a[6]!) * inv,+ (a[1]! * a[6]! - a[0]! * a[7]!) * inv,+ (a[1]! * a[5]! - a[2]! * a[4]!) * inv, (a[2]! * a[3]! - a[0]! * a[5]!) * inv,+ (a[0]! * a[4]! - a[1]! * a[3]!) * inv,+ ];+}+export interface DecalBakeOptions {/** How far from facing the projector a surface may be. @see DEFAULT_FACING_COSINE */facing?: number;diff --git a/sdk/src/decal/components.ts b/sdk/src/decal/components.tsnew file mode 100644index 000000000..779b9040d--- /dev/null+++ b/sdk/src/decal/components.ts@@ -0,0 +1,49 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file components.ts+ * @brief What a project AUTHORS about a decal: how squarely it prints.+ *+ * @details One declaration and no policy, on the shape BakedLighting has. The+ * engine never reads it — the geometry is cut at creation time and drawn+ * as an ordinary mesh — so it is a TypeScript component.+ *+ * WHERE it prints is not here: that is the entity's own Transform, whose+ * unit cube is the box. A decal is placed, turned and sized with the+ * gizmo every other object uses.+ */++import { defineComponent, type ComponentDef } from '../ecs/component';+import { DEFAULT_FACING_COSINE } from './clip';++/** The fields of the `DecalProjector` component. @experimental */+export interface DecalProjectorData {+ /** How far from facing the projector a surface may be and still take the+ * decal, as a cosine. 1 accepts only what squarely faces it; 0 accepts+ * anything not turned away. */+ facing: number;+ /** What the last cut was OF. Empty until one has run; different from what+ * the scene reads as now means the decal is out of date. The baker writes it. */+ bakedFrom: string;+}++/**+ * Declares that the entity carrying it prints its material onto what it covers.+ *+ * The result is an ordinary mesh on this same entity's MeshRenderer — so+ * instancing, LOD, culling and picking need to know nothing about decals, and+ * the material's own depth bias is what wins it against the surface.+ *+ * @experimental+ */+export const DecalProjector: ComponentDef<DecalProjectorData> = defineComponent<DecalProjectorData>(+ 'DecalProjector',+ { facing: DEFAULT_FACING_COSINE, bakedFrom: '' },+ {+ fields: {+ facing: { min: -1, max: 1, step: 0.05,+ tooltip: 'How squarely a surface must face the projector to take the decal.' },+ bakedFrom: { advanced: true, tooltip: 'What the last cut read.' },+ },+ },+);diff --git a/sdk/src/decal/index.ts b/sdk/src/decal/index.tsindex a0c75464d..c0e38cc49 100644--- a/sdk/src/decal/index.ts+++ b/sdk/src/decal/index.ts@@ -8,4 +8,5 @@ export {clipToProjector, projectorUV, DEFAULT_FACING_COSINE, CLIP_EPSILON,type ClipVertex, type ClipTriangle,} from './clip';-export { bakeDecalMesh, type DecalReceiver, type DecalBakeOptions } from './bake';+export { bakeDecalMesh, receiverFromMesh, type DecalReceiver, type DecalBakeOptions } from './bake';+export { DecalProjector, type DecalProjectorData } from './components';diff --git a/sdk/tests/decal-bake.test.ts b/sdk/tests/decal-bake.test.tsindex 349789dba..f906d996e 100644--- a/sdk/tests/decal-bake.test.ts+++ b/sdk/tests/decal-bake.test.ts@@ -9,10 +9,10 @@* screenshot taken from the angle it was authored at. Pure TS.*/import { describe, it, expect } from 'vitest';-import { bakeDecalMesh, type DecalReceiver } from '../src/decal/bake';+import { bakeDecalMesh, receiverFromMesh, type DecalReceiver } from '../src/decal/bake';import { CLIP_EPSILON } from '../src/decal/clip';import { composeTRS } from '../src/math/mat4';-import { MeshChannel } from '../src/asset/meshFormat';+import { MeshChannel, MeshChannelType, type MeshData } from '../src/asset/meshFormat';/** A big flat floor at world y = 0, facing up. */function floor(extent = 500): DecalReceiver {@@ -50,6 +50,63 @@ const uvsOf = (m: { vertices: Uint8Array; vertexCount: number }): number[][] =>return out;};+/** One quad as a `.esmesh` would carry it: position + normal, interleaved. */+function quadMesh(): MeshData {+ const v = new Float32Array([+ -1, 0, -1, 0, 1, 0, 1, 0, -1, 0, 1, 0,+ 1, 0, 1, 0, 1, 0, -1, 0, 1, 0, 1, 0,+ ]);+ return {+ channels: [+ { semantic: MeshChannel.Position, components: 3, type: MeshChannelType.Float32, offset: 0 },+ { semantic: MeshChannel.Normal, components: 3, type: MeshChannelType.Float32, offset: 12 },+ ],+ vertexStride: 24,+ vertexCount: 4,+ vertices: new Uint8Array(v.buffer),+ indices: new Uint32Array([0, 1, 2, 0, 2, 3]),+ aabbMin: [-1, 0, -1],+ aabbMax: [1, 0, 1],+ };+}++describe('receiverFromMesh', () => {+ it('places a mesh by its transform', () => {+ // Ten times bigger, moved 50 along +X.+ const r = receiverFromMesh(quadMesh(),+ composeTRS({ x: 50, y: 0, z: 0 }, { x: 0, y: 0, z: 0, w: 1 },+ { x: 10, y: 10, z: 10 }))!;+ expect(r.positions[0]).toBeCloseTo(40, 4);+ expect(r.positions[2]).toBeCloseTo(-10, 4);+ expect(r.indices).toHaveLength(6);+ });++ it('turns a normal by the INVERSE-transpose, not the transform', () => {+ // Flattened on Y: the position transform would tilt an up-facing normal+ // towards nothing; the inverse-transpose keeps it up.+ const r = receiverFromMesh(quadMesh(),+ composeTRS({ x: 0, y: 0, z: 0 }, { x: 0, y: 0, z: 0, w: 1 },+ { x: 10, y: 0.1, z: 10 }))!;+ expect(r.normals[1]).toBeCloseTo(1, 4);+ expect(Math.abs(r.normals[0]!)).toBeLessThan(1e-4);+ });++ it('gives geometry with no normals the viewer-facing one', () => {+ const noNormals = quadMesh();+ noNormals.channels = [noNormals.channels[0]!];+ const r = receiverFromMesh(noNormals, composeTRS(+ { x: 0, y: 0, z: 0 }, { x: 0, y: 0, z: 0, w: 1 }, { x: 1, y: 1, z: 1 }))!;+ expect(r.normals[2]).toBeCloseTo(1, 5);+ });++ it('refuses geometry with no positions', () => {+ const nothing = quadMesh();+ nothing.channels = [];+ expect(receiverFromMesh(nothing, composeTRS(+ { x: 0, y: 0, z: 0 }, { x: 0, y: 0, z: 0, w: 1 }, { x: 1, y: 1, z: 1 }))).toBeNull();+ });+});+describe('decal bake', () => {it('cuts a patch of floor the size of the projector', () => {const mesh = bakeDecalMesh([floor()], projectorAbove([0, 100, 0], 200));diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 70a54bd63..90837fe77 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,9 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'feat(decal): a projector you can place, and a bake that prints it':+ { note: 'Decals you can place.' },+'feat(decal): the surface under a projector, cut to its box':{ note: "A decal's geometry, cut." },