se-dev-plugin

SE Dev Plugin 技能

Space Engineers 版本 1 的插件开发。

⚠️ 关键：命令在 UNIX shell 中运行。请使用 bash 语法。在 Windows 上使用 BusyBox；在 Linux 上使用原生 shell。

示例：

• ✅ test -f file.txt && echo exists
• ✅ ls -la | head -10
• ❌ if exist file.txt (echo exists) - 无法运行

操作：

• prepare：运行一次性准备步骤（Windows 上运行 Prepare.bat，Linux 上运行 prepare.sh）
• bash：通过 busybox 运行 UNIX shell 命令
• search：使用 search_plugins.py 搜索插件代码

路由判定

按顺序检查以下模式——匹配到的第一个模式优先：

优先级	模式	示例	路由
1	空调用或不带参数的调用	se-dev-plugin	显示帮助
2	准备相关关键字	se-dev-plugin prepare、se-dev-plugin setup、se-dev-plugin init	prepare
3	Bash/shell 相关关键字	se-dev-plugin bash、se-dev-plugin grep、se-dev-plugin cat	bash
4	搜索相关关键字	se-dev-plugin search、se-dev-plugin find class、se-dev-plugin lookup	search

开始使用

⚠️ 关键：运行任何命令之前，请先阅读 CommandExecution.md，以避免导致命令失败的常见错误。

如果此文件夹中缺少 Prepare.DONE 文件，则必须先运行一次性准备步骤。请参阅 prepare 操作。

核心文档

• CommandExecution.md - ⚠️ 请先阅读此文档 - Windows 命令执行详情；在 Linux 上请保留 bash 语法并使用 prepare.sh

插件开发文档

请阅读相应文档以了解更多详情：

• Plugin.md 插件开发（客户端和服务端共用技能）
• ClientPlugin.md 客户端插件开发（适用于客户端）
• ServerPlugin.md 服务端插件开发（适用于服务端）
• se-dev-plugin-guide 技能：用于回答有关插件开发流程的一般问题（模板、本地测试、清单 XML、提交到 hub）。
• Publicizer.md 如何使用 Krafs publicizer 访问原始游戏代码中的内部、受保护或私有成员（可选）。
• OtherPluginsAsExamples.md 如何查看其他插件的源代码并将其用作示例。

Harmony 补丁文档

Harmony 补丁的渐进式文档（先了解基础知识，再按需阅读进阶主题）：

1. Patching.md - 从这里开始：补丁类型、前缀/后缀基础知识、常见模式
2. PatchInjections.md - 特殊参数：__instance、__result、___fields、__state
3. AccessTools.md - 用于查找方法、字段和类型的反射工具
4. TranspilerPatching.md - 用于复杂修改的 IL 级补丁
5. PatchingSpecialCases.md - Finalizer、反向补丁、辅助方法、优先级
6. PreloaderPatching.md - JIT 前补丁（Mono.Cecil，仅限客户端）

目标：客户端和服务器

插件面向以下一项或两项：

• 客户端 — 在游戏客户端内运行，由 Pulsar 加载，并发布到 PluginHub。
• 服务器 — 在专用服务器内运行，由 Magnetar 加载，并发布到 MagnetarHub。服务器插件通过 Magnetar 的 PluginSdk 声明配置；为此请使用 se-dev-plugin-sdk 技能。管理员通过 Quasar（Magnetar 控制平面）远程配置服务器插件。

仅面向客户端的插件使用客户端插件模板。需要服务器端配套插件（或仅面向服务器）的插件使用服务器插件模板，该模板包含 ClientPlugin 目标、ServerPlugin 目标和 Shared 项目。请参阅 ServerPlugin.md。

插件分发

客户端插件仅在 PluginHub 上发布。所有客户端插件都必须开源，因为它们会在玩家的计算机上，根据 PluginHub 注册信息指定的 GitHub 源代码版本进行编译。提交的插件会接受安全性审核，但审核仅尽力而为，不提供任何法律保证。插件运行原生代码，可以执行任何操作。

