SimpleLauncher 使用文档

SimpleLauncher 的完整中文产品使用文档

兼容性

Unreal Engine 5.2–5.8
版本 1.1.0（Version 2）

快速开始

只需两步从游戏中启动外部程序：

步骤 1：配置预设

打开 项目设置 → Plugins → Simple Launcher，在 Launchers 中添加预设：

设置 Key 为预设名称，如 MyServer
设置 CommandLine 为要执行的命令，如 notepad.exe 或 python script.py

步骤 2：调用 API 启动

从蓝图或 C++ 调用：

FProcessId Id = USimpleLauncherGameSubsystem::StartProcess(FName("MyServer"));

程序将启动。当游戏退出时，插件会自动关闭它。

配置

每个预设包含以下设置：

Key（预设名称）

此预设的名称。所有 API 通过此名称引用预设。

使用任意名称，如 MyServer、Logger、DataSync
名称在所有预设中必须唯一

CommandLine

要执行的完整命令，包括程序路径和参数。

notepad.exe file.txt
"C:\Program Files\app.exe" -port 8080
'/usr/bin/app' -arg

如果路径包含空格，必须用引号包裹程序路径，否则解析会失败。

bLaunchHidden

是否隐藏程序窗口。默认为 false（窗口可见）。

设为 true：程序在后台运行，无可见窗口
适用于不需要用户交互的后台服务或工具

bLaunchDetached

控制游戏退出时是否关闭程序。默认为 false（随游戏关闭）。

false（默认）：游戏退出时自动关闭程序——适用于游戏服务器、临时工具
true：游戏退出后程序继续运行——适用于日志收集器或其他持久服务

WorkingDirectory

程序的工作目录。默认为空（使用游戏的工作目录）。

使用绝对路径，如 C:\MyApp 或 /home/user/app
程序使用的相对路径将基于此目录解析

API 参考

所有 API 都是 USimpleLauncherGameSubsystem 上的静态函数，可从蓝图和 C++ 调用。

配置管理

函数	说明
`UpdateConfig(Name, Config, bOverrideIfExists, bCreateIfNotExists)`	创建或更新预设
`GetConfig(Name, OutConfig)`	获取预设配置
`GetAllConfig()`	获取所有预设
`RemoveConfig(Name)`	移除预设（同时停止其所有进程）

UpdateConfig 有两个可选参数用于精确控制：

参数	默认值	说明
`bOverrideIfExists`	`true`	预设已存在时是否覆盖。设为 `false` 防止意外覆盖
`bCreateIfNotExists`	`true`	预设不存在时是否创建。设为 `false` 仅更新现有预设

除了在项目设置中配置预设，也可以在运行时动态创建：

FLauncherConfig Config;
Config.CommandLine = TEXT("python script.py");
Config.bLaunchHidden = true;
USimpleLauncherGameSubsystem::UpdateConfig(FName("TempTask"), Config);

运行时创建的预设在游戏重启后丢失。持久预设请在项目设置中配置。

进程控制

函数	说明
`StartProcess(Name)`	启动进程，返回 ProcessId
`StopProcess(ProcessId)`	停止单个进程
`StopProcesses(Name)`	停止预设的所有进程
`StopAllProcesses()`	停止所有进程

可以对同一预设多次调用 StartProcess。每次调用启动新进程并返回不同的 ProcessId：

FProcessId Id1 = USimpleLauncherGameSubsystem::StartProcess(FName("MyServer"));
FProcessId Id2 = USimpleLauncherGameSubsystem::StartProcess(FName("MyServer"));
// Id1 和 Id2 是两个独立运行的进程

状态查询

函数	说明
`IsProcessRunning(ProcessId)`	检查特定进程是否仍在运行
`HasRunningProcesses(Name)`	检查预设是否有运行中的进程
`GetProcessCount(Name)`	获取预设的运行进程数
`GetProcesses(Name)`	获取预设所有运行中的 ProcessId

进程退出回调

进程退出时获得通知并执行自定义逻辑（如重启、日志记录）。

函数	说明
`BindProcessExited(ProcessId, Delegate)`	监听特定进程退出
`UnbindProcessExited(ProcessId, Delegate)`	停止监听特定进程
`BindProcessesExited(Name, Delegate)`	监听预设下所有进程退出
`UnbindProcessesExited(Name, Delegate)`	停止监听预设

回调接收两个参数：

ProcessId — 哪个进程退出了
bNaturalExit — 退出原因：true 表示程序自行终止，false 表示被代码停止

回调触发时机：

场景	触发回调	bNaturalExit
程序自行完成或崩溃	是	true
通过 StopProcess 停止	是	false
通过 StopProcesses 停止	是	false
通过 RemoveConfig 停止	是	false
游戏退出时自动清理	否	-

多次绑定相同委托会被静默忽略——不会触发重复回调。

游戏退出时不触发回调，以避免访问已销毁的对象导致崩溃。

注意事项

UpdateConfig 仅更新配置数据，不影响已运行的进程。新配置在下次 StartProcess 调用时生效。
RemoveConfig 在移除前会停止预设的所有进程。但绑定的回调不会被清除——如果重新创建同名预设，它们仍然有效。

平台支持

插件支持 Windows、Linux 和 macOS。底层使用 UE 的 FPlatformProcess::CreateProc，因此操作系统能执行的任何程序都可以启动——没有文件类型限制。

版本历史

