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(editor): a probe can ask the running game what it thinks is going on

esenginee5f682d9fd6b
diff --git a/desktop/shared/toolCatalog.mjs b/desktop/shared/toolCatalog.mjs
index b2fd289c4..5ed8c2945 100644
--- a/desktop/shared/toolCatalog.mjs
+++ b/desktop/shared/toolCatalog.mjs
@@ -514,7 +514,7 @@ export const TOOLS = [
return { total: t.length, from, events: t.slice(from) };
})` },
{ name: 'play_probe', effect: 'irreversible',
- description: "Evaluate JS inside the RUNNING play realm and return the result — the gameplay probe. One expression gives its value; several statements need an explicit `return`. window.__estellaPlay = { app, getComponent }: `getComponent(NAME)` gives the component DEFINITION, `app.world.get(entity, def)` a COPY of its data, and a write only lands through `app.world.insert(entity, def, data)` — assigning to the copy changes nothing; to drive gameplay input, dispatch KeyboardEvents on DOCUMENT (the engine listens there, not on window): document.dispatchEvent(new KeyboardEvent('keydown', {code:'ArrowRight'})). frame picks the realm in multiplayer previews (0 = host).",
+ description: "Evaluate JS inside the RUNNING play realm and return the result — the gameplay probe. One expression gives its value; several statements need an explicit `return`. window.__estellaPlay = { app, getComponent, find, componentNames, input }: **`find(NAME)` is the one to reach for** — it returns every entity carrying that component with its live data, which is how you ask what the game currently thinks is going on; `componentNames()` lists what you may ask for. `getComponent(NAME)` gives the DEFINITION and `app.world.tryGet(entity, def)` one entity's data (`get` returns a ZEROED object for an entity that lacks the component, so it cannot be used to test for one); a write only lands through `app.world.insert(entity, def, data)` — assigning to a copy changes nothing. Use play_input, not synthetic DOM events, to drive input. frame picks the realm in multiplayer previews (0 = host).",
schema: obj({ code: { type: 'string' }, frame: { type: 'number' } }, ['code']),
op: 'play_probe' },
{ name: 'play_input', effect: 'irreversible',
diff --git a/desktop/src/playHost.ts b/desktop/src/playHost.ts
index bf5b75ae3..da8f67505 100644
--- a/desktop/src/playHost.ts
+++ b/desktop/src/playHost.ts
@@ -290,6 +290,38 @@ async function buildAppAndRun(msg: InitMessage): Promise<void> {
(window as unknown as { __estellaPlay?: unknown }).__estellaPlay = {
app,
getComponent,
+ /**
+ * Every entity carrying `name`, with that component's data — "what does my
+ * game think is going on right now", which is the question a probe has.
+ *
+ * `world.get(entity, def)` needs an entity id, and there was no way to
+ * obtain one: an agent verifying the game it had just built tried
+ * `world.getComponentDef`, `world.entities`, then went digging in the wasm
+ * module's exports, and got a wrong answer from each. Worse, `get` on an
+ * entity WITHOUT the component returns a zeroed object rather than nothing,
+ * so counting up from 0 does not merely fail — it lies. `tryGet` is the one
+ * that answers honestly, and this is it, aimed at the whole world.
+ */
+ find: (name: string, limit = 200) => {
+ const world = app!.world;
+ const def = getComponent(name);
+ if (!def) {
+ return { error: `no component named "${name}" is registered in this realm` };
+ }
+ const out: Array<{ entity: number; data: unknown }> = [];
+ for (const e of world.getAllEntities()) {
+ const data = world.tryGet(e, def);
+ if (data === null || data === undefined) continue;
+ if (out.length >= limit) return { total: out.length, truncatedAt: limit, entities: out };
+ out.push({ entity: e as never as number, data });
+ }
+ return { total: out.length, entities: out };
+ },
+ /** What `find` can be asked about: the component names this realm knows. */
+ componentNames: () => app!.world.getAllEntities()
+ .flatMap((e) => app!.world.getComponentTypes(e as never))
+ .filter((t, i, a) => a.indexOf(t) === i)
+ .sort(),
input: {
move: (x: number, y: number) => injected.onPointerMove?.(x, y),
down: (x: number, y: number, button = 0) => injected.onPointerDown?.(button, x, y),