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
feat: add binary and asset-safe plugin filesystem APIs
yhha345e182a1f1
diff --git a/.github/workflows/editor-acceptance.yml b/.github/workflows/editor-acceptance.ymlindex 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 hoverif: 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 evidencediff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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/desktopindex 6ece066bf..a1acec43c 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 6ece066bf9925638a68e13cae69e3fb2485b4cce+Subproject commit a1acec43c6f90d45608746acad949b505ca409bbdiff --git a/docs/astro/src/content/docs/extending/editor-plugins.mdx b/docs/astro/src/content/docs/extending/editor-plugins.mdxindex 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 Loand leaves the other importers running. A file is never imported twice at once, soan 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 toolThe built-in agent's entire vocabulary is the tool catalog. A plugin that adds adiff --git a/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx b/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdxindex 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.tsindex 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.mjsindex 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.' },