@nebulaaa/launcher 0.0.0-stage → 1.0.0

package/dist/launcher.cjs

@@ -0,0 +1,194 @@
+'use strict';
+
+var cc = require('cc');
+var dict = require('@nebulaaa/dict');
+var env = require('@nebulaaa/env');
+var eventBus = require('@nebulaaa/event-bus');
+var ms = require('@nebulaaa/ms');
+var plugin = require('@nebulaaa/plugin');
+var web = require('@nebulaaa/web');
+
+/**
+ * 应用构建版本
+ */
+exports.Build = void 0;
+(function (Build) {
+    /** 内部开发版 */
+    Build["Dev"] = "dev";
+    /** 内部测试版 */
+    Build["Alpha"] = "alpha";
+    /** 公开测试版 */
+    Build["Beta"] = "beta";
+    /** 候选发布版 */
+    Build["Candidate"] = "candidate";
+    /** 正式发布版 */
+    Build["Release"] = "release";
+})(exports.Build || (exports.Build = {}));
+
+/** 宏定义 */
+const LAUNCHER_EVENT = {
+    /** 应用进入后台 */
+    ENTER_BACKGROUND: 'app@enter-background',
+    /** 应用进入前台 */
+    ENTER_FOREGROUND: 'app@enter-foreground',
+    /** 应用退出 */
+    QUIT: 'app@quit',
+    /** 应用低内存告警 */
+    LOW_MEMORY: 'app@low-memory',
+    /** 场景启动 */
+    STAGE_READY: 'app@stage-ready',
+};
+/** 允许经 URL 覆写的配置键白名单（可经 config.UrlKeys 追加） */
+const LAUNCHER_URL_OVERRIDABLE_KEYS = ['Workspace'];
+/** 保留键（扩展白名单也拒绝注入，防止 URL 伪装构建版本等核心语义） */
+const LAUNCHER_RESERVED_KEYS = ['App', 'Version', 'Build', 'Language'];
+
+/**
+ * 启动器
+ */
+class Launcher extends plugin.Plugin {
+    constructor(deps, cfg) {
+        var _a;
+        dict.Override(cfg !== null && cfg !== void 0 ? cfg : {}, {
+            app: 'nebulaaa',
+            version: '1.0.0',
+            build: exports.Build.Dev,
+            language: [cc.sys.Language.CHINESE, cc.sys.Language.ENGLISH],
+            env: 'default',
+        });
+        if ((env.MISC.BROWSER && cfg.Build === exports.Build.Dev) || cfg.Build === exports.Build.Alpha) {
+            const qs = web.GetQueryString();
+            const whitelist = [...LAUNCHER_URL_OVERRIDABLE_KEYS, ...((_a = cfg.AllowedUrlKeys) !== null && _a !== void 0 ? _a : [])];
+            dict.Each(qs, (key, value) => {
+                if (LAUNCHER_RESERVED_KEYS.includes(key))
+                    return; // 保留键拒绝注入
+                if (!whitelist.includes(key))
+                    return; // 白名单外的键拒绝注入
+                try {
+                    cfg[key] = decodeURIComponent(value);
+                }
+                catch (_a) {
+                    cfg[key] = value;
+                }
+            });
+        }
+        super(deps, cfg);
+        this.App = this.Cfg.App;
+        this.Version = this.Cfg.Version;
+        this.Build = this.Cfg.Build;
+        this.IsDev = this.Cfg.Build === exports.Build.Dev;
+        this.IsAlpha = this.Cfg.Build === exports.Build.Alpha;
+        this.IsBeta = this.Cfg.Build === exports.Build.Beta;
+        this.IsCandidate = this.Cfg.Build === exports.Build.Candidate;
+        this.IsRelease = this.Cfg.Build === exports.Build.Release;
+        this.Workspace = this.Cfg.Workspace;
+        this.SupportedLanguages = this.Cfg.Language;
+        this._runningLogic = true;
+        this._runningInternal = true;
+        this._timingPause = 0;
+        this._elapsed = 0;
+        cc.director.once(cc.Director.EVENT_BEFORE_SCENE_LAUNCH, this.onSceneLaunch, this);
+        cc.game.on(cc.Game.EVENT_SHOW, this.internalResume, this);
+        cc.game.on(cc.Game.EVENT_HIDE, this.internalPause, this);
+        cc.game.on(cc.Game.EVENT_CLOSE, this.internalClose, this);
+        cc.game.on(cc.Game.EVENT_LOW_MEMORY, this.internalLowMemory, this);
+        this.Logger.Info(`🔥 ${this.App} ${this.Version}_${this.Build}`);
+    }
+    /** 应用退到后台 */
+    internalPause() {
+        this._runningInternal = false;
+        this._timingPause = ms.Now();
+        this.Deps.EventBus.Sys.Notify(eventBus.EventMessage.Void(LAUNCHER_EVENT.ENTER_BACKGROUND));
+    }
+    /** 应用回到前台 */
+    internalResume() {
+        this._runningInternal = true;
+        if (this._timingPause > 0) {
+            this._elapsed = ms.Now() - this._timingPause; // 仅完整的 hide→show 往返计入，首启 SHOW 不产生垃圾值
+            this._timingPause = 0;
+        }
+        this.Deps.EventBus.Sys.Notify(eventBus.EventMessage.Void(LAUNCHER_EVENT.ENTER_FOREGROUND));
+    }
+    /** 应用退出 */
+    internalClose() {
+        this.Deps.EventBus.Sys.Notify(eventBus.EventMessage.Void(LAUNCHER_EVENT.QUIT));
+        cc.game.targetOff(this);
+        cc.director.targetOff(this);
+    }
+    /** 内存报警 */
+    internalLowMemory() {
+        // 巡检的节流周期由引擎帧驱动，低内存时须跳过等待立即清扫（此前误传秒值使清扫形同虚设）
+        this.Deps.EventBus.Sys.Notify(eventBus.EventMessage.Void(LAUNCHER_EVENT.LOW_MEMORY));
+    }
+    /** 场景启动 */
+    onSceneLaunch(scene) {
+        var _a, _b;
+        const ctx = this;
+        // Scene
+        ctx.Scene = scene;
+        // Mnt
+        ctx.Mnt = scene.getChildByName('mnt');
+        if (!ctx.Mnt) {
+            ctx.Mnt = new cc.Node('mnt');
+            ctx.Mnt.layer = 0;
+            ctx.Scene.insertChild(this.Mnt, 0);
+        }
+        // Root
+        ctx.Root = scene.getChildByName('Canvas');
+        if (!this.Root) {
+            // Canvas 是舞台的挂载前提，缺失时中止装配；仅记录日志，不向引擎事件派发抛出异常
+            this.Logger.Error(`启动错误：场景 ${scene.name} 缺少名为 Canvas 的根节点，舞台装配中止`);
+            return;
+        }
+        // Stage
+        ctx.Stage = ctx.Root.getChildByName('Stage');
+        if (!ctx.Stage) {
+            const node = new cc.Node('Stage');
+            node.layer = cc.Layers.BitMask.UI_2D;
+            const wid = node.addComponent(cc.Widget);
+            wid.left = wid.top = wid.right = wid.bottom = 0;
+            wid.isAlignLeft = wid.isAlignTop = wid.isAlignBottom = wid.isAlignRight = true;
+            wid.alignMode = cc.Widget.AlignMode.ON_WINDOW_RESIZE;
+            wid.updateAlignment();
+            ctx.Stage = node;
+            this.Root.insertChild(this.Stage, 1);
+        }
+        // Canvas
+        ctx.Canvas = ctx.Root.getComponent(cc.Canvas);
+        // CameraUi
+        ctx.CameraUi = (_b = (_a = ctx.Root.getChildByName('Camera')) === null || _a === void 0 ? void 0 : _a.getComponent(cc.Camera)) !== null && _b !== void 0 ? _b : null;
+        if (!this.CameraUi) {
+            this.Logger.Warn('启动警告：Canvas 缺少名为 Camera 的子节点，UI 相机不可用');
+        }
+        this.Deps.EventBus.Sys.Notify(eventBus.EventMessage.Void(LAUNCHER_EVENT.STAGE_READY));
+    }
+    /** 是否指定构建版本 */
+    IsBuildOf(build) {
+        return this.Build === build;
+    }
+    /** 是否支持语言 */
+    IsLanguageSupported(language) {
+        return this.Cfg.Language.includes(language);
+    }
+    /** 暂停逻辑 */
+    Pause() {
+        this._runningLogic = false;
+    }
+    /** 恢复逻辑 */
+    Resume() {
+        this._runningLogic = true;
+    }
+    /** 从后台回到前台经历的时间（ms，未经历完整后台往返时为 0） */
+    get Elapsed() {
+        return this._elapsed;
+    }
+    /** 运行状态 */
+    get Running() {
+        return this._runningInternal && this._runningLogic;
+    }
+}
+
+exports.LAUNCHER_EVENT = LAUNCHER_EVENT;
+exports.LAUNCHER_RESERVED_KEYS = LAUNCHER_RESERVED_KEYS;
+exports.LAUNCHER_URL_OVERRIDABLE_KEYS = LAUNCHER_URL_OVERRIDABLE_KEYS;
+exports.Launcher = Launcher;

