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(mcp): frame stats carry what texture streaming holds; the MCP docs say when the editor starts

yhhcd72e47a3d08
diff --git a/desktop b/desktop
index b43c06857..110946826 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit b43c0685777ead176ed1f4566d74c9bec6bf2db5
+Subproject commit 110946826b3caf631bfe48febc304e0659f3d546
diff --git a/docs/astro/src/content/docs/agents/mcp.mdx b/docs/astro/src/content/docs/agents/mcp.mdx
index 84fbfa5ab..e5435f2fa 100644
--- a/docs/astro/src/content/docs/agents/mcp.mdx
+++ b/docs/astro/src/content/docs/agents/mcp.mdx
@@ -81,6 +81,11 @@ claude mcp add estella --env ESTELLA_MCP_ALLOW_WRITES=1 -- \
`--editor` launches the installed editor with the MCP endpoint enabled. Node.js 20+
must be on your PATH.
+The editor is launched by the first tool call, not when your AI tool starts the server: the server answers at once, a
+session that calls no tool never starts an editor, and an editor slow to come up cold cannot make the tool give up on the
+server. Add `--eager` to start it in the background as soon as the tool connects, and `--hidden` to drive it without a
+window.
+
<Aside type="caution">
Without `ESTELLA_MCP_ALLOW_WRITES=1` the agent can only **observe** — every
mutating tool (creating entities, editing fields, saving, exporting) is hidden and
@@ -219,7 +224,7 @@ folder in one call — each asset keeps the settings the patch does not name.
In a source checkout, `pnpm --filter @estella/editor editor:mcp` serves the same
registry against a headless fixtures host (scene tools only), `editor:mcp -- --editor`
-boots the dev editor, and two e2e suites (`editor:mcp:e2e`,
+boots the dev editor (add `--hidden` to keep its window from appearing), and two e2e suites (`editor:mcp:e2e`,
`editor:mcp:editor-e2e`) prove the full loop.
## See also
diff --git a/docs/astro/src/content/docs/zh-cn/agents/mcp.mdx b/docs/astro/src/content/docs/zh-cn/agents/mcp.mdx
index 84b9c6eaa..6e945d503 100644
--- a/docs/astro/src/content/docs/zh-cn/agents/mcp.mdx
+++ b/docs/astro/src/content/docs/zh-cn/agents/mcp.mdx
@@ -74,6 +74,8 @@ claude mcp add estella --env ESTELLA_MCP_ALLOW_WRITES=1 -- \
`--editor` 会以启用 MCP 端点的方式启动安装版编辑器。PATH 里需要 Node.js 20+。
+编辑器在第一次调用工具时才启动,而不是在 AI 工具启动服务器的时候:服务器立刻就能应答,一次工具都没调用的会话不会拉起编辑器,冷启动慢的编辑器也不会让 AI 工具放弃这个服务器。加 `--eager` 可以在 AI 工具连上后就在后台启动它,加 `--hidden` 则不显示窗口。
+
<Aside type="caution">
不设 `ESTELLA_MCP_ALLOW_WRITES=1` 时代理只能**观察**——所有会产生修改的工具
(创建实体、改字段、保存、导出)都被隐藏并拒绝。写权限请有意识地授予。
@@ -201,7 +203,7 @@ claude mcp add estella --env ESTELLA_MCP_ALLOW_WRITES=1 -- \
## 从源码仓库使用(贡献者)
源码仓库里,`pnpm --filter @estella/editor editor:mcp` 用无头夹具宿主提供同一套
-注册表(仅场景工具),`editor:mcp -- --editor` 拉起开发版编辑器;两套 e2e
+注册表(仅场景工具),`editor:mcp -- --editor` 拉起开发版编辑器(加 `--hidden` 不显示窗口);两套 e2e
(`editor:mcp:e2e`、`editor:mcp:editor-e2e`)验证完整闭环。
## 参见
diff --git a/sdk/src/runtime/frameStats.ts b/sdk/src/runtime/frameStats.ts
index 6acf56895..7d9f1504a 100644
--- a/sdk/src/runtime/frameStats.ts
+++ b/sdk/src/runtime/frameStats.ts
@@ -9,7 +9,9 @@ import type { App, FrameCosts } from '../app/app';
import { engineApi } from '../ecs/bridge/engineApi';
import { Quality } from '../render/qualityRuntime';
import { Audio } from '../audio/Audio';
+import { Assets } from '../asset/AssetPlugin';
import { StaticBatchingRes, type StaticBatchSummary } from '../render/staticBatchPlugin';
+import { TextureStreamingRes } from '../render/textureStreaming';
import type { QualityReport } from '../render/quality';
export interface FrameStatsReport {
@@ -38,6 +40,8 @@ export interface FrameStatsReport {
/** What static batching merged and left out; absent until a mesh has been marked. */
staticBatch?: StaticBatchSummary;
quality?: QualityReport;
+ /** What texture streaming holds: how many textures, the megabytes they take and would at full size, and how many moves it has made. */
+ textureStreaming?: { enabled: boolean; textures: number; streamedMB: number; fullMB: number; moves: number; failures: number; startedSmall: number };
}
function jsonMap(json: string | undefined): Record<string, number> {
@@ -71,5 +75,15 @@ export function frameStatsReport(app: App): FrameStatsReport {
...audioStats(app),
...(app.hasResource(StaticBatchingRes) ? (() => { const s = app.getResource(StaticBatchingRes).summary(); return s ? { staticBatch: s } : {}; })() : {}),
quality: app.hasResource(Quality) ? app.getResource(Quality)?.report() : undefined,
+ ...textureStreamingStats(app),
};
}
+
+function textureStreamingStats(app: App): Pick<FrameStatsReport, 'textureStreaming'> {
+ if (!app.hasResource(TextureStreamingRes)) return {};
+ const s = app.getResource(TextureStreamingRes);
+ const b = s.bytes();
+ const loader = app.hasResource(Assets) ? app.getResource(Assets).getTextureLoader() : null;
+ return { textureStreaming: { enabled: s.enabled, textures: s.textures.size, streamedMB: b.now / 1048576, fullMB: b.full / 1048576,
+ moves: s.moves, failures: s.failures, startedSmall: loader?.startedSmall ?? 0 } };
+}