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(scripting): the first behaviour example taught a write that does nothing

yhhdca3e9fa6f49
diff --git a/docs/astro/src/content/docs/scripting/overview.mdx b/docs/astro/src/content/docs/scripting/overview.mdx
index 7aeaf916e..1fa8eaa17 100644
--- a/docs/astro/src/content/docs/scripting/overview.mdx
+++ b/docs/astro/src/content/docs/scripting/overview.mdx
@@ -28,11 +28,22 @@ import { defineBehavior, Transform } from 'esengine';
export const Patrol = defineBehavior('Patrol', {
state: { speed: 60 }, // per-entity data, editable in the Details panel
update(ctx, dt) {
- ctx.get(Transform).position.x += ctx.self.speed * dt;
+ const t = ctx.get(Transform);
+ t.position.x += ctx.self.speed * dt;
+ ctx.set(Transform, t);
},
});
```
+<Aside type="caution">
+ **Engine components come back as a copy.** `ctx.get` hands you the stored object
+ for a *script* component — your own `defineComponent`, and `ctx.self` — so mutating
+ it sticks. `Transform`, `Sprite`, `RigidBody` and every other C++-backed component
+ are decoded out of the wasm heap on each read, so `ctx.get(Transform).position.x += …`
+ changes a value nobody keeps, silently. Read it, change it, hand it back with
+ `ctx.set`.
+</Aside>
+
That single call registers the update system. To put the behavior on an entity, insert
its component — optionally overriding the starting `state`:
@@ -227,7 +238,11 @@ export const PlayerController = defineBehavior('PlayerController', {
update(ctx, dt) {
const move = (ctx.input.isKeyDown('KeyD') ? 1 : 0) - (ctx.input.isKeyDown('KeyA') ? 1 : 0);
if (move !== 0) ctx.self.facing = move; // mutating self persists
- ctx.get(Transform).position.x += move * ctx.self.speed * dt;
+ if (move !== 0) {
+ const t = ctx.get(Transform); // a copy — Transform is C++-backed
+ t.position.x += move * ctx.self.speed * dt;
+ ctx.set(Transform, t); // …so hand it back
+ }
},
});
```
diff --git a/docs/astro/src/content/docs/zh-cn/scripting/overview.mdx b/docs/astro/src/content/docs/zh-cn/scripting/overview.mdx
index f168dadc1..b96d6df98 100644
--- a/docs/astro/src/content/docs/zh-cn/scripting/overview.mdx
+++ b/docs/astro/src/content/docs/zh-cn/scripting/overview.mdx
@@ -25,11 +25,21 @@ import { defineBehavior, Transform } from 'esengine';
export const Patrol = defineBehavior('Patrol', {
state: { speed: 60 }, // 每实体数据,可在 Details 面板里编辑
update(ctx, dt) {
- ctx.get(Transform).position.x += ctx.self.speed * dt;
+ const t = ctx.get(Transform);
+ t.position.x += ctx.self.speed * dt;
+ ctx.set(Transform, t);
},
});
```
+<Aside type="caution">
+ **引擎组件拿到的是拷贝。** 对*脚本*组件——你自己 `defineComponent` 出来的,以及 `ctx.self`
+ ——`ctx.get` 给的就是存储对象本身,改了就生效。而 `Transform`、`Sprite`、`RigidBody` 这些
+ C++ 支撑的组件,每次读都是从 wasm 堆里解出来的一份拷贝,所以
+ `ctx.get(Transform).position.x += …` 改的是一个没人保存的值,而且**静默无效**。
+ 读出来、改完、用 `ctx.set` 交回去。
+</Aside>
+
这一次调用就注册了更新系统。要把行为放到实体上,insert 它的组件——还能顺便覆盖起始 `state`:
```typescript
@@ -202,7 +212,11 @@ export const PlayerController = defineBehavior('PlayerController', {
update(ctx, dt) {
const move = (ctx.input.isKeyDown('KeyD') ? 1 : 0) - (ctx.input.isKeyDown('KeyA') ? 1 : 0);
if (move !== 0) ctx.self.facing = move; // 改 self 会持久化
- ctx.get(Transform).position.x += move * ctx.self.speed * dt;
+ if (move !== 0) {
+ const t = ctx.get(Transform); // 拷贝——Transform 由 C++ 支撑
+ t.position.x += move * ctx.self.speed * dt;
+ ctx.set(Transform, t); // ……所以要交回去
+ }
},
});
```
diff --git a/sdk/src/behavior.ts b/sdk/src/behavior.ts
index 17439113f..05c94cf92 100644
--- a/sdk/src/behavior.ts
+++ b/sdk/src/behavior.ts
@@ -44,9 +44,16 @@ export interface BehaviorContext<S extends object> {
readonly commands: CommandsInstance;
/** The world, for cross-entity access. */
readonly world: World;
- /** Read another component on THIS entity. */
+ /**
+ * Read another component on THIS entity.
+ *
+ * For a script component this IS the stored object, so mutating it sticks.
+ * For an ENGINE component (Transform, Sprite, RigidBody — anything C++-backed)
+ * it is a copy decoded out of the wasm heap: mutating it changes nothing.
+ * Read it, change it, and hand it back through {@link set}.
+ */
get<C extends AnyComponentDef>(component: C): ComponentData<C>;
- /** Write another component on THIS entity. */
+ /** Write another component on THIS entity — how an engine component is changed. */
set<C extends AnyComponentDef>(component: C, data: ComponentData<C>): void;
/** Whether THIS entity has `component`. */
has(component: AnyComponentDef): boolean;
@@ -88,7 +95,11 @@ interface MutableContext<S extends object> {
* @example
* export const Patrol = defineBehavior('Patrol', {
* state: { speed: 60 },
- * update(ctx, dt) { ctx.get(Transform).position.x += ctx.self.speed * dt; },
+ * update(ctx, dt) {
+ * const t = ctx.get(Transform); // a copy — Transform is C++-backed
+ * t.position.x += ctx.self.speed * dt;
+ * ctx.set(Transform, t); // …so hand it back
+ * },
* });
*/
export function defineBehavior<S extends object>(name: string, def: BehaviorDef<S>): ComponentDef<S> {