msw-packages

MSW Packages — 官方预构建目录

MSW-Git/MSWPackages 是官方的 MSW 一方预构建功能包仓库。在从头编写任何标准游戏功能之前，请先检查此目录——如果有匹配的包，应提议集成，而不是从零开始实现。

此技能是一个精简索引。每个包的详细信息（README、源代码、集成步骤）会按需从 GitHub 获取，而不是镜像到此处，因此目录会自动保持最新。

---

决策流程

User asks for feature X
        │
        ▼
Match X against Feature → Package table below
        │
   ┌────┴─────┐
   │ Match    │ No match
   ▼          ▼
Scope-First check      Proceed with normal MSW
(see section below):   authoring (msw-scripting,
system vs UI-only?     msw-search, etc.)
        │
   ┌────┴───────────┐
   │ system         │ UI-only
   ▼                ▼
Fetch package    Route to msw-ui-system
README           (+ references/templates/, skip the rest of this skill)
        │
        ▼
Summarize for user
"Found <package>. README says: <summary>.
 Integrate this, or build from scratch?"
        │
   ┌────┴─────┐
   │          │
   ▼          ▼
Integrate    Build from scratch
        │
        ▼
Run Integration Workflow (below)

默认做法：集成前先询问用户。未经确认请勿自动安装——这些包可能与用户项目中现有的 UUID、精灵图 RUID 或命名规范冲突。

---

功能 → 包映射

当用户请求提到以下任一功能（韩语或英语）时，查找匹配的包并先获取其 README。

功能领域	包	GitHub 路径
Toast / 通知 / 横幅	maplestory-toast-package	链接
排名 / 排行榜 / 计分板（基础）	ranking-basic-package	链接
排名 / 排行榜（高级 — 多榜单、赛季）	ranking-advanced-package	链接
背包 / 物品袋 / 装备	inventory-package	链接
商店 / 商铺 / 购买	shop-package	链接
世界商店 / 高级商店	worldshop-package	链接
邮件 / 邮箱	mail-package	链接
任务 / 成就 / 使命	quest-achievement-package	链接
对话 / NPC 对话（打字机样式）	dialog-package	链接
按键绑定 / 虚拟按钮	key-binding-package	链接
游戏事件广播 / 发布-订阅	game-event-package	链接
玩家数据 / 存档 / 档案	player-data-package	链接
收藏 / 图鉴 / dex	collections-package	链接
斜杠命令 / 聊天命令	command-package	链接
虚拟化滚动列表 / 大型列表	recyclescrollview-package	链接
掉落表 / 战利品概率	droptable-resolver-package	链接
全局配置 / 共享设置	global-config-package	链接
GM / 系统公告	gm-message-package	链接
游戏资源（货币、能量、可补充资源）	resource-package	链接
UI 组件和预制体模型	ui-component-package	链接

如果可能匹配多个包（例如，“排名”→基础版或高级版），请获取这两个包的 README，并让用户根据对比结果进行选择。

---

先确定范围（UI 还是系统）

当请求符合目录中的某个关键词，但不清楚用户需要的是完整系统（数据 + 逻辑 + UI）还是仅 UI 界面时，请在获取软件包文件前先问一个简短的问题。使用下表中对应的问题。

请求关键词	要问的问题
排名 / 排行榜	“您还需要保存分数和计算排名吗，还是只需要排行榜界面？”
背包 / 库存	“您还需要添加 / 移除物品的逻辑吗，还是只需要物品槽界面？”
商店 / 店铺	“您还需要扣除货币和处理购买吗，还是只需要商店界面？”
邮件 / 邮箱	“您还需要发送 / 接收逻辑吗，还是只需要邮箱界面？”
任务 / 成就	“您还需要追踪进度和发放奖励吗，还是只需要任务列表界面？”
Toast / 通知	“您还需要排队 / 计时系统吗，还是只需要消息弹窗？”
对话 / NPC 对话	“您还需要分支对话和状态吗，还是只需要对话窗口？”
收藏 / 图鉴	“您还需要收藏状态和进度追踪吗，还是只需要图鉴界面？”
玩家数据 / 存档	“您还需要持久化和加载 / 保存流程吗，还是只需要个人资料界面？”
其他 / 不明确	“您需要可运行的功能，还是只需要 UI 界面？”

路由规则

根据用户的回答，将请求映射到相应目标：

用户说……	路由到
“功能”“系统”“逻辑”“保存”“计算”“处理”	留在此处（msw-packages） — 继续执行下方的 Fetch Protocol
“界面”“UI”“外观”“视觉效果”“只要布局”“只展示”	msw-ui-system skill（+ references/templates/）— 选择一个样式模板，然后通过 UI builder 构建
低层级问题（锚点、组件属性、枚举）	msw-ui-system skill — 直接通过 references/component-api.md（含 §Enums）/ ui-fundamentals.md 作答，无需获取文件

何时跳过提问

当用户的请求已经明确时，跳过范围确认问题，直接路由：

