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.

refactor(examples): lighting-2d rides Sprite.lit instead of a hand-rolled lit material

yhhb131b4561ecd
diff --git a/examples/README.md b/examples/README.md
index 2f96a2cc6..fda4fb8e3 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -26,7 +26,7 @@ for your own game.
| **physics-spinner** | Physics | Revolute joints and continuous rotation. |
| **particle-demo** | Effects | A configurable particle emitter with additive blending. |
| **postprocess-effects** | Effects | Full-screen post-processing: bloom, vignette, color grading. |
-| **lighting-2d** | Rendering | 2D lights and shadow casters with a normal-mapped, Lit-2D material. |
+| **lighting-2d** | Rendering | Dynamic 2D lights and soft shadow casters over `Sprite.lit` surfaces. |
| **effects-gallery** | Rendering | The built-in material effect templates — hit flash, outline, dissolve, pixelate, UV scroll — with params driven from code. |
| **tilemap-demo** | Tilemap | Two scenes: a Tiled `.tmj` import and an engine-native `.estileset` — multi-tileset, parallax, animated water, per-tile collision. |
| **ui-controls** | UI | Buttons, sliders, toggles and progress bars. |
diff --git a/examples/lighting-2d/README.md b/examples/lighting-2d/README.md
index 7b7081b10..fb602ce0f 100644
--- a/examples/lighting-2d/README.md
+++ b/examples/lighting-2d/README.md
@@ -25,12 +25,12 @@ Lighting is **multiplicative**: a lit surface renders as
unlit wall is nearly black — so a light does not just brighten the room, it
*reveals* it.
-- **The room** is a grid of tiles plus a few prop sprites, all using the
- `assets/materials/lit.esmaterial` material. Its shader declares
- `#pragma domain Lit2D`, which makes the engine inject the per-frame light
- uniforms and the `es_applyLighting2D()` helper the fragment shader calls. A
- sprite with no material stays unlit (full-bright) — that is why the light
- markers and obstacle boxes are always visible.
+- **The room** is a grid of tiles plus a few prop sprites, all with `lit: true`
+ on their `Sprite` — the one-flag way to receive 2D lights (in the editor it is
+ the **Lit** checkbox). A sprite without the flag stays unlit (full-bright) —
+ that is why the light markers and obstacle boxes are always visible. When a
+ surface needs more than the flag (a tint, a normal map), give it a `Lit2D`
+ material instead — see the [lighting guide](../../docs/astro/src/content/docs/guides/lighting.mdx).
- **The torch** (`src/systems/torch.ts`) is a `Light2D` of type `Point`. Each
frame it is moved to `UICameraInfo.worldMouseX/Y`, the cursor already
projected into world space by the active camera.
@@ -47,11 +47,8 @@ larger value for a wide penumbra, placed lights a smaller one for crisper edges.
```
assets/
- materials/
- lit.esshader # #pragma domain Lit2D — flat-normal lit surface
- lit.esmaterial # material that binds the shader (no texture → color = albedo)
scenes/
- main.esscene # camera, ambient, torch, the tile/prop room, two pillars
+ main.esscene # camera, ambient, torch, the lit tile/prop room, two pillars
src/
main.ts # registers the three systems
config.ts # shared tuning (colors, radii, caps, fade)
diff --git a/examples/lighting-2d/assets/materials/lit.esmaterial b/examples/lighting-2d/assets/materials/lit.esmaterial
deleted file mode 100644
index ac92f1385..000000000
--- a/examples/lighting-2d/assets/materials/lit.esmaterial
+++ /dev/null
@@ -1,8 +0,0 @@
-{
- "version": "1.0",
- "type": "material",
- "shader": "lit.esshader",
- "blendMode": 0,
- "depthTest": false,
- "properties": {}
-}
diff --git a/examples/lighting-2d/assets/materials/lit.esmaterial.meta b/examples/lighting-2d/assets/materials/lit.esmaterial.meta
deleted file mode 100644
index 12e848ba6..000000000
--- a/examples/lighting-2d/assets/materials/lit.esmaterial.meta
+++ /dev/null
@@ -1,6 +0,0 @@
-{
- "uuid": "7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d",
- "version": "2.0",
- "type": "material",
- "importer": {}
-}
diff --git a/examples/lighting-2d/assets/materials/lit.esshader b/examples/lighting-2d/assets/materials/lit.esshader
deleted file mode 100644
index c0b712e37..000000000
--- a/examples/lighting-2d/assets/materials/lit.esshader
+++ /dev/null
@@ -1,26 +0,0 @@
-#pragma shader "Lighting2D"
-#pragma version 300 es
-#pragma domain Lit2D
-
-#pragma fragment
-precision mediump float;
-
-in vec4 v_color;
-in vec2 v_texCoord;
-in highp vec2 v_worldPos;
-
-uniform sampler2D u_textures[8];
-
-out vec4 fragColor;
-
-// The LightConstants block + applyLighting2D() are injected by the engine for
-// `#pragma domain Lit2D`; the vertex stage is engine-injected too. These surfaces
-// carry no texture, so u_textures[0] is the default 1×1 white — the sprite's
-// `color` is the albedo the lights multiply. A flat normal faces the camera.
-void main() {
- vec4 base = texture(u_textures[0], v_texCoord) * v_color;
- vec3 N = vec3(0.0, 0.0, 1.0);
- vec3 lit = applyLighting2D(base.rgb, N, v_worldPos);
- fragColor = vec4(lit, base.a);
-}
-#pragma end
diff --git a/examples/lighting-2d/assets/materials/lit.esshader.meta b/examples/lighting-2d/assets/materials/lit.esshader.meta
deleted file mode 100644
index 009a98ddf..000000000
--- a/examples/lighting-2d/assets/materials/lit.esshader.meta
+++ /dev/null
@@ -1,6 +0,0 @@
-{
- "uuid": "2b8e6d40-1a3c-4f9b-8e7d-5c4b3a2f1e0d",
- "version": "2.0",
- "type": "shader",
- "importer": {}
-}
diff --git a/examples/lighting-2d/assets/scenes/main.esscene b/examples/lighting-2d/assets/scenes/main.esscene
index 8e84fe000..8ddef34b5 100644
--- a/examples/lighting-2d/assets/scenes/main.esscene
+++ b/examples/lighting-2d/assets/scenes/main.esscene
@@ -138,7 +138,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -174,7 +174,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -210,7 +210,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -246,7 +246,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -282,7 +282,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -318,7 +318,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -354,7 +354,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -390,7 +390,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -426,7 +426,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -462,7 +462,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -498,7 +498,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -534,7 +534,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -570,7 +570,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -606,7 +606,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -642,7 +642,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -678,7 +678,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -714,7 +714,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -750,7 +750,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -786,7 +786,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -822,7 +822,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -858,7 +858,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -894,7 +894,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -930,7 +930,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -966,7 +966,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1002,7 +1002,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1038,7 +1038,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1074,7 +1074,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1110,7 +1110,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1146,7 +1146,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1182,7 +1182,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1218,7 +1218,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1254,7 +1254,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1290,7 +1290,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1326,7 +1326,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1362,7 +1362,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1398,7 +1398,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1434,7 +1434,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1470,7 +1470,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1506,7 +1506,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1542,7 +1542,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1578,7 +1578,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1614,7 +1614,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1650,7 +1650,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1686,7 +1686,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1722,7 +1722,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1758,7 +1758,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1794,7 +1794,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1830,7 +1830,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1866,7 +1866,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1902,7 +1902,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1938,7 +1938,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -1974,7 +1974,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -2010,7 +2010,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -2046,7 +2046,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -2082,7 +2082,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -2118,7 +2118,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -2154,7 +2154,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -2190,7 +2190,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -2226,7 +2226,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -2262,7 +2262,7 @@
"a": 1
},
"layer": 0,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -2298,7 +2298,7 @@
"a": 1
},
"layer": 1,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -2334,7 +2334,7 @@
"a": 1
},
"layer": 1,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -2370,7 +2370,7 @@
"a": 1
},
"layer": 1,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
@@ -2406,7 +2406,7 @@
"a": 1
},
"layer": 1,
- "material": "@uuid:7f3a9c12-4d5e-4b6a-9c8d-1e2f3a4b5c6d"
+ "lit": true
}
}
],
diff --git a/examples/lighting-2d/src/main.ts b/examples/lighting-2d/src/main.ts
index c457cbce9..dde38ea82 100644
--- a/examples/lighting-2d/src/main.ts
+++ b/examples/lighting-2d/src/main.ts
@@ -1,6 +1,6 @@
// 2D Lighting — the engine's dynamic Light2D + ShadowCaster2D system shown
-// interactively. The scene is a near-black room whose walls and props use a
-// `Lit2D` material, so they are only visible where light reaches them.
+// interactively. The scene is a near-black room whose walls and props have
+// `lit: true` on their Sprite, so they are only visible where light reaches them.
//
// • Move the mouse — a torch (Point light) follows the cursor, revealing the
// room and casting soft shadows off the pillars.
diff --git a/examples/lighting-2d/src/systems/place.ts b/examples/lighting-2d/src/systems/place.ts
index 32356fd36..6a4ac4812 100644
--- a/examples/lighting-2d/src/systems/place.ts
+++ b/examples/lighting-2d/src/systems/place.ts
@@ -17,7 +17,7 @@ const obstacles: number[] = [];
let nextColor = 0;
// Left-click → colored Point light, right-click → box obstacle, C → clear.
-// Placed markers use the default (unlit) material so a light always reads as a
+// Placed markers stay unlit (no `lit` flag) so a light always reads as a
// bright dot and an obstacle as a solid block, regardless of the lighting.
export const placeSystem = defineSystem(
[Res(Input), Res(UICameraInfo), Commands()],