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(scene): sceneOutOfBandFields names what a component carries beside its fields
yhh6285a7315ccf
diff --git a/desktop b/desktopindex 1df21b57c..f72c18dd8 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 1df21b57c99957f2d584b5603998c87e9571be7f+Subproject commit f72c18dd8a278f7cfe1b7f50698f244333ee71a4diff --git a/docs/astro/src/content/docs/graphics/drawing.mdx b/docs/astro/src/content/docs/graphics/drawing.mdxindex 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, adiff --git a/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdxindex 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.tsindex 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.tsindex 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.tsindex 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: SceneComponentCsceneComponentCodecs.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)// =============================================================================