使用模板创建的插件会在两个位置设置版本。每次发布时都要同时更新两处：Version.Build.props 中的 <Version>，以及 Plugin.cs 中的 AssemblyVersion 和 AssemblyFileVersion 属性（客户端插件位于 ClientPlugin/Plugin.cs，服务器插件位于 ServerPlugin/Plugin.cs）。本地构建会定义 LOCAL_BUILD，并从 Version.Build.props 获取版本。Pulsar 和 Magnetar 编译源代码时不会定义 LOCAL_BUILD，因此游戏和服务器中显示的版本来自这些属性。如果只更新了 Version.Build.props，显示的仍会是旧版本。

使用 se-dev-game-code 阅读你调用或修改的确切代码。如果安装了 se-dev-game-book 手册，请先阅读它，了解游戏系统的工作方式以及涉及的类型；如果未安装，也要搜索游戏代码来了解这些内容。服务器插件同样使用 se-dev-server-code 和 se-dev-server-book。

Graphify 图

准备过程会为下载的插件源代码在 Data/Sources（或 SE_DEV_PLUGIN_PROJECT_ROOT）下构建单独的 Graphify 图。使用快速 Rust 聚类后端时（通过 uv 使用 Python 3.12，自动配置），准备过程会自动构建此图；这个代码库规模较小，因此无论如何构建都很快。若快速后端不可用，则需要通过 SE_DEV_GRAPHIFY=1 选择启用；SE_DEV_GRAPHIFY=0 可禁用此功能。按需阅读——常规搜索时可跳过：通过 GraphifyPrepare.md 构建，通过 GraphifyUsage.md 查询。

参考资料

• Pulsar Space Engineers 游戏客户端的插件加载器
• Pulsar Installer Windows 版 Pulsar 安装程序
• PluginHub Pulsar 的公共插件注册表
• Magnetar Space Engineers 专用服务器的插件加载器
• MagnetarHub Magnetar 的公共插件注册表

插件注册表

会同时搜索两个注册表，它们都使用相同的 GitHub 插件 XML 架构：

• PluginHub — 客户端插件（Pulsar）。较早的条目会将 Owner/Repo 放在 <Id> 中；较新的条目使用 GUID 作为 <Id>，并将 GitHub 仓库放在 <RepoId> 中。
• MagnetarHub — 服务端插件（Magnetar）。<Id> 是 GUID；GitHub 仓库位于 <RepoId> 中。

准备阶段会将两个注册表克隆到 Data/PluginHub 和 Data/MagnetarHub。使用 uv run download_pluginhub.py 和 uv run download_magnetarhub.py 刷新它们。若要使用本地 注册表检出目录替代（或补充）克隆的注册表，请将 SE_PLUGIN_REGISTRY_DIR 设置为注册表根目录（其中包含 Plugins/*.xml 的文件夹）。 list_plugins.py、download_plugin_source.py 和索引器会读取所有已配置的注册表；list_plugins.py 会为每个条目标记 [PluginHub] 或 [MagnetarHub]。

插件代码搜索

搜索任一注册表中插件的源代码，以查找示例和模式：

# List available plugins (tagged by registry), or search them
uv run list_plugins.py
uv run list_plugins.py --search "camera"

# Download a plugin's source (use the EXACT name, GUID/Id, or Owner/Repo from the list); skip the ones listed as [LOCAL]
uv run download_plugin_source.py "Tool Switcher"
uv run download_plugin_source.py CometWorks/essentials

# Index downloaded plugins (automatic after download)
uv run index_plugins.py

# Search plugin code
uv run search_plugins.py class declaration Plugin
uv run search_plugins.py method signature Patch

# Count results before viewing (useful for large result sets)
uv run search_plugins.py class usage Plugin --count

# Limit number of results
uv run search_plugins.py class usage IPlugin --limit 20

注册表包含所有可用插件的说明。下载可能对你的任务有所帮助的插件源代码，然后为其建立索引并进行搜索。

完整文档请参阅搜索操作。

操作参考

请按照以下详细说明操作：

• 准备操作 - 一次性准备
• bash 操作 - 通过 busybox 运行 UNIX shell 命令
• 搜索操作 - 搜索插件代码以查找示例

备注

此技能的原始来源：https://github.com/CometWorks/skills