Skip to content

快速开始 ​

基础环境 ​

项目说明
Python 版本3.12.2(解释器核心静态链在 Program.exe 里,exe 旁没有 python312.dll)
语法使用 Python 3 语法
开发模式source 模式(源码)—— 修改 .py 文件后自动热重载
发布模式MCP 模式(遗留,仅 source 模式受支持)
Python 运行时source/Lib/(标准库 + site-packages/),由 exe 的 PYTHONHOME=<exe>\source 定位
插件目录scripts/ —— 所有插件均放在此目录下

不要修改 source/

source/ 是 Vector 运行环境(框架脚本 + 标准库)。你的代码放 scripts/。

装第三方库 ​

Vector 内置完整 Python 3.12 标准库。如需第三方库:

bash
# 用系统 Python 的 pip 安装到 Vector 的 site-packages:
pip install requests --target "Vector\source\Lib\site-packages"

或直接把纯 Python 包复制到 source/Lib/site-packages/。插件里直接 import 即可。

只支持纯 Python 包

wheel 文件名形如 py3-none-any 的才可以。带平台 tag 的包(numpy、Pillow、lxml 这类 cp312-...-win_amd64 wheel)装进去也无法 import —— 解释器是静态链接的, 官方 .pyd 加载不了。

原因和绕法见静态链接与扩展限制。

插件目录结构 ​

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()

否则重载时会崩溃 —— 旧线程还在跑,引用的模块对象已经被卸载了。 见代码模板 · 线程与资源。

下一步 ​

第三方库请参阅各自目录下的许可证文件