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 file too big for one reply can be paged through

yhh393c3b412bb3
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index 8126675ea..a1f8e8d6a 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -8,7 +8,7 @@ import path from 'node:path';
import {
openProject,
readManifest,
- readInRoot,
+ readSliceInRoot,
readOptionalInRoot,
writeInRoot,
readDirInRoot,
@@ -911,7 +911,8 @@ ipcMain.handle('project:thumbnail', async (_e, rect: { x: number; y: number; wid
await writeFile(path.join(requireRoot(), 'thumbnail.png'), scaled.toPNG());
});
-ipcMain.handle('fs:read', (_e, relPath: string) => readInRoot(requireRoot(), relPath));
+ipcMain.handle('fs:read', (_e, relPath: string, offset?: number, limit?: number) =>
+ readSliceInRoot(requireRoot(), relPath, offset, limit));
ipcMain.handle('fs:readOptional', (_e, relPath: string) => readOptionalInRoot(requireRoot(), relPath));
ipcMain.handle('fs:write', (_e, relPath: string, contents: string) =>
writeInRoot(requireRoot(), relPath, contents),
diff --git a/desktop/electron/preload.ts b/desktop/electron/preload.ts
index ecfb00270..56ebda35e 100644
--- a/desktop/electron/preload.ts
+++ b/desktop/electron/preload.ts
@@ -237,7 +237,10 @@ const api = {
},
// Filesystem, scoped to the open project root (paths are project-relative).
fs: {
- read: (relPath: string): Promise<string> => ipcRenderer.invoke('fs:read', relPath),
+ /** `offset` (1-based line) and `limit` (line count) page a large file; omit
+ * both for the whole thing. */
+ read: (relPath: string, offset?: number, limit?: number): Promise<string> =>
+ ipcRenderer.invoke('fs:read', relPath, offset, limit),
/** Read a file that may legitimately not exist (optional project config) —
* `null` when it isn't there, so "absent" never travels as a failed IPC call. */
readOptional: (relPath: string): Promise<string | null> =>
diff --git a/desktop/electron/projectFs.ts b/desktop/electron/projectFs.ts
index 3cd677ede..d6468ac24 100644
--- a/desktop/electron/projectFs.ts
+++ b/desktop/electron/projectFs.ts
@@ -89,6 +89,37 @@ export function readInRoot(root: string, relPath: string): Promise<string> {
return readTextInRoot(resolveInRoot(root, relPath));
}
+/**
+ * A WINDOW of a file's lines — `offset` 1-based, `limit` a count. Omit both and
+ * it is the whole file, byte for byte, so every existing caller is unchanged.
+ *
+ * A caller that cannot page a large file has only one move when its reply comes
+ * back truncated, which is to ask for the same thing again. A driver reading a
+ * 200 KB declaration file spent four rounds on `offset: 40000`, `offset: 160000`,
+ * `limit: 100` — every one of them silently dropped, every reply the identical
+ * first 24 000 characters — and concluded "the offset doesn't seem to work". It
+ * did not exist.
+ *
+ * An out-of-range offset is an ERROR naming the file's length rather than an
+ * empty string: empty reads as "the file ends here", which is how a caller
+ * decides it has seen everything.
+ */
+export async function readSliceInRoot(
+ root: string, relPath: string, offset?: number, limit?: number,
+): Promise<string> {
+ const text = await readTextInRoot(resolveInRoot(root, relPath));
+ if (offset === undefined && limit === undefined) return text;
+ const lines = text.split('\n');
+ const from = Math.max(1, Math.floor(offset ?? 1));
+ if (from > lines.length) {
+ throw new Error(
+ `offset ${from} is past the end of ${relPath}, which has ${lines.length} line(s)`,
+ );
+ }
+ const count = limit === undefined ? lines.length : Math.max(0, Math.floor(limit));
+ return lines.slice(from - 1, from - 1 + count).join('\n');
+}
+
/**
* Read a file that is allowed not to exist — `null` instead of a throw.
*
diff --git a/desktop/shared/toolCatalog.mjs b/desktop/shared/toolCatalog.mjs
index 5085be88b..4d41e360c 100644
--- a/desktop/shared/toolCatalog.mjs
+++ b/desktop/shared/toolCatalog.mjs
@@ -409,9 +409,11 @@ export const TOOLS = [
schema: obj({ path: { type: 'string' }, patch: { type: 'object' } }, ['path', 'patch']),
method: 'setImportSettings', args: (i) => [i.path, i.patch], root: 'editor' },
{ name: 'read_project_file',
- description: 'Read a text file by project-relative path — game scripts (src/*.ts), project.esproject, .meta files, any project text. Complements get_inspector: scenes are model state, behaviour is code.',
- schema: obj({ path: { type: 'string' } }, ['path']),
- js: (i) => `window.estella.fs.read(${JSON.stringify(i.path)})` },
+ description: 'Read a text file by project-relative path — game scripts (src/*.ts), project.esproject, .meta files, any project text. Complements get_inspector: scenes are model state, behaviour is code. '
+ + 'A big file comes back TRUNCATED; page through it with `offset` (1-based LINE number) and `limit` (how many lines), which is the "narrow the request" the truncation notice asks for. '
+ + 'An offset past the end is refused, naming the line count — so an empty reply always means those lines are empty, never that you have run off the end.',
+ schema: obj({ path: { type: 'string' }, offset: { type: 'number' }, limit: { type: 'number' } }, ['path']),
+ js: (i) => `window.estella.fs.read(${JSON.stringify(i.path)}, ${i.offset ?? 'undefined'}, ${i.limit ?? 'undefined'})` },
{ name: 'write_project_file', effect: 'irreversible',
description: 'Write a text file by project-relative path, CREATING or OVERWRITING it. This is how game scripts (src/*.ts) are authored — create_asset only makes .meta-carrying asset types and refuses to overwrite (it uniquifies to "name 2"). '
+ 'Writing project sources does not itself rebuild them; the editor picks the change up through its file watcher.',
diff --git a/desktop/tests/project-fs.test.ts b/desktop/tests/project-fs.test.ts
index 3eacdd082..06f5412ac 100644
--- a/desktop/tests/project-fs.test.ts
+++ b/desktop/tests/project-fs.test.ts
@@ -18,6 +18,7 @@ import {
mkdirInRoot,
duplicateInRoot,
statInRoot,
+ readSliceInRoot,
snapshotForTrash,
restoreTrashed,
} from '../electron/projectFs';
@@ -232,3 +233,36 @@ describe('createAsset', () => {
expect(read('assets/scene.esscene')).toBe('{"v":"1.0"}'); // original untouched
});
});
+
+describe('readSliceInRoot (paging a file too big for one reply)', () => {
+ const LINES = 500;
+ const NL = String.fromCharCode(10);
+ beforeEach(() => {
+ writeFileSync(path.join(root, 'big.ts'), Array.from({ length: LINES }, (_, i) => `line ${i + 1}`).join(NL));
+ });
+
+ it('returns the whole file byte for byte when neither bound is given', async () => {
+ const all = await readSliceInRoot(root, 'big.ts');
+ expect(all).toBe(readFileSync(path.join(root, 'big.ts'), 'utf8'));
+ });
+
+ it('takes offset as a 1-based line and limit as a count', async () => {
+ expect(await readSliceInRoot(root, 'big.ts', 1, 2)).toBe(['line 1', 'line 2'].join(NL));
+ expect(await readSliceInRoot(root, 'big.ts', 100, 3)).toBe(['line 100', 'line 101', 'line 102'].join(NL));
+ // A limit past the end simply stops at the end.
+ expect(await readSliceInRoot(root, 'big.ts', 499, 50)).toBe(['line 499', 'line 500'].join(NL));
+ // An offset with no limit runs to the end.
+ expect(await readSliceInRoot(root, 'big.ts', 498)).toBe(['line 498', 'line 499', 'line 500'].join(NL));
+ });
+
+ it('refuses an offset past the end, naming the length', async () => {
+ // Empty would read as "the file ends here", which is how a caller decides it
+ // has seen everything — the exact wrong conclusion.
+ await expect(readSliceInRoot(root, 'big.ts', 501)).rejects.toThrow(/past the end/);
+ await expect(readSliceInRoot(root, 'big.ts', 501)).rejects.toThrow(/500 line/);
+ });
+
+ it('still refuses to leave the project root', async () => {
+ await expect(readSliceInRoot(root, '../outside.txt', 1, 1)).rejects.toThrow();
+ });
+});