[break] refactor(scene): lib service interface — per-service access, drop browser globals

packages/cocos-cli-types/__tests__/dts-snapshot.test.ts

@@ -8,11 +8,11 @@ const dtsFiles = [
     'assets.d.ts',
     'base.d.ts',
     'builder.d.ts',
-    'cli.d.ts',
     'configuration.d.ts',
     'engine.d.ts',
     'project.d.ts',
     'scripting.d.ts',
+    'service.d.ts',
 ];
 
 function stripComments(content: string): string {

src/core/preview/game-preview.middleware.ts

@@ -167,12 +167,15 @@ export default {
             async handler(req: Request, res: Response, next: NextFunction) {
                 try {
                     const { default: scripting } = await import('../../core/scripting');
-                    const serverBaseUrl = `${req.protocol}://${req.get('host')}`;
+                    const host = req.get('host') || '';
+                    const colon = host.lastIndexOf(':');
                     const scene = typeof req.query.scene === 'string' ? req.query.scene : '';
                     const sceneQuery = scene ? `?scene=${encodeURIComponent(scene)}` : '';
                     const renderData = {
                         title: `Cocos Creator - ${basename(scripting.projectPath)}`,
-                        serverURL: serverBaseUrl,
+                        ip: colon >= 0 ? host.slice(0, colon) : host,
+                        port: colon >= 0 ? host.slice(colon + 1) : '',
+                        https: req.protocol === 'https',
                         settingsJs: `/preview/settings.js${sceneQuery}`,
                         sceneQuery,
                     };

src/core/scene/scene-process/engine-bootstrap.ts

@@ -2,7 +2,6 @@ import * as EditorExtends from '../../engine/editor-extends';
 import { Rpc } from './rpc';
 import { serviceManager } from './service/service-manager';
 import { Service as DecoratorService } from './service/core/decorator';
-import { messageManager } from './service/message';
 import { initLocalI18n } from './i18n';
 
 import './service';
@@ -24,13 +23,13 @@ declare const cc: any;
 export async function startup(options: {
     serverURL: string;
 }) {
-    const defaultConfig = await fetch('/scripting/engine/game-config');
+    const { serverURL } = options;
+    const defaultConfig = await fetch(`${serverURL}/scripting/engine/game-config`);
     const config = await defaultConfig.json();
-    const modules = await fetch('/scripting/engine/modules');
+    const modules = await fetch(`${serverURL}/scripting/engine/modules`);
     const features = (await modules.json()) as string[];
-    const { serverURL } = options;
 
-    serviceManager.initialize(serverURL);
+    serviceManager.init(serverURL);
 
     const requiredModules = [
         'cc',
@@ -84,9 +83,6 @@ export async function startup(options: {
 
     (globalThis as any).cce = (globalThis as any).cce || {};
     (globalThis as any).cce.Script = DecoratorService.Script;
-    (globalThis as any).cli = {};
-    (globalThis as any).cli.Scene = DecoratorService;
-    (globalThis as any).cli.SceneEvents = messageManager;
 
     if (EditorExtends.init) {
         await EditorExtends.init();
@@ -153,7 +149,7 @@ export async function startup(options: {
     // are available before preview services initialize.
     await (async () => {
         try {
-            const res = await fetch('/query-asset-infos/cc.EffectAsset');
+            const res = await fetch(`${serverURL}/query-asset-infos/cc.EffectAsset`);
             if (!res.ok) return;
             const effectInfos: any[] = await res.json();
             if (!effectInfos.length) return;
@@ -168,7 +164,7 @@ export async function startup(options: {
                     const encodedUuid = encodeURIComponent(uuid);
                     const ext = (lib['.bin'] && !lib['.json']) ? 'bin' : 'json';
 
-                    const r = await fetch(`/import/${encodedUuid}.${ext}?isBrowser=true`);
+                    const r = await fetch(`${serverURL}/import/${encodedUuid}.${ext}?isBrowser=true`);
                     if (!r.ok) return;
 
                     const isBinary = ext === 'bin';
@@ -275,7 +271,7 @@ export async function startup(options: {
         // reports width 0, and every SpriteFrame on it fails checkRect and gets
         // its rect reset (e.g. sprite frames from a plist atlas in a prefab).
         try {
-            const res = await fetch(`/query-asset-info/${encodeURIComponent(uuid)}`);
+            const res = await fetch(`${serverURL}/query-asset-info/${encodeURIComponent(uuid)}`);
             if (!res.ok) return '';
             const info: any = await res.json();
             const lib = info?.library;
@@ -306,8 +302,8 @@ export async function startup(options: {
         const encodedUuid = encodeURIComponent(uuid);
         const isSubAsset = nativeExt.length > 0 && nativeExt[0] !== '.';
         const nativeUrl = isSubAsset
-            ? `/native/${encodedUuid}/${nativeExt}?isBrowser=true`
-            : `/native/${encodedUuid}${nativeExt}?isBrowser=true`;
+            ? `${serverURL}/native/${encodedUuid}/${nativeExt}?isBrowser=true`
+            : `${serverURL}/native/${encodedUuid}${nativeExt}?isBrowser=true`;
 
         try {
             const res = await fetch(nativeUrl);
@@ -340,12 +336,12 @@ export async function startup(options: {
             // binary (.bin/cconb) instead of .json.
             let ext = 'json';
             try {
-                const extRes = await fetch(`/query-extname/${encodedUuid}`);
+                const extRes = await fetch(`${serverURL}/query-extname/${encodedUuid}`);
                 const queryExt = (await extRes.text()).trim();
                 if (queryExt === '.cconb') ext = 'bin';
             } catch { /* default to json */ }
 
-            const res = await fetch(`/import/${encodedUuid}.${ext}?isBrowser=true`);
+            const res = await fetch(`${serverURL}/import/${encodedUuid}.${ext}?isBrowser=true`);
             if (!res.ok) throw new Error(`Asset fetch failed (${res.status}): ${uuid}`);
 
             const isBinary = ext === 'bin';

src/core/scene/scene-process/main.ts

@@ -30,7 +30,7 @@ async function startup() {
     }
 
     // 初始化 service-manager
-    serviceManager.initialize(serverURL ?? '');
+    serviceManager.init(serverURL ?? '');
 
     await Engine.init(enginePath);
     // 这里 importBase 与 nativeBase 用服务器是为了让服务器转换资源真实存放的路径

src/core/scene/scene-process/service/engine.ts

@@ -8,6 +8,7 @@ import { Service } from './core/decorator';
 import type { ICustomLayerConfig, IEngineEvents, IEngineService } from '../../common';
 import { NodeEventType } from '../../common';
 import { Rpc } from '../rpc';
+import { serviceManager } from './service-manager';
 import { TimerUtil } from './utils/timer-util';
 
 const tickTime = 1000 / 60;
@@ -93,7 +94,7 @@ export class EngineService extends BaseService<IEngineEvents> implements IEngine
      * 渲染调试视图（DebugView）：单一通道调试 / 组合光照项开关 / 纯光照带固有色 / 级联阴影染色。
      * 与 cocos-editor scene-facade-manager.changeDebugOption 对齐。
      * 注意：不对外暴露为公共 API（未加入 IEngineService / EngineProxy，不生成到 cocos-cli-types）；
-     * 目前仅由场景编辑器页面（scene-editor.ejs）在浏览器内通过 window.cli.Scene.Engine 直接调用。
+     * 目前仅由场景编辑器页面（scene-editor.ejs）在浏览器内通过 serviceManager.getServices().Engine 直接调用。
      * @param key 'single' | 'composite' | 'LIGHTING_WITH_BASE_COLOR' | 'CSM_LAYER_COLORATION'
      * @param value single: DebugViewSingleType 数值；composite: { key: DebugViewCompositeType | 10000(=ALL), value: boolean }；其余: boolean
      */
@@ -149,7 +150,8 @@ export class EngineService extends BaseService<IEngineEvents> implements IEngine
             if (!view || typeof fetch !== 'function') {
                 return;
             }
-            const res = await fetch('/scripting/engine/design-resolution');
+            const serverURL = serviceManager.getServerUrl();
+            const res = await fetch(`${serverURL}/scripting/engine/design-resolution`);
             const dr = await res.json();
             const width = Number(dr?.width);
             const height = Number(dr?.height);

src/core/scene/scene-process/service/service-manager.ts

@@ -1,7 +1,9 @@
-import { getServiceAll, IServiceEvents, ServiceEvents } from './core';
+import { getServiceAll, IServiceEvents, ServiceEvents, Service } from './core';
 import { InternalServiceEvents } from './core/internal-events';
 import { IEditorEvents, INodeEvents, IComponentEvents, IScriptEvents, IAssetEvents, ISelectionEvents } from '../../common';
 import { messageManager } from './message';
+import type { IServiceManager } from './interfaces';
+import type { GlobalEventManager } from './core/global-events';
 
 type AllEvents = IEditorEvents & INodeEvents & IComponentEvents & IScriptEvents & IAssetEvents & ISelectionEvents;
 
@@ -99,10 +101,32 @@ export class ServiceManager {
         this.registerAutoForwardEvents();
     }
 
+    /** Alias of {@link initialize}; the public entry used by callers/boot. */
+    init(serverUrl: string) {
+        this.initialize(serverUrl);
+    }
+
     getServerUrl() {
         return this.serverUrl;
     }
 
+    /**
+     * The typed service map (Engine / Editor / Camera / Preview / ...).
+     * Both cli's own browser pages and external IDEs go through this instead of
+     * the former `window.cli.Scene` global.
+     */
+    getServices(): IServiceManager {
+        return Service;
+    }
+
+    /**
+     * The global service event bus where service events (e.g. `editor:open`)
+     * are actually emitted (see base-service emit -> ServiceEvents).
+     */
+    getServiceEvents(): GlobalEventManager {
+        return ServiceEvents;
+    }
+
     /**
      * Camera/Gizmo 依赖的编辑器内置 effect UUID
      */

src/core/scene/scene.scripting.middleware.ts

@@ -18,10 +18,13 @@ export default {
                         return res.redirect(302, '/scene-editor/');
                     }
                     const { default: scripting } = await import('../../core/scripting');
-                    const serverBaseUrl = `${req.protocol}://${req.get('host')}`;
+                    const host = req.get('host') || '';
+                    const colon = host.lastIndexOf(':');
                     const renderData = {
                         title: `Cocos Creator Preview - ${basename(scripting.projectPath)}`,
-                        serverURL: serverBaseUrl
+                        ip: colon >= 0 ? host.slice(0, colon) : host,
+                        port: colon >= 0 ? host.slice(colon + 1) : '',
+                        https: req.protocol === 'https',
                     };
                     const templatePath = join(GlobalPaths.workspace, 'static', 'web', 'scene-editor.ejs');
                     const html = await ejs.renderFile(templatePath, renderData);
@@ -36,10 +39,13 @@ export default {
             async handler(req: Request, res: Response, next: NextFunction) {
                 try {
                     const { default: scripting } = await import('../../core/scripting');
-                    const serverBaseUrl = `${req.protocol}://${req.get('host')}`;
+                    const host = req.get('host') || '';
+                    const colon = host.lastIndexOf(':');
                     const renderData = {
                         title: `Resource Preview - ${basename(scripting.projectPath)}`,
-                        serverURL: serverBaseUrl
+                        ip: colon >= 0 ? host.slice(0, colon) : host,
+                        port: colon >= 0 ? host.slice(colon + 1) : '',
+                        https: req.protocol === 'https',
                     };
                     const templatePath = join(GlobalPaths.workspace, 'static', 'web', 'preview.ejs');
                     const html = await ejs.renderFile(templatePath, renderData);

src/lib/index.ts

@@ -8,3 +8,4 @@ export * as Server from './server/server';
 export * as Scene from './scene/scene';
 export * as Scripting from './scripting/scripting';
 export * as i18n from '../i18n';
+

src/lib/server/server.ts

@@ -11,16 +11,19 @@ let isRunning = false;
 /**
  * Initialize and start the Express HTTP server.
  *
- * @param port Optional port number; auto-selected if omitted
- * @returns The server base URL (e.g. http://localhost:9527)
+ * @param options Optional `{ ip, port }`. `port` is auto-selected if omitted (and
+ *                retried on conflict); `ip` sets the bind/base-URL host (defaults
+ *                to localhost). More parameters can be added here later.
+ * @returns The server base URL (e.g. http://localhost:9527), reflecting the
+ *          actual bound port and the configured ip.
  */
-export async function start(port?: number): Promise<string> {
+export async function start(options?: { ip?: string; port?: number }): Promise<string> {
     if (isRunning && serverUrl) {
         return serverUrl;
     }
 
     const { serverService } = await import('../../server/server');
-    await serverService.start(port);
+    await serverService.start(options?.port, options?.ip);
 
     serverUrl = serverService.url;
     isRunning = true;

src/lib/service/asset.ts

@@ -0,0 +1,13 @@
+/**
+ * Asset service entry.
+ *
+ * Importing this module runs the service's `@register('Asset')` decorator and
+ * exposes the ready instance. Import only the services you actually use:
+ *
+ *   import { Asset } from '<cli>/lib/service/asset';
+ *   await Asset.xxx(...);
+ */
+import { Service } from '../../core/scene/scene-process/service/core/decorator';
+import '../../core/scene/scene-process/service/asset';
+
+export const Asset = Service.Asset;