package/dist/launcher.d.ts

@@ -0,0 +1,169 @@
+import { __private, Scene, Node, Canvas, Camera } from 'cc';
+import { IEventBus } from '@nebulaaa/event-bus';
+import { IPlugin, PluginDeps, PluginCfg, Plugin } from '@nebulaaa/plugin';
+
+/** 语言代码 */
+type Language = __private._pal_system_info_enum_type_language__Language;
+/**
+ * 应用构建版本
+ */
+declare enum Build {
+    /** 内部开发版 */
+    Dev = "dev",
+    /** 内部测试版 */
+    Alpha = "alpha",
+    /** 公开测试版 */
+    Beta = "beta",
+    /** 候选发布版 */
+    Candidate = "candidate",
+    /** 正式发布版 */
+    Release = "release"
+}
+/** 启动器插件依赖 */
+interface LauncherDeps extends PluginDeps {
+    EventBus: IEventBus;
+}
+/** 启动器插件配置 */
+interface LauncherCfg extends PluginCfg {
+    /** 应用名称 */
+    App: string;
+    /** 应用版本号 */
+    Version: string;
+    /** 构建版本 */
+    Build: Build;
+    /** 支持语言 */
+    Language: Language[];
+    /** 用户空间标识（仅开发时使用，用于区分独立数据的用户空间，默认 `default`） */
+    Workspace?: string;
+    /** 允许经 URL 覆写的配置键（在默认白名单基础上追加，保留键除外） */
+    AllowedUrlKeys?: string[];
+    [k: string]: unknown;
+}
+/**
+ * 启动器能力接口
+ *
+ * - 负责管理启动参数
+ *
+ * @tip 【单场景架构约束】
+ * scene/root/mnt/canvas/cameraUi/stage 仅在首个场景启动时装配一次，并随之发出 STAGE_READY 事件。
+ */
+interface ILauncher extends IPlugin<LauncherDeps, LauncherCfg> {
+    /** 应用名称 */
+    readonly App: string;
+    /** 应用版本号 */
+    readonly Version: string;
+    /** 构建版本 */
+    readonly Build: Build;
+    /** 是否开发版本 */
+    readonly IsDev: boolean;
+    /** 是否内测版本 */
+    readonly IsAlpha: boolean;
+    /** 是否公测版本 */
+    readonly IsBeta: boolean;
+    /** 是否候选版本 */
+    readonly IsCandidate: boolean;
+    /** 是否正式版本 */
+    readonly IsRelease: boolean;
+    /** 用户空间标识 */
+    readonly Workspace: string;
+    /** 获取当前支持的语言列表 */
+    readonly SupportedLanguages: Language[];
+    /** 是否指定构建版本 */
+    IsBuildOf(build: Build): boolean;
+    /** 是否支持语言 */
+    IsLanguageSupported(language: Language): boolean;
+    /** 场景 */
+    readonly Scene: Scene;
+    /** 根节点 */
+    readonly Root: Node;
+    /** 挂载节点 */
+    readonly Mnt: Node;
+    /** 画布 */
+    readonly Canvas: Canvas;
+    /** UI相机 */
+    readonly CameraUi: Camera;
+    /** 舞台 */
+    readonly Stage: Node;
+    /** 暂停逻辑 */
+    Pause(): void;
+    /** 恢复逻辑 */
+    Resume(): void;
+    /** 从后台回到前台经历的时间（ms，未经历完整后台往返时为 0） */
+    get Elapsed(): number;
+    /** 运行状态 */
+    get Running(): boolean;
+}
+
+/** 宏定义 */
+declare const LAUNCHER_EVENT: {
+    /** 应用进入后台 */
+    readonly ENTER_BACKGROUND: "app@enter-background";
+    /** 应用进入前台 */
+    readonly ENTER_FOREGROUND: "app@enter-foreground";
+    /** 应用退出 */
+    readonly QUIT: "app@quit";
+    /** 应用低内存告警 */
+    readonly LOW_MEMORY: "app@low-memory";
+    /** 场景启动 */
+    readonly STAGE_READY: "app@stage-ready";
+};
+/** 允许经 URL 覆写的配置键白名单（可经 config.UrlKeys 追加） */
+declare const LAUNCHER_URL_OVERRIDABLE_KEYS: string[];
+/** 保留键（扩展白名单也拒绝注入，防止 URL 伪装构建版本等核心语义） */
+declare const LAUNCHER_RESERVED_KEYS: string[];
+
+/**
+ * 启动器
+ */
+declare class Launcher extends Plugin<LauncherDeps, LauncherCfg> implements ILauncher {
+    readonly App: string;
+    readonly Version: string;
+    readonly Build: Build;
+    readonly IsDev: boolean;
+    readonly IsAlpha: boolean;
+    readonly IsBeta: boolean;
+    readonly IsCandidate: boolean;
+    readonly IsRelease: boolean;
+    readonly Workspace: string;
+    readonly SupportedLanguages: Language[];
+    readonly Scene: Scene;
+    readonly Root: Node;
+    readonly Mnt: Node;
+    readonly Canvas: Canvas;
+    readonly CameraUi: Camera;
+    readonly Stage: Node;
+    /** 逻辑运行状态 */
+    private _runningLogic;
+    /** 内部运行状态 */
+    private _runningInternal;
+    /** 内部暂停计时点（0 表示不在后台往返中） */
+    private _timingPause;
+    /** 最近一次后台滞留时长（未经历完整 hide→show 往返时为 0） */
+    private _elapsed;
+    constructor(deps: LauncherDeps, cfg: LauncherCfg);
+    /** 应用退到后台 */
+    private internalPause;
+    /** 应用回到前台 */
+    private internalResume;
+    /** 应用退出 */
+    private internalClose;
+    /** 内存报警 */
+    private internalLowMemory;
+    /** 场景启动 */
+    private onSceneLaunch;
+    /** 是否指定构建版本 */
+    IsBuildOf(build: Build): boolean;
+    /** 是否支持语言 */
+    IsLanguageSupported(language: Language): boolean;
+    /** 暂停逻辑 */
+    Pause(): void;
+    /** 恢复逻辑 */
+    Resume(): void;
+    /** 从后台回到前台经历的时间（ms，未经历完整后台往返时为 0） */
+    get Elapsed(): number;
+    /** 运行状态 */
+    get Running(): boolean;
+}
+
+export { Build, LAUNCHER_EVENT, LAUNCHER_RESERVED_KEYS, LAUNCHER_URL_OVERRIDABLE_KEYS, Launcher };
+export type { ILauncher, Language, LauncherCfg, LauncherDeps };

