se-dev-script

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SE Dev Script Skill

SE 开发脚本技能

In-game (programmable block, aka PB) script development for Space Engineers version 1.

⚠️ CRITICAL: Commands run in a UNIX shell. Use bash syntax. On Windows this is BusyBox; on Linux use the native shell.

Examples:

✅
```
test -f file.txt && echo exists
```
✅
```
ls -la | head -10
```
❌
```
if exist file.txt (echo exists)
```
- This will NOT work

Actions:

prepare: Run the one-time preparation (
```
Prepare.bat
```
on Windows,
```
prepare.sh
```
on Linux)
bash: Run UNIX shell commands via busybox
search: Search script code using
```
search_scripts.py
```

适用于《太空工程师》（Space Engineers）版本1的游戏内可编程方块（简称PB）脚本开发。

⚠️ 重要提示：命令在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_scripts.py
```
搜索脚本代码

Routing Decision

路由规则

Check these patterns in order - first match wins:

Priority	Pattern	Example	Route
1	Empty or bare invocation	`se-dev-script`	Show this help
2	Prepare keywords	`se-dev-script prepare` , `se-dev-script setup` , `se-dev-script init`	prepare
3	Bash/shell keywords	`se-dev-script bash` , `se-dev-script grep` , `se-dev-script cat`	bash
4	Search keywords	`se-dev-script search` , `se-dev-script find class` , `se-dev-script lookup`	search

按顺序检查以下模式，匹配到第一个即生效：

优先级	模式	示例	路由目标
1	空调用或仅执行命令名	`se-dev-script`	显示本帮助文档
2	包含prepare相关关键词	`se-dev-script prepare` , `se-dev-script setup` , `se-dev-script init`	prepare
3	包含bash/shell相关关键词	`se-dev-script bash` , `se-dev-script grep` , `se-dev-script cat`	bash
4	包含search相关关键词	`se-dev-script search` , `se-dev-script find class` , `se-dev-script lookup`	search

Getting Started

快速开始

⚠️ CRITICAL: Before running ANY commands, read CommandExecution.md to avoid common mistakes that cause command failures.

If the

Prepare.DONE

file is missing in this folder, you MUST run the one-time preparation steps first. See the prepare action.

⚠️ 重要提示：在运行任何命令前，请阅读CommandExecution.md以避免导致命令失败的常见错误。

如果此文件夹中缺少

Prepare.DONE

文件，您必须先执行一次性准备步骤。请查看prepare操作文档。

Essential Documentation

核心文档

CommandExecution.md - ⚠️ READ THIS FIRST - Windows command execution details; on Linux keep bash syntax and use
```
prepare.sh
```

CommandExecution.md - ⚠️ 请先阅读此文档 - Windows系统命令执行细节；Linux系统请保持bash语法并使用
```
prepare.sh
```

Script Development

脚本开发

Use only names matching the PB API whitelist: PBApiWhitelist.txt The whitelist was exported from game version

1.208.015

using MDK2's

Mdk.Extractor

In-game (PB) scripts are released on the Steam Workshop or Mod.IO, mostly on the former. In-game scripts are compiled by the game on loading into the PB or world loading (if the PB has a script loaded) with a PB Script API whitelist enforced, which is supposed to guarantee safety and security. Scripts cannot crash the game, since any exception is caught and the script is killed by the game. Scripts can still lag the game if no specific resource usage enforcement is set up by the player or server admin.

The script's source code size is limited to 100,000 bytes when the player loads it. The ScriptDev plugin can load more from local file into offline (local) games for testing purposes, therefore scripts can be tested without source code compression, which is useful to get fully detailed exception tracebacks.

Use the

se-dev-game-code

skill to search the game's decompiled code. You may need this to understand how the game's internals work and how to script it properly. Stick to game code searches corresponding to names on the PB API whitelist for efficiency.

仅使用与PB API白名单匹配的名称：PBApiWhitelist.txt 该白名单是使用MDK2的

Mdk.Extractor

从游戏版本

1.208.015

导出的。

游戏内（PB）脚本发布在Steam Workshop或Mod.IO平台，其中大部分发布在前者。游戏内脚本会在加载到PB或加载世界时（如果PB已加载脚本）由游戏编译，并且会强制执行PB Script API白名单，以保障安全性。

脚本不会导致游戏崩溃，因为任何异常都会被捕获，游戏会终止该脚本的运行。

如果玩家或服务器管理员未设置特定的资源使用限制，脚本仍可能导致游戏卡顿。

玩家加载脚本时，脚本源代码大小限制为100,000字节。ScriptDev插件可以从本地文件加载更大的脚本到离线（本地）游戏中进行测试，因此无需压缩源代码即可测试脚本，这有助于获取完整详细的异常回溯信息。

使用

se-dev-game-code

技能搜索游戏的反编译代码。您可能需要通过它来了解游戏内部机制以及如何正确编写脚本。为提高效率，请仅搜索与PB API白名单中名称对应的游戏代码。

Folder Structure

文件夹结构

```
Data/
```
— junction/symlink to the per-user persistent script data folder (
```
%USERPROFILE%\.se-dev\script
```
on Windows,
```
~/.se-dev/script
```
on Linux). Persistent skill data lives here:
- ```
Data/scripts.json
```
  — quick inventory of all installed PB scripts.
- ```
Data/script_hashes.json
```
  — per-script aggregate sha1 used by the indexer for change detection.
- ```
Data/CodeIndex/
```
  — full Tree-sitter C# index (one CSV per category, plus hierarchy trees).
```
LocalScripts/
```
— junction/symlink to the game's local-script folder (
```
%AppData%\SpaceEngineers\IngameScripts\local
```
on Windows, the Proton appdata equivalent on Linux), the game's local-PB-script folder.
Steam Workshop content is read in-place from the Steam folder; it is not copied or symlinked into the skill. PB scripts are detected by the presence of a top-level
```
Script.cs
```
file inside each numeric workshop folder. The workshop folder is resolved from
```
SE_GAME_ROOT
```
(env var) or the Steam registry entry for app id 244850.

```
Data/
```
— 指向每个用户的持久化脚本数据文件夹的连接/符号链接（Windows系统为
```
%USERPROFILE%\.se-dev\script
```
，Linux系统为
```
~/.se-dev/script
```
）。持久化技能数据存储在此处：
- ```
Data/scripts.json
```
  — 所有已安装PB脚本的快速清单。
- ```
Data/script_hashes.json
```
  — 每个脚本的聚合sha1值，供索引器用于检测变化。
- ```
Data/CodeIndex/
```
  — 完整的Tree-sitter C#索引（每个类别对应一个CSV文件，加上层次树）。
```
LocalScripts/
```
— 指向游戏本地脚本文件夹的连接/符号链接（Windows系统为
```
%AppData%\SpaceEngineers\IngameScripts\local
```
，Linux系统为Proton对应的appdata路径），即游戏的本地PB脚本文件夹。
Steam Workshop内容直接从Steam文件夹读取；不会复制或创建符号链接到本技能中。PB脚本通过每个数字 workshop 文件夹中的顶级
```
Script.cs
```
文件来识别。workshop文件夹路径从环境变量
```
SE_GAME_ROOT
```
或Steam注册表中应用ID为244850的条目解析而来。

References

参考资源

Script Template repo PB script template repository to start a new project. See ScriptTemplate.md
Script Merge tool Merging PB scripts from C# projects into single file with optional code compression. See ScriptMerge.md
Script Dev plugin Automatic script loading into the PB in-game for easier testing. See ScriptDev.md
Mod Development Kit (MDK2)
Programmable Block API
Wiki on Scripting

脚本模板仓库用于启动新项目的PB脚本模板仓库。请查看ScriptTemplate.md
脚本合并工具将C#项目中的PB脚本合并为单个文件，支持可选代码压缩。请查看ScriptMerge.md
脚本开发插件自动将脚本加载到游戏内的PB中，便于测试。请查看ScriptDev.md
模组开发工具包（MDK2）
可编程方块API
脚本编写维基

Script Code Search

脚本代码搜索

Search the source code of Steam and local PB scripts for examples and patterns:

bash

undefined

搜索Steam和本地PB脚本的源代码，查找示例与模式：

bash

undefined

Search for patterns

uv run search_scripts.py class declaration Program uv run search_scripts.py method usage Main uv run search_scripts.py class children MyGridProgram

Count results before viewing (useful for large result sets)

uv run search_scripts.py class usage Program --count

Limit number of results

uv run search_scripts.py class usage GridTerminalSystem --limit 30


Before searching, ensure the index exists. If `Data/CodeIndex/` is missing, run:
```bash
uv run list_scripts.py     # quick inventory (always cheap)
uv run index_scripts.py    # full code index (incremental: only changed scripts reparsed)

