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: add binary and asset-safe plugin filesystem APIs

yhha345e182a1f1
diff --git a/.github/workflows/editor-acceptance.yml b/.github/workflows/editor-acceptance.yml
index 2c5ca77df..b0de8abf6 100644
--- a/.github/workflows/editor-acceptance.yml
+++ b/.github/workflows/editor-acceptance.yml
@@ -70,7 +70,6 @@ jobs:
- name: Verify trusted transform-handle hover
if: always() && inputs.gizmo_hover && steps.build_editor.conclusion == 'success'
env:
- ELECTRON_DISABLE_SANDBOX: '1'
ESTELLA_MCP_EDITOR_VISIBLE: '1'
run: node tools/verify-gizmo-hover.mjs
- name: Keep trusted hover evidence
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d9215480b..4e21d993e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Added
+- **Plugin filesystem operations.** Editor plugins can read and write binary assets directly, list directories, inspect files, create folders, rename and delete in their own directory or the capability-gated project scope. Moves preserve asset UUID sidecars, deletion uses the OS trash, and project edits join the existing file journal. User-installed plugins outside the project are supported; generated plugin data no longer repeatedly reloads its producer. Addresses [#99](https://github.com/esengine/estella/issues/99).
+
- **One-click LAN device preview.** Scan Preview beside Play prepares the current scene for a phone browser, with a QR popover, tokenized local-network address, connected devices and advanced scene/interface settings. Scene and asset saves publish complete preview builds; compatible script changes retain the world through existing hot-swap APIs, with explicit reload reasons otherwise. Closing the project or stopping invalidates the session. The same Web runtime serves 2D and 3D; native/minigame device acceptance remains separate.
- **Budgeted particle scene collisions.** Particles query existing 2D or 3D physics along their movement segments, with layer filtering, rotating per-emitter/App query budgets, camera-distance culling and explicit floor/skip fallback. Bounded collision events use the standard EventReader; collision-triggered sub-emitters support local storage and capped inheritance depth. Details adds live counters and transient hit normals. A side-by-side sample demonstrates both physics paths and project-owned contact counters; device and performance acceptance remain pending.
- **Reusable UI trees and color pickers.** TreeView adapts arbitrary project records with stable IDs to the existing virtualized ListView. It supports expansion, selection, keyboard navigation, row and empty-state prefabs, and validated drop requests whose mutations remain project-owned. ColorPicker composes HSV/RGB/HEX and alpha editing with standard sliders and text inputs, per-control recent colors, and canonical RGBA change events for 2D UI, sprites and 3D materials. Both have UI Widgets presets and themed Inspectors; preview sample data never overwrites saved project data. Their Details panels use standard property alignment, shared override/reset feedback, concise manual links and folded editor-only previews. Recent-color capacity is disabled without losing its value when history is off; opaque color editing fixes alpha at 1.
diff --git a/desktop b/desktop
index 6ece066bf..a1acec43c 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 6ece066bf9925638a68e13cae69e3fb2485b4cce
+Subproject commit a1acec43c6f90d45608746acad949b505ca409bb
diff --git a/docs/astro/src/content/docs/extending/editor-plugins.mdx b/docs/astro/src/content/docs/extending/editor-plugins.mdx
index 40e48be70..54ff882d7 100644
--- a/docs/astro/src/content/docs/extending/editor-plugins.mdx
+++ b/docs/astro/src/content/docs/extending/editor-plugins.mdx
@@ -358,6 +358,41 @@ Throwing (or rejecting) reports the failure against your plugin in the Output Lo
and leaves the other importers running. A file is never imported twice at once, so
an import that takes a while cannot be re-entered by the writes it is making.
+### Binary assets and filesystem operations
+
+`ctx.fs` works in the plugin's own directory, including user-installed plugins outside
+the project. The `*Project` methods work in the open project and require `fs:project`.
+All paths are relative to the corresponding root; traversal and escaping symlinks are rejected.
+
+| Operation | Plugin directory | Project directory |
+| --- | --- | --- |
+| UTF-8 text | `read`, `write` | `readProject`, `writeProject` |
+| Binary `Uint8Array` | `readBytes`, `writeBytes` | `readProjectBytes`, `writeProjectBytes` |
+| Directory entries | `readDir` | `readProjectDir` |
+| Size, modified time, directory flag | `stat` | `statProject` |
+| Create directory | `mkdir` | `mkdirProject` |
+| Move / rename | `rename` | `renameProject` |
+| Move to OS trash | `delete` | `deleteProject` |
+
+```typescript
+const blob = await new Promise<Blob>((resolve, reject) =>
+ canvas.toBlob(value => value ? resolve(value) : reject(new Error('PNG encoding failed')), 'image/png'));
+await ctx.fs.writeProjectBytes('assets/generated/atlas.png', new Uint8Array(await blob.arrayBuffer()));
+await ctx.project.refreshAssets();
+```
+
+The file contains actual PNG bytes: no data URL, base64 text or external decoder is needed.
+Binary writes create parent directories and publish a complete file. Rename preserves the
+`.meta` sidecar and UUID and refuses existing targets, including orphaned metadata. Delete
+moves the item and its sidecar to the OS trash. Project mutations participate in the existing
+agent file journal; plugin-local files outside the project do not. Directory reads include
+dotfiles and metadata, rather than the Content Browser's filtered view. `mkdir` refuses an
+existing directory; other I/O failures reject normally. A disposed context or a context
+belonging to an old project cannot continue writing through this API.
+
+Generated files in a plugin directory do not reload the plugin unless they are actual
+bundle inputs. Editing an imported source, imported JSON or `plugin.json` still reloads it.
+
### Lending the agent a tool
The built-in agent's entire vocabulary is the tool catalog. A plugin that adds a
diff --git a/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx b/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx
index 42b5bfe0b..a4ba68fc4 100644
--- a/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx
+++ b/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx
@@ -331,6 +331,39 @@ ctx.assets.registerImporter({
抛异常(或 reject)会把这次失败记在你的插件名下(输出日志里),其余导入器照常运行。
同一个文件不会被同时导入两次,所以一次耗时较久的导入不会被它自己写出的文件重新触发。
+### 二进制资产与文件操作
+
+`ctx.fs` 默认操作插件自己的目录,也支持位于项目外的用户插件。项目版本的方法需要
+声明 `fs:project`,操作当前项目。路径相对于对应根目录;`..` 越界和指向根目录外的
+软链接都会被拒绝。
+
+| 操作 | 插件自己的目录 | 当前项目 |
+| --- | --- | --- |
+| UTF-8 文本 | `read`、`write` | `readProject`、`writeProject` |
+| 二进制 `Uint8Array` | `readBytes`、`writeBytes` | `readProjectBytes`、`writeProjectBytes` |
+| 列目录 | `readDir` | `readProjectDir` |
+| 大小、修改时间、目录标志 | `stat` | `statProject` |
+| 创建目录 | `mkdir` | `mkdirProject` |
+| 移动 / 重命名 | `rename` | `renameProject` |
+| 移到系统回收站 | `delete` | `deleteProject` |
+
+```typescript
+const blob = await new Promise<Blob>((resolve, reject) =>
+ canvas.toBlob(value => value ? resolve(value) : reject(new Error('PNG encoding failed')), 'image/png'));
+await ctx.fs.writeProjectBytes('assets/generated/atlas.png', new Uint8Array(await blob.arrayBuffer()));
+await ctx.project.refreshAssets();
+```
+
+落盘的是真正的 PNG 字节,无需 data URL、base64 文本或额外的 Node 解码脚本。
+二进制写入会创建父目录,完整写好后再替换目标。重命名会保留 `.meta` 和 UUID,目标文件
+或孤立的目标 `.meta` 已存在时会拒绝覆盖。删除会把文件及其 sidecar 移到系统回收站。
+项目修改接入已有 Agent 文件撤回日志;项目外的插件本地文件不计入项目撤回。目录列表包含
+点文件和 metadata,不经过 Content Browser 的显示过滤。`mkdir` 遇到已存在目录会拒绝;
+其他读写失败也以 Promise rejection 返回。插件上下文释放或切换项目后,旧上下文不能继续写入。
+
+写到插件目录中的生成文件不会反复重载插件;实际构建依赖中的源码、导入的 JSON 和
+`plugin.json` 修改后仍然正常热重载。
+
### 借一个工具给 Agent
内置 Agent 的全部词汇就是工具目录。**插件加了能力却没加工具,等于只给人加了、没给 Agent 加**——所以如果你的插件能烘焙遮蔽,就把它教给 Agent:
diff --git a/editor-api/index.ts b/editor-api/index.ts
index d81283dcb..0fa9b7344 100644
--- a/editor-api/index.ts
+++ b/editor-api/index.ts
@@ -522,15 +522,34 @@ export interface EditorProjectApi {
setFeature(name: string, value: unknown): Promise<void>;
}
+export interface PluginDirEntry { name: string; isDir: boolean }
+export interface PluginFileStat { size: number; mtimeMs: number; isDir: boolean }
/** Files a plugin may read/write. Paths are relative to the plugin's own folder
* unless the plugin declared the `fs:project` capability and uses `project*`. */
export interface PluginFs {
read(relPath: string): Promise<string>;
write(relPath: string, contents: string): Promise<void>;
+ readBytes(relPath: string): Promise<Uint8Array>;
+ writeBytes(relPath: string, bytes: Uint8Array): Promise<void>;
+ readDir(relPath: string): Promise<PluginDirEntry[]>;
+ stat(relPath: string): Promise<PluginFileStat>;
+ /** Moves to the OS trash, including an asset's .meta sidecar. */
+ delete(relPath: string): Promise<void>;
+ /** Moves without overwriting the destination; asset identity is preserved. */
+ rename(relPath: string, newRelPath: string): Promise<void>;
+ mkdir(relPath: string): Promise<void>;
/** Requires the `fs:project` capability; paths are project-relative. */
readProject(relPath: string): Promise<string>;
/** Requires the `fs:project` capability; paths are project-relative. */
writeProject(relPath: string, contents: string): Promise<void>;
+ /** The following methods also require fs:project. */
+ readProjectBytes(relPath: string): Promise<Uint8Array>;
+ writeProjectBytes(relPath: string, bytes: Uint8Array): Promise<void>;
+ readProjectDir(relPath: string): Promise<PluginDirEntry[]>;
+ statProject(relPath: string): Promise<PluginFileStat>;
+ deleteProject(relPath: string): Promise<void>;
+ renameProject(relPath: string, newRelPath: string): Promise<void>;
+ mkdirProject(relPath: string): Promise<void>;
}
/**
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 1691f4378..20c304149 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'feat(editor): complete scoped plugin filesystem operations': { note: 'Plugin filesystem operations.' },
+ 'feat: add binary and asset-safe plugin filesystem APIs': { note: 'Plugin filesystem operations.' },
'fix(editor): reuse mesh selection geometry and index multi-inspection': { note: 'Faster 3D multi-selection.' },
'fix: restore gizmo hover CI and optimize 3d multi-selection': { note: 'Faster 3D multi-selection.' },
'feat: add shared web runtime support for LAN device preview': { note: 'One-click LAN device preview.' },