package/dist/launcher.min.cjs

@@ -0,0 +1 @@
+"use strict";var e,t=require("cc"),i=require("@nebulaaa/dict"),s=require("@nebulaaa/env"),n=require("@nebulaaa/event-bus"),a=require("@nebulaaa/ms"),r=require("@nebulaaa/plugin"),o=require("@nebulaaa/web");exports.Build=void 0,(e=exports.Build||(exports.Build={})).Dev="dev",e.Alpha="alpha",e.Beta="beta",e.Candidate="candidate",e.Release="release";const u={ENTER_BACKGROUND:"app@enter-background",ENTER_FOREGROUND:"app@enter-foreground",QUIT:"app@quit",LOW_MEMORY:"app@low-memory",STAGE_READY:"app@stage-ready"},l=["Workspace"],g=["App","Version","Build","Language"];class h extends r.Plugin{constructor(e,n){var a;if(i.Override(null!=n?n:{},{app:"nebulaaa",version:"1.0.0",build:exports.Build.Dev,language:[t.sys.Language.CHINESE,t.sys.Language.ENGLISH],env:"default"}),s.MISC.BROWSER&&n.Build===exports.Build.Dev||n.Build===exports.Build.Alpha){const e=o.GetQueryString(),t=[...l,...null!==(a=n.AllowedUrlKeys)&&void 0!==a?a:[]];i.Each(e,(e,i)=>{if(!g.includes(e)&&t.includes(e))try{n[e]=decodeURIComponent(i)}catch(t){n[e]=i}})}super(e,n),this.App=this.Cfg.App,this.Version=this.Cfg.Version,this.Build=this.Cfg.Build,this.IsDev=this.Cfg.Build===exports.Build.Dev,this.IsAlpha=this.Cfg.Build===exports.Build.Alpha,this.IsBeta=this.Cfg.Build===exports.Build.Beta,this.IsCandidate=this.Cfg.Build===exports.Build.Candidate,this.IsRelease=this.Cfg.Build===exports.Build.Release,this.Workspace=this.Cfg.Workspace,this.SupportedLanguages=this.Cfg.Language,this._runningLogic=!0,this._runningInternal=!0,this._timingPause=0,this._elapsed=0,t.director.once(t.Director.EVENT_BEFORE_SCENE_LAUNCH,this.onSceneLaunch,this),t.game.on(t.Game.EVENT_SHOW,this.internalResume,this),t.game.on(t.Game.EVENT_HIDE,this.internalPause,this),t.game.on(t.Game.EVENT_CLOSE,this.internalClose,this),t.game.on(t.Game.EVENT_LOW_MEMORY,this.internalLowMemory,this),this.Logger.Info(`🔥 ${this.App} ${this.Version}_${this.Build}`)}internalPause(){this._runningInternal=!1,this._timingPause=a.Now(),this.Deps.EventBus.Sys.Notify(n.EventMessage.Void(u.ENTER_BACKGROUND))}internalResume(){this._runningInternal=!0,this._timingPause>0&&(this._elapsed=a.Now()-this._timingPause,this._timingPause=0),this.Deps.EventBus.Sys.Notify(n.EventMessage.Void(u.ENTER_FOREGROUND))}internalClose(){this.Deps.EventBus.Sys.Notify(n.EventMessage.Void(u.QUIT)),t.game.targetOff(this),t.director.targetOff(this)}internalLowMemory(){this.Deps.EventBus.Sys.Notify(n.EventMessage.Void(u.LOW_MEMORY))}onSceneLaunch(e){var i,s;const a=this;if(a.Scene=e,a.Mnt=e.getChildByName("mnt"),a.Mnt||(a.Mnt=new t.Node("mnt"),a.Mnt.layer=0,a.Scene.insertChild(this.Mnt,0)),a.Root=e.getChildByName("Canvas"),this.Root){if(a.Stage=a.Root.getChildByName("Stage"),!a.Stage){const e=new t.Node("Stage");e.layer=t.Layers.BitMask.UI_2D;const i=e.addComponent(t.Widget);i.left=i.top=i.right=i.bottom=0,i.isAlignLeft=i.isAlignTop=i.isAlignBottom=i.isAlignRight=!0,i.alignMode=t.Widget.AlignMode.ON_WINDOW_RESIZE,i.updateAlignment(),a.Stage=e,this.Root.insertChild(this.Stage,1)}a.Canvas=a.Root.getComponent(t.Canvas),a.CameraUi=null!==(s=null===(i=a.Root.getChildByName("Camera"))||void 0===i?void 0:i.getComponent(t.Camera))&&void 0!==s?s:null,this.CameraUi||this.Logger.Warn("启动警告：Canvas 缺少名为 Camera 的子节点，UI 相机不可用"),this.Deps.EventBus.Sys.Notify(n.EventMessage.Void(u.STAGE_READY))}else this.Logger.Error(`启动错误：场景 ${e.name} 缺少名为 Canvas 的根节点，舞台装配中止`)}IsBuildOf(e){return this.Build===e}IsLanguageSupported(e){return this.Cfg.Language.includes(e)}Pause(){this._runningLogic=!1}Resume(){this._runningLogic=!0}get Elapsed(){return this._elapsed}get Running(){return this._runningInternal&&this._runningLogic}}exports.LAUNCHER_EVENT=u,exports.LAUNCHER_RESERVED_KEYS=g,exports.LAUNCHER_URL_OVERRIDABLE_KEYS=l,exports.Launcher=h;