Re-indexing after new subscriptions: When you subscribe to new scripts on Steam Workshop, load them in a world once (so the game downloads them), then re-run the two commands above (or just

Prepare.bat

). The indexer hashes each script's .cs files and only reparses scripts whose hash changed since the previous run, so reruns are fast.

See search action for complete documentation.

uv run search_scripts.py class usage GridTerminalSystem --limit 30


搜索前，请确保索引已存在。如果`Data/CodeIndex/`缺失，请运行：
```bash
uv run list_scripts.py     # quick inventory (always cheap)
uv run index_scripts.py    # full code index (incremental: only changed scripts reparsed)

订阅新脚本后重新索引： 当您在Steam Workshop订阅新脚本后，在世界中加载一次（以便游戏下载它们），然后重新运行上述两个命令（或仅运行

Prepare.bat

）。索引器会对每个脚本的.cs文件进行哈希计算，仅重新解析自上次运行以来哈希值发生变化的脚本，因此重新运行速度很快。

完整文档请查看search操作文档。

Action References

操作参考

Follow the detailed instructions in:

prepare action - One-time preparation
bash action - Running UNIX shell commands via busybox
search action - Search script code for examples

请遵循以下文档中的详细说明：

prepare操作文档 - 一次性准备操作
bash操作文档 - 通过busybox运行UNIX shell命令
search操作文档 - 搜索脚本代码示例

Remarks

备注

The original source of this skill: https://github.com/viktor-ferenczi/se-dev-skills

本技能的原始来源：https://github.com/viktor-ferenczi/se-dev-skills