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(outliner): folders interleave with entities — drag a folder anywhere among them

esengine391cfeb10ec9
diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.ts
index aa5639b5f..1e51b5d98 100644
--- a/desktop/src/engine/EditorControlSurface.ts
+++ b/desktop/src/engine/EditorControlSurface.ts
@@ -172,9 +172,9 @@ export class EditorControlSurfaceImpl {
deleteFolder(path: string): void {
this.s.commands.deleteFolder(path);
}
- /** Reorder a folder before/after a sibling (manual sort). */
- reorderFolder(srcPath: string, targetPath: string, before: boolean): void {
- this.s.commands.reorderFolder(srcPath, targetPath, before);
+ /** Place a folder at a manual sort position among its siblings (drag-between). */
+ placeFolder(path: string, key: number): void {
+ this.s.commands.placeFolder(path, key);
}
/** Move entities into a folder (`null` = scene root); un-parents them. */
moveToFolder(ids: readonly EntityId[], path: string | null): void {
diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.ts
index 5b833e46a..5c39dcd0b 100644
--- a/desktop/src/engine/SceneCommands.ts
+++ b/desktop/src/engine/SceneCommands.ts
@@ -555,29 +555,22 @@ export class SceneCommandsImpl {
}
/**
- * Reorder a folder among its siblings (drag-between, manual sort). Promotes both
- * folders to explicit (so the order persists) and places `srcPath` immediately
- * before/after `targetPath` in the scene folder list. One undo step; only valid
- * for same-parent siblings (a cross-parent move is a nest via {@link renameFolder}).
+ * Place a folder at a manual sort position among its siblings (drag-between).
+ * `key` is a number on the sibling-order scale — entities use their scene index,
+ * so dragging a folder before/after a row passes that row's `sortKey` ∓ 0.5,
+ * interleaving the folder among the entities. One undo step.
*/
- reorderFolder(srcPath: string, targetPath: string, before: boolean): void {
- const src = normalizeFolder(srcPath);
- const tgt = normalizeFolder(targetPath);
- if (!src || !tgt || src === tgt) return;
- if (folderParent(src) !== folderParent(tgt)) return; // not siblings → not a reorder
-
- const beforeList = this.model.sceneFolders();
- const list = [...beforeList];
- if (!list.includes(src)) list.push(src);
- if (!list.includes(tgt)) list.push(tgt);
- const without = list.filter((f) => f !== src);
- const ti = without.indexOf(tgt);
- without.splice(before ? ti : ti + 1, 0, src);
-
- const same = beforeList.length === without.length && beforeList.every((f, i) => f === without[i]);
- if (same) return;
- this.model.setSceneFolders(without);
- this.history.record('Reorder Folder', () => this.model.setSceneFolders(without), () => this.model.setSceneFolders(beforeList));
+ placeFolder(path: string, key: number): void {
+ const norm = normalizeFolder(path);
+ if (!norm) return;
+ const before = this.model.folderOrderOf(norm);
+ if (before === key) return;
+ this.model.setFolderOrder(norm, key);
+ this.history.record(
+ 'Move Folder',
+ () => this.model.setFolderOrder(norm, key),
+ () => this.model.setFolderOrder(norm, before),
+ );
}
/**
diff --git a/desktop/src/engine/SceneModel.ts b/desktop/src/engine/SceneModel.ts
index 7175c7f79..5bd7a56df 100644
--- a/desktop/src/engine/SceneModel.ts
+++ b/desktop/src/engine/SceneModel.ts
@@ -302,6 +302,24 @@ export class SceneModelImpl {
this.emit({ kind: 'foldersChanged' });
}
+ /** A folder's manual sort position (drag-placed), or undefined for the default. */
+ folderOrderOf(path: string): number | undefined {
+ const d = this.data as (SceneData & { folderOrder?: Record<string, number> }) | null;
+ return d?.folderOrder?.[path];
+ }
+
+ /** Set (or, with undefined, clear) a folder's manual sort position. */
+ setFolderOrder(path: string, value: number | undefined): void {
+ if (!this.data) return;
+ const d = this.data as SceneData & { folderOrder?: Record<string, number> };
+ if (value === undefined) {
+ if (d.folderOrder) delete d.folderOrder[path];
+ } else {
+ (d.folderOrder ??= {})[path] = value;
+ }
+ this.emit({ kind: 'foldersChanged' });
+ }
+
// ── Editor visibility / lock (per-entity, editor-only — UE5 bHiddenInEditor) ──
// Like `folder`: an editor-only per-entity field, lossless, never a World
// component. `hidden` the reconciler folds into the render projection (without
diff --git a/desktop/src/outliner/OutlinerModel.ts b/desktop/src/outliner/OutlinerModel.ts
index 182f1218c..f071bea54 100644
--- a/desktop/src/outliner/OutlinerModel.ts
+++ b/desktop/src/outliner/OutlinerModel.ts
@@ -30,6 +30,8 @@ interface OutlinerItemBase {
/** Whether this node's children are shown (drives the twist + the walk). */
expanded: boolean;
parentKey: string | null;
+ /** Manual-order position among its siblings (drag-between reads ±0.5 of this). */
+ sortKey: number;
}
export interface OutlinerEntityItem extends OutlinerItemBase {
kind: 'entity';
@@ -62,6 +64,8 @@ export interface BuildOutlinerOpts {
sort?: SortMode;
/** A root entity's folder path (`""` = scene root). Absent ⇒ no folders (PIE). */
folderOf?: (id: EntityId) => string;
+ /** A folder's manual sort position (drag-placed); absent ⇒ default (top of level). */
+ folderOrderOf?: (path: string) => number | undefined;
/** The scene's explicit (incl. empty) folders, so empties still show. */
folders?: readonly string[];
/** Free-text name filter; matches + their ancestors survive (case-insensitive). */
@@ -152,46 +156,71 @@ export function buildOutlinerItems(data: SceneData | null, opts: BuildOutlinerOp
}
if (!active) for (const f of opts.folders ?? []) for (const pre of folderPrefixes(normalizeFolder(f))) allFolders.add(pre);
- // Manual sort orders sibling folders by their position in the scene's explicit
- // folder list (drag-reorderable, like entities); derived/list-absent folders
- // fall to the end alphabetically. name/type sort is plain alphabetical.
- const folderRank = sort === 'manual' ? new Map((opts.folders ?? []).map((f, i) => [normalizeFolder(f), i])) : null;
- const childFolders = (path: string): string[] => {
- const kids = [...allFolders].filter((p) => folderParent(p) === path);
- if (folderRank) {
- return kids.sort(
- (a, b) => (folderRank.get(a) ?? Infinity) - (folderRank.get(b) ?? Infinity) || folderName(a).localeCompare(folderName(b)),
- );
- }
- return kids.sort((a, b) => folderName(a).localeCompare(folderName(b)));
- };
+ const childFolders = (path: string): string[] => [...allFolders].filter((p) => folderParent(p) === path);
const countUnder = (path: string): number => {
let n = 0;
for (const [fp, arr] of rootsByFolder) if (isFolderUnder(fp, path)) n += arr.length;
return n;
};
+ // Unified sibling ordering: folders and root entities INTERLEAVE at each level.
+ // Manual key: entity → its scene (data) index; folder → its drag-placed order,
+ // else the top of the level (a fresh folder isn't lost among the entities).
+ // name/type sort orders folders + entities together by name / kind.
+ const FOLDER_DEFAULT_TOP = -1e6;
+ const entityIndex = new Map((data?.entities ?? []).map((e, i) => [e.id, i] as const));
+ const folderOrderOf = opts.folderOrderOf ?? (() => undefined);
+ const manualFolderKey = (p: string): number => {
+ const o = folderOrderOf(p);
+ if (o !== undefined) return o;
+ const i = (opts.folders ?? []).indexOf(p);
+ return FOLDER_DEFAULT_TOP + (i < 0 ? 0 : i);
+ };
+
+ type Sib = { folder: string } | { entity: SceneNode };
+ const nameOf = (s: Sib): string => ('folder' in s ? folderName(s.folder) : s.entity.name);
+ const kindOf = (s: Sib): string => ('folder' in s ? 'folder' : s.entity.kind);
+ const manualKey = (s: Sib): number => ('folder' in s ? manualFolderKey(s.folder) : (entityIndex.get(s.entity.id) ?? 0));
+ const sortSibs = (sibs: Sib[]): Sib[] => {
+ if (sort === 'name') return sibs.sort((a, b) => nameOf(a).localeCompare(nameOf(b)));
+ if (sort === 'type') return sibs.sort((a, b) => kindOf(a).localeCompare(kindOf(b)) || nameOf(a).localeCompare(nameOf(b)));
+ return sibs.sort((a, b) => manualKey(a) - manualKey(b) || nameOf(a).localeCompare(nameOf(b)));
+ };
+
const out: OutlinerItem[] = [];
- const emitEntity = (node: SceneNode, depth: number, parentKey: string | null): void => {
+ const emitEntity = (node: SceneNode, depth: number, parentKey: string | null, sortKey: number): void => {
const hasChildren = !!node.children?.length;
const expanded = expandAll || opts.expanded.has(entityKey(node.id));
- out.push({ kind: 'entity', key: entityKey(node.id), id: node.id, node, depth, hasChildren, expanded, parentKey });
- if (hasChildren && expanded) for (const c of sortNodes(node.children!, sort)) emitEntity(c, depth + 1, entityKey(node.id));
+ out.push({ kind: 'entity', key: entityKey(node.id), id: node.id, node, depth, hasChildren, expanded, parentKey, sortKey });
+ if (hasChildren && expanded) {
+ sortNodes(node.children!, sort).forEach((c, i) =>
+ emitEntity(c, depth + 1, entityKey(node.id), sort === 'manual' ? (entityIndex.get(c.id) ?? i) : i),
+ );
+ }
};
- // Emit the child folders of `path` (nested) then the entity roots directly in it.
- const emitFolderContents = (path: string, depth: number, parentKey: string | null): void => {
- for (const fp of childFolders(path)) {
- const hasKids = childFolders(fp).length > 0 || (rootsByFolder.get(fp)?.length ?? 0) > 0;
- const expanded = expandAll || opts.expanded.has(folderKey(fp));
- out.push({ kind: 'folder', key: folderKey(fp), path: fp, name: folderName(fp), count: countUnder(fp), depth, hasChildren: hasKids, expanded, parentKey });
- if (expanded) emitFolderContents(fp, depth + 1, folderKey(fp));
- }
- for (const root of sortNodes(rootsByFolder.get(path) ?? [], sort)) emitEntity(root, depth, parentKey);
+ const emitLevel = (path: string, depth: number, parentKey: string | null): void => {
+ const sibs: Sib[] = [
+ ...childFolders(path).map((p): Sib => ({ folder: p })),
+ ...(rootsByFolder.get(path) ?? []).map((n): Sib => ({ entity: n })),
+ ];
+ sortSibs(sibs);
+ sibs.forEach((s, i) => {
+ const sortKey = sort === 'manual' ? manualKey(s) : i;
+ if ('folder' in s) {
+ const fp = s.folder;
+ const hasKids = childFolders(fp).length > 0 || (rootsByFolder.get(fp)?.length ?? 0) > 0;
+ const expanded = expandAll || opts.expanded.has(folderKey(fp));
+ out.push({ kind: 'folder', key: folderKey(fp), path: fp, name: folderName(fp), count: countUnder(fp), depth, hasChildren: hasKids, expanded, parentKey, sortKey });
+ if (expanded) emitLevel(fp, depth + 1, folderKey(fp));
+ } else {
+ emitEntity(s.entity, depth, parentKey, sortKey);
+ }
+ });
};
- emitFolderContents(ROOT_FOLDER, 0, null);
+ emitLevel(ROOT_FOLDER, 0, null);
return out;
}
diff --git a/desktop/src/panels/Outliner.tsx b/desktop/src/panels/Outliner.tsx
index 0652a8278..9c986dbfe 100644
--- a/desktop/src/panels/Outliner.tsx
+++ b/desktop/src/panels/Outliner.tsx
@@ -101,6 +101,7 @@ export function Outliner() {
query,
sort: sortMode,
folderOf: (id) => SceneModel.folderOf(id),
+ folderOrderOf: (p) => SceneModel.folderOrderOf(p),
folders: SceneModel.sceneFolders(),
})
: [],
@@ -292,6 +293,13 @@ export function Outliner() {
void ProjectStore.instantiatePrefabFromPath(path, parent);
return true;
};
+ // The folder level a row sits at (for placing a dragged folder as its sibling):
+ // a folder's parent path, or a ROOT entity's folder; null = not a level sibling.
+ const folderDropLevel = (item: OutlinerItem): string | null => {
+ if (item.kind === 'folder') return folderParent(item.path);
+ const e = SceneModel.entityBySource(item.id);
+ return e && e.parent == null ? SceneModel.folderOf(item.id) : null;
+ };
const onDragStartRow = (item: OutlinerItem, e: React.DragEvent) => {
e.dataTransfer.effectAllowed = 'move';
if (item.kind === 'folder') {
@@ -317,13 +325,9 @@ export function Outliner() {
const rect = e.currentTarget.getBoundingClientRect();
const rel = (e.clientY - rect.top) / rect.height;
pos = rel < 0.25 ? 'before' : rel > 0.75 ? 'after' : 'on';
- } else if (
- dragFolder.current &&
- item.kind === 'folder' &&
- sortMode === 'manual' &&
- folderParent(dragFolder.current) === folderParent(item.path)
- ) {
- // Sibling folders → top/bottom third reorders, middle nests.
+ } else if (dragFolder.current && sortMode === 'manual' && folderDropLevel(item) === folderParent(dragFolder.current)) {
+ // Folder over a same-level sibling (folder OR root entity) → top/bottom third
+ // places the folder before/after it (interleaved); the middle nests/absorbs.
const rect = e.currentTarget.getBoundingClientRect();
const rel = (e.clientY - rect.top) / rect.height;
pos = rel < 0.33 ? 'before' : rel > 0.66 ? 'after' : 'on';
@@ -361,13 +365,13 @@ export function Outliner() {
if (dragFolder.current != null) {
const src = dragFolder.current;
dragFolder.current = null;
- if (item.kind === 'folder') {
- // sibling between-rows → reorder; else → nest under the target folder
- if (pos !== 'on' && folderParent(src) === folderParent(item.path)) SceneCommands.reorderFolder(src, item.path, pos === 'before');
- else moveFolderInto(src, item.path);
+ if (pos !== 'on') {
+ // between-rows → place the folder at that position (interleaved with entities)
+ SceneCommands.placeFolder(src, item.sortKey + (pos === 'before' ? -0.5 : 0.5));
+ } else if (item.kind === 'folder') {
+ moveFolderInto(src, item.path); // middle of a folder → nest
} else {
- // dropped onto an entity → that entity (+ any selection) joins the folder
- SceneCommands.moveToFolder(selectionOrTarget(item.id), src);
+ SceneCommands.moveToFolder(selectionOrTarget(item.id), src); // middle of an entity → absorb it
}
return;
}
diff --git a/desktop/tests/outliner-folders.test.ts b/desktop/tests/outliner-folders.test.ts
index 5a6ed5d39..387bbb14c 100644
--- a/desktop/tests/outliner-folders.test.ts
+++ b/desktop/tests/outliner-folders.test.ts
@@ -111,21 +111,13 @@ describe('SceneCommands folders (undoable)', () => {
expect(S.model.sceneFolders()).toContain('A/B/C');
});
- it('reorderFolder moves a sibling folder in the manual order; undo restores', () => {
- S.commands.createFolder('Zebra');
- S.commands.createFolder('Apple');
- expect(S.model.sceneFolders()).toEqual(['Zebra', 'Apple']);
- S.commands.reorderFolder('Apple', 'Zebra', true); // Apple before Zebra
- expect(S.model.sceneFolders()).toEqual(['Apple', 'Zebra']);
- S.history.undo();
- expect(S.model.sceneFolders()).toEqual(['Zebra', 'Apple']);
- });
-
- it('reorderFolder only touches same-parent siblings (cross-parent is a no-op)', () => {
+ it('placeFolder sets a folder manual sort position; undo clears it', () => {
S.commands.createFolder('A');
- S.commands.createFolder('B/C');
- S.commands.reorderFolder('B/C', 'A', true); // different parents → rejected
- expect(S.model.sceneFolders()).toEqual(['A', 'B/C']);
+ expect(S.model.folderOrderOf('A')).toBeUndefined();
+ S.commands.placeFolder('A', 2.5); // drag-placed between scene entities #2 and #3
+ expect(S.model.folderOrderOf('A')).toBe(2.5);
+ S.history.undo();
+ expect(S.model.folderOrderOf('A')).toBeUndefined();
});
it('folders round-trip through serialize (lossless, editor-only)', () => {
diff --git a/desktop/tests/outliner-model.test.ts b/desktop/tests/outliner-model.test.ts
index dba61da04..24c12f9ba 100644
--- a/desktop/tests/outliner-model.test.ts
+++ b/desktop/tests/outliner-model.test.ts
@@ -193,4 +193,21 @@ describe('sort mode', () => {
expect(keys(buildOutlinerItems(data, { expanded: new Set(), folders }))).toEqual([folderKey('Zebra'), folderKey('Apple')]);
expect(keys(buildOutlinerItems(data, { expanded: new Set(), folders, sort: 'name' }))).toEqual([folderKey('Apple'), folderKey('Zebra')]);
});
+
+ it('a drag-placed folder interleaves among root entities (manual sort key)', () => {
+ const data = {
+ version: '1.0',
+ name: 'i',
+ entities: [
+ { id: 1, name: 'A', parent: null, children: [], components: [] },
+ { id: 2, name: 'B', parent: null, children: [], components: [] },
+ { id: 3, name: 'C', parent: null, children: [], components: [] },
+ ],
+ } as unknown as SceneData;
+ // Folder F placed at 1.5 → between entity index 1 (e2) and index 2 (e3).
+ const items = buildOutlinerItems(data, { expanded: new Set(), folders: ['F'], folderOrderOf: (p) => (p === 'F' ? 1.5 : undefined) });
+ expect(keys(items)).toEqual(['e1', 'e2', folderKey('F'), 'e3']);
+ // Its sortKey is the placed order, so a drag-after reads 1.5 + 0.5 = 2.
+ expect(items.find((i) => i.key === folderKey('F'))!.sortKey).toBe(1.5);
+ });
});