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(editor): GUI to author asset-delivery groups + CDN profile
yhhb8c1eb90b619
diff --git a/desktop/src/components/BuildDialog.tsx b/desktop/src/components/BuildDialog.tsxindex 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.tsindex 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.tsindex 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.tsxindex 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 (<divkey={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.tsindex 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 Teamimport { 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.mdindex 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 @@ DragPluginFocusPlugin```+## 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): SystemDefdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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 @@ DragPluginFocusPlugin```+## 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): SystemDefdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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 @@ DragPluginFocusPlugin```+## 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): SystemDefdiff --git a/sdk/src/asset/assetGroups.ts b/sdk/src/asset/assetGroups.tsindex 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.tsindex 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.tsindex 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.tsindex 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',