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.

docs: rewrite the Materials guide to the complete-reference template

yhh28a97b768eb8
diff --git a/docs/astro/src/content/docs/guides/material.mdx b/docs/astro/src/content/docs/guides/material.mdx
index 91d4a0189..b1c250747 100644
--- a/docs/astro/src/content/docs/guides/material.mdx
+++ b/docs/astro/src/content/docs/guides/material.mdx
@@ -1,18 +1,23 @@
---
title: Materials & Shaders
-description: Custom GLSL shaders with reflected #pragma param uniforms.
+description: The complete guide to custom materials — authoring GLSL with reflected #pragma param uniforms, the Material API, and applying materials to renderers.
---
import { Aside } from '@astrojs/starlight/components';
A material is a **shader plus parameters**. Renderers that support materials —
-`Sprite`, `SpineAnimation`, `ParticleEmitter`, tilemap layers — have a `material`
-handle field; set it to draw with your own shader.
+`Sprite`, `SpineAnimation`, `ParticleEmitter`, and tilemap layers — expose a
+`material` handle field; set it to draw with your own shader instead of the default.
-## Declaring parameters with `#pragma param`
+## How it works
+
+You author an `.esshader` that declares its tunable parameters with `#pragma param`.
+The engine **reflects** those into a std140 uniform block, so the CPU can set them by
+name and they reach the GPU safely. A `Material` binds a compiled shader to a set of
+parameter values; assigning its handle to a renderer's `material` field draws that
+renderer with it.
-An `.esshader` declares the parameters the CPU is allowed to set. The engine
-reflects them into a std140 uniform block, so they reach the GPU by name:
+## Declaring parameters with `#pragma param`
```glsl
#pragma param u_tint color default(1, 1, 1, 1)
@@ -22,18 +27,23 @@ reflects them into a std140 uniform block, so they reach the GPU by name:
// … your GLSL fragment code, reading u_tint / u_intensity / u_mask …
```
-Parameter types are `float`, `color` (rgba), and `texture`. A `#pragma switch`
-selects a static shader permutation baked into the material at compile time.
+| Param type | GLSL | Value shape | Notes |
+|---|---|---|---|
+| `float` | `float` | `number` | Scalar knob. |
+| `color` | `vec4` | `[r, g, b, a]` | RGBA, 0..1. |
+| `texture` | `sampler2D` | texture handle | `default(white)` etc. for a fallback. |
-## Create and apply in code
+A `#pragma switch` selects a static shader permutation baked into the material at
+compile time (via the `features` argument to `compileShader`).
-Compile the shader (which reflects its params) and make a material, then point a
-renderer at it by setting its `material` handle:
+## Create & apply in code
+
+Compile the shader **once** (not per frame), make a material, then point a renderer
+at it:
```typescript
import { Material } from 'esengine';
-// Compile once (not per frame).
const shader = Material.compileShader(tintShaderSource);
const tintMat = Material.create({
shader,
@@ -51,16 +61,43 @@ const applyMaterial = defineSystem([Query(Mut(Sprite))], (q) => {
});
```
-## Update a parameter at runtime
+## Update parameters at runtime
```typescript
Material.setUniform(tintMat, 'u_intensity', 2.5);
+const v = Material.getUniform(tintMat, 'u_intensity');
```
+## `Material` API reference
+
+| Method | Description |
+|---|---|
+| `compileShader(esshaderSource, features?)` | Compile an `.esshader` (reflects `#pragma param`); returns a shader handle. |
+| `createShader(vertexSrc, fragmentSrc)` | Compile a raw GLSL vertex/fragment pair (no reflected params). |
+| `create({ shader, uniforms })` | Build a material binding a shader to parameter values. |
+| `setUniform(material, name, value)` | Set a reflected parameter at runtime. |
+| `getUniform(material, name)` | Read a parameter's current value. |
+
+## Best practices
+
+- **Compile shaders once** at startup and reuse the handle — never in a per-frame
+ system.
+- **Share one material** across renderers that use the same shader + params so they
+ batch into fewer draw calls.
+- **Prefer the editor's material graph** for authoring; it generates the
+ `#pragma param` shader and lets you assign the material visually. The code API here
+ is for procedural materials.
+- **Drive animated effects via `setUniform`** on a shared material rather than
+ recreating materials.
+
<Aside type="note">
For raw shaders without reflected params, use `Material.createShader(vertexSrc,
- fragmentSrc)` instead of `compileShader`. Most of the time you'll author
- materials in the editor's **material graph** — it generates the `#pragma param`
- shader for you and you assign the material to a renderer there; the code API
- above is for procedural materials.
+ fragmentSrc)` instead of `compileShader`. `ShapeRenderer` has no `material` field —
+ only `Sprite`, `SpineAnimation`, `ParticleEmitter`, and tilemap layers do.
</Aside>
+
+## See also
+
+- [Post-processing](/docs/guides/postprocess/) — full-screen effects (a separate pipeline).
+- [Assets](/docs/guides/assets/) — `loadMaterial` and shader handles.
+- [Particles](/docs/guides/particle/) — assign a custom `material` to an emitter.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/material.mdx b/docs/astro/src/content/docs/zh-cn/guides/material.mdx
index fff33ccd6..7a749d5e1 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/material.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/material.mdx
@@ -1,38 +1,44 @@
---
title: 材质与着色器
-description: 带 #pragma param 反射 uniform 的自定义 GLSL 着色器。
+description: 自定义材质完整指南——用 #pragma param 反射 uniform 编写 GLSL、Material API,以及把材质应用到渲染器。
---
import { Aside } from '@astrojs/starlight/components';
-材质就是**着色器 + 参数**。支持材质的渲染组件——`Sprite`、`SpineAnimation`、
-`ParticleEmitter`、瓦片图层——都有一个 `material` 句柄字段;把它设好就能用你自己的
-着色器绘制。
+材质是**着色器加参数**。支持材质的渲染器——`Sprite`、`SpineAnimation`、`ParticleEmitter`
+和瓦片图层——都暴露一个 `material` 句柄字段;设置它就用你自己的着色器绘制,而非默认。
-## 用 `#pragma param` 声明参数
+## 工作原理
+
+你编写一个 `.esshader`,用 `#pragma param` 声明它可调的参数。引擎把它们**反射**进一个
+std140 uniform 块,于是 CPU 能按名字设置、并安全地送到 GPU。一个 `Material` 把编译好的
+着色器绑定到一组参数值;把它的句柄赋给渲染器的 `material` 字段,就用它来绘制该渲染器。
-`.esshader` 声明 CPU 可设置的参数。引擎把它们反射进一个 std140 uniform 块,于是它们能
-按名字到达 GPU:
+## 用 `#pragma param` 声明参数
```glsl
#pragma param u_tint color default(1, 1, 1, 1)
#pragma param u_intensity float default(1.0)
#pragma param u_mask texture default(white)
-// … 你的 GLSL 片段代码,读取 u_tint / u_intensity / u_mask …
+// … your GLSL fragment code, reading u_tint / u_intensity / u_mask …
```
-参数类型有 `float`、`color`(rgba)和 `texture`。`#pragma switch` 选择在编译期烘焙进
-材质的静态着色器排列(permutation)。
+| 参数类型 | GLSL | 值的形状 | 备注 |
+|---|---|---|---|
+| `float` | `float` | `number` | 标量旋钮。 |
+| `color` | `vec4` | `[r, g, b, a]` | RGBA,0..1。 |
+| `texture` | `sampler2D` | 纹理句柄 | `default(white)` 等作为回退。 |
-## 在代码里创建并应用
+`#pragma switch` 选择编译期烘焙进材质的静态着色器排列(通过 `compileShader` 的 `features` 参数)。
-编译着色器(它会反射出参数)并创建材质,然后把某个渲染组件的 `material` 句柄指向它:
+## 用代码创建与应用
+
+**只编译一次**着色器(不要每帧),做一个材质,然后把渲染器指向它:
```typescript
import { Material } from 'esengine';
-// 只编译一次(不要每帧)。
const shader = Material.compileShader(tintShaderSource);
const tintMat = Material.create({
shader,
@@ -45,7 +51,7 @@ import { defineSystem, Query, Mut, Sprite } from 'esengine';
const applyMaterial = defineSystem([Query(Mut(Sprite))], (q) => {
for (const [entity, sprite] of q) {
- sprite.material = tintMat; // 材质句柄
+ sprite.material = tintMat; // the material handle
}
});
```
@@ -54,11 +60,35 @@ const applyMaterial = defineSystem([Query(Mut(Sprite))], (q) => {
```typescript
Material.setUniform(tintMat, 'u_intensity', 2.5);
+const v = Material.getUniform(tintMat, 'u_intensity');
```
+## `Material` API 参考
+
+| 方法 | 说明 |
+|---|---|
+| `compileShader(esshaderSource, features?)` | 编译一个 `.esshader`(反射 `#pragma param`);返回着色器句柄。 |
+| `createShader(vertexSrc, fragmentSrc)` | 编译一对原始 GLSL 顶点/片元(无反射参数)。 |
+| `create({ shader, uniforms })` | 构建一个把着色器绑定到参数值的材质。 |
+| `setUniform(material, name, value)` | 运行时设置一个反射参数。 |
+| `getUniform(material, name)` | 读取一个参数的当前值。 |
+
+## 最佳实践
+
+- 启动时**只编译一次**着色器并复用句柄——绝不在每帧系统里编译。
+- 让使用相同着色器 + 参数的渲染器**共享一个材质**,以合批成更少的 draw call。
+- **优先用编辑器的材质图(material graph)** 编写;它会生成 `#pragma param` 着色器并让你
+ 可视化地赋材质。这里的代码 API 用于程序化材质。
+- **动画效果用 `setUniform`** 驱动共享材质,而不是重建材质。
+
<Aside type="note">
- 若是没有反射参数的原始着色器,用 `Material.createShader(vertexSrc, fragmentSrc)`
- 而不是 `compileShader`。大多数情况下你会在编辑器的**材质图(material graph)**里
- 编排材质——它会替你生成 `#pragma param` 着色器,并在那里把材质指派给渲染组件;上面
- 的代码 API 用于程序化材质。
+ 没有反射参数的原始着色器用 `Material.createShader(vertexSrc, fragmentSrc)` 而非
+ `compileShader`。`ShapeRenderer` 没有 `material` 字段——只有 `Sprite`、`SpineAnimation`、
+ `ParticleEmitter` 和瓦片图层有。
</Aside>
+
+## 参见
+
+- [后处理](/docs/zh-cn/guides/postprocess/) —— 全屏效果(独立的管线)。
+- [资源](/docs/zh-cn/guides/assets/) —— `loadMaterial` 与着色器句柄。
+- [粒子](/docs/zh-cn/guides/particle/) —— 给发射器指定自定义 `material`。