package/dist/launcher.min.mjs

@@ -0,0 +1 @@
+import{sys as t,director as e,Director as i,game as n,Game as s,Node as a,Layers as o,Widget as r,Canvas as l,Camera as h}from"cc";import{Override as g,Each as u}from"@nebulaaa/dict";import{MISC as d}from"@nebulaaa/env";import{EventMessage as p}from"@nebulaaa/event-bus";import{Now as E}from"@nebulaaa/ms";import{Plugin as m}from"@nebulaaa/plugin";import{GetQueryString as C}from"@nebulaaa/web";var f;!function(t){t.Dev="dev",t.Alpha="alpha",t.Beta="beta",t.Candidate="candidate",t.Release="release"}(f||(f={}));const _={ENTER_BACKGROUND:"app@enter-background",ENTER_FOREGROUND:"app@enter-foreground",QUIT:"app@quit",LOW_MEMORY:"app@low-memory",STAGE_READY:"app@stage-ready"},c=["Workspace"],R=["App","Version","Build","Language"];class B extends m{constructor(a,o){var r;if(g(null!=o?o:{},{app:"nebulaaa",version:"1.0.0",build:f.Dev,language:[t.Language.CHINESE,t.Language.ENGLISH],env:"default"}),d.BROWSER&&o.Build===f.Dev||o.Build===f.Alpha){const t=C(),e=[...c,...null!==(r=o.AllowedUrlKeys)&&void 0!==r?r:[]];u(t,(t,i)=>{if(!R.includes(t)&&e.includes(t))try{o[t]=decodeURIComponent(i)}catch(e){o[t]=i}})}super(a,o),this.App=this.Cfg.App,this.Version=this.Cfg.Version,this.Build=this.Cfg.Build,this.IsDev=this.Cfg.Build===f.Dev,this.IsAlpha=this.Cfg.Build===f.Alpha,this.IsBeta=this.Cfg.Build===f.Beta,this.IsCandidate=this.Cfg.Build===f.Candidate,this.IsRelease=this.Cfg.Build===f.Release,this.Workspace=this.Cfg.Workspace,this.SupportedLanguages=this.Cfg.Language,this._runningLogic=!0,this._runningInternal=!0,this._timingPause=0,this._elapsed=0,e.once(i.EVENT_BEFORE_SCENE_LAUNCH,this.onSceneLaunch,this),n.on(s.EVENT_SHOW,this.internalResume,this),n.on(s.EVENT_HIDE,this.internalPause,this),n.on(s.EVENT_CLOSE,this.internalClose,this),n.on(s.EVENT_LOW_MEMORY,this.internalLowMemory,this),this.Logger.Info(`🔥 ${this.App} ${this.Version}_${this.Build}`)}internalPause(){this._runningInternal=!1,this._timingPause=E(),this.Deps.EventBus.Sys.Notify(p.Void(_.ENTER_BACKGROUND))}internalResume(){this._runningInternal=!0,this._timingPause>0&&(this._elapsed=E()-this._timingPause,this._timingPause=0),this.Deps.EventBus.Sys.Notify(p.Void(_.ENTER_FOREGROUND))}internalClose(){this.Deps.EventBus.Sys.Notify(p.Void(_.QUIT)),n.targetOff(this),e.targetOff(this)}internalLowMemory(){this.Deps.EventBus.Sys.Notify(p.Void(_.LOW_MEMORY))}onSceneLaunch(t){var e,i;const n=this;if(n.Scene=t,n.Mnt=t.getChildByName("mnt"),n.Mnt||(n.Mnt=new a("mnt"),n.Mnt.layer=0,n.Scene.insertChild(this.Mnt,0)),n.Root=t.getChildByName("Canvas"),this.Root){if(n.Stage=n.Root.getChildByName("Stage"),!n.Stage){const t=new a("Stage");t.layer=o.BitMask.UI_2D;const e=t.addComponent(r);e.left=e.top=e.right=e.bottom=0,e.isAlignLeft=e.isAlignTop=e.isAlignBottom=e.isAlignRight=!0,e.alignMode=r.AlignMode.ON_WINDOW_RESIZE,e.updateAlignment(),n.Stage=t,this.Root.insertChild(this.Stage,1)}n.Canvas=n.Root.getComponent(l),n.CameraUi=null!==(i=null===(e=n.Root.getChildByName("Camera"))||void 0===e?void 0:e.getComponent(h))&&void 0!==i?i:null,this.CameraUi||this.Logger.Warn("启动警告：Canvas 缺少名为 Camera 的子节点，UI 相机不可用"),this.Deps.EventBus.Sys.Notify(p.Void(_.STAGE_READY))}else this.Logger.Error(`启动错误：场景 ${t.name} 缺少名为 Canvas 的根节点，舞台装配中止`)}IsBuildOf(t){return this.Build===t}IsLanguageSupported(t){return this.Cfg.Language.includes(t)}Pause(){this._runningLogic=!1}Resume(){this._runningLogic=!0}get Elapsed(){return this._elapsed}get Running(){return this._runningInternal&&this._runningLogic}}export{f as Build,_ as LAUNCHER_EVENT,R as LAUNCHER_RESERVED_KEYS,c as LAUNCHER_URL_OVERRIDABLE_KEYS,B as Launcher};