• “从头开始” / “只要 UI” / “只要界面” → msw-ui-system skill（+ references/templates/）
• “完整系统” / “带后端” / “带数据” / “保存分数” → 留在 msw-packages
• 纯低层级 UI 问题（例如“如何设置锚点？”）→ msw-ui-system skill

仅当关键词匹配目录中的软件包，且范围确实不明确时才提问。

---

获取流程

确定候选软件包后：

1. 始终先查看 README

https://raw.githubusercontent.com/MSW-Git/MSWPackages/main/<package-name>/README.md

使用 WebFetch 获取此内容。在继续之前，先向用户概述公开 API 和适用场景。

2. 文件树（可能需要集成时）

使用 GitHub tree API，并通过 grep 查找软件包路径：

https://api.github.com/repos/MSW-Git/MSWPackages/git/trees/main?recursive=1

响应内容很大，可能会被截断。对响应内容执行 grep，搜索 <package-name>/ 以提取文件列表。如果内容被截断，则改用逐目录 tree 调用：

https://api.github.com/repos/MSW-Git/MSWPackages/contents/<package-name>/MyDesk

标准软件包布局：

• <package-name>/README.md
• <package-name>/<PackageName>.modpackage — 安装程序清单（视为不透明内容）
• <package-name>/MyDesk/<PackageName>/Core/ — 要复制的核心脚本 / UI
• <package-name>/MyDesk/<PackageName>/Sample/ — 用法示例（除非用户要求，否则不要复制）
• <package-name>/MyDesk/Util/ — 共享实用程序（部分软件包包含）

3. 获取原始文件（按需逐个获取）

https://raw.githubusercontent.com/MSW-Git/MSWPackages/main/<path>

对于任何浏览 URL，将 github.com/.../blob/main/... 替换为 raw.githubusercontent.com/.../main/...。

---

集成工作流

用户确认集成后：

1. 将文件映射到项目布局：

   • MyDesk/<PackageName>/Core/*.mlua → RootDesk/MyDesk/<PackageName>/
   • MyDesk/<PackageName>/Core/*.ui → ui/
   • MyDesk/<PackageName>/Core/*.model → RootDesk/MyDesk/Models/<Category>/
   • MyDesk/Util/* → RootDesk/MyDesk/Util/（如果已存在则复用）

2. 检查 UUID 冲突：传入的 .ui/.model 文件中，每个实体的 id 和 EntryKey 都不能已存在于用户项目中。写入前用 grep 在工作区中搜索冲突。为所有冲突的 UUID 重新生成新的十六进制 UUID。

3. 检查精灵图 RUID 依赖项：扫描软件包文件中的硬编码 RUID。它们引用的是 MSW 社区资源，通常没有问题，但如果有可疑项或需要替代资源，请用 msw-search 验证。

4. 解决跨软件包依赖项：有些软件包依赖其他软件包（例如，ranking 可能基于 player-data 构建）。阅读软件包的 README 和源文件头部——先安装传递依赖软件包，再安装当前软件包。

5. 按标准 MSW 工作流应用：stop → refresh_workspace → play。在构建日志和运行时日志中进行验证。

6. 接入用户的代码：大多数软件包会公开一个 _<PackageName> Logic 单例。从用户现有的脚本中调用其 API（例如 _MaplestoryToast:Show(...)）。

---

易错点

• 在此工作流中，.modpackage 文件不是自动安装脚本——它们是 Maker 编辑器元数据。真正完成软件包集成的是手动复制文件。
• 示例中的硬编码精灵图 RUID：软件包示例通常引用特定的装饰精灵图 RUID。这些资源可以使用，但用户可能想要替换。总结时请注明这一点。
• UI 文件使用 UIGroup 根实体——复制时应通过 msw-ui-system 处理（使用 UIBuilder.read/load 检查，使用 builder API 修改；UIGroup 根配置、锚点模式等设计规则也在同一技能中）。不要手动编辑原始 .ui JSON。
• Sample/ 内容仅供示例，并非生产内容——除非用户明确提出要求，否则不要复制 Sample/ 文件。示例脚本通常会绑定与用户控件冲突的键盘快捷键。
• 软件包无法取代对 mlua 的理解——软件包提供预构建功能，但用户仍需掌握 msw-scripting 知识才能扩展这些功能。
• 不要凭猜测批量安装多个软件包——每次集成都会增加文件和复杂度。每次安装一个功能，验证后再继续。

---

用户已选择“从头开始构建”时

完全跳过集成。按常规 MSW 编写流程继续（msw-scripting、msw-search 等）。不要暗中继续引导用户转而使用软件包。

---

无法访问 MSW-Git/MSWPackages 时

• WebFetch 返回错误或 404 → 确认 URL 是否已更改。
• 沙盒网络可能会阻止直接 curl 访问 api.github.com——获取原始内容和 HTML 页面时优先使用 WebFetch。
• 如果所有方法都失败，则改为从头开始构建，并告知用户当前无法访问该软件包。

---

交叉引用

• msw-general — 工作区、文件路径、MCP 工具、坐标系。
• msw-scripting — 用于将软件包 API 接入游戏逻辑的 .mlua 语法。
• msw-search — 替换软件包捆绑资源时，用于查找精灵图/动画/音效 RUID。