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(scene): sceneOutOfBandFields names what a component carries beside its fields

yhh6285a7315ccf
diff --git a/desktop b/desktop
index 1df21b57c..f72c18dd8 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 1df21b57c99957f2d584b5603998c87e9571be7f
+Subproject commit f72c18dd8a278f7cfe1b7f50698f244333ee71a4
diff --git a/docs/astro/src/content/docs/graphics/drawing.mdx b/docs/astro/src/content/docs/graphics/drawing.mdx
index 15526db4a..cce2c05ed 100644
--- a/docs/astro/src/content/docs/graphics/drawing.mdx
+++ b/docs/astro/src/content/docs/graphics/drawing.mdx
@@ -154,6 +154,12 @@ 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.
+Inline `geometry` is data code supplies while the game runs: it is not an inspector
+field, `set_field` does not reach it, and the edit viewport does not show geometry a
+script builds. For geometry an entity should keep, use the `mesh` field instead — a
+built-in shape (`builtin:cube`, `builtin:sphere`, `builtin:plane`, …), an `.esmesh`
+asset, or at run time a handle from `assets.createMesh(data)`.
+
### 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
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx
index 256e861fd..d486c3e3b 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,8 @@ cmds.spawn()
`MeshRenderers` 资源——`setGeometry(entity, geometry)` 重新上传(索引在引擎侧校验),
另有 `getGeometry` / `clearGeometry`。只改 `geometry` 字段本身不会被变更检测。
+内联 `geometry` 是游戏运行时由代码提供的数据:它不是检查器字段,`set_field` 改不到,编辑视口也看不到脚本生成的几何体。实体需要长期保有的几何体请用 `mesh` 字段:内置形状(`builtin:cube`、`builtin:sphere`、`builtin:plane` 等)、`.esmesh` 资源,或运行时用 `assets.createMesh(data)` 得到的句柄。
+
### 朝向相机的卡片:`Billboard`
MeshRenderer 旁边的 `Billboard` 会把网格转向每个画它的视图:招牌、3D 世界里角色的精灵、画在卡片上的远处的树、镜头闪光。
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 6478c8b18..acaae864d 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -236,6 +236,7 @@ export {
RENAMED_COMPONENT_TYPES,
SCENE_FORMAT_VERSION,
registerSceneComponentCodec,
+ sceneOutOfBandFields,
getComponentAssetFields,
getComponentAssetFieldDescriptors,
getComponentSkeletalFieldDescriptor,
diff --git a/sdk/src/render/meshRenderer.ts b/sdk/src/render/meshRenderer.ts
index 9b5c81067..25d58c2c9 100644
--- a/sdk/src/render/meshRenderer.ts
+++ b/sdk/src/render/meshRenderer.ts
@@ -12,7 +12,7 @@ import type { EngineApi } from '../ecs/bridge/engineApi';
import { engineApi } from '../ecs/bridge/engineApi';
import type { MeshRendererGeometry } from '../ecs/component';
import { defineResource } from '../ecs/resource';
-import { registerSceneComponentCodec } from '../scene/scene';
+import { declareSceneOutOfBandFields, registerSceneComponentCodec } from '../scene/scene';
import { withScratch } from '../wasm/wasmScratch';
import { installBlobShadows } from './blobShadow';
@@ -24,6 +24,10 @@ function packRgba(colors: number[], v: number): number {
| (clamp(colors[v * 4 + 3] ?? 1) << 24)) >>> 0;
}
+/** The inline vertices are the codec's, not a field's — known before the plugin builds. */
+const OUT_OF_BAND = ['geometry'] as const;
+declareSceneOutOfBandFields('MeshRenderer', OUT_OF_BAND);
+
export class MeshRendererAPI {
/** Entity → authored geometry, so scene save round-trips what was uploaded. */
private readonly authored_ = new Map<number, MeshRendererGeometry>();
@@ -121,7 +125,7 @@ export class MeshRendererPlugin implements Plugin {
// field — carry it out-of-band and upload it through the validated entry
// point on load (the same pattern as particle gradients / tilemap chunks).
registerSceneComponentCodec('MeshRenderer', {
- outOfBandFields: ['geometry'],
+ outOfBandFields: OUT_OF_BAND,
importData: (entity, outOfBand) => {
const g = outOfBand.geometry as MeshRendererGeometry | undefined;
if (g && g.positions?.length && g.indices?.length) {
diff --git a/sdk/src/scene/scene.ts b/sdk/src/scene/scene.ts
index dd5ca57f7..9c1ab26eb 100644
--- a/sdk/src/scene/scene.ts
+++ b/sdk/src/scene/scene.ts
@@ -279,6 +279,26 @@ export function registerSceneComponentCodec(type: string, codec: SceneComponentC
sceneComponentCodecs.set(type, codec);
}
+/**
+ * What a component carries beside its fields — a MeshRenderer's inline `geometry`:
+ * saved with the scene by its codec, but no field, so no inspector or set_field
+ * reaches it. Empty for a component without such data.
+ */
+export function sceneOutOfBandFields(type: string): readonly string[] {
+ return sceneComponentCodecs.get(type)?.outOfBandFields ?? declaredOutOfBand.get(type) ?? [];
+}
+
+const declaredOutOfBand = new Map<string, readonly string[]>();
+
+/**
+ * @internal Say which data a component carries beside its fields before its codec
+ * is installed (codecs install with their plugin, which a tool asking about a
+ * component may never build).
+ */
+export function declareSceneOutOfBandFields(type: string, fields: readonly string[]): void {
+ declaredOutOfBand.set(type, fields);
+}
+
// =============================================================================
// Prefab instance entries (runtime play == ship)
// =============================================================================