package/dist/launcher.mjs

@@ -0,0 +1,189 @@
+import { sys, director, Director, game, Game, Node, Layers, Widget, Canvas, Camera } from 'cc';
+import { Override, Each } from '@nebulaaa/dict';
+import { MISC } from '@nebulaaa/env';
+import { EventMessage } from '@nebulaaa/event-bus';
+import { Now } from '@nebulaaa/ms';
+import { Plugin } from '@nebulaaa/plugin';
+import { GetQueryString } from '@nebulaaa/web';
+
+/**
+ * 应用构建版本
+ */
+var Build;
+(function (Build) {
+    /** 内部开发版 */
+    Build["Dev"] = "dev";
+    /** 内部测试版 */
+    Build["Alpha"] = "alpha";
+    /** 公开测试版 */
+    Build["Beta"] = "beta";
+    /** 候选发布版 */
+    Build["Candidate"] = "candidate";
+    /** 正式发布版 */
+    Build["Release"] = "release";
+})(Build || (Build = {}));
+
+/** 宏定义 */
+const LAUNCHER_EVENT = {
+    /** 应用进入后台 */
+    ENTER_BACKGROUND: 'app@enter-background',
+    /** 应用进入前台 */
+    ENTER_FOREGROUND: 'app@enter-foreground',
+    /** 应用退出 */
+    QUIT: 'app@quit',
+    /** 应用低内存告警 */
+    LOW_MEMORY: 'app@low-memory',
+    /** 场景启动 */
+    STAGE_READY: 'app@stage-ready',
+};
+/** 允许经 URL 覆写的配置键白名单（可经 config.UrlKeys 追加） */
+const LAUNCHER_URL_OVERRIDABLE_KEYS = ['Workspace'];
+/** 保留键（扩展白名单也拒绝注入，防止 URL 伪装构建版本等核心语义） */
+const LAUNCHER_RESERVED_KEYS = ['App', 'Version', 'Build', 'Language'];
+
+/**
+ * 启动器
+ */
+class Launcher extends Plugin {
+    constructor(deps, cfg) {
+        var _a;
+        Override(cfg !== null && cfg !== void 0 ? cfg : {}, {
+            app: 'nebulaaa',
+            version: '1.0.0',
+            build: Build.Dev,
+            language: [sys.Language.CHINESE, sys.Language.ENGLISH],
+            env: 'default',
+        });
+        if ((MISC.BROWSER && cfg.Build === Build.Dev) || cfg.Build === Build.Alpha) {
+            const qs = GetQueryString();
+            const whitelist = [...LAUNCHER_URL_OVERRIDABLE_KEYS, ...((_a = cfg.AllowedUrlKeys) !== null && _a !== void 0 ? _a : [])];
+            Each(qs, (key, value) => {
+                if (LAUNCHER_RESERVED_KEYS.includes(key))
+                    return; // 保留键拒绝注入
+                if (!whitelist.includes(key))
+                    return; // 白名单外的键拒绝注入
+                try {
+                    cfg[key] = decodeURIComponent(value);
+                }
+                catch (_a) {
+                    cfg[key] = value;
+                }
+            });
+        }
+        super(deps, cfg);
+        this.App = this.Cfg.App;
+        this.Version = this.Cfg.Version;
+        this.Build = this.Cfg.Build;
+        this.IsDev = this.Cfg.Build === Build.Dev;
+        this.IsAlpha = this.Cfg.Build === Build.Alpha;
+        this.IsBeta = this.Cfg.Build === Build.Beta;
+        this.IsCandidate = this.Cfg.Build === Build.Candidate;
+        this.IsRelease = this.Cfg.Build === Build.Release;
+        this.Workspace = this.Cfg.Workspace;
+        this.SupportedLanguages = this.Cfg.Language;
+        this._runningLogic = true;
+        this._runningInternal = true;
+        this._timingPause = 0;
+        this._elapsed = 0;
+        director.once(Director.EVENT_BEFORE_SCENE_LAUNCH, this.onSceneLaunch, this);
+        game.on(Game.EVENT_SHOW, this.internalResume, this);
+        game.on(Game.EVENT_HIDE, this.internalPause, this);
+        game.on(Game.EVENT_CLOSE, this.internalClose, this);
+        game.on(Game.EVENT_LOW_MEMORY, this.internalLowMemory, this);
+        this.Logger.Info(`🔥 ${this.App} ${this.Version}_${this.Build}`);
+    }
+    /** 应用退到后台 */
+    internalPause() {
+        this._runningInternal = false;
+        this._timingPause = Now();
+        this.Deps.EventBus.Sys.Notify(EventMessage.Void(LAUNCHER_EVENT.ENTER_BACKGROUND));
+    }
+    /** 应用回到前台 */
+    internalResume() {
+        this._runningInternal = true;
+        if (this._timingPause > 0) {
+            this._elapsed = Now() - this._timingPause; // 仅完整的 hide→show 往返计入，首启 SHOW 不产生垃圾值
+            this._timingPause = 0;
+        }
+        this.Deps.EventBus.Sys.Notify(EventMessage.Void(LAUNCHER_EVENT.ENTER_FOREGROUND));
+    }
+    /** 应用退出 */
+    internalClose() {
+        this.Deps.EventBus.Sys.Notify(EventMessage.Void(LAUNCHER_EVENT.QUIT));
+        game.targetOff(this);
+        director.targetOff(this);
+    }
+    /** 内存报警 */
+    internalLowMemory() {
+        // 巡检的节流周期由引擎帧驱动，低内存时须跳过等待立即清扫（此前误传秒值使清扫形同虚设）
+        this.Deps.EventBus.Sys.Notify(EventMessage.Void(LAUNCHER_EVENT.LOW_MEMORY));
+    }
+    /** 场景启动 */
+    onSceneLaunch(scene) {
+        var _a, _b;
+        const ctx = this;
+        // Scene
+        ctx.Scene = scene;
+        // Mnt
+        ctx.Mnt = scene.getChildByName('mnt');
+        if (!ctx.Mnt) {
+            ctx.Mnt = new Node('mnt');
+            ctx.Mnt.layer = 0;
+            ctx.Scene.insertChild(this.Mnt, 0);
+        }
+        // Root
+        ctx.Root = scene.getChildByName('Canvas');
+        if (!this.Root) {
+            // Canvas 是舞台的挂载前提，缺失时中止装配；仅记录日志，不向引擎事件派发抛出异常
+            this.Logger.Error(`启动错误：场景 ${scene.name} 缺少名为 Canvas 的根节点，舞台装配中止`);
+            return;
+        }
+        // Stage
+        ctx.Stage = ctx.Root.getChildByName('Stage');
+        if (!ctx.Stage) {
+            const node = new Node('Stage');
+            node.layer = Layers.BitMask.UI_2D;
+            const wid = node.addComponent(Widget);
+            wid.left = wid.top = wid.right = wid.bottom = 0;
+            wid.isAlignLeft = wid.isAlignTop = wid.isAlignBottom = wid.isAlignRight = true;
+            wid.alignMode = Widget.AlignMode.ON_WINDOW_RESIZE;
+            wid.updateAlignment();
+            ctx.Stage = node;
+            this.Root.insertChild(this.Stage, 1);
+        }
+        // Canvas
+        ctx.Canvas = ctx.Root.getComponent(Canvas);
+        // CameraUi
+        ctx.CameraUi = (_b = (_a = ctx.Root.getChildByName('Camera')) === null || _a === void 0 ? void 0 : _a.getComponent(Camera)) !== null && _b !== void 0 ? _b : null;
+        if (!this.CameraUi) {
+            this.Logger.Warn('启动警告：Canvas 缺少名为 Camera 的子节点，UI 相机不可用');
+        }
+        this.Deps.EventBus.Sys.Notify(EventMessage.Void(LAUNCHER_EVENT.STAGE_READY));
+    }
+    /** 是否指定构建版本 */
+    IsBuildOf(build) {
+        return this.Build === build;
+    }
+    /** 是否支持语言 */
+    IsLanguageSupported(language) {
+        return this.Cfg.Language.includes(language);
+    }
+    /** 暂停逻辑 */
+    Pause() {
+        this._runningLogic = false;
+    }
+    /** 恢复逻辑 */
+    Resume() {
+        this._runningLogic = true;
+    }
+    /** 从后台回到前台经历的时间（ms，未经历完整后台往返时为 0） */
+    get Elapsed() {
+        return this._elapsed;
+    }
+    /** 运行状态 */
+    get Running() {
+        return this._runningInternal && this._runningLogic;
+    }
+}
+
+export { Build, LAUNCHER_EVENT, LAUNCHER_RESERVED_KEYS, LAUNCHER_URL_OVERRIDABLE_KEYS, Launcher };

