Back to Details

msw-packages

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MSW Packages — Official Prebuilt Catalog

MSW Packages —— 官方预构建包目录

MSW-Git/MSWPackages
 is the official MSW first-party repository of prebuilt feature packages. Before writing any standard game feature from scratch, check this catalog first — if a package matches, propose integration instead of zero-from-scratch implementation.
This skill is a thin index. Per-package details (README, source, integration steps) are fetched on demand from GitHub rather than mirrored here, so the catalog stays current automatically.
MSW-Git/MSWPackages
 是MSW官方第一方预构建功能包仓库。在从零开发任何标准游戏功能前，请先查看此目录——如果有匹配的包，建议集成而非从零实现。
此技能仅作为轻量索引。各包的详细信息（README、源码、集成步骤）会按需从GitHub获取，而非在此镜像，因此目录会自动保持最新。

Decision Flow

决策流程

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)
Default posture: ask the user before integrating. Do not auto-install without confirmation — packages can collide with existing UUIDs, sprite RUIDs, or naming conventions in the user's project.
用户请求功能X
        │
        ▼
将X与下方的「功能→包」对照表进行匹配
        │
   ┌────┴─────┐
   │ 匹配到    │ 未匹配到
   ▼          ▼
优先范围检查      继续常规MSW开发
(见下方章节):   （msw-scripting、
完整系统vs仅UI？  msw-search等）
        │
   ┌────┴───────────┐
   │ 完整系统         │ 仅UI
   ▼                ▼
获取包的README    路由到msw-ui-system
                  （+ references/templates/，跳过此技能的其余步骤）
        │
        ▼
向用户总结：
「找到<package>包。README说明：<摘要>。
 是集成此包，还是从零构建？」
        │
   ┌────┴─────┐
   │          │
   ▼          ▼
集成包        从零构建
        │
        ▼
执行下方的集成流程
默认原则：集成前需询问用户。请勿自动安装——包可能与用户项目中已有的UUID、精灵RUID或命名规则冲突。

Feature → Package Mapping

功能→包映射表

When a user request mentions one of these features (Korean or English), look up the matching package and fetch its README first.
Feature domainPackageGitHub path
Toast / notification / banner
maplestory-toast-package
link
Ranking / leaderboard / scoreboard (basic)
ranking-basic-package
link
Ranking / leaderboard (advanced — multi-board, season)
ranking-advanced-package
link
Inventory / item bag / equipment
inventory-package
link
Shop / store / purchase
shop-package
link
World shop / premium shop
worldshop-package
link
Mail / mailbox
mail-package
link
Quest / achievement / mission
quest-achievement-package
link
Dialog / NPC conversation (typewriter style)
dialog-package
link
Key binding / virtual button
key-binding-package
link
Game event broadcast / pub-sub
game-event-package
link
Player data / save / profile
player-data-package
link
Collection / gallery / dex
collections-package
link
Slash command / chat command
command-package
link
Virtualized scroll list / large list
recyclescrollview-package
link
Drop table / loot probability
droptable-resolver-package
link
Global config / shared settings
global-config-package
link
GM / system announcement
gm-message-package
link
Game resource (currency, energy, refillable)
resource-package
link
UI components and prefab models
ui-component-package
link
If multiple packages plausibly match (e.g. "ranking" → basic vs advanced), fetch both READMEs and let the user choose based on the comparison.
当用户请求提及以下任一功能（韩文或英文）时，请先查找匹配的包并获取其README。
功能领域包名称GitHub路径
提示框/通知/横幅
maplestory-toast-package
链接
排行榜（基础版）
ranking-basic-package
链接
排行榜（进阶版——多榜单、赛季）
ranking-advanced-package
链接
背包/物品栏/装备
inventory-package
链接
商店/商城/购买
shop-package
链接
世界商店/ premium商店
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
链接
掉落表/ loot概率
droptable-resolver-package
链接
全局配置/共享设置
global-config-package
链接
GM/系统公告
gm-message-package
链接
游戏资源（货币、能量、可补充资源）
resource-package
链接
UI组件与预制模型
ui-component-package
链接
如果多个包可能匹配（例如「排行榜」→基础版vs进阶版），请获取两个包的README并让用户根据对比结果选择。