打开 编辑 → 项目设置，进入 SimpleLauncher 设置页，将 Language 设置为 English 或中文。默认语言为英文。面向用户的界面、提示、通知和功能日志会立即更新，无需重启编辑器；公开 API 名称以及模块启动/关闭日志始终保持英文。

联系

如有使用问题或合作需求，请前往联系页面。

联系入口： 联系与合作

使用说明补充

SimpleLauncher 使用指南

通过命名预设启动和管理外部程序；同一预设可以运行多个实例。

配置与进程接口

1.1 预设配置系统

插件通过预设（Preset） 管理进程配置：

USTRUCT(BlueprintType)
struct FLauncherConfig
{
    // 完整命令行（可执行文件路径 + 参数）
    FString CommandLine;

    // 隐藏进程窗口
    bool bLaunchHidden = false;

    // 分离运行（true=游戏退出后进程继续运行）
    bool bLaunchDetached = false;

    // 工作目录
    FString WorkingDirectory;
};

可以在项目设置中预先配置多个启动器，每个都有独立的名称：

路径：Edit > Project Settings > Simple Launcher

Launchers:
  "LocalServer"  → "D:/Server/server.exe --port 7777"
  "LogCollector" → "python D:/Tools/log_collector.py"
  "AIService"    → "D:/AI/inference.exe --model gpt"

1.2 进程生命周期管理

启动进程：

// 通过预设名称启动
FProcessId Id = USimpleLauncherGameSubsystem::StartProcess("LocalServer");

停止进程：

// 停止单个进程
StopProcess(ProcessId);

// 停止某个预设的所有实例
StopProcesses("LocalServer");

// 停止所有进程
StopAllProcesses();

自动清理：

当 bLaunchDetached = false（默认）时，插件会在游戏退出时自动终止该进程。设置为 true 的分离进程则会在游戏退出后继续运行。

1.3 多实例支持

同一个预设可以启动多个实例，每个实例都有独立的 FProcessId：

USTRUCT(BlueprintType)
struct FProcessId
{
    FName Name;    // 预设名称
    int32 Index;   // 实例索引（自动递增）
};

// 启动3个本地服务器实例
FProcessId Server1 = StartProcess("LocalServer");  // Index = 0
FProcessId Server2 = StartProcess("LocalServer");  // Index = 1
FProcessId Server3 = StartProcess("LocalServer");  // Index = 2

// 独立管理每个实例
StopProcess(Server2);  // 只停止第二个
IsProcessRunning(Server1);  // 检查第一个是否在运行
GetProcessCount("LocalServer");  // 返回 2（还剩两个在运行）

1.4 进程退出回调

插件通过 Tick 轮询检测进程状态，支持两种粒度的退出通知：

单个进程回调：

// 监听特定进程的退出事件
BindProcessExited(ProcessId, OnExitDelegate);
// 回调参数：ProcessId, bNaturalExit（true=自然退出，false=被强制停止）

预设级回调：

// 监听某个预设下所有实例的退出事件
BindProcessesExited("LocalServer", OnExitDelegate);

典型用法——自动重启：

OnProcessExited(ProcessId, bNaturalExit):
  if bNaturalExit:
    // 进程意外退出，自动重启
    StartProcess(ProcessId.Name)

1.5 运行时配置管理

除了编辑器中的静态配置，插件还支持运行时动态管理：

// 运行时更新配置
UpdateConfig("DynamicServer", NewConfig, true, true);

// 查询配置
GetConfig("LocalServer", OutConfig);

// 获取所有配置
GetAllConfig();

// 删除配置（同时停止该预设的所有进程）
RemoveConfig("OldServer");

1.6 智能命令行解析

插件自动处理带引号的路径和参数分割：

// 支持带空格的路径
"C:/Program Files/MyApp/app.exe" --port 8080

// 也支持不带引号的简单路径
D:/Tools/server.exe --config default

调用示例

场景1：随游戏启动本地服务器

1. 项目设置中配置预设 "LocalServer"
   CommandLine: "D:/Server/dedicated_server.exe -port=7777"
   bLaunchHidden: true
   bLaunchDetached: false  // 游戏退出时自动关闭

2. 游戏启动时：
   StartProcess("LocalServer")

3. 游戏退出时：
   插件自动终止服务器进程

场景2：后台数据处理

1. 配置 Python 脚本预设
   CommandLine: "python D:/Scripts/data_processor.py --input data.json"
   bLaunchHidden: true

2. 需要时启动：
   FProcessId Id = StartProcess("DataProcessor")
   BindProcessExited(Id, OnDataProcessed)

3. 脚本完成后自动触发回调

场景3：多服务器集群测试

// 启动多个服务器实例
for i in 0..4:
    StartProcess("TestServer")

// 查询运行状态
GetProcessCount("TestServer")  // 5

// 测试完成后一键停止
StopProcesses("TestServer")

安装与使用

步骤1：安装插件

将插件文件夹复制到项目的 Plugins 目录，重启编辑器。

步骤2：配置预设

路径：Edit > Project Settings > Simple Launcher

添加你需要的启动器配置。

步骤3：蓝图中使用

所有函数都在 SimpleLauncher 分类下，核心流程：

1. StartProcess("预设名") → 获得 ProcessId
2. IsProcessRunning(ProcessId) → 检查状态
3. BindProcessExited(ProcessId, Callback) → 监听退出
4. StopProcess(ProcessId) → 手动停止

生命周期注意事项

bLaunchDetached 为 false 时，游戏退出会清理由该配置启动的进程；为 true 时进程可继续运行。根据外部程序的用途选择设置，避免在停止测试时关闭仍需运行的程序。