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): GUI to author asset-delivery groups + CDN profile

yhhb8c1eb90b619
diff --git a/desktop/src/components/BuildDialog.tsx b/desktop/src/components/BuildDialog.tsx
index 1aabe674f..234e56922 100644
--- a/desktop/src/components/BuildDialog.tsx
+++ b/desktop/src/components/BuildDialog.tsx
@@ -103,6 +103,9 @@ export function BuildDialog() {
const [phase, setPhase] = useState<Phase>('idle');
const [result, setResult] = useState<Result | null>(null);
const [log, setLog] = useState<string[]>([]);
+ // Active build profile's CDN root (asset-groups.json) — where remote-group
+ // assets are fetched from for hot update. Written on blur.
+ const [cdnRoot, setCdnRoot] = useState(() => ProjectStore.activeProfileRemoteRoot());
const def = PLATFORMS.find((p) => p.id === platform)!;
const running = phase === 'running';
@@ -276,6 +279,18 @@ export function BuildDialog() {
{t('build.compressAudio')}
</label>
+ <div className="build__row">
+ <span className="build__label" title={t('build.cdnRootTip')}>{t('build.cdnRoot')}</span>
+ <input
+ value={cdnRoot}
+ spellCheck={false}
+ placeholder="https://cdn…"
+ title={t('build.cdnRootTip')}
+ onChange={(e) => setCdnRoot(e.target.value)}
+ onBlur={() => void ProjectStore.setActiveProfileRemoteRoot(cdnRoot.trim())}
+ />
+ </div>
+
{def.prereq && (
<div className="build__prereq">
<Info size={13} /> <span className="selectable">{def.prereq}</span>
diff --git a/desktop/src/i18n/messages/content.ts b/desktop/src/i18n/messages/content.ts
index 790cfb22a..a546cec23 100644
--- a/desktop/src/i18n/messages/content.ts
+++ b/desktop/src/i18n/messages/content.ts
@@ -74,6 +74,12 @@ export const contentMessages = defineMessages({
'cb.menuNewAnimatorController': { en: 'New Animation Controller', zh: '新建动画控制器' },
'cb.menuNewBehaviorTree': { en: 'New Behavior Tree', zh: '新建行为树' },
'cb.menuShowInExplorer': { en: 'Show in Explorer', zh: '在资源管理器中显示' },
+ 'cb.delivery': { en: 'Delivery', zh: '交付方式' },
+ 'cb.deliveryLocal': { en: 'Local (in package)', zh: '本地(打进包)' },
+ 'cb.deliverySubpackage': { en: 'Subpackage (on-demand)', zh: '分包(按需)' },
+ 'cb.deliveryRemote': { en: 'Remote (CDN / hot-update)', zh: '远端(CDN / 热更)' },
+ 'cb.badgeSubpackage': { en: 'PKG', zh: '分包' },
+ 'cb.badgeRemote': { en: 'CDN', zh: 'CDN' },
'cb.menuOpen': { en: 'Open', zh: '打开' },
'cb.menuSetStartupScene': { en: 'Set as Startup Scene', zh: '设为启动场景' },
'cb.menuIncludeInExport': { en: 'Include in Export', zh: '包含在导出中' },
diff --git a/desktop/src/i18n/messages/project.ts b/desktop/src/i18n/messages/project.ts
index 7d8fb68e9..867cf8688 100644
--- a/desktop/src/i18n/messages/project.ts
+++ b/desktop/src/i18n/messages/project.ts
@@ -83,6 +83,13 @@ export const projectMessages = defineMessages({
zh: 'Playable 仅打包启动场景——一个有体积上限的单文件。',
},
+ // — Asset delivery (CDN / hot-update) —
+ 'build.cdnRoot': { en: 'CDN root (hot-update)', zh: 'CDN 地址(热更)' },
+ 'build.cdnRootTip': {
+ en: 'Base URL that remote-group assets are fetched from for this build profile. Empty → remote groups load from the game origin. Mark folders remote in the Content Browser (right-click → Delivery).',
+ zh: '当前构建 profile 下远端组资产的拉取根地址。留空则从游戏同源加载。在内容浏览器右键文件夹 → 交付方式 里把文件夹标为远端。',
+ },
+
// — Run / progress / result —
'build.package': { en: 'Package', zh: '打包' },
'build.packaging': { en: 'Packaging…', zh: '打包中…' },
@@ -146,6 +153,7 @@ export const projectMessages = defineMessages({
'proj.saveSortingLayersFailed': { en: 'Failed to save sorting layers', zh: '保存排序层失败' },
'proj.saveDesignResolutionFailed': { en: 'Failed to save design resolution', zh: '保存设计分辨率失败' },
'proj.savePackagingFailed': { en: 'Failed to save packaging settings', zh: '保存打包设置失败' },
+ 'proj.saveAssetGroupsFailed': { en: 'Failed to save asset delivery config', zh: '保存资产交付配置失败' },
'proj.savePlatformFailed': { en: 'Failed to save platform settings', zh: '保存平台设置失败' },
'proj.savePhysicsFailed': { en: 'Failed to save physics setting', zh: '保存物理设置失败' },
'proj.saveAudioFailed': { en: 'Failed to save audio setting', zh: '保存音频设置失败' },
diff --git a/desktop/src/panels/ContentBrowser.tsx b/desktop/src/panels/ContentBrowser.tsx
index f4514cb4e..555fdffd2 100644
--- a/desktop/src/panels/ContentBrowser.tsx
+++ b/desktop/src/panels/ContentBrowser.tsx
@@ -1015,6 +1015,18 @@ export function ContentBrowser() {
...(isMaterial
? [{ label: t('cb.menuCreateMaterialInstance'), onClick: () => void createMaterialInstance(path) }]
: []),
+ // A folder's delivery mode (local / subpackage / remote-CDN) — writes
+ // .esengine/asset-groups.json; the cook + Play realm read it via one resolver.
+ ...(entry.isDir
+ ? [{
+ label: t('cb.delivery'),
+ children: (['local', 'subpackage', 'remote'] as const).map((m) => ({
+ label: m === 'local' ? t('cb.deliveryLocal') : m === 'subpackage' ? t('cb.deliverySubpackage') : t('cb.deliveryRemote'),
+ checked: ProjectStore.folderDeliveryMode(path) === m,
+ onClick: () => void ProjectStore.setFolderDeliveryMode(path, m),
+ })),
+ }]
+ : []),
{ label: t('ui.rename'), onClick: () => startRename(path, !!ctx?.target?.inTree) },
{ label: t('cb.menuDuplicate'), onClick: () => void duplicate(path) },
{ sep: true },
@@ -1198,6 +1210,7 @@ export function ContentBrowser() {
const path = it.path;
const type: AssetType = it.isDir ? 'folder' : assetType(it.name);
const isImg = !it.isDir && IMAGE_RE.test(it.name);
+ const deliv = it.isDir ? ProjectStore.folderDeliveryMode(path) : 'local';
return (
<div
key={path}
@@ -1215,6 +1228,15 @@ export function ContentBrowser() {
<AssetIcon type={type} size={30} />
)}
{!it.isDir && TYPE_CODE[type] && <span className="badge">{TYPE_CODE[type]}</span>}
+ {deliv !== 'local' && (
+ <span
+ className="badge"
+ style={{ background: deliv === 'remote' ? '#2f6df6' : '#8a5cf6', color: '#fff' }}
+ title={deliv === 'remote' ? t('cb.deliveryRemote') : t('cb.deliverySubpackage')}
+ >
+ {deliv === 'remote' ? t('cb.badgeRemote') : t('cb.badgeSubpackage')}
+ </span>
+ )}
{path === project?.defaultScene && (
<span className="badge start" title={t('cb.startupScene')}>
<Play size={9} strokeWidth={2.5} />
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index 8eb67ba51..f17371c00 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -1,9 +1,9 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { createStore } from 'zustand/vanilla';
-import { getComponent, getEditorType, Assets, migratePrefabData, extractPrefab, flattenPrefab, collectExternalEntityRefs, collapseInstance, applyDeltaToSource, buildVariant, validateOverrides, setTextureParams, TextureFilter, TextureWrap, Renderer, RETIRED_COMPONENT_TYPES, parseThemeOverrides, resolveAssetGroup } from 'esengine';
+import { getComponent, getEditorType, Assets, migratePrefabData, extractPrefab, flattenPrefab, collectExternalEntityRefs, collapseInstance, applyDeltaToSource, buildVariant, validateOverrides, setTextureParams, TextureFilter, TextureWrap, Renderer, RETIRED_COMPONENT_TYPES, parseThemeOverrides, resolveAssetGroup, folderGroupMode, withFolderGroup, withActiveRemoteRoot } from 'esengine';
import { readTextureImportSettings } from './assetImporter';
-import type { SceneData, PrefabData, ExtractEntity, ProcessedEntity, PhysicsPluginConfig, AudioProjectConfig, AssetsData, ThemeOverrides, StaleOverride, PrefabOverride, AddressableManifest, AssetGroupsConfig } from 'esengine';
+import type { SceneData, PrefabData, ExtractEntity, ProcessedEntity, PhysicsPluginConfig, AudioProjectConfig, AssetsData, ThemeOverrides, StaleOverride, PrefabOverride, AddressableManifest, AssetGroupsConfig, AssetGroupMode } from 'esengine';
import { EngineHost } from '@/engine/EngineHost';
import { applyWidgetTheme } from '@/engine/widgetTheme';
import { bootProfiler } from '@/engine/bootProfiler';
@@ -1725,6 +1725,47 @@ class ProjectStoreImpl {
}
}
+ // ── Asset delivery groups (.esengine/asset-groups.json) ──────────────────────
+
+ /** The delivery mode configured for `folder` — `local` when unconfigured. The
+ * Content Browser menu-check / folder-badge source. */
+ folderDeliveryMode(folder: string): AssetGroupMode {
+ return folderGroupMode(this.assetGroupsConfig, folder);
+ }
+
+ /** The active build profile's CDN root ('' when unset) — the Build dialog field. */
+ activeProfileRemoteRoot(): string {
+ const cfg = this.assetGroupsConfig;
+ const active = cfg?.activeProfile;
+ return (active ? cfg?.profiles?.[active]?.remoteRoot : '') ?? '';
+ }
+
+ /** Mark a folder as a delivery group (`subpackage` / `remote`) or clear it back
+ * to `local`, writing `.esengine/asset-groups.json`. Cook and the Play realm
+ * both read this through the shared resolveAssetGroup, so it takes effect on
+ * the next cook / Play. */
+ async setFolderDeliveryMode(folder: string, mode: AssetGroupMode): Promise<void> {
+ await this.writeAssetGroups(withFolderGroup(this.assetGroupsConfig, folder, mode));
+ }
+
+ /** Set the active build profile's CDN root (empty → remote groups load same-origin). */
+ async setActiveProfileRemoteRoot(remoteRoot: string): Promise<void> {
+ await this.writeAssetGroups(withActiveRemoteRoot(this.assetGroupsConfig, remoteRoot));
+ }
+
+ private async writeAssetGroups(cfg: AssetGroupsConfig): Promise<void> {
+ this.assetGroupsConfig = cfg;
+ // Re-emit so the Content Browser badge / menu check reflect the change live.
+ const st = this.state;
+ if (st) this.store.setState({ project: { ...st } });
+ try {
+ await window.estella.fs.write(`${WORKSPACE_DIR}/asset-groups.json`, JSON.stringify(cfg, null, 2) + '\n');
+ } catch (e) {
+ Toasts.push(t('proj.saveAssetGroupsFailed'), 'error');
+ console.error('[project] asset-groups write failed', e);
+ }
+ }
+
/** The project's effective screen orientation — the explicit packaging setting, else
* derived from the design resolution's aspect. Drives the export targets and the
* editor's device preview; the segmented control reflects this resolved value. */
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 687fab122..537f97428 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1313 stable · 17 beta · 0 deprecated
+Symbols: 1316 stable · 17 beta · 0 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -8595,6 +8595,11 @@ DragPlugin
FocusPlugin
```
+## folderGroupMode — function
+```
+(config: AssetGroupsConfig | null | undefined, folder: string): AssetGroupMode
+```
+
## fsmEdges — function
```
(def: FsmDefinition): FsmEdge[]
@@ -10090,6 +10095,16 @@ VideoPlugin
(build: (world: World) => Entity, name: string): PrefabData
```
+## withActiveRemoteRoot — function
+```
+(config: AssetGroupsConfig | null | undefined, remoteRoot: string): AssetGroupsConfig
+```
+
+## withFolderGroup — function
+```
+(config: AssetGroupsConfig | null | undefined, folder: string, mode: AssetGroupMode): AssetGroupsConfig
+```
+
## wrapSceneSystem — function
```
(app: App, sceneName: string, system: SystemDef): SystemDef
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index ea1513bf0..22d0afd9d 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1312 stable · 19 beta · 0 deprecated
+Symbols: 1315 stable · 19 beta · 0 deprecated
## ANCHOR_AXES — const
```
@@ -8590,6 +8590,11 @@ DragPlugin
FocusPlugin
```
+## folderGroupMode — function
+```
+(config: AssetGroupsConfig | null | undefined, folder: string): AssetGroupMode
+```
+
## fsmEdges — function
```
(def: FsmDefinition): FsmEdge[]
@@ -10095,6 +10100,16 @@ VideoPlugin
(build: (world: World) => Entity, name: string): PrefabData
```
+## withActiveRemoteRoot — function
+```
+(config: AssetGroupsConfig | null | undefined, remoteRoot: string): AssetGroupsConfig
+```
+
+## withFolderGroup — function
+```
+(config: AssetGroupsConfig | null | undefined, folder: string, mode: AssetGroupMode): AssetGroupsConfig
+```
+
## wrapSceneSystem — function
```
(app: App, sceneName: string, system: SystemDef): SystemDef
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 3e6d2ceb1..3cf74883f 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1323 stable · 17 beta · 0 deprecated
+Symbols: 1326 stable · 17 beta · 0 deprecated
## ANCHOR_AXES — const
```
@@ -8614,6 +8614,11 @@ DragPlugin
FocusPlugin
```
+## folderGroupMode — function
+```
+(config: AssetGroupsConfig | null | undefined, folder: string): AssetGroupMode
+```
+
## fsmEdges — function
```
(def: FsmDefinition): FsmEdge[]
@@ -10114,6 +10119,16 @@ VideoPlugin
(build: (world: World) => Entity, name: string): PrefabData
```
+## withActiveRemoteRoot — function
+```
+(config: AssetGroupsConfig | null | undefined, remoteRoot: string): AssetGroupsConfig
+```
+
+## withFolderGroup — function
+```
+(config: AssetGroupsConfig | null | undefined, folder: string, mode: AssetGroupMode): AssetGroupsConfig
+```
+
## wrapSceneSystem — function
```
(app: App, sceneName: string, system: SystemDef): SystemDef
diff --git a/sdk/src/asset/assetGroups.ts b/sdk/src/asset/assetGroups.ts
index 2f83e5685..49a2963c1 100644
--- a/sdk/src/asset/assetGroups.ts
+++ b/sdk/src/asset/assetGroups.ts
@@ -104,3 +104,54 @@ export function activeRemoteRoot(config: AssetGroupsConfig | null | undefined):
const root = config?.profiles?.[active]?.remoteRoot;
return root && root.trim() !== '' ? root.replace(/\/+$/, '') : undefined;
}
+
+const normFolder = (folder: string): string => folder.replace(/\\/g, '/').replace(/\/+$/, '');
+
+/** The delivery mode a config assigns to `folder` directly — `local` when the
+ * folder has no group of its own (parent-folder groups don't count here; this is
+ * the per-folder authoring state, for a menu check / badge). */
+export function folderGroupMode(config: AssetGroupsConfig | null | undefined, folder: string): AssetGroupMode {
+ const norm = normFolder(folder);
+ for (const def of Object.values(config?.groups ?? {})) {
+ if (normFolder(def.folder) === norm) return def.mode;
+ }
+ return 'local';
+}
+
+/**
+ * A copy of `config` with `folder` assigned delivery `mode` — the pure authoring
+ * mutation the editor writes to `.esengine/asset-groups.json`. `local` removes any
+ * group for the folder; otherwise the group name is the folder's last path segment
+ * (deduped against existing names).
+ */
+export function withFolderGroup(
+ config: AssetGroupsConfig | null | undefined,
+ folder: string,
+ mode: AssetGroupMode,
+): AssetGroupsConfig {
+ const norm = normFolder(folder);
+ const groups: Record<string, AssetGroupDef> = { ...(config?.groups ?? {}) };
+ for (const [name, def] of Object.entries(groups)) {
+ if (normFolder(def.folder) === norm) delete groups[name];
+ }
+ if (norm !== '' && mode !== 'local') {
+ const base = norm.split('/').pop() || 'group';
+ let name = base;
+ let i = 2;
+ while (groups[name]) name = `${base}${i++}`;
+ groups[name] = { folder: norm, mode };
+ }
+ return { version: '1.0', ...config, groups };
+}
+
+/** A copy of `config` with the active build profile's CDN root set (creating the
+ * profile — default `dev` — and making it active). Pure. */
+export function withActiveRemoteRoot(
+ config: AssetGroupsConfig | null | undefined,
+ remoteRoot: string,
+): AssetGroupsConfig {
+ const active = config?.activeProfile ?? 'dev';
+ const profiles: Record<string, BuildProfile> = { ...(config?.profiles ?? {}) };
+ profiles[active] = { ...profiles[active], remoteRoot };
+ return { version: '1.0', ...config, activeProfile: active, profiles };
+}
diff --git a/sdk/src/asset/index.ts b/sdk/src/asset/index.ts
index dc4a30dda..4936246a1 100644
--- a/sdk/src/asset/index.ts
+++ b/sdk/src/asset/index.ts
@@ -16,6 +16,9 @@ export {
resolveAssetGroup,
activeRemoteRoot,
modeToDelivery,
+ folderGroupMode,
+ withFolderGroup,
+ withActiveRemoteRoot,
type AssetGroupMode,
type AssetGroupDef,
type BuildProfile,
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 946de2358..50c0fc042 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -70,6 +70,9 @@ export {
resolveAssetGroup,
activeRemoteRoot,
modeToDelivery,
+ folderGroupMode,
+ withFolderGroup,
+ withActiveRemoteRoot,
type AssetGroupMode,
type AssetGroupDef,
type BuildProfile,
diff --git a/sdk/tests/asset-groups.test.ts b/sdk/tests/asset-groups.test.ts
index a54f74f38..023e3990d 100644
--- a/sdk/tests/asset-groups.test.ts
+++ b/sdk/tests/asset-groups.test.ts
@@ -5,6 +5,9 @@ import {
resolveAssetGroup,
activeRemoteRoot,
modeToDelivery,
+ folderGroupMode,
+ withFolderGroup,
+ withActiveRemoteRoot,
type AssetGroupsConfig,
} from '../src/asset/assetGroups';
@@ -63,6 +66,63 @@ describe('resolveAssetGroup — legacy folder-name convention (fallback / back-c
});
});
+describe('withFolderGroup / folderGroupMode — the editor authoring mutation', () => {
+ it('adds a remote group for an ordinarily-named folder', () => {
+ const cfg = withFolderGroup(null, 'assets/cdn', 'remote');
+ expect(cfg.groups).toEqual({ cdn: { folder: 'assets/cdn', mode: 'remote' } });
+ expect(folderGroupMode(cfg, 'assets/cdn')).toBe('remote');
+ });
+
+ it('local removes the folder\'s group', () => {
+ const withGroup = withFolderGroup(null, 'assets/cdn', 'subpackage');
+ const cleared = withFolderGroup(withGroup, 'assets/cdn', 'local');
+ expect(cleared.groups).toEqual({});
+ expect(folderGroupMode(cleared, 'assets/cdn')).toBe('local');
+ });
+
+ it('re-marking a folder replaces its mode, not duplicates it', () => {
+ let cfg = withFolderGroup(null, 'assets/cdn', 'remote');
+ cfg = withFolderGroup(cfg, 'assets/cdn', 'subpackage');
+ expect(Object.keys(cfg.groups ?? {})).toHaveLength(1);
+ expect(folderGroupMode(cfg, 'assets/cdn')).toBe('subpackage');
+ });
+
+ it('dedupes the group name when two folders share a last segment', () => {
+ let cfg = withFolderGroup(null, 'assets/a/cdn', 'remote');
+ cfg = withFolderGroup(cfg, 'assets/b/cdn', 'remote');
+ expect(Object.keys(cfg.groups ?? {}).sort()).toEqual(['cdn', 'cdn2']);
+ expect(folderGroupMode(cfg, 'assets/b/cdn')).toBe('remote');
+ });
+
+ it('folderGroupMode is per-folder (a parent group does not count for a child)', () => {
+ const cfg = withFolderGroup(null, 'assets/dlc', 'remote');
+ expect(folderGroupMode(cfg, 'assets/dlc')).toBe('remote');
+ expect(folderGroupMode(cfg, 'assets/dlc/hd')).toBe('local'); // not directly configured
+ });
+
+ it('preserves profiles when editing groups', () => {
+ const base: AssetGroupsConfig = { version: '1.0', activeProfile: 'dev', profiles: { dev: { remoteRoot: 'u' } } };
+ const cfg = withFolderGroup(base, 'assets/cdn', 'remote');
+ expect(cfg.profiles).toEqual({ dev: { remoteRoot: 'u' } });
+ expect(cfg.activeProfile).toBe('dev');
+ });
+});
+
+describe('withActiveRemoteRoot', () => {
+ it('sets the active profile CDN root, creating a dev profile by default', () => {
+ const cfg = withActiveRemoteRoot(null, 'https://cdn.x');
+ expect(cfg.activeProfile).toBe('dev');
+ expect(activeRemoteRoot(cfg)).toBe('https://cdn.x');
+ });
+
+ it('updates the existing active profile and preserves groups', () => {
+ const base = withFolderGroup(null, 'assets/cdn', 'remote');
+ const cfg = withActiveRemoteRoot({ ...base, activeProfile: 'prod', profiles: { prod: {} } }, 'https://p');
+ expect(activeRemoteRoot(cfg)).toBe('https://p');
+ expect(cfg.groups).toEqual({ cdn: { folder: 'assets/cdn', mode: 'remote' } });
+ });
+});
+
describe('activeRemoteRoot', () => {
const config: AssetGroupsConfig = {
version: '1.0',