Scope-First Routing (UI vs System)

优先范围路由（UI vs 完整系统）

When a request matches a catalog keyword but it is unclear whether the user wants the full system (data + logic + UI) or just the UI screen, ask ONE short question BEFORE fetching package files. Use the matching row from the table below.
Request keywordQuestion to ask
Ranking / leaderboard"Do you need score saving and rank calculation too, or just the leaderboard screen?"
Inventory / bag"Do you need add/remove item logic too, or just the slot screen?"
Shop / store"Do you need currency deduction and purchase handling too, or just the shop screen?"
Mail / mailbox"Do you need send/receive logic too, or just the mailbox screen?"
Quest / achievement"Do you need progress tracking and rewards too, or just the quest list screen?"
Toast / notification"Do you need the queueing/timing system too, or just the message popup?"
Dialog / NPC conversation"Do you need branching dialogue and state too, or just the dialog window?"
Collection / dex"Do you need collection state and progress tracking too, or just the dex screen?"
Player data / save"Do you need persistence and load/save flow too, or just a profile screen?"
Anything else / unclear"Do you need the working feature, or just the UI screen?"
当请求匹配目录关键词，但无法明确用户需要完整系统（数据+逻辑+UI）还是仅UI界面时，请在获取包文件前先问一个简短问题。使用下表中的对应问题。
请求关键词询问问题
排行榜"你需要分数保存和排名计算功能，还是仅需要排行榜界面？"
背包/物品栏"你需要物品增删逻辑，还是仅需要物品槽界面？"
商店/商城"你需要货币扣除和购买处理逻辑，还是仅需要商店界面？"
邮件/邮箱"你需要收发逻辑，还是仅需要邮箱界面？"
任务/成就"你需要进度追踪和奖励发放逻辑，还是仅需要任务列表界面？"
提示框/通知"你需要队列/计时系统，还是仅需要消息弹窗？"
对话/NPC交互"你需要分支对话和状态管理，还是仅需要对话窗口？"
收集/图鉴"你需要收集状态和进度追踪，还是仅需要图鉴界面？"
玩家数据/存档"你需要持久化和加载/存档流程，还是仅需要档案界面？"
其他/不明确"你需要可用的完整功能，还是仅需要UI界面？"

Routing rule

路由规则

Map the user's answer to a destination:
User says...Route to
"feature", "system", "logic", "save", "calculate", "handle", "process"Stay here (
msw-packages
) — proceed to Fetch Protocol below
"screen", "UI", "look", "visual", "just the layout", "show only"
msw-ui-system
skill (+ 
references/templates/
) — pick a style template, then build via the UI builder
Low-level question (anchor, component property, enum)
msw-ui-system
skill — answer directly via 
references/component-api.md
(incl. §Enums) / 
ui-fundamentals.md
, no fetch needed
根据用户的回答路由到对应目的地：
用户回答包含...路由至
"功能"、"系统"、"逻辑"、"保存"、"计算"、"处理"、"流程"留在当前技能（
msw-packages
）——继续执行下方的获取协议
"界面"、"UI"、"外观"、"视觉"、"仅布局"、"仅展示"
msw-ui-system
技能（+ 
references/templates/
）——选择样式模板，然后通过UI构建器创建
底层问题（锚点、组件属性、枚举）
msw-ui-system
技能——直接通过
references/component-api.md
（含§Enums）/
ui-fundamentals.md
回答，无需获取包

When to skip the question

何时跳过询问

Skip the Scope-First question and route directly when the user's request is already explicit:
  • "from scratch" / "just the UI" / "only the screen" → 
    msw-ui-system
    skill (+ 
    references/templates/
    )
  • "full system" / "with backend" / "with data" / "save score" → stay in 
    msw-packages
  • Pure low-level UI question (e.g. "how do I set anchor?") → 
    msw-ui-system
    skill
