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
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.mdxindex 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 panelupdate(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, insertits 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.mdxindex 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.tsindex 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> {