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.

fix(agent): a game is not tested until it has been played

yhh4aaf07a624f0
diff --git a/desktop/electron/agent/host.ts b/desktop/electron/agent/host.ts
index 38d35b336..e3eab2cdf 100644
--- a/desktop/electron/agent/host.ts
+++ b/desktop/electron/agent/host.ts
@@ -41,8 +41,21 @@ export interface AgentStatus {
model: string | null;
/** Why the last attempt did not happen. Cleared by one that does. */
error: string | null;
+ /**
+ * How the last turn ENDED — null before the first one.
+ *
+ * `phase` going back to 'idle' says a turn stopped, not whether it finished:
+ * a run cut off at the round cap idles exactly like one that answered the
+ * question. The drawer shows the difference (a badge, and a Resume); a driver
+ * polling status could not see it at all, and read half a game as a delivered
+ * one.
+ */
+ lastTurn: TurnEndReason | null;
}
+/** Why a turn stopped. `max_rounds` and `aborted` leave the work UNFINISHED. */
+export type TurnEndReason = 'end_turn' | 'aborted' | 'error' | 'refusal' | 'max_rounds';
+
/** One push to the window: a transcript event, or the mirror's new state. */
export type AgentMessage =
| { kind: 'event'; event: AgentEvent }
@@ -159,6 +172,7 @@ export function createAgentHost(deps: AgentHostDeps): AgentHost {
let acceptsImages = true;
let phase: AgentPhase = 'idle';
let error: string | null = null;
+ let lastTurn: TurnEndReason | null = null;
let running: AbortController | null = null;
const pending = new Map<string, (decision: ConfirmDecision) => void>();
@@ -168,6 +182,7 @@ export function createAgentHost(deps: AgentHostDeps): AgentHost {
phase,
model,
error,
+ lastTurn,
});
// Deltas out first: status and transcript share one channel BECAUSE the two
@@ -250,6 +265,9 @@ export function createAgentHost(deps: AgentHostDeps): AgentHost {
};
const emit = (event: AgentEvent): void => {
+ // Every ending passes through here (invariant 1), so this is the one place
+ // that can answer "did the last run finish?" — see AgentStatus.lastTurn.
+ if (event.type === 'turn_end') lastTurn = event.reason;
if (isDelta(event)) {
if (buffered && mergeable(buffered, event)) {
buffered = { ...buffered, delta: buffered.delta + event.delta };
diff --git a/desktop/electron/agent/prompt.ts b/desktop/electron/agent/prompt.ts
index 886d8afe9..64e94ab65 100644
--- a/desktop/electron/agent/prompt.ts
+++ b/desktop/electron/agent/prompt.ts
@@ -31,6 +31,7 @@ Working style:
- Look before you edit. get_scene_tree, get_inspector and get_document cost one round trip and are the difference between editing the right entity and editing a plausible one.
- You can see the result: capture_viewport renders what the user is looking at, and screenshot takes in the whole window including a running game. LOOK before you call a visual change done — a material, an effect, a layout, anything whose whole point is what it looks like. Reading back the data you just wrote proves you wrote it, not that it did anything; the difference between "the component says 1.0" and "the sprite is gone" is the entire job.
+- A game you have built is not tested until you have PLAYED it: toggle_play, then step to advance it (its loop is throttled to about a frame a second whenever the editor window is not the focused one, so waiting shows you a frozen picture of a healthy game), play_input to press the keys a player would, play_probe to read what the game now thinks, and screenshot to see what a player would see. Step-look-step is the loop; twenty probes without a screenshot is how a project ships game-over-on-arrival with every component reporting exactly the value it should.
- Prefer one apply_scene_ops over many small calls when building something: it is one undo step for the user and one round trip for you, and it is the ONE write the user sees BEFORE it lands — they get a line-by-line preview and can strike parts of it out. A dozen set_field calls give them no such chance, so build with a batch and save the single writes for genuinely single changes.
- Units are the editor's: 1 world unit = 1 design pixel. Y is up in the world, and UI is laid out top-down.
- Game content lives in the WORLD: a board, its pieces, a character are Sprite / ShapeRenderer entities you place with Transform.position. A Canvas and its UINodes are for HUD and menus, and their placement is the layout's OUTPUT — a Transform.position written on a UI node is overwritten at the next relayout, which looks like nothing happened. Move those with layout inputs instead (UINode.position = Absolute, then left/top), or let the flow place them.
diff --git a/desktop/src/store/AgentStore.ts b/desktop/src/store/AgentStore.ts
index 49b76f35a..091dbc37d 100644
--- a/desktop/src/store/AgentStore.ts
+++ b/desktop/src/store/AgentStore.ts
@@ -149,7 +149,7 @@ export interface AgentTurn {
const MAX_TURNS = 100;
const IDLE: AgentStatus = {
- ready: false, conversation: false, phase: 'idle', model: null, error: null,
+ ready: false, conversation: false, phase: 'idle', model: null, error: null, lastTurn: null,
};
interface AgentState {
diff --git a/desktop/tests/agent-brief-compiles.test.ts b/desktop/tests/agent-brief-compiles.test.ts
index 519376911..9f638f307 100644
--- a/desktop/tests/agent-brief-compiles.test.ts
+++ b/desktop/tests/agent-brief-compiles.test.ts
@@ -87,6 +87,16 @@ describe("the agent's brief", () => {
expect(SYSTEM_PROMPT).not.toContain('v_uv');
});
+ it('names the loop that tests a game, not just the tools in it', () => {
+ // A Breakout dogfood spent 75 of its 158 calls probing component data and none
+ // looking, and delivered a game that is GAME OVER within half a second — every
+ // value it read was exactly what it should have been.
+ for (const taught of ['toggle_play', 'step', 'play_input', 'play_probe', 'screenshot']) {
+ expect([taught, SYSTEM_PROMPT.includes(taught)]).toEqual([taught, true]);
+ }
+ expect(SYSTEM_PROMPT).toMatch(/not tested until you have PLAYED it/);
+ });
+
it('tells it to look at a visual change before calling it done', () => {
// It built the material, wired the system, set the wrong param name, read the
// component back at 1.0 and reported success — without ever taking a picture of
diff --git a/desktop/tests/agent-host.test.ts b/desktop/tests/agent-host.test.ts
index 1c13c2006..bd50e67f2 100644
--- a/desktop/tests/agent-host.test.ts
+++ b/desktop/tests/agent-host.test.ts
@@ -118,6 +118,17 @@ describe('the agent host', () => {
expect(h.status().model).toBe('fake-model');
});
+ // Idle says a turn stopped, not that it finished. A run cut off at the round cap
+ // idles exactly like one that answered the question, and a driver polling status
+ // read half a game as a delivered one.
+ it('says how the last turn ended, not only that it ended', async () => {
+ const h = host();
+ expect(h.status().lastTurn).toBeNull();
+ h.send('hi');
+ await settled(h);
+ expect(h.status().lastTurn).toBe('end_turn');
+ });
+
// The conversation is the point of a session: a follow-up that built a second
// one would drop everything said so far and re-bill the whole prefix.
it('keeps one session across follow-ups, and drops it on reset', async () => {
diff --git a/desktop/tests/agent-queue.test.ts b/desktop/tests/agent-queue.test.ts
index ce47f4122..7ed7ddc95 100644
--- a/desktop/tests/agent-queue.test.ts
+++ b/desktop/tests/agent-queue.test.ts
@@ -20,7 +20,7 @@ const stop = vi.fn();
const retry = vi.fn(async (_n: number, _text: string) => undefined);
const status = (phase: AgentStatus['phase']): AgentStatus =>
- ({ ready: true, conversation: true, phase, model: 'opus-5', error: null });
+ ({ ready: true, conversation: true, phase, model: 'opus-5', error: null, lastTurn: null });
/** What main pushes when a turn starts or ends. */
const pushStatus = (phase: AgentStatus['phase']) => applyAgentMessage({ kind: 'status', status: status(phase) });
diff --git a/desktop/tests/agent-replay.test.ts b/desktop/tests/agent-replay.test.ts
index b15ed488d..cbd52e2bc 100644
--- a/desktop/tests/agent-replay.test.ts
+++ b/desktop/tests/agent-replay.test.ts
@@ -15,7 +15,7 @@ import type { AgentEvent } from '../electron/agent/types';
import type { AgentStatus } from '../electron/agent/host';
const status: AgentStatus =
- { ready: true, conversation: true, phase: 'idle', model: 'opus-5', error: null };
+ { ready: true, conversation: true, phase: 'idle', model: 'opus-5', error: null, lastTurn: null };
/** A conversation of two finished runs, as main would have logged it. */
const conversation = (from = 0): AgentEvent[] => [