Only ask when the keyword matches a catalog package AND the scope is genuinely ambiguous.
当用户请求已经明确时，跳过优先范围询问直接路由：
  • 包含「从零构建」/「仅UI」/「仅界面」→ 
    msw-ui-system
    技能（+ 
    references/templates/
    ）
  • 包含「完整系统」/「带后端」/「带数据」/「保存分数」→ 留在
    msw-packages
  • 纯底层UI问题（例如「如何设置锚点？」）→ 
    msw-ui-system
    技能
仅当关键词匹配目录包且范围确实不明确时才询问。

Fetch Protocol

获取协议

When a candidate package is identified:
当确定候选包后：

1. README first (always)

1. 优先获取README（始终执行）

https://raw.githubusercontent.com/MSW-Git/MSWPackages/main/<package-name>/README.md
Use 
WebFetch
to pull this. Summarize the public API and use cases for the user before going further.
https://raw.githubusercontent.com/MSW-Git/MSWPackages/main/<package-name>/README.md
使用
WebFetch
拉取此文件。在进一步操作前，向用户总结包的公开API和使用场景。

2. File tree (when integration is likely)

2. 获取文件树（当可能进行集成时）

Use the GitHub tree API and grep for the package path:
https://api.github.com/repos/MSW-Git/MSWPackages/git/trees/main?recursive=1
The response is large and may be truncated. Grep the response for 
<package-name>/
to extract the file list. If truncated, fall back to per-directory tree calls:
https://api.github.com/repos/MSW-Git/MSWPackages/contents/<package-name>/MyDesk
Standard package layout:
  • <package-name>/README.md
  • <package-name>/<PackageName>.modpackage
    — installer manifest (treat as opaque)
  • <package-name>/MyDesk/<PackageName>/Core/
    — core scripts/UI to copy
  • <package-name>/MyDesk/<PackageName>/Sample/
    — example usage (do not copy unless requested)
  • <package-name>/MyDesk/Util/
    — shared utilities (some packages)
使用GitHub树API并筛选包路径：
https://api.github.com/repos/MSW-Git/MSWPackages/git/trees/main?recursive=1
响应内容较大可能被截断。在响应中筛选
<package-name>/
以提取文件列表。如果被截断，回退到按目录调用树API：
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. Raw file fetch (per-file as needed)

3. 按需获取原始文件

https://raw.githubusercontent.com/MSW-Git/MSWPackages/main/<path>
Substitute 
github.com/.../blob/main/...
with 
raw.githubusercontent.com/.../main/...
for any browsing URL.
https://raw.githubusercontent.com/MSW-Git/MSWPackages/main/<path>
将任何浏览URL中的
github.com/.../blob/main/...
替换为
raw.githubusercontent.com/.../main/...
即可获取原始文件。

Integration Workflow

集成流程

After the user confirms integration:
  1. Map files into project layout:
    • 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/
      (reuse if already present)
  2. Check UUID collisions: every entity 
    id
    and 
    EntryKey
    in incoming 
    .ui
    /
    .model
    files must not already exist in the user's project. 
    grep
    the workspace for collisions before writing. Regenerate any colliding UUID with a fresh hex UUID.
  3. Check sprite RUID dependencies: scan the package files for hard-coded RUIDs. They reference MSW community resources — usually fine, but verify with 
    msw-search
    if any look suspicious or you need a substitute.
  4. Resolve cross-package dependencies: some packages depend on others (e.g. ranking may build on player-data). Read the package's README and source headers — install transitive packages first, then this one.
  5. Apply with the standard MSW workflow: 
    stop
    → 
    refresh_workspace
    → 
    play
    . Verify in build logs and runtime logs.
  6. Wire into user's code: most packages expose a 
    _<PackageName>
    Logic singleton. Call its API from the user's existing scripts (e.g. 
    _MaplestoryToast:Show(...)
    ).
用户确认集成后：
  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
    必须不存在于用户项目中。写入前先在工作区中搜索冲突。对冲突的UUID重新生成新的十六进制UUID。
  3. 检查精灵RUID依赖：扫描包文件中的硬编码RUID。它们引用MSW社区资源——通常可以正常使用，但如果看起来可疑或需要替换，请使用
    msw-search
    验证。
  4. 解决跨包依赖：部分包依赖其他包（例如排行榜可能基于玩家数据包构建）。阅读包的README和源码头部——先安装依赖包，再安装当前包。
  5. 按标准MSW流程应用：
    stop
    → 
    refresh_workspace
    → 
    play
    。在构建日志和运行时日志中验证。
  6. 接入用户代码：大多数包会暴露
    _<PackageName>
    逻辑单例。从用户现有脚本中调用其API（例如
    _MaplestoryToast:Show(...)
    ）。

