Skip to content

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

feat(decal): a projector you can place, and a bake that prints it

esenginee4177be77cf9
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 the
time. 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 sticker
hovering in front of a wall — it is the wall, cut to the projector's box and
drawn again with the decal's own material, won on depth by that material's
diff --git a/desktop b/desktop
index 5eebbe685..31b8113f8 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 5eebbe6853f2edabc23742978df8899249fdd21d
+Subproject commit 31b8113f8e9c6eceeb3875af6cde6affa69183ae
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 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.ts
index 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.json
index 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.esmaterial
new file mode 100644
index 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.meta
new file mode 100644
index 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.esshader
new file mode 100644
index 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 end
diff --git a/examples/physics-3d/assets/materials/decal-target.esshader.meta b/examples/physics-3d/assets/materials/decal-target.esshader.meta
new file mode 100644
index 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.esscene
index 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.esmesh
new file mode 100644
index 000000000..b92637fc3
Binary files /dev/null and b/examples/physics-3d/assets/scenes/main_decal_51.esmesh differ
diff --git a/examples/physics-3d/assets/scenes/main_decal_51.esmesh.meta b/examples/physics-3d/assets/scenes/main_decal_51.esmesh.meta
new file mode 100644
index 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.mjs
index 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.ts
new file mode 100644
index 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.md
index 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 = 8
facing: 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>): void
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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 = 8
facing: 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>): void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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 = 8
facing: 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>): void
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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 = 8
facing: 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>): void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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 = 8
facing: 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>): void
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.mjs
index 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." },