package/dist/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@nebulaaa/launcher",
+  "version": "1.0.0",
+  "description": "启动器插件",
+  "author": "doooreyn",
+  "license": "MIT",
+  "keywords": [
+    "launcher",
+    "nebulaaa"
+  ],
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=10.0.0"
+  },
+  "main": "./launcher.cjs",
+  "module": "./launcher.mjs",
+  "types": "./launcher.d.ts",
+  "exports": {
+    ".": {
+      "types": "./launcher.d.ts",
+      "require": "./launcher.cjs",
+      "import": "./launcher.mjs",
+      "default": "./launcher.cjs"
+    },
+    "./min": {
+      "require": "./launcher.min.cjs",
+      "import": "./launcher.min.mjs"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/package.json

@@ -1,6 +1,73 @@
-{
-  "name": "@nebulaaa/launcher",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@nebulaaa/launcher",
+  "version": "1.0.0",
+  "description": "启动器插件",
+  "main": "./dist/launcher.cjs",
+  "module": "./dist/launcher.mjs",
+  "types": "./dist/launcher.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/launcher.cjs",
+      "import": "./dist/launcher.mjs",
+      "types": "./dist/launcher.d.ts",
+      "default": "./dist/launcher.cjs"
+    },
+    "./min": {
+      "require": "./dist/launcher.min.cjs",
+      "import": "./dist/launcher.min.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && rollup -c rollup.config.mjs && node ../scripts/write-dist-package.mjs launcher",
+    "test": "jest"
+  },
+  "keywords": [
+    "launcher",
+    "nebulaaa"
+  ],
+  "author": "doooreyn",
+  "license": "MIT",
+  "devEngines": {
+    "packageManager": {
+      "name": "npm",
+      "version": ">=10.0.0",
+      "onFail": "warn"
+    }
+  },
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=10.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "allowScripts": {
+    "unrs-resolver@1.12.2": true,
+    "@parcel/watcher@2.6.0": true
+  },
+  "devDependencies": {
+    "@rollup/plugin-terser": "^1.0.2",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.10.2",
+    "jest": "^30.5.2",
+    "rollup": "^4.28.1",
+    "rollup-plugin-dts": "^6.1.1",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "typescript": "5.7.3"
+  },
+  "dependencies": {
+    "@nebulaaa/dict": "^1.1.0",
+    "@nebulaaa/env": "^1.0.2",
+    "@nebulaaa/event-bus": "^1.0.0",
+    "@nebulaaa/ms": "^1.1.0",
+    "@nebulaaa/plugin": "^1.0.0",
+    "@nebulaaa/web": "^1.1.0"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.