Pitfalls

注意事项

  • .modpackage
    files are NOT auto-installer scripts in this workflow     — they are Maker-editor metadata. Manual file copy is what actually integrates the package.
  • Hardcoded sprite RUIDs in samples: package samples often reference specific RUIDs for decoration sprites. These work but the user may want to substitute. Note this when summarizing.
  • UI files use UIGroup root entities — when copying, route through 
    msw-ui-system
    (
    UIBuilder.read/load
    to inspect, builder API to mutate; design rules — UIGroup root configuration, anchor mode pitfalls — live in the same skill). Do not hand-edit raw 
    .ui
    JSON.
  • Sample/
    content is illustrative, not production     — do not copy 
    Sample/
    files unless the user explicitly asks. Sample scripts often bind to keyboard shortcuts that conflict with the user's controls.
  • No package replaces understanding of mlua — packages provide pre-built features but the user still needs 
    msw-scripting
    knowledge to extend them.
  • Don't bulk-install multiple packages speculatively — each integration adds files and surface area. Install one feature at a time, validate, then move on.
  • 此流程中
    .modpackage
    文件不是自动安装脚本——它们是Maker编辑器元数据。实际集成需手动复制文件。
  • 示例中的硬编码精灵RUID：包的示例通常引用特定RUID作为装饰精灵。这些可以正常使用，但用户可能希望替换。总结时需注意这一点。
  • UI文件使用UIGroup根实体——复制时需通过
    msw-ui-system
    （使用
    UIBuilder.read/load
    检查，使用构建器API修改；设计规则——UIGroup根配置、锚点模式注意事项——均在此技能中）。请勿手动编辑原始
    .ui
    JSON。
  • Sample/
    内容仅作演示，非生产可用——除非用户明确要求，否则不要复制
    Sample/
    文件。示例脚本通常绑定到与用户控件冲突的键盘快捷键。
  • 包无法替代对mlua的理解——包提供预构建功能，但用户仍需掌握
    msw-scripting
    知识以扩展功能。
  • 请勿批量安装多个包——每个集成都会增加文件和功能范围。一次安装一个功能，验证后再进行下一步。

When the user has already chosen "build from scratch"

当用户选择「从零构建」时

Skip integration entirely. Proceed with normal MSW authoring (
msw-scripting
, 
msw-search
, etc.). Do not silently keep nudging toward packages.
完全跳过集成。继续常规MSW开发（
msw-scripting
、
msw-search
等）。请勿反复暗示使用包。

When 
MSW-Git/MSWPackages
is unreachable

当
MSW-Git/MSWPackages
无法访问时

  • WebFetch returns an error or 404 → confirm the URL hasn't changed.
  • Sandboxed network may block direct 
    curl
    to 
    api.github.com
    — prefer 
    WebFetch
    for raw and HTML URLs.
  • If everything fails, fall back to building from scratch and tell the user the package is currently inaccessible.
  • WebFetch返回错误或404 → 确认URL未更改。
  • 沙箱网络可能阻止直接
    curl
    访问
    api.github.com
    → 优先使用
    WebFetch
    获取原始URL和HTML URL。
  • 如果所有方法都失败，回退到从零构建并告知用户当前包无法访问。

Cross-references

交叉引用

  • msw-general
    — workspace, file paths, MCP tools, coordinate systems.
  • msw-scripting
    — 
    .mlua
    syntax for hooking package APIs into game logic.
  • msw-search
    — sprite/animation/sound RUID lookup when substituting package-bundled resources.
  • msw-general
    ——工作区、文件路径、MCP工具、坐标系。
  • msw-scripting
    ——将包API接入游戏逻辑的
    .mlua
    语法。
  • msw-search
    ——替换包捆绑资源时的精灵/动画/音效RUID查找。