快速开始
基础环境
| 项目 | 说明 |
|---|---|
| Python 版本 | 3.12.2（动态链接：Program.exe 同目录带 python312.dll / python3.dll，标准库随 python312\ 目录提供） |
| 语法 | 使用 Python 3 语法 |
| 开发模式 | source 模式（源码）—— 修改 .py 文件后自动热重载 |
| 发布模式 | MCP 模式（遗留，仅 source 模式受支持） |
| Python 运行时 | python312\（标准库在 python312\Lib\，第三方包在 python312\Lib\site-packages\），由 exe 的 PYTHONHOME=<exe目录>\python312 定位 |
| 插件目录 | ./scripts —— 默认插件目录，每个插件一个子目录；可用 --PluginDir <路径> 改 |
不要修改 source/
source/ 是 Vector 的框架脚本目录。你的代码放插件目录 scripts/（或 --PluginDir 指定的目录）。
装第三方库
Vector 随包带完整 Python 3.12 标准库（python312\Lib\）。如需第三方库：
bash
# 用系统里同版本的 Python 3.12 的 pip 安装到 Vector 的 site-packages：
pip install requests --target "Vector\python312\Lib\site-packages"
pip install numpy --target "Vector\python312\Lib\site-packages"纯 Python 包（py3-none-any）同样照此安装，或者直接把目录复制进 python312\Lib\site-packages\。插件里直接 import 即可。
官方平台 wheel 可以直接用
解释器就是标准的 python312.dll，所以带平台 tag 的 wheel（numpy、Pillow、lxml 这类 cp312-...-win_amd64）能正常 import。只要 cp312 里的 312 与嵌入的 解释器一致（当前 3.12.2）即可。
细节见 Python 运行时与扩展。
插件目录结构
text
scripts/
my_plugin/ ← 插件根目录（与内层包名一致）
redirect.py ← MCP 导入钩子（source 模式可为空文件）
my_plugin/ ← 实际 Python 包
__init__.py ← 插件入口（必须，加载时自动执行）
other_module.py ← 其他模块（可选）
utils/ ← 子包（可选）
__init__.py命名规则：
- 插件根目录名 = 内层包名 = 插件名，三者必须一致
__init__.py是插件入口，加载时自动执行redirect.py只在 MCP 模式下生效，source 模式可以放空文件- 不要在插件根目录放
__init__.py，否则会和内层包冲突
一个最小插件：
python
# scripts/my_plugin/my_plugin/__init__.py
def on_start(args):
print('MyPlugin loaded!')
engine.message('', 'Hello, world!')
engine.register(on_start, "ModEventStartUp")加载流程
text
start_game 事件
→ init.py 调用 load_all_plugins()
→ 扫描 scripts/ 下的插件目录
→ 将插件根目录加入 sys.path
→ __import__('插件名') 执行 __init__.py
→ 触发 ModEventStartUp 事件（所有插件加载完成）热重载
开发阶段（source 模式）自带文件监视：
- 每 1.5 秒扫描
scripts/下所有.py文件的修改时间 - 只重载有修改的那个插件，不影响其他插件
- 保存文件即生效，无需手动操作
单插件重载流程：
text
1. 调用插件的 on_uninit()（如果实现了）
2. 精准注销该插件注册的所有事件
3. importlib.reload() 重新执行插件代码全量重载：
python
engine.trigger("reload") # 或 engine.trigger("mod_reload")text
1. 触发 ModEventUnInit 事件（所有插件收到）
2. engine.cleanup_user() 清除所有用户事件
3. engine.clear_all_user_protocol_event() 清除所有用户协议事件
4. 逐个 reload() 所有已加载插件
5. 触发 ModEventStartUp 事件也可以在 Python 层调用：
python
import init
init.reload_plugin("my_plugin") # 重载指定插件
init.reload_all_plugins() # 重载所有插件有后台线程就必须实现 on_uninit()
否则重载时会崩溃 —— 旧线程还在跑，引用的模块对象已经被卸载了。 见代码模板 · 线程与资源。