SGS Framework Manual

概览

SGS Framework 在 Laya 初始化前由下载器注入。Core 提供生命周期、事件、可逆 Hook、插件管理、配置 UI、LocalStorage 隔离和 Laya 底层访问。插件权限只用于安装前披露，不构成沙箱或能力拒绝。

SGS Framework 插件配置窗口 — Core 配置窗口：插件管理、插件配置与 Core 管理三个 Tab。

全局入口window.SgsFramework

官方源/script/plugin/index.json

默认超时5000 ms

安装与入口

在油猴脚本管理器中打开 download.mjs。
下载器先从本站获取 core.mjs，失败后请求 GitHub；每个请求分别超时 5 秒。
网络源都失败时读取本地缓存；缓存也不可用时才显示继续游戏或刷新重试。

https://sgs.senrax.com/script/download.mjs

Core API

入口	用途
`events`	`on`、`once`、`off`、`emit` 事件总线。
`logger`	Core/插件作用域日志。
`storage`	序列化 LocalStorage 与作用域前缀。
`timers`	自动参与热重载清理的定时器。
`hooks`	可逆的公开方法包装。
`dom`	Overlay、Panel、Button 与 Toast。
`browser`	URL 打开、限时 Fetch、Text/JSON/Header 请求。
`laya`	获取 Laya/Stage、遍历、查找和节点快照。
`runtime`	战斗、窗口和公开战斗日志生命周期。
`plugins`	安装、启停、更新、配置、来源和清理。
`update`	Core 版本检测与热重载。
`ui`	悬浮窗、配置窗口、确认框与刷新。

const framework = window.SgsFramework;
framework.events.on("battle:start", ({ scene, manager }) => {
  framework.logger.info("battle started", scene, manager);
});

插件格式

插件是可直接下载的经典 JavaScript 文件。Header 在执行前用于显示名称、简介、版本、权限与更新模式；正文必须调用 SgsFramework.plugins.define()。

// ==SgsPlugin==
// @id           example.plugin
// @name         Example Plugin
// @version      1.0.0
// @description  Example description.
// @permissions  core.events,browser.dom-overlay
// @updateMode   default
// ==/SgsPlugin==

(() => {
  SgsFramework.plugins.define({
    id: "example.plugin",
    manifest: {
      name: "Example Plugin",
      version: "1.0.0",
      permissions: ["core.events", "browser.dom-overlay"]
    },
    defaults: {},
    settings: [],
    install(context) {
      return () => {};
    }
  });
})();

插件配置

插件只声明配置结构与动作，布局由 Core 统一生成。支持 Group、Toggle、Button、TextBox、Select 和 Custom。没有配置项的插件仍会出现在配置页，并显示“无可配置项”。

defaults: { enabled: true, mode: "safe" },
settings: [{
  id: "general",
  name: "General",
  items: [
    { key: "enabled", name: "Enabled", type: "toggle", onChange: "apply" },
    { key: "name", name: "Name", type: "text", patterns: ["^.{1,20}$"] },
    { key: "mode", name: "Mode", type: "select", options: [
      { value: "safe", label: "Safe" },
      { value: "full", label: "Full" }
    ]},
    { name: "Open list", type: "button", action: "openList" }
  ]
}]

更新检测

模式	行为
`default`	GET 插件 JavaScript，并从 Header 读取版本。
`header`	HEAD 请求，不读取响应体；默认读取 `x-sgs-plugin-version`。
`api`	GET JSON API，读取 `version`，可选读取 `url`。

跨域 Header 模式来源还必须通过 Access-Control-Expose-Headers 暴露版本响应头；只有 Access-Control-Allow-Origin 时，浏览器 JavaScript 仍无法读取自定义 Header。

Core 启动后自动检测插件和 Core 版本；手动检测按钮会立即重新请求。有新版本时对应行出现更新按钮，插件与 Core 都支持当前页面热重载。

运行时事件

事件	证据与 Payload
`battle:start`	有效可见的 `TableGameScene`/`RogueLikeGameScene` 且 `manager.seats` 存在。
`battle:end`	战斗 Scene 离开、不可见或被替换；插件必须立即清理战斗 UI。
`battle:log`	来自公开 Laya HTML 战斗日志容器，不代表隐藏手牌权限。
`window:open`	Stage 中有效可见的 Window/Dialog/Popup 节点出现。
`window:close`	此前可见窗口节点离开有效可见集合。

不通过 console.log 判断战斗。窗口注册表可能残留，Core 以 Laya.stage 实际有效可见节点为准。

存储

sgs.framework.ui.*
sgs.framework.plugins.registry
sgs.framework.plugins.sources
sgs.framework.plugins.<pluginId>.code
sgs.framework.plugins.<pluginId>.config
sgs.framework.plugins.<pluginId>.data.*

context.config 保存 Core 排版配置；context.storage 保存插件内部数据。实际键名均由 Core 添加插件前缀。删除插件不会立即删除配置，Core 页的“清理配置”会列出孤儿配置供用户决定。

插件源

官方源固定为 /script/plugin/index.json。第三方源可添加名称与 URL，并支持禁用、重命名和删除。Catalog 结构如下：

{
  "name": "Source name",
  "plugins": [
    { "id": "example.plugin", "url": "https://example/plugin.js" }
  ]
}

官方插件

SGS Card Tracker

无配置项。仅在战斗 Scene 有效可见时启用 UI，离开战斗立即停止描画。已知牌只来自自己的手牌、公开日志/窗口、公开区和明确揭示牌的协议记录，不读取隐藏对手 handCards。

SGS Blocker

提供广告、选定特效、道具弹窗三个独立开关。规则只隐藏命名匹配的节点并保存原始 visible/alpha，禁用或卸载时恢复；不会全局关闭 Tween、Timer、Animation 或渲染。

权限与风险

Framework 不屏蔽付费、购买或其他能力，也不以权限名拒绝插件。安装前会展示插件声明的权限、简介、版本和来源，由用户决定是否安装。插件在页面环境中执行，不是安全沙箱；只安装可信来源并审查高风险插件。