Disenone's Wiki

Blog

Tue, 17 Feb 2026 04:33:08 +0000

Blog

Tue, 17 Feb 2026 04:32:17 +0000

Blog

Tue, 17 Feb 2026 04:24:38 +0000

Blog

Tue, 17 Feb 2026 04:20:25 +0000

Blog

Tue, 17 Feb 2026 04:16:12 +0000

Blog

Tue, 17 Feb 2026 04:11:54 +0000

Blog

Tue, 17 Feb 2026 04:07:36 +0000

Blog

Tue, 17 Feb 2026 04:03:24 +0000

Blog

Tue, 17 Feb 2026 04:02:34 +0000

Blog

CllamaServer (llama.cpp server)

Thu, 12 Feb 2026 08:03:39 +0000

蓝图篇 - CllamaServer (llama.cpp server)

概述

CllamaServer 是基于 llama.cpp 的 Server 模式实现的，可以在本地启动一个兼容 OpenAI API 的服务器，支持多种功能：

本地推理服务: 在本地启动 AI 推理服务器，无需依赖外部 API
兼容 OpenAI API: 使用 OpenAI 兼容的 API 格式，方便迁移和集成
多会话支持: 支持多个并发请求
Tool Calling: 支持函数调用功能
语音转文字: 支持 Speech-to-Text 功能
可视化管理: 编辑器内置 Server 管理界面

与 Cllama 的区别： * Cllama: 直接在进程内加载模型进行推理，单次只能处理一个请求 * CllamaServer: 启动独立的 HTTP 服务器，可以处理多个并发请求，API 兼容 OpenAI 格式

准备工作

由于是本地运行，需要先准备好离线模型文件，例如从 HuggingFace 下载：Qwen1.5-1.8B-Chat-Q8_0.gguf

把模型放在某个文件夹下面，譬如放在游戏项目的目录 Content/LLAMA 下。

创建 CllamaServer

使用蓝图创建 Server

在蓝图中右键创建节点 Create Cllama Server In World

配置 Server 参数

创建 Cllama Server Param 节点，并配置关键参数：

Model: 模型文件路径（必填）
Port: 服务器端口（0 表示自动分配）
Host: 监听地址，默认 127.0.0.1
NGpuLayers: GPU 层数（-1 表示全部使用 GPU）

绑定回调事件

绑定 Server 的回调事件：

On Started: Server 启动成功时触发
On Stopped: Server 停止时触发
On Failed: Server 启动失败时触发

完整的创建蓝图

完整的 Server 创建蓝图如下：

运行蓝图后，Server 启动成功会触发 On Started 事件。

Server 参数详解

FAIChatPlus_CllamaServerParam 结构体包含以下参数：

常用参数

参数	类型	默认值	说明
Model	FString	-	模型文件路径（必填）
Port	int32	0	监听端口，0 表示自动分配
Host	FString	127.0.0.1	监听地址
NGpuLayers	int32	-1	GPU 层数，-1 表示全部
bUseJinja	bool	false	使用 Jinja 模板
MMProj	FString	-	多模态投影文件路径
Temperature	float	0.8	采样温度

推理参数

参数	类型	默认值	说明
CtxSize	int32	4096	上下文大小
NPredict	int32	-1	预测 Token 数，-1 表示无限
Threads	int32	-1	CPU 线程数，-1 表示自动
BatchSize	int32	2048	批处理大小

采样参数

参数	类型	默认值	说明
TopK	int32	40	Top-K 采样
TopP	float	0.9	Top-P 采样
MinP	float	0.1	Min-P 采样
RepeatPenalty	float	1.0	重复惩罚

服务器参数

参数	类型	默认值	说明
ApiKey	FString	-	API 密钥（可选）
Timeout	int32	600	超时时间（秒）
Parallel	int32	1	并行序列数
bNoWebUI	bool	false	禁用 Web UI
bVerbose	bool	false	详细日志

使用 CllamaServer 进行聊天

创建 Chat Request

Server 启动成功后，可以使用 Send CllamaServer Chat Request 节点发送聊天请求。

配置 Chat Options

创建 CllamaServer Chat Request Options 节点，设置 BaseUrl 为 Server 地址。

可以通过 Get Server Info By ID 节点获取 Server 信息。

创建 Messages

创建 Messages 数组，添加 System Message 和 User Message。

绑定回调处理响应

绑定 On Message 或 On Message Finished 事件来接收模型响应。

完整的聊天蓝图

完整的聊天蓝图如下：

运行结果

运行蓝图，可以看到模型返回的消息显示在屏幕上。

Server 管理

获取 Server 信息

使用 Get Server Info 节点获取 Server 的详细信息。

Server Info 包含以下信息： * ServerID: 服务器唯一 ID * Host: 监听地址 * Port: 监听端口 * Address: 完整地址（host:port） * HttpAddress: HTTP 地址（http://host:port） * bIsRunning: 是否正在运行 * Param: 服务器参数

停止 Server

使用 Stop Server By ID 节点停止当前 Server。

静态管理函数

AIChatPlus 提供了一系列静态函数用于管理所有 Server：

函数	说明
`Is Server Valid (Static)`	检查 Server 是否有效
`Is Server Running (Static)`	检查 Server 是否运行中
`Stop Server By ID`	通过 ID 停止指定 Server
`Stop All Servers`	停止所有 Server
`Get Server Info By ID`	通过 ID 获取 Server 信息
`Get All Server IDs`	获取所有 Server ID
`Get Server By ID`	通过 ID 获取 Server 实例

多模态支持

CllamaServer 支持多模态模型（如 Moondream、Qwen2-VL 等）。

配置多模态参数

在 Server 参数中设置 MMProj（多模态投影文件路径）：

发送图片消息

在 Messages 中添加图片：

Tool Calling

CllamaServer 支持 Tool Calling（函数调用）功能，用法与 OpenAI 类似。

详细用法请参考 Tool Call 文档。

使用 CllamaServer 进行 Tool Call 时，需要： 1. 在 Server 参数中设置 bUseJinja = true 2. 在 Chat Options 的 Tools 字段中定义工具

编辑器 Server 管理

AIChatPlus 在编辑器工具中提供了可视化的 CllamaServer 管理界面，方便创建、监控和管理多个 Server。

打开编辑器工具：Tools -> AIChatPlus -> AIChat，打开 Cllama Server Manager 标签页。

在编辑器中可以： * 创建新的 Server * 查看运行中的 Server 状态 * 停止指定的 Server * 配置 Server 参数 * Server 配置会自动保存

与其他 API 的关系

由于 CllamaServer 兼容 OpenAI API 格式，你也可以使用 OpenAI 的 Chat Request 节点来与 CllamaServer 通信，只需将 BaseUrl 设置为 CllamaServer 的地址即可。

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Json 操作

Thu, 12 Feb 2026 08:03:39 +0000

蓝图篇 - Json 操作

概述

AIChatPlus 提供了完整的 JSON 蓝图操作支持，方便在蓝图中处理 JSON 数据。主要包含三个类：

UAIChatPlus_JsonObject: JSON 对象操作类，用于处理 {} 格式的 JSON
UAIChatPlus_JsonArray: JSON 数组操作类，用于处理 [] 格式的 JSON
UAIChatPlus_JsonLibrary: JSON 工具函数库，提供静态工具函数

这些类支持： * 创建、解析、序列化 JSON * 读取和设置字段值 * 嵌套路径查询 * JSON 与 USTRUCT 互转 * 文件读写 * 链式调用

JsonObject 基础操作

创建 JsonObject

使用 Create Json Object 创建一个空的 JSON 对象：

从字符串解析

使用 Parse Json Object 从 JSON 字符串创建对象：

设置字段值

JsonObject 提供了多种 Set 方法，支持链式调用：

函数	说明
`Set String Field`	设置字符串字段
`Set Number Field`	设置浮点数字段
`Set Integer Field`	设置整数字段
`Set Boolean Field`	设置布尔字段
`Set Object Field`	设置嵌套对象字段
`Set Array Field`	设置数组字段
`Set Null Field`	设置 null 字段

获取字段值

JsonObject 提供了多种 Get 方法：

函数	说明
`Get String Field`	获取字符串字段
`Get Number Field`	获取浮点数字段
`Get Integer Field`	获取整数字段
`Get Boolean Field`	获取布尔字段
`Get Object Field`	获取嵌套对象字段
`Get Array Field`	获取数组字段

字段检查

函数	说明
`Has Field`	检查字段是否存在
`Get Field Type`	获取字段类型
`Get Field Names`	获取所有字段名
`Remove Field`	删除字段
`Clear`	清空所有字段

序列化为字符串

使用 To Json String 将 JsonObject 转换为字符串：

JsonArray 基础操作

创建 JsonArray

使用 Create Json Array 创建一个空的 JSON 数组：

添加元素

JsonArray 提供了多种 Add 方法，支持链式调用：

函数	说明
`Add String`	添加字符串元素
`Add Number`	添加浮点数元素
`Add Integer`	添加整数元素
`Add Boolean`	添加布尔元素
`Add Object`	添加对象元素
`Add Array`	添加数组元素
`Add Null`	添加 null 元素

获取元素

JsonArray 提供了按索引获取元素的方法：

函数	说明
`Get String`	获取字符串元素
`Get Number`	获取浮点数元素
`Get Integer`	获取整数元素
`Get Boolean`	获取布尔元素
`Get Object`	获取对象元素
`Get Array`	获取数组元素

数组操作

函数	说明
`Length`	获取数组长度
`Is Valid Index`	检查索引是否有效
`Get Element Type`	获取元素类型
`Remove At`	删除指定索引的元素
`Clear`	清空数组

批量转换

JsonArray 支持与 UE 数组的批量转换：

函数	说明
`From String Array`	从字符串数组创建
`To String Array`	转换为字符串数组
`From Integer Array`	从整数数组创建
`To Integer Array`	转换为整数数组

路径查询

JsonObject 支持使用点分隔的路径访问嵌套数据，如 player.inventory.gold。

按路径获取值

使用 Get String By Path 按路径获取字符串值：

{
    "player": {
        "name": "Hero",
        "inventory": {
            "gold": 1000
        }
    }
}

按路径设置值

使用 Set String By Path 按路径设置值：

查询结果

路径查询返回 FAIChatPlus_JsonQueryResult 结构，包含：

bSuccess: 查询是否成功
ValueType: 返回值的类型
ErrorMessage: 错误信息（如果失败）

JSON 与 USTRUCT 转换

AIChatPlus 支持 JSON 与 USTRUCT 之间的转换，方便与蓝图结构体配合使用。

JSON 字符串转 USTRUCT

使用 Json String To Struct 将 JSON 字符串直接转换为 USTRUCT：

USTRUCT 转 JSON 字符串

使用 Struct To Json String 将 USTRUCT 转换为 JSON 字符串：

JsonObject 转 USTRUCT

使用 JsonObject 的 To Struct 方法：

USTRUCT 转 JsonObject

使用 From Struct 静态方法从 USTRUCT 创建 JsonObject：

JsonLibrary 工具函数

UAIChatPlus_JsonLibrary 提供了一系列静态工具函数。

快速创建

函数	说明
`Make Json Object With String Field`	快速创建带单个字段的 JsonObject
`Make Json Object From String Map`	从 Map 创建 JsonObject

验证

函数	说明
`Validate Json String`	验证 JSON 字符串是否有效
`Is Json Object`	检查是否为 JSON 对象
`Is Json Array`	检查是否为 JSON 数组

格式化

函数	说明
`Prettify Json`	格式化 JSON（添加缩进换行）
`Minify Json`	压缩 JSON（移除空白）

文件操作

函数	说明
`Load Json Object From File`	从文件加载 JsonObject
`Save Json Object To File`	保存 JsonObject 到文件
`Load Json Array From File`	从文件加载 JsonArray
`Save Json Array To File`	保存 JsonArray 到文件

比较

函数	说明
`Equals Json Object`	比较两个 JsonObject 是否相等
`Equals Json Array`	比较两个 JsonArray 是否相等

高级路径查询

函数	说明
`Query String By Path`	按路径查询字符串（支持数组索引，如 `items[0].name`）
`Query Object By Path`	按路径查询对象
`Query Array By Path`	按路径查询数组

批量操作

函数	说明
`Set String Fields From Map`	批量设置字符串字段
`Get String Fields To Map`	批量获取字符串字段

其他操作

合并 JsonObject

使用 Merge 方法合并两个 JsonObject：

复制 JsonObject

使用 Duplicate 方法深拷贝 JsonObject：

实际应用示例

解析 API 响应

从 AI 聊天响应中提取 Tool Call 的参数：

构建请求参数

使用 JsonObject 构建复杂的请求参数：

配置文件读写

从 JSON 文件加载配置，修改后保存：

类型枚举

EAIChatPlus_JsonValueType 枚举定义了 JSON 值的类型：

枚举值	说明
`None`	未知类型
`Null`	null 值
`String`	字符串
`Number`	数字
`Boolean`	布尔值
`Array`	数组
`Object`	对象

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Tool Call

Thu, 12 Feb 2026 08:03:39 +0000

蓝图篇 - Tool Call

Tool Call（工具调用）也被称为 Function Calling（函数调用），是指大模型可以根据对话内容，判断是否需要调用外部工具/函数来获取信息或执行操作。模型会返回需要调用的函数名称和参数，由开发者执行实际调用后，将结果返回给模型继续对话。

AIChatPlus 支持以下平台的 Tool Call 功能：

OpenAI
Claude
Gemini
Ollama
CllamaServer（llama.cpp server）

核心概念

Tool 定义

Tool 的定义包含以下关键字段：

Type: 工具类型，目前仅支持 Function
Name: 函数名称，必须由 a-z、A-Z、0-9、下划线或连字符组成，最大长度 64
Description: 函数描述，模型会根据此描述判断何时调用该函数
Properties: 函数参数列表，每个参数包含 Name、Description、Type、Required 等属性

Tool Call 流程

Tool Call 的完整流程如下：

发送请求: 向模型发送包含 Tools 定义的聊天请求
模型判断: 模型根据对话内容判断是否需要调用工具
返回 Tool Calls: 如果需要调用，模型返回要调用的函数名和参数
执行函数: 开发者根据返回信息执行实际的函数调用
返回结果: 将函数执行结果作为新消息发送给模型
继续对话: 模型根据函数结果生成最终回复

OpenAI Tool Call 示例

下面以 OpenAI 为例，演示如何使用 Tool Call 功能。

1. 定义 Tool

首先创建 Tool 定义。本例中我们定义一个获取快递包裹送达时间的函数 get_delivery_date。

2. 定义 Tool 参数

为 Tool 添加 Properties（参数）。本例中添加一个 order_id 参数，类型为 string，设置为必填。

3. 配置 Options

创建 OpenAI Chat Request Options 节点，设置 API Key 和 Model，并将 Tools 数组连接到 Options。

4. 创建 Messages

创建用户消息，询问快递包裹相关的问题。

5. 发送请求并处理 Tool Call

创建 Send OpenAI Chat Request In World 节点，绑定 On Message Finished 事件。在事件回调中，从 Payload 获取 ToolCalls 数组。

当模型决定调用工具时，ToolCalls 数组不为空。遍历数组获取每个 Tool Call 的信息：

Id: Tool Call 的唯一标识符
FunctionName: 要调用的函数名
FunctionArguments: 函数参数（JSON 字符串格式）

6. 执行函数并返回结果

根据 FunctionName 执行对应的函数逻辑（本例中模拟获取快递包裹送达时间），然后将结果作为 ToolCallResult 类型的消息返回给模型。

创建新的 Message，需要设置：

Role: 设置为 Tool
Content: 函数执行的结果
ToolCallResults: 添加一个 FAIChatPlus_ChatRequestToolCallResult，设置 Id（使用之前的 Tool Call Id）、FunctionName 和 FunctionResult

7. 继续对话

将包含 ToolCallResult 结果的消息添加到历史消息中，再次发送请求。模型会根据函数返回的结果生成最终的自然语言回复。

高级用法

多个 Tools

可以同时定义多个 Tools，模型会根据需要选择调用哪个或哪些函数。

复杂参数类型

Tool 参数支持多种类型，可以通过 ExtraJsonString 或 ExtraJsonObject 字段添加更复杂的参数定义，例如枚举类型：

{"enum": ["Beijing", "HongKong"]}

其他平台

Claude、Gemini、Ollama 和 CllamaServer 的 Tool Call 用法与 OpenAI 类似，只需替换相应的 Request 和 Options 节点即可。各平台的核心数据结构（FAIChatPlus_ChatRequestTool、FAIChatPlus_ChatResponseToolCall 等）是通用的。

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Claude

Thu, 12 Feb 2026 08:03:39 +0000

Macro Syntax Error

File: zh/ue-插件-AIChatPlus-Usage-Source-Claude.md

Line 250 in Markdown file: expected token 'end of print statement', got ':'

        {{TEXT("What's the weather like in Paris?"), EAIChatPlus_ChatRole::User}});

Cllama(已废弃)

Thu, 12 Feb 2026 08:03:39 +0000

Macro Syntax Error

File: zh/ue-插件-AIChatPlus-Usage-Source-Cllama.md

Line 367 in Markdown file: expected token 'end of print statement', got ':'

        {{TEXT("Write a short poem."), EAIChatPlus_ChatRole::User}});

CllamaServer

Thu, 12 Feb 2026 08:03:39 +0000

Macro Syntax Error

File: zh/ue-插件-AIChatPlus-Usage-Source-CllamaServer.md

Line 672 in Markdown file: expected token 'end of print statement', got ':'

        {{TEXT("Hello!"), EAIChatPlus_ChatRole::User}});

Gemini

Thu, 12 Feb 2026 08:03:39 +0000

Macro Syntax Error

File: zh/ue-插件-AIChatPlus-Usage-Source-Gemini.md

Line 244 in Markdown file: expected token 'end of print statement', got ':'

        {{TEXT("What's the weather like in Tokyo?"), EAIChatPlus_ChatRole::User}});

Ollama

Thu, 12 Feb 2026 08:03:39 +0000

Macro Syntax Error

File: zh/ue-插件-AIChatPlus-Usage-Source-Ollama.md

Line 519 in Markdown file: expected token 'end of print statement', got ':'

        {{TEXT("Hello!"), EAIChatPlus_ChatRole::User}});

OpenAI / Azure

Thu, 12 Feb 2026 08:03:39 +0000

Macro Syntax Error

File: zh/ue-插件-AIChatPlus-Usage-Source-OpenAI.md

Line 218 in Markdown file: expected token 'end of print statement', got ':'

        Options, {{TEXT("You are a game analyst."), EAIChatPlus_ChatRole::System}, ImageMessage});

API Reference

Thu, 12 Feb 2026 08:03:39 +0000

C++ 篇 - API Reference

本文档提供 AIChatPlus 插件的 C++ API 参考，包含所有公开类、结构体、枚举和关键方法的说明。

枚举类型

EAIChatPlus_ChatApiProvider

AI 聊天 API 提供商枚举。

enum class EAIChatPlus_ChatApiProvider : uint8
{
    OpenAI,         // OpenAI API
    Azure,          // Azure OpenAI API
    Claude,         // Anthropic Claude API
    Gemini,         // Google Gemini API
    Ollama,         // Ollama 本地服务
    Cllama,         // llama.cpp 直接调用（已废弃）
    CllamaServer    // llama.cpp 服务器模式
};

EAIChatPlus_ImageApiProvider

图片生成 API 提供商枚举。

enum class EAIChatPlus_ImageApiProvider : uint8
{
    OpenAI,   // OpenAI DALL-E
    Azure     // Azure OpenAI DALL-E
};

EAIChatPlus_ChatRole

消息角色枚举。

enum class EAIChatPlus_ChatRole : uint8
{
    System,     // 系统指令（旧模型）
    User,       // 用户消息
    Assistant,  // AI 回复
    Developer,  // 开发者指令（o1+ 模型）
    Tool        // 工具调用结果
};

EAIChatPlus_ImageChatType

图片操作类型枚举。

enum class EAIChatPlus_ImageChatType : uint8
{
    Generation,  // 图片生成
    Edit,        // 图片编辑
    Variation    // 图片变体
};

EAIChatPlus_JsonValueType

JSON 值类型枚举。

enum class EAIChatPlus_JsonValueType : uint8
{
    None,     // 无效
    Null,     // 空值
    String,   // 字符串
    Number,   // 数字
    Boolean,  // 布尔
    Array,    // 数组
    Object    // 对象
};

核心基类

UAIChatPlus_RequestBase

所有请求的基类（抽象类）。

关键方法：

方法	返回类型	描述
`SendRequest()`	`bool`	发送请求
`StopRequest()`	`void`	停止请求
`Activate()`	`void`	激活请求对象
`IsActivated()`	`bool`	检查是否已激活
`SetIsAutoDestroy(bool)`	`void`	设置完成后自动销毁

委托：

委托名	签名	描述
`OnStartedListeners`	`void()`	请求开始
`OnMessageListeners`	`void(const FString&)`	收到流式消息
`OnFinishedListeners`	`void(const FAIChatPlus_PointerWrapper&)`	请求完成
`OnFailedListeners`	`void(const FAIChatPlus_PointerWrapper&)`	请求失败

UAIChatPlus_ChatRequestBase

聊天请求基类，继承自 UAIChatPlus_RequestBase。

静态工厂方法：

// 按 Provider 创建请求
static UAIChatPlus_ChatRequestBase* CreateByApi(EAIChatPlus_ChatApiProvider InApiProvider);
static UAIChatPlus_ChatRequestBase* CreateByApiInWorld(EAIChatPlus_ChatApiProvider InApiProvider, const UObject* InWorldContext);

关键方法：

方法	返回类型	描述
`SetMessages(const TArray<FAIChatPlus_ChatRequestMessage>&)`	`void`	设置消息列表
`GetFullUrl()`	`FString`	获取完整请求 URL
`GetModelText()`	`FString`	获取模型名称
`GetTokenUsageText()`	`FString`	获取 Token 用量描述
`GetApiProvider()`	`EAIChatPlus_ChatApiProvider`	获取 API Provider 类型

UAIChatPlus_ImageRequestBase

图片请求基类，继承自 UAIChatPlus_RequestBase。

静态工厂方法：

static UAIChatPlus_ImageRequestBase* CreateByApi(EAIChatPlus_ImageApiProvider InApiProvider);
static UAIChatPlus_ImageRequestBase* CreateByApiInWorld(EAIChatPlus_ImageApiProvider InApiProvider, const UObject* InWorldContext);

关键方法：

方法	返回类型	描述
`SetPrompt(const FString&)`	`void`	设置图片生成提示词
`SetImages(const TArray<UAIChatPlus_Texture*>&)`	`void`	设置输入图片（编辑/变体）
`GetModelText()`	`FString`	获取模型名称
`GetStyleText()`	`FString`	获取风格名称
`GetRevisedPrompt()`	`FString`	获取修正后的提示词
`GetImageChatType()`	`FString`	获取图片操作类型

UAIChatPlus_ModelRequestBase

模型列表请求基类，继承自 UAIChatPlus_RequestBase。

静态工厂方法：

static UAIChatPlus_ModelRequestBase* CreateByApi(EAIChatPlus_ChatApiProvider InApiProvider);
static UAIChatPlus_ModelRequestBase* CreateByApiInWorld(EAIChatPlus_ChatApiProvider InApiProvider, const UObject* InWorldContext);

Handler 类

UAIChatPlus_HandlerBase

所有 Handler 的基类。

关键方法：

方法	返回类型	描述
`SetIsAutoDestroy(bool)`	`void`	设置自动销毁
`AutoDestroy()`	`void`	执行自动销毁
`Destroy()`	`void`	立即销毁

UAIChatPlus_ChatHandlerBase

聊天请求 Handler，继承自 UAIChatPlus_HandlerBase。

静态工厂方法：

static UAIChatPlus_ChatHandlerBase* New();

绑定方法：

方法	描述
`BindChatRequest(UAIChatPlus_ChatRequestBase*)`	绑定聊天请求
`BindImageRequest(UAIChatPlus_ImageRequestBase*)`	绑定图片请求
`BindModelRequest(UAIChatPlus_ModelRequestBase*)`	绑定模型请求
`ClearDelegates()`	清除所有委托绑定

委托：

委托名	签名	描述
`OnStarted`	`void()`	请求开始
`OnStopped`	`void()`	请求停止
`OnMessage`	`void(const FString&)`	流式消息
`OnMessageFinished`	`void(const FAIChatPlus_MessageFinishedPayload&)`	消息完成
`OnUpdated`	`void(const FAIChatPlus_PointerWrapper&)`	请求更新
`OnFinished`	`void(const FAIChatPlus_PointerWrapper&)`	请求完成
`OnFailed`	`void(const FAIChatPlus_PointerWrapper&)`	请求失败
`OnImages`	`void(const TArray<UTexture2D*>&, bool)`	图片生成
`OnModels`	`void(const TArray<FString>&)`	模型列表

UAIChatPlus_CllamaServerHandler

CllamaServer 专用 Handler。

静态工厂方法：

static UAIChatPlus_CllamaServerHandler* CreateHandler();

委托：

委托名	签名	描述
`OnServerStarted`	`void(FGuid)`	服务器启动
`OnServerStopped`	`void(FGuid)`	服务器停止
`OnServerFailed`	`void(FGuid, const FString&)`	服务器失败

Request 类

所有 Provider 的 Request 类都遵循相同的工厂方法模式：

通用工厂方法模式

// 以 OpenAI 为例，其他 Provider 类似
static UAIChatPlus_OpenAIChatRequest* Create();
static UAIChatPlus_OpenAIChatRequest* CreateWithOptions(const FAIChatPlus_OpenAIChatRequestOptions& InOptions);
static UAIChatPlus_OpenAIChatRequest* CreateWithOptionsAndMessages(
    const FAIChatPlus_OpenAIChatRequestOptions& InOptions,
    const TArray<FAIChatPlus_ChatRequestMessage>& InMessages);
static UAIChatPlus_OpenAIChatRequest* CreateInWorld(const UObject* InWorldContext);
static UAIChatPlus_OpenAIChatRequest* CreateInWorldWithOptions(
    const UObject* InWorldContext,
    const FAIChatPlus_OpenAIChatRequestOptions& InOptions);
static UAIChatPlus_OpenAIChatRequest* CreateInWorldWithOptionsAndMessages(
    const UObject* InWorldContext,
    const FAIChatPlus_OpenAIChatRequestOptions& InOptions,
    const TArray<FAIChatPlus_ChatRequestMessage>& InMessages);

通用静态方法

所有 Request 类都提供 CastWrapperToResponse 方法用于类型转换：

// 从 PointerWrapper 提取响应数据
static FAIChatPlus_XXXResponseBody& CastWrapperToResponse(const FAIChatPlus_PointerWrapper& InWrapper);
static FAIChatPlus_PointerWrapper CastResponseToWrapper(const FAIChatPlus_XXXResponseBody& InResponse);

UAIChatPlus_OpenAIChatRequest

OpenAI 聊天请求。

头文件： Common_OpenAI/AIChatPlus_OpenAIChatRequest.h

Options 类型： FAIChatPlus_OpenAIChatRequestOptions

Response 类型： FAIChatPlus_OpenAIChatResponseBody

UAIChatPlus_AzureChatRequest

Azure OpenAI 聊天请求。

头文件： Common_Azure/AIChatPlus_AzureChatRequest.h

Options 类型： FAIChatPlus_AzureChatRequestOptions

Response 类型： FAIChatPlus_AzureChatResponseBody

UAIChatPlus_ClaudeChatRequest

Claude 聊天请求。

头文件： Common_Claude/AIChatPlus_ClaudeChatRequest.h

Options 类型： FAIChatPlus_ClaudeChatRequestOptions

Response 类型： FAIChatPlus_ClaudeChatResponseBody

UAIChatPlus_GeminiChatRequest

Gemini 聊天请求。

头文件： Common_Gemini/AIChatPlus_GeminiChatRequest.h

Options 类型： FAIChatPlus_GeminiChatRequestOptions

Response 类型： FAIChatPlus_GeminiChatResponseBody

UAIChatPlus_OllamaChatRequest

Ollama 聊天请求。

头文件： Common_Ollama/AIChatPlus_OllamaChatRequest.h

Options 类型： FAIChatPlus_OllamaChatRequestOptions

Response 类型： FAIChatPlus_OllamaChatResponseBody

UAIChatPlus_OllamaModelRequest

Ollama 模型列表请求。

头文件： Common_Ollama/AIChatPlus_OllamaModelRequest.h

Options 类型： FAIChatPlus_OllamaModelRequestOptions

Response 类型： FAIChatPlus_OllamaModelResponseBody

特有方法：

方法	返回类型	描述
`GetModelNames()`	`TArray<FString>`	获取模型名称列表

UAIChatPlus_CllamaChatRequest（已废弃）

Cllama 离线聊天请求（已废弃，推荐使用 CllamaServer）。

头文件： Common_Cllama/AIChatPlus_CllamaChatRequest.h

Options 类型： FAIChatPlus_CllamaChatRequestOptions

Response 类型： FAIChatPlus_CllamaChatResponseBody

UAIChatPlus_CllamaServerChatRequest

CllamaServer 聊天请求。

头文件： Common_CllamaServer/AIChatPlus_CllamaServerChatRequest.h

Options 类型： FAIChatPlus_CllamaServerChatRequestOptions

Response 类型： FAIChatPlus_CllamaServerChatResponseBody

UAIChatPlus_OpenAIImageRequest

OpenAI 图片生成请求。

头文件： Common_OpenAI/AIChatPlus_OpenAIImageRequest.h

Options 类型： FAIChatPlus_OpenAIImageRequestOptions

Response 类型： FAIChatPlus_OpenAIImageResponseBody

UAIChatPlus_AzureImageRequest

Azure 图片生成请求。

头文件： Common_Azure/AIChatPlus_AzureImageRequest.h

Options 类型： FAIChatPlus_AzureImageRequestOptions

Response 类型： FAIChatPlus_AzureImageResponseBody

UAIChatPlus_CllamaServer

CllamaServer 服务器管理类。

头文件： Common_CllamaServer/AIChatPlus_CllamaServer.h

静态工厂方法：

static UAIChatPlus_CllamaServer* CreateServer(
    const FAIChatPlus_CllamaServerParam& InParams,
    FGuid InServerID = FGuid());
static UAIChatPlus_CllamaServer* CreateServerInWorld(
    const UObject* InWorldContext,
    const FAIChatPlus_CllamaServerParam& InParams,
    FGuid InServerID = FGuid());
static UAIChatPlus_CllamaServer* CreateServerWithHandler(
    const FAIChatPlus_CllamaServerParam& InParams,
    UAIChatPlus_CllamaServerHandler* InHandler,
    FGuid InServerID = FGuid());

实例方法：

方法	返回类型	描述
`Activate()`	`void`	启动服务器
`StopServer()`	`void`	停止服务器
`IsRunning()`	`bool`	检查是否运行中
`GetServerID()`	`FGuid`	获取服务器 ID
`GetHost()`	`FString`	获取主机地址
`GetAddress()`	`FString`	获取完整地址
`GetServerInfo(FAIChatPlus_CllamaServerInfo&)`	`bool`	获取服务器信息

静态管理方法：

方法	返回类型	描述
`IsServerValid(const FGuid&)`	`bool`	检查服务器是否有效
`IsServerRunning(const FGuid&)`	`bool`	检查服务器是否运行中
`StopServerByID(const FGuid&)`	`void`	按 ID 停止服务器
`StopAllServers()`	`void`	停止所有服务器
`GetServerByID(const FGuid&)`	`UAIChatPlus_CllamaServer*`	按 ID 获取服务器
`GetAllServerIDs()`	`TArray<FGuid>`	获取所有服务器 ID

工具类

UAIChatPlus_Util

通用工具类，提供各种静态辅助方法。

头文件： Common/AIChatPlus_Util.h

日志相关

方法	返回类型	描述
`SetInternalLogVerbosity(EAIChatPlus_LogVerbosityType)`	`void`	设置内部日志级别

Wrapper 转换

方法	返回类型	描述
`CastWrapperToError(const FAIChatPlus_PointerWrapper&)`	`FAIChatPlus_ResponseErrorBase&`	提取错误信息
`CastWrapperToResponse(const FAIChatPlus_PointerWrapper&)`	`FAIChatPlus_ChatResponseBodyBase&`	提取响应数据
`GetErrorWrapperDescription(const FAIChatPlus_PointerWrapper&)`	`FString`	获取错误描述
`GetResponseWrapperMessage(const FAIChatPlus_PointerWrapper&)`	`FString`	获取响应消息

图片工具

方法	返回类型	描述
`LoadImage(const FString&, bool)`	`UTexture2D*`	从文件加载图片
`SaveImage(UTexture2D*, const FString&)`	`bool`	保存图片到文件
`ImageToB64(UTexture2D*, int32)`	`FString`	图片转 Base64
`CopyTexture2D(UTexture2D, UObject, FName, EObjectFlags)`	`UTexture2D*`	复制纹理
`FitImageSize(const FVector2D&, const FVector2D&)`	`FVector2D`	计算适配尺寸
`CopyTexture2DToClipboard(UTexture2D*)`	`void`	复制到剪贴板
`IsCanCopyTexture2DToClipboard()`	`bool`	检查是否支持

音频工具

方法	返回类型	描述
`LoadSoundWav(const FString&)`	`USoundWave*`	从文件加载音频
`SaveSoundWav(USoundWave*, const FString&)`	`bool`	保存音频到文件
`SoundToB64(USoundWave*)`	`FString`	音频转 Base64
`CopySoundWave(const USoundWave, UObject, FName)`	`USoundWave*`	复制音频
`WavDataToSoundWave(const TArray<uint8>&, bool, bool)`	`USoundWave*`	WAV 数据转音频
`GetSoundWavePCMData(USoundWave*)`	`TArray<uint8>`	获取 PCM 数据

JSON 工具

方法	返回类型	描述
`MergeJsonObjects(const FString&, const FString&)`	`FString`	合并 JSON 字符串
`LoadJsonString(const FString&)`	`TSharedPtr<FJsonObject>`	解析 JSON 字符串
`ToJsonString(const TSharedPtr<FJsonObject>&)`	`FString`	转为 JSON 字符串

Cllama 工具

方法	返回类型	描述
`Cllama_IsValid()`	`bool`	检查 Cllama 是否可用
`Cllama_IsSupportGpu()`	`bool`	检查是否支持 GPU
`Cllama_GetSupportBackends()`	`TArray<FString>`	获取支持的后端
`Cllama_PrepareModelPathFromPak(const FString&)`	`FString`	从 Pak 准备模型路径

模型信息

方法	返回类型	描述
`GetOpenAIChatDefaultModels()`	`const TArray<FName>&`	OpenAI 默认模型列表
`GetOpenAIChatModelInfo(const FString&)`	`FAIChatPlus_ChatModelInfo`	获取 OpenAI 模型信息
`GetClaudeChatDefaultModels()`	`const TArray<FName>&`	Claude 默认模型列表
`GetClaudeChatModelInfo(const FString&)`	`FAIChatPlus_ChatModelInfo`	获取 Claude 模型信息
`GetGeminiChatDefaultModels()`	`const TArray<FName>&`	Gemini 默认模型列表
`GetGeminiChatModelInfo(const FString&)`	`FAIChatPlus_ChatModelInfo`	获取 Gemini 模型信息

UAIChatPlus_Texture

图片包装类，支持异步加载和 Base64 转换。

头文件： Common/AIChatPlus_Texture.h

静态工厂方法：

static UAIChatPlus_Texture* New(UTexture2D* InTexture = nullptr, const FString& InSourcePath = "");
static UAIChatPlus_Texture* CreateInBlueprint(UObject* WorldContextObject, UTexture2D* InTexture);

方法：

方法	返回类型	描述
`LoadFromFile(const FString&)`	`bool`	从文件加载（同步）
`LoadFromFileAsync(const FString&, Callback)`	`FLoadingTaskType*`	从文件加载（异步）
`LoadFromAsset(UObject*, const FString&)`	`bool`	从资产加载（同步）
`LoadFromAssetAsync(UObject*, Callback, const FString&)`	`FLoadingTaskType*`	从资产加载（异步）
`ToB64()`	`const FString&`	转为 Base64（同步）
`ToB64Async(Callback)`	`FLoadingTaskType*`	转为 Base64（异步）
`GetBrush(bool)`	`const FSlateBrush*`	获取 Slate 笔刷
`GetBrushCopy(bool)`	`FSlateBrush`	获取笔刷副本
`GetSize()`	`FIntVector2`	获取尺寸
`GetSize2D()`	`FVector2D`	获取尺寸（浮点）
`IsValid()`	`bool`	检查是否有效
`IsLoading()`	`bool`	检查是否加载中
`Reset()`	`void`	重置
`WaitLoadingComplete()`	`void`	等待加载完成

UAIChatPlus_Sound

音频包装类，支持异步加载和 Base64 转换。

头文件： Common/AIChatPlus_Sound.h

静态工厂方法：

static UAIChatPlus_Sound* New(USoundWave* InSound = nullptr, const FString& InSourcePath = "");
static UAIChatPlus_Sound* CreateInBlueprint(UObject* WorldContextObject, USoundWave* InSound);

方法：

方法	返回类型	描述
`LoadFromFile(const FString&)`	`bool`	从文件加载（同步）
`LoadFromFileAsync(const FString&, Callback)`	`FLoadingTaskType*`	从文件加载（异步）
`LoadFromAsset(UObject*, const FString&)`	`bool`	从资产加载（同步）
`LoadFromAssetAsync(UObject*, Callback, const FString&)`	`FLoadingTaskType*`	从资产加载（异步）
`ToB64()`	`const FString&`	转为 Base64（同步）
`ToB64Async(Callback)`	`FLoadingTaskType*`	转为 Base64（异步）
`IsValid()`	`bool`	检查是否有效
`IsLoading()`	`bool`	检查是否加载中
`Reset()`	`void`	重置
`WaitLoadingComplete()`	`void`	等待加载完成
`PlayInEditor()`	`void`	在编辑器中播放

JSON 类

UAIChatPlus_JsonObject

JSON 对象包装类。

头文件： Common/Json/AIChatPlus_JsonObject.h

静态工厂方法：

static UAIChatPlus_JsonObject* Create();
static UAIChatPlus_JsonObject* Parse(const FString& JsonString, bool& bSuccess, FString& ErrorMessage);
static UAIChatPlus_JsonObject* FromStruct(const int32& Struct);  // CustomThunk

设置字段方法（支持链式调用）：

方法	返回类型	描述
`SetStringField(const FString&, const FString&)`	`UAIChatPlus_JsonObject*`	设置字符串字段
`SetNumberField(const FString&, float)`	`UAIChatPlus_JsonObject*`	设置数字字段
`SetIntegerField(const FString&, int32)`	`UAIChatPlus_JsonObject*`	设置整数字段
`SetBooleanField(const FString&, bool)`	`UAIChatPlus_JsonObject*`	设置布尔字段
`SetObjectField(const FString&, UAIChatPlus_JsonObject*)`	`UAIChatPlus_JsonObject*`	设置对象字段
`SetArrayField(const FString&, UAIChatPlus_JsonArray*)`	`UAIChatPlus_JsonObject*`	设置数组字段
`SetNullField(const FString&)`	`UAIChatPlus_JsonObject*`	设置空字段

获取字段方法：

方法	返回类型	描述
`GetStringField(const FString&, const FString&, bool&)`	`FString`	获取字符串
`GetNumberField(const FString&, float, bool&)`	`float`	获取数字
`GetIntegerField(const FString&, int32, bool&)`	`int32`	获取整数
`GetBooleanField(const FString&, bool, bool&)`	`bool`	获取布尔
`GetObjectField(const FString&, bool&)`	`UAIChatPlus_JsonObject*`	获取对象
`GetArrayField(const FString&, bool&)`	`UAIChatPlus_JsonArray*`	获取数组

其他方法：

方法	返回类型	描述
`HasField(const FString&)`	`bool`	检查字段存在
`GetFieldType(const FString&)`	`EAIChatPlus_JsonValueType`	获取字段类型
`RemoveField(const FString&)`	`UAIChatPlus_JsonObject*`	移除字段
`Clear()`	`UAIChatPlus_JsonObject*`	清空所有字段
`ToString(bool)`	`FString`	转为字符串
`ToStruct(int32&)`	`bool`	转为结构体
`Merge(UAIChatPlus_JsonObject*, bool)`	`UAIChatPlus_JsonObject*`	合并对象
`Duplicate()`	`UAIChatPlus_JsonObject*`	复制对象
`IsValid()`	`bool`	检查有效性

路径查询方法：

方法	返回类型	描述
`SetStringByPath(const FString&, const FString&, const FAIChatPlus_JsonPathOptions&)`	`UAIChatPlus_JsonObject*`	按路径设置字符串
`GetStringByPath(const FString&, const FString&, FAIChatPlus_JsonQueryResult&)`	`FString`	按路径获取字符串

UAIChatPlus_JsonArray

JSON 数组包装类。

头文件： Common/Json/AIChatPlus_JsonArray.h

静态工厂方法：

static UAIChatPlus_JsonArray* Create();
static UAIChatPlus_JsonArray* Parse(const FString& JsonString, bool& bSuccess, FString& ErrorMessage);
static UAIChatPlus_JsonArray* FromStringArray(const TArray<FString>& Values);
static UAIChatPlus_JsonArray* FromIntegerArray(const TArray<int32>& Values);

添加元素方法（支持链式调用）：

方法	返回类型	描述
`AddString(const FString&)`	`UAIChatPlus_JsonArray*`	添加字符串
`AddNumber(float)`	`UAIChatPlus_JsonArray*`	添加数字
`AddInteger(int32)`	`UAIChatPlus_JsonArray*`	添加整数
`AddBoolean(bool)`	`UAIChatPlus_JsonArray*`	添加布尔
`AddObject(UAIChatPlus_JsonObject*)`	`UAIChatPlus_JsonArray*`	添加对象
`AddArray(UAIChatPlus_JsonArray*)`	`UAIChatPlus_JsonArray*`	添加数组
`AddNull()`	`UAIChatPlus_JsonArray*`	添加空值

获取元素方法：

方法	返回类型	描述
`GetString(int32, const FString&, bool&)`	`FString`	获取字符串
`GetNumber(int32, float, bool&)`	`float`	获取数字
`GetInteger(int32, int32, bool&)`	`int32`	获取整数
`GetBoolean(int32, bool, bool&)`	`bool`	获取布尔
`GetObject(int32, bool&)`	`UAIChatPlus_JsonObject*`	获取对象
`GetArray(int32, bool&)`	`UAIChatPlus_JsonArray*`	获取数组

其他方法：

方法	返回类型	描述
`Length()`	`int32`	获取长度
`GetElementType(int32)`	`EAIChatPlus_JsonValueType`	获取元素类型
`SetString(int32, const FString&, bool&)`	`UAIChatPlus_JsonArray*`	设置字符串
`SetObject(int32, UAIChatPlus_JsonObject*, bool&)`	`UAIChatPlus_JsonArray*`	设置对象
`RemoveAt(int32, bool&)`	`UAIChatPlus_JsonArray*`	移除元素
`Clear()`	`UAIChatPlus_JsonArray*`	清空数组
`ToString(bool)`	`FString`	转为字符串
`Duplicate()`	`UAIChatPlus_JsonArray*`	复制数组
`IsValid()`	`bool`	检查有效性

UAIChatPlus_JsonLibrary

JSON 静态工具库。

头文件： Common/Json/AIChatPlus_JsonLibrary.h

创建方法：

方法	返回类型	描述
`MakeJsonObjectWithStringField(const FString&, const FString&)`	`UAIChatPlus_JsonObject*`	创建单字段对象
`MakeJsonObjectFromStringMap(const TMap<FString, FString>&)`	`UAIChatPlus_JsonObject*`	从 Map 创建对象

验证方法：

方法	返回类型	描述
`ValidateJsonString(const FString&, FString&)`	`bool`	验证 JSON 字符串
`IsJsonObject(const FString&)`	`bool`	检查是否为对象
`IsJsonArray(const FString&)`	`bool`	检查是否为数组

格式化方法：

方法	返回类型	描述
`PrettifyJson(const FString&)`	`FString`	美化 JSON
`MinifyJson(const FString&)`	`FString`	压缩 JSON

结构体转换（CustomThunk）：

方法	返回类型	描述
`JsonStringToStruct(const FString&, int32&)`	`bool`	JSON 转结构体
`StructToJsonString(const int32&, bool)`	`FString`	结构体转 JSON

文件操作：

方法	返回类型	描述
`LoadJsonObjectFromFile(const FString&, bool&, FString&)`	`UAIChatPlus_JsonObject*`	从文件加载对象
`SaveJsonObjectToFile(UAIChatPlus_JsonObject*, const FString&, bool, FString&)`	`bool`	保存对象到文件
`LoadJsonArrayFromFile(const FString&, bool&, FString&)`	`UAIChatPlus_JsonArray*`	从文件加载数组
`SaveJsonArrayToFile(UAIChatPlus_JsonArray*, const FString&, bool, FString&)`	`bool`	保存数组到文件

比较方法：

方法	返回类型	描述
`EqualsJsonObject(UAIChatPlus_JsonObject, UAIChatPlus_JsonObject)`	`bool`	比较对象
`EqualsJsonArray(UAIChatPlus_JsonArray, UAIChatPlus_JsonArray)`	`bool`	比较数组

路径查询：

方法	返回类型	描述
`QueryStringByPath(UAIChatPlus_JsonObject*, const FString&, const FString&, FAIChatPlus_JsonQueryResult&)`	`FString`	按路径查询字符串
`QueryObjectByPath(UAIChatPlus_JsonObject*, const FString&, FAIChatPlus_JsonQueryResult&)`	`UAIChatPlus_JsonObject*`	按路径查询对象
`QueryArrayByPath(UAIChatPlus_JsonObject*, const FString&, FAIChatPlus_JsonQueryResult&)`	`UAIChatPlus_JsonArray*`	按路径查询数组

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Utils

Thu, 12 Feb 2026 08:03:39 +0000

C++ 篇 - Utils

本文档介绍 AIChatPlus 提供的工具类，包括 JSON 操作、图片处理和音频处理等功能。

准备工作

在项目的 .Build.cs 文件中添加模块依赖：

PublicDependencyModuleNames.AddRange(new string[]
{
    "AIChatPlusCommon"
});

包含必要的头文件：

#include "Common/AIChatPlus_Util.h"
#include "Common/Json/AIChatPlus_JsonObject.h"
#include "Common/Json/AIChatPlus_JsonArray.h"

JSON 操作

AIChatPlus 提供了 Blueprint 友好的 JSON 操作类，支持链式调用和类型安全操作。

UAIChatPlus_JsonObject - JSON 对象

创建和解析

#include "Common/Json/AIChatPlus_JsonObject.h"

void UMyClass::JsonObjectBasics()
{
    // 创建空 JSON 对象
    UAIChatPlus_JsonObject* JsonObj = UAIChatPlus_JsonObject::Create();

    // 从字符串解析
    FString JsonString = TEXT(R"({"name": "John", "age": 30, "active": true})");
    bool bSuccess;
    FString ErrorMessage;
    UAIChatPlus_JsonObject* ParsedObj = UAIChatPlus_JsonObject::Parse(JsonString, bSuccess, ErrorMessage);

    if (bSuccess)
    {
        UE_LOG(LogTemp, Display, TEXT("Parsed successfully"));
    }
    else
    {
        UE_LOG(LogTemp, Error, TEXT("Parse error: %s"), *ErrorMessage);
    }
}

设置字段（链式调用）

void UMyClass::SetJsonFields()
{
    UAIChatPlus_JsonObject* JsonObj = UAIChatPlus_JsonObject::Create();

    // 链式设置字段
    JsonObj->SetStringField(TEXT("name"), TEXT("John"))
           ->SetIntegerField(TEXT("age"), 30)
           ->SetBooleanField(TEXT("active"), true)
           ->SetNumberField(TEXT("score"), 95.5f)
           ->SetNullField(TEXT("extra"));

    // 设置嵌套对象
    UAIChatPlus_JsonObject* AddressObj = UAIChatPlus_JsonObject::Create();
    AddressObj->SetStringField(TEXT("city"), TEXT("Tokyo"))
              ->SetStringField(TEXT("country"), TEXT("Japan"));

    JsonObj->SetObjectField(TEXT("address"), AddressObj);

    // 输出
    FString Result = JsonObj->ToString(true);  // true = 格式化输出
    UE_LOG(LogTemp, Display, TEXT("%s"), *Result);
}

获取字段

void UMyClass::GetJsonFields()
{
    FString JsonString = TEXT(R"({"name": "John", "age": 30, "scores": [85, 90, 95]})");
    bool bParseSuccess;
    FString ErrorMessage;
    UAIChatPlus_JsonObject* JsonObj = UAIChatPlus_JsonObject::Parse(JsonString, bParseSuccess, ErrorMessage);

    if (!bParseSuccess) return;

    bool bSuccess;

    // 获取字符串字段
    FString Name = JsonObj->GetStringField(TEXT("name"), TEXT("Unknown"), bSuccess);
    if (bSuccess)
    {
        UE_LOG(LogTemp, Display, TEXT("Name: %s"), *Name);
    }

    // 获取整数字段
    int32 Age = JsonObj->GetIntegerField(TEXT("age"), 0, bSuccess);

    // 获取布尔字段
    bool bActive = JsonObj->GetBooleanField(TEXT("active"), false, bSuccess);

    // 获取数组字段
    UAIChatPlus_JsonArray* Scores = JsonObj->GetArrayField(TEXT("scores"), bSuccess);
    if (bSuccess && Scores)
    {
        for (int32 i = 0; i < Scores->Length(); ++i)
        {
            int32 Score = Scores->GetInteger(i, 0, bSuccess);
            UE_LOG(LogTemp, Display, TEXT("Score[%d]: %d"), i, Score);
        }
    }

    // 获取嵌套对象字段
    UAIChatPlus_JsonObject* AddressObj = JsonObj->GetObjectField(TEXT("address"), bSuccess);
    if (bSuccess && AddressObj)
    {
        FString City = AddressObj->GetStringField(TEXT("city"), TEXT(""), bSuccess);
    }
}

字段检查和管理

void UMyClass::ManageJsonFields()
{
    UAIChatPlus_JsonObject* JsonObj = UAIChatPlus_JsonObject::Create();
    JsonObj->SetStringField(TEXT("name"), TEXT("John"))
           ->SetIntegerField(TEXT("age"), 30);

    // 检查字段是否存在
    if (JsonObj->HasField(TEXT("name")))
    {
        UE_LOG(LogTemp, Display, TEXT("Field 'name' exists"));
    }

    // 获取字段类型
    EAIChatPlus_JsonValueType FieldType = JsonObj->GetFieldType(TEXT("age"));
    // FieldType == EAIChatPlus_JsonValueType::Number

    // 获取所有字段名
    TArray<FString> FieldNames = JsonObj->GetFieldNames();
    for (const FString& Name : FieldNames)
    {
        UE_LOG(LogTemp, Display, TEXT("Field: %s"), *Name);
    }

    // 删除字段
    JsonObj->RemoveField(TEXT("age"));

    // 清空所有字段
    JsonObj->Clear();
}

路径查询（嵌套访问）

void UMyClass::PathQuery()
{
    FString JsonString = TEXT(R"({
        "player": {
            "inventory": {
                "gold": 1000,
                "items": ["sword", "shield"]
            }
        }
    })");

    bool bParseSuccess;
    FString ErrorMessage;
    UAIChatPlus_JsonObject* JsonObj = UAIChatPlus_JsonObject::Parse(JsonString, bParseSuccess, ErrorMessage);

    // 通过路径获取值
    FAIChatPlus_JsonQueryResult Result;
    FString Gold = JsonObj->GetStringByPath(TEXT("player.inventory.gold"), TEXT("0"), Result);
    // Gold = "1000"

    // 通过路径设置值
    FAIChatPlus_JsonPathOptions PathOptions;
    JsonObj->SetStringByPath(TEXT("player.inventory.gold"), TEXT("2000"), PathOptions);
}

合并和复制

void UMyClass::MergeAndDuplicate()
{
    UAIChatPlus_JsonObject* Obj1 = UAIChatPlus_JsonObject::Create();
    Obj1->SetStringField(TEXT("name"), TEXT("John"));

    UAIChatPlus_JsonObject* Obj2 = UAIChatPlus_JsonObject::Create();
    Obj2->SetIntegerField(TEXT("age"), 30)
        ->SetStringField(TEXT("name"), TEXT("Jane"));  // 覆盖 name

    // 合并（bOverwrite = true 时覆盖已存在的字段）
    Obj1->Merge(Obj2, true);
    // Obj1 现在包含 {"name": "Jane", "age": 30}

    // 深拷贝
    UAIChatPlus_JsonObject* Copy = Obj1->Duplicate();
}

与 UStruct 互转

USTRUCT(BlueprintType)
struct FMyData
{
    GENERATED_BODY()

    UPROPERTY()
    FString Name;

    UPROPERTY()
    int32 Age;
};

void UMyClass::StructConversion()
{
    // UStruct 转 JsonObject
    FMyData Data;
    Data.Name = TEXT("John");
    Data.Age = 30;

    UAIChatPlus_JsonObject* JsonObj = UAIChatPlus_JsonObject::FromStruct(Data);

    // JsonObject 转 UStruct
    FMyData OutData;
    bool bSuccess = JsonObj->ToStruct(OutData);

    if (bSuccess)
    {
        UE_LOG(LogTemp, Display, TEXT("Name: %s, Age: %d"), *OutData.Name, OutData.Age);
    }
}

UAIChatPlus_JsonArray - JSON 数组

创建和操作

#include "Common/Json/AIChatPlus_JsonArray.h"

void UMyClass::JsonArrayBasics()
{
    // 创建空数组
    UAIChatPlus_JsonArray* JsonArray = UAIChatPlus_JsonArray::Create();

    // 添加元素（链式调用）
    JsonArray->AddString(TEXT("apple"))
             ->AddString(TEXT("banana"))
             ->AddInteger(42)
             ->AddBoolean(true)
             ->AddNull();

    // 添加对象元素
    UAIChatPlus_JsonObject* ItemObj = UAIChatPlus_JsonObject::Create();
    ItemObj->SetStringField(TEXT("name"), TEXT("sword"));
    JsonArray->AddObject(ItemObj);

    // 添加嵌套数组
    UAIChatPlus_JsonArray* NestedArray = UAIChatPlus_JsonArray::Create();
    NestedArray->AddInteger(1)->AddInteger(2)->AddInteger(3);
    JsonArray->AddArray(NestedArray);

    // 输出
    FString Result = JsonArray->ToString(true);
    UE_LOG(LogTemp, Display, TEXT("%s"), *Result);
}

获取元素

void UMyClass::GetArrayElements()
{
    FString JsonString = TEXT(R"(["apple", "banana", 42, true, {"name": "item"}])");
    bool bParseSuccess;
    FString ErrorMessage;
    UAIChatPlus_JsonArray* JsonArray = UAIChatPlus_JsonArray::Parse(JsonString, bParseSuccess, ErrorMessage);

    if (!bParseSuccess) return;

    bool bSuccess;

    // 获取字符串元素
    FString Fruit = JsonArray->GetString(0, TEXT(""), bSuccess);  // "apple"

    // 获取整数元素
    int32 Number = JsonArray->GetInteger(2, 0, bSuccess);  // 42

    // 获取布尔元素
    bool bValue = JsonArray->GetBoolean(3, false, bSuccess);  // true

    // 获取对象元素
    UAIChatPlus_JsonObject* Obj = JsonArray->GetObject(4, bSuccess);
    if (bSuccess && Obj)
    {
        FString Name = Obj->GetStringField(TEXT("name"), TEXT(""), bSuccess);
    }

    // 遍历数组
    for (int32 i = 0; i < JsonArray->Length(); ++i)
    {
        EAIChatPlus_JsonValueType Type = JsonArray->GetElementType(i);
        UE_LOG(LogTemp, Display, TEXT("Element[%d] type: %d"), i, static_cast<int32>(Type));
    }
}

数组操作

void UMyClass::ArrayOperations()
{
    UAIChatPlus_JsonArray* JsonArray = UAIChatPlus_JsonArray::Create();
    JsonArray->AddString(TEXT("a"))
             ->AddString(TEXT("b"))
             ->AddString(TEXT("c"));

    // 获取长度
    int32 Len = JsonArray->Length();  // 3

    // 检查索引是否有效
    bool bValid = JsonArray->IsValidIndex(1);  // true

    // 设置元素
    bool bSuccess;
    JsonArray->SetString(1, TEXT("B"), bSuccess);

    // 删除元素
    JsonArray->RemoveAt(0, bSuccess);

    // 清空数组
    JsonArray->Clear();

    // 深拷贝
    UAIChatPlus_JsonArray* Copy = JsonArray->Duplicate();
}

批量转换

void UMyClass::BatchConversion()
{
    // 从字符串数组创建
    TArray<FString> StringArray = {TEXT("a"), TEXT("b"), TEXT("c")};
    UAIChatPlus_JsonArray* JsonArray = UAIChatPlus_JsonArray::FromStringArray(StringArray);

    // 转回字符串数组
    bool bSuccess;
    TArray<FString> OutArray = JsonArray->ToStringArray(bSuccess);

    // 从整数数组创建
    TArray<int32> IntArray = {1, 2, 3, 4, 5};
    UAIChatPlus_JsonArray* IntJsonArray = UAIChatPlus_JsonArray::FromIntegerArray(IntArray);

    // 转回整数数组
    TArray<int32> OutIntArray = IntJsonArray->ToIntegerArray(bSuccess);
}

UAIChatPlus_Util - JSON 辅助函数

void UMyClass::JsonUtilFunctions()
{
    // 合并两个 JSON 字符串
    FString Json1 = TEXT(R"({"name": "John"})");
    FString Json2 = TEXT(R"({"age": 30, "name": "Jane"})");
    FString Merged = UAIChatPlus_Util::MergeJsonObjects(Json1, Json2);
    // Merged = {"name": "Jane", "age": 30}

    // 加载 JSON 字符串为对象
    TSharedPtr<FJsonObject> JsonObj = UAIChatPlus_Util::LoadJsonString(Json1);

    // 对象转字符串
    FString JsonString = UAIChatPlus_Util::ToJsonString(JsonObj);
}

图片工具

加载和保存图片

#include "Common/AIChatPlus_Util.h"

void UMyClass::ImageLoadSave()
{
    // 从文件加载图片
    FString ImagePath = FPaths::ProjectContentDir() / TEXT("Images/sample.png");
    UTexture2D* Texture = UAIChatPlus_Util::LoadImage(ImagePath, true);  // true = 完成编译

    if (Texture)
    {
        UE_LOG(LogTemp, Display, TEXT("Image loaded: %dx%d"),
            Texture->GetSizeX(), Texture->GetSizeY());
    }

    // 保存图片到文件
    FString SavePath = FPaths::ProjectSavedDir() / TEXT("output.png");
    bool bSaved = UAIChatPlus_Util::SaveImage(Texture, SavePath);

    if (bSaved)
    {
        UE_LOG(LogTemp, Display, TEXT("Image saved to: %s"), *SavePath);
    }
}

图片转 Base64

void UMyClass::ImageToBase64()
{
    UTexture2D* Texture = UAIChatPlus_Util::LoadImage(TEXT("D:/image.png"));

    // 转换为 Base64 字符串
    // InQuality: 0 = PNG, 1-100 = JPEG 质量
    FString B64String = UAIChatPlus_Util::ImageToB64(Texture, 0);  // PNG 格式

    UE_LOG(LogTemp, Display, TEXT("Base64 length: %d"), B64String.Len());
}

复制图片

void UMyClass::CopyTexture()
{
    UTexture2D* Original = UAIChatPlus_Util::LoadImage(TEXT("D:/image.png"));

    // 复制纹理
    UTexture2D* Copy = UAIChatPlus_Util::CopyTexture2D(
        Original,
        nullptr,        // Outer（nullptr = GetTransientPackage()）
        NAME_None,      // 名称
        RF_NoFlags      // 标志
    );

    // Blueprint 版本（带默认标志）
    UTexture2D* BPCopy = UAIChatPlus_Util::CopyTexture2DInBlueprint(Original);
}

从 URL 获取图片

void UMyClass::GetImageFromUrl()
{
    FString ImageUrl = TEXT("https://example.com/image.png");

    UAIChatPlus_Util::GetImageFromUrl(ImageUrl,
        UAIChatPlus_Util::OnImageCreated::CreateLambda([](UTexture2D* Texture, const FString& Error)
        {
            if (Texture)
            {
                UE_LOG(LogTemp, Display, TEXT("Image downloaded: %dx%d"),
                    Texture->GetSizeX(), Texture->GetSizeY());
            }
            else
            {
                UE_LOG(LogTemp, Error, TEXT("Download failed: %s"), *Error);
            }
        }));
}

从 Base64 获取图片

void UMyClass::GetImageFromBase64()
{
    FString B64String = TEXT("iVBORw0KGgoAAAANSUhEUg...");  // Base64 数据

    UAIChatPlus_Util::GetImageFromB64(B64String,
        UAIChatPlus_Util::OnImageCreated::CreateLambda([](UTexture2D* Texture, const FString& Error)
        {
            if (Texture)
            {
                UE_LOG(LogTemp, Display, TEXT("Image decoded successfully"));
            }
            else
            {
                UE_LOG(LogTemp, Error, TEXT("Decode failed: %s"), *Error);
            }
        }));
}

复制图片到剪贴板

void UMyClass::CopyToClipboard()
{
    UTexture2D* Texture = UAIChatPlus_Util::LoadImage(TEXT("D:/image.png"));

    // 检查是否支持
    if (UAIChatPlus_Util::IsCanCopyTexture2DToClipboard())
    {
        UAIChatPlus_Util::CopyTexture2DToClipboard(Texture);
        UE_LOG(LogTemp, Display, TEXT("Image copied to clipboard"));
    }
}

音频工具

加载 WAV 文件

void UMyClass::LoadWavFile()
{
    FString WavPath = FPaths::ProjectContentDir() / TEXT("Audio/sample.wav");
    USoundWave* Sound = UAIChatPlus_Util::LoadSoundWav(WavPath);

    if (Sound)
    {
        UE_LOG(LogTemp, Display, TEXT("Sound loaded: Duration=%.2f, Channels=%d, SampleRate=%d"),
            Sound->Duration,
            Sound->NumChannels,
            Sound->GetSampleRateForCurrentPlatform());
    }
}

保存音频为 WAV 文件

void UMyClass::SaveWavFile()
{
    // 假设 Sound 是已有的 USoundWave
    USoundWave* Sound = /* 获取音频 */;

    FString SavePath = FPaths::ProjectSavedDir() / TEXT("output.wav");
    bool bSaved = UAIChatPlus_Util::SaveSoundWav(Sound, SavePath);

    if (bSaved)
    {
        UE_LOG(LogTemp, Display, TEXT("Sound saved to: %s"), *SavePath);
    }
}

音频转 Base64

void UMyClass::SoundToBase64()
{
    USoundWave* Sound = UAIChatPlus_Util::LoadSoundWav(TEXT("D:/audio.wav"));

    // 转换为 Base64 字符串
    FString B64String = UAIChatPlus_Util::SoundToB64(Sound);

    UE_LOG(LogTemp, Display, TEXT("Audio Base64 length: %d"), B64String.Len());
}

WAV 数据转 SoundWave

void UMyClass::WavDataToSound()
{
    // 从文件读取原始数据
    TArray<uint8> RawData;
    FFileHelper::LoadFileToArray(RawData, TEXT("D:/audio.wav"));

    // 转换为 SoundWave
    USoundWave* Sound = UAIChatPlus_Util::WavDataToSoundWave(
        RawData,
        false,  // bIsAmbiX
        false   // bIsFuMa
    );

    if (Sound)
    {
        UE_LOG(LogTemp, Display, TEXT("Sound created from data"));
    }
}

复制 SoundWave

void UMyClass::CopySoundWave()
{
    USoundWave* Original = UAIChatPlus_Util::LoadSoundWav(TEXT("D:/audio.wav"));

    // 复制音频
    USoundWave* Copy = UAIChatPlus_Util::CopySoundWave(
        Original,
        nullptr,    // Outer
        NAME_None   // 名称
    );
}

获取原始 PCM 数据

void UMyClass::GetPCMData()
{
    USoundWave* Sound = UAIChatPlus_Util::LoadSoundWav(TEXT("D:/audio.wav"));

    // 获取原始 PCM 数据
    TArray<uint8> PCMData = UAIChatPlus_Util::GetSoundWavePCMData(Sound);

    UE_LOG(LogTemp, Display, TEXT("PCM data size: %d bytes"), PCMData.Num());
}

从录音数据创建 SoundWave

void UMyClass::RecorderDataToSound()
{
    // 假设从 Audio Capture 获取的录音数据
    TArray<float> RecorderData;  // 音频采样数据
    int32 NumChannels = 1;       // 单声道
    int32 SampleRate = 16000;    // 采样率

    USoundWave* Sound = UAIChatPlus_Util::RecorderDataToSoundWave(
        RecorderData,
        NumChannels,
        SampleRate
    );

    if (Sound)
    {
        UE_LOG(LogTemp, Display, TEXT("Sound created from recorder data"));
    }
}

日志控制

void UMyClass::ControlLogging()
{
    // 设置内部日志级别
    UAIChatPlus_Util::SetInternalLogVerbosity(EAIChatPlus_LogVerbosityType::Verbose);

    // 可用级别：
    // - NoLogging
    // - Fatal
    // - Error
    // - Warning
    // - Display
    // - Log
    // - Verbose
    // - VeryVerbose
}

响应包装器辅助函数

在回调中处理响应时，需要将 FAIChatPlus_PointerWrapper 转换为具体类型：

void UMyClass::HandleCallbackResponse()
{
    // 在 OnFinished 回调中
    Request->OnFinishedListeners.AddLambda([](const FAIChatPlus_PointerWrapper& ResponseWrapper)
    {
        // 获取响应消息
        FString Message = UAIChatPlus_Util::GetResponseWrapperMessage(ResponseWrapper);
        UE_LOG(LogTemp, Display, TEXT("Message: %s"), *Message);

        // 或者转换为基础响应类型
        FAIChatPlus_ChatResponseBodyBase& Response = UAIChatPlus_Util::CastWrapperToResponse(ResponseWrapper);
    });

    // 在 OnFailed 回调中
    Request->OnFailedListeners.AddLambda([](const FAIChatPlus_PointerWrapper& ErrorWrapper)
    {
        // 获取错误描述
        FString ErrorDesc = UAIChatPlus_Util::GetErrorWrapperDescription(ErrorWrapper);
        UE_LOG(LogTemp, Error, TEXT("Error: %s"), *ErrorDesc);

        // 或者转换为错误类型
        FAIChatPlus_ResponseErrorBase& Error = UAIChatPlus_Util::CastWrapperToError(ErrorWrapper);
    });
}

模型信息查询

void UMyClass::QueryModelInfo()
{
    // 获取 OpenAI 默认模型列表
    const TArray<FName>& OpenAIModels = UAIChatPlus_Util::GetOpenAIChatDefaultModels();

    // 获取特定模型信息
    FAIChatPlus_ChatModelInfo ModelInfo = UAIChatPlus_Util::GetOpenAIChatModelInfo(TEXT("gpt-4o"));
    UE_LOG(LogTemp, Display, TEXT("Model: %s, MaxTokens: %d, SupportImage: %s"),
        *ModelInfo.Name.ToString(),
        ModelInfo.MaxTokens,
        ModelInfo.IsSupportSendImage ? TEXT("Yes") : TEXT("No"));

    // Claude 模型
    const TArray<FName>& ClaudeModels = UAIChatPlus_Util::GetClaudeChatDefaultModels();
    FAIChatPlus_ChatModelInfo ClaudeInfo = UAIChatPlus_Util::GetClaudeChatModelInfo(TEXT("claude-3-5-sonnet"));

    // Gemini 模型
    const TArray<FName>& GeminiModels = UAIChatPlus_Util::GetGeminiChatDefaultModels();
    FAIChatPlus_ChatModelInfo GeminiInfo = UAIChatPlus_Util::GetGeminiChatModelInfo(TEXT("gemini-1.5-pro"));
}

Cllama 辅助函数

void UMyClass::CllamaUtilities()
{
    // 检查 Cllama 是否可用
    if (UAIChatPlus_Util::Cllama_IsValid())
    {
        UE_LOG(LogTemp, Display, TEXT("Cllama is available"));
    }

    // 检查 GPU 支持
    if (UAIChatPlus_Util::Cllama_IsSupportGpu())
    {
        UE_LOG(LogTemp, Display, TEXT("GPU acceleration supported"));
    }

    // 获取支持的后端
    TArray<FString> Backends = UAIChatPlus_Util::Cllama_GetSupportBackends();
    for (const FString& Backend : Backends)
    {
        UE_LOG(LogTemp, Display, TEXT("Backend: %s"), *Backend);
    }

    // 准备 Pak 中的模型路径
    FString ModelPath = TEXT("Models/my_model.gguf");
    FString ActualPath = UAIChatPlus_Util::Cllama_PrepareModelPathFromPak(ModelPath);
    // 如果模型在 Pak 中，会解压到临时目录并返回新路径
}

文件辅助函数

void UMyClass::FileUtilities()
{
    // 获取插件基础目录
    FString PluginDir = UAIChatPlus_Util::GetPluginBaseDir(TEXT("AIChatPlus"));
    UE_LOG(LogTemp, Display, TEXT("Plugin dir: %s"), *PluginDir);

    // 复制目录
    FString SourceDir = FPaths::ProjectContentDir() / TEXT("Source");
    FString DestDir = FPaths::ProjectSavedDir() / TEXT("Backup");
    bool bCopied = UAIChatPlus_Util::CopyDirectory(SourceDir, DestDir, true);  // true = 覆盖
}

Prompt 模板

void UMyClass::PromptTemplates()
{
    // 获取 Prompt 模板 JSON 文件列表
    TArray<FDirectoryPath> ExtraDirs;  // 额外搜索目录（可选）
    TArray<FFilePath> TemplateFiles = UAIChatPlus_Util::GetPromptTemplateJsonFiles(ExtraDirs);

    // 加载 Prompt 模板
    TArray<FAIChatPlus_PromptTemplate> Templates = UAIChatPlus_Util::GetPromptTemplates(TemplateFiles);

    for (const FAIChatPlus_PromptTemplate& Template : Templates)
    {
        UE_LOG(LogTemp, Display, TEXT("Template: %s"), *Template.Name);
    }
}

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

打包

Sun, 09 Mar 2025 15:29:24 +0000

打包

插件打包

Unreal 打包的时候，会自动把插件需要的动态库文件都打包好，只需要启用插件即可。

譬如对于 Windows，打包会自动把 llama.cpp, CUDA 相关的 dll 文件都放到打包后的目录中。对于其他平台 Android / Mac / IOS 也是同样的。

可以在打包后的 Development 版本游戏里面执行指令 "AIChatPlus.PrintCllamaInfo"，查看当前的 Cllama 环境状态，确认是否状态是否正常，是否支持 GPU backend。

模型打包

假设加入项目的模型文件放在了目录 Content/LLAMA 下面，那么可以设置打包的时候包含此目录：

打开 "Project Setting"，选择 Packaging 页签，或者直接搜索 "asset package"，看到设置 "Additional Non-Asset Directories to Package"，添加目录 Content/LLAMA 即可：

添加目录之后，Unreal 在打包的时候就会自动把目录的所有文件都打包好。

读取打包后的离线模型文件

一般 Uneal 会把项目文件都打包到 .Pak 文件中，此时如果把 .Pak 中的文件路径传递给 Cllam 离线模型，是会执行失败的，因为 llama.cpp 无法直接读取 .Pak 中打包后的模型文件。

因此需要先把 .Pak 中的模型文件复制出来文件系统中，插件提供了一个方便的函数可以直接把 .Pak 的模型文件复制出来，并返回复制后的文件路径，让 Cllama 可以方便读取。

蓝图节点是 "Cllama Prepare ModelFile In Pak": 自动把 Pak 中的模型文件复制到文件系统中

C++ 代码函数是：

#include <Cllama/AIChatPlusCllama_Util.h>

auto ModelPath = FAIChatPlusCllama_Util::PrepareModelFileInPak(InContentPath);

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

版本日志

Thu, 06 Mar 2025 17:44:59 +0000

UE 插件 AIChatPlus 版本日志

v2.0.0 - 2026.02.14

Tool Calling 多平台支持: 新增 OpenAI、Claude、Gemini、Ollama、CllamaServer 五大平台的工具调用/函数调用功能
Cllama Server 集成: 完整支持本地 llama.cpp Server，包括创建、管理、Speech-to-Text，并提供编辑器可视化管理界面
JSON 蓝图库: 新增 JsonObject/JsonArray 蓝图操作类，支持 JSON 与 USTRUCT 互转
OpenAI Audio: 支持 OpenAI 音频输入输出，编辑器可预览音频响应

v1.8.0 - 2025.11.03

升级 llama.cpp b6792

v1.7.0 - 2025.07.06

升级 llama.cpp b5536

支持 UE5.6

Android 发布 shipping 会 crash，禁用掉 llama.cpp

v1.6.2 - 2025.03.17

新功能

Cllama 增加 KeepContext 参数，默认 false，Context 在 Chat 结束后自动销毁

Cllama 增加 KeepAlive 参数，可以减少 model 重复读取

v1.6.1 - 2025.03.07

Bug Fix

OpenAI Image Chat 蓝图支持输入图片

Editor Tool Cllama mmproj 模型允许空

v1.6.0 - 2025.03.02

新功能

llama.cpp 升级至 b4604 版本

Cllama 支持 GPU backends: cuda 和 metal

chat tool Cllama 支持使用 GPU

支持读取打包 Pak 中的模型文件

Bug Fix

修复 Cllama 在推理的时候 reload 会崩溃的问题

修复 ios 编译报错

v1.5.1 - 2025.01.30

新功能

只允许 Gemini 发音频

优化获取 PCMData 的方法，生成 B64 的时候再解压缩音频数据

request 增加两个回调 OnMessageFinished OnImagesFinished

优化 Gemini Method，自动根据 bStream 获取 Method

增加一些蓝图函数，方便转换 Wrapper 到实际类型，并且获取 Response Message 和 Error

Bug Fix

修复 Request Finish 多次调用问题

v1.5.0 - 2025.01.29

新功能

支持给 Gemini 发音频

编辑器工具支持发送音频和录音

Bug Fix

修复 Session copy 失败的 bug

v1.4.1 - 2025.01.04

问题修复

聊天工具支持只发图片不发信息

修复 OpenAI 接口发送图片问题失败文图

修复 OpanAI、Azure 聊天工具设置遗漏了参数 Quality、Style、ApiVersion 问题=

v1.4.0 - 2024.12.30

新功能

（实验性功能）Cllama(llama.cpp) 支持多模态模型，可以处理图片

所有的蓝图类型参数都加上了详细提示

v1.3.4 - 2024.12.05

新功能

OpenAI 支持 vision api

问题修复

修复 OpenAI stream=false 时的错误

v1.3.3 - 2024.11.25

新功能

支持 UE-5.5

问题修复

修复部分蓝图不生效问题

v1.3.2 - 2024.10.10

问题修复

修复手动停止 request 的时候 cllama 崩溃

修复商城下载版本 win 打包找不到 ggml.dll llama.dll 文件的问题

创建请求时检查是否在 GameThread 中，CreateRequest check in game thread

v1.3.1 - 2024.9.30

新功能

增加一个 SystemTemplateViewer，可以查看和使用几百个 system 设置模版

问题修复

修复从商城下载的插件，llama.cpp 找不到链接库

修复 LLAMACpp 路径过长问题

修复 windows 打包后的链接 llama.dll 错误

修复 ios/android 读取文件路径问题

修复 Cllame 设置名字错误

v1.3.0 - 2024.9.23

重大新功能

整合了 llama.cpp，支持本地离线执行大模型

v1.2.0 - 2024.08.20

新功能

支持 OpenAI Image Edit/Image Variation

支持 Ollama API，支持自动获取 Ollama 支持的模型列表

v1.1.0 - 2024.08.07

新功能

支持蓝图

v1.0.0 - 2024.08.05

新功能

基础完整功能

支持 OpenAI， Azure，Claude，Gemini

自带功能完善编辑器聊天工具

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Azure

Thu, 06 Mar 2025 17:44:59 +0000

蓝图篇 - Azure

Azure 的用法跟 OpenAI 也很相似，所以这里简略介绍

文本聊天

创建 "Azure Chat Options" 节点，设置参数 "Deployment Name", "Base Url", "Api Key"

创建 "Messages" 相关节点，并连接 "Azure Chat Request"，点击运行，即可看到屏幕上打印 Azure 返回的聊天信息。如图

创建图片

创建 "Azure Image Options" 节点，设置参数 "Deployment Name", "Base Url", "Api Key"

设置好 "Azure Image Request" 等节点，点击运行，即可看到屏幕上打印 Azure 返回的聊天信息。如图

根据上面蓝图的设置，图片会保存在路径 D:\Dwnloads\butterfly.png

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Claude

Thu, 06 Mar 2025 17:44:59 +0000

蓝图篇 - Claude

文本聊天

创建 "Options" 节点，设置参数 "Model", "Api Key", "Anthropic Version"

连接 "Claude Request" 节点和 "Messages" 相关节点，点击运行，即可看到屏幕上打印 Claude 返回的聊天信息。如图

图片生成文字

Claude 同样支持 Vision 功能

在蓝图中右键创建一个节点 Send Claude Chat Request

创建 Options 节点，并设置 Stream=true, Api Key="you api key from Clude", Max Output Tokens=1024

创建 Messages，从文件创建 Texture2D，并从 Texture2D 创建 AIChatPlusTexture，把 AIChatPlusTexture 添加到 Message 中

Event 并把信息打印到游戏屏幕上

完整的蓝图看起来是这样的，运行蓝图，即可看到游戏屏幕在打印大模型返回的消息

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Cllama (llama.cpp)(已废弃)

Thu, 06 Mar 2025 17:44:59 +0000

蓝图篇 - Cllama (llama.cpp)(已废弃)

已废弃

Cllama 已经标记为废弃，不再维护。

Cllama 原有功能由 CllamaServer 来承载。

离线模型

Cllama 是基于 llama.cpp 来实现的，支持离线使用 AI 推理模型。

由于是离线，因为我们需要先准备好模型文件，譬如从 HuggingFace 网站下载离线模型：Qwen1.5-1.8B-Chat-Q8_0.gguf

把模型放在某个文件夹下面，譬如放在游戏项目的目录 Content/LLAMA 下

E:/UE/projects/FP_Test1/Content/LLAMA > ls
qwen1.5-1_8b-chat-q8_0.gguf*

有了离线模型文件之后，我们就可以通过 Cllama 来进行 AI 聊天

文本聊天

使用 Cllama 进行文本聊天

在蓝图中右键创建一个节点 Send Cllama Chat Request

创建 Options 节点，并设置 Stream=true, ModelPath="E:\UE\projects\FP_Test1\Content\LLAMA\qwen1.5-1_8b-chat-q8_0.gguf"

创建 Messages，分别添加一条 System Message 和 User Message

创建 Delegate 接受模型输出的信息，并打印在屏幕上

完整的蓝图看起来是这样的，运行蓝图，即可看到游戏屏幕在打印大模型返回的消息

图片生成文字 llava

Cllama 还实验性支持了 llava 库，提供了 Vision 的能力

首先准备好 Multimodal 离线模型文件，例如 Moondream （moondream2-text-model-f16.gguf, moondream2-mmproj-f16.gguf）或者 Qwen2-VL（Qwen2-VL-7B-Instruct-Q8_0.gguf, mmproj-Qwen2-VL-7B-Instruct-f16.gguf）或者其他 llama.cpp 支持的 Multimodal 模型。

创建 Options 节点，分别设置参数 "Model Path" 和 "MMProject Model Path" 为对应的 Multimodal 模型文件。

创建节点读取图片文件 flower.png，并设置 Messages

最后创建节点接受返回的信息，并打印到屏幕上，完整的蓝图看起来是这样的

运行蓝图可看到返回的文字

llama.cpp 使用 GPU

"Cllama Chat Request Options" 增加参数 "Num Gpu Layer" ，可以设置 llama.cpp 的 gpu payload，可以控制需要在 GPU 上计算的层数。如图

KeepAlive

"Cllama Chat Request Options" 增加参数 "KeepAlive"，可以让读取后的模型文件保留在内存中，方便下次直接使用，减少读取模型的次数。KeepAlive 是模型保留的时间，0 表示不保留，使用后立即释放；-1 表示永久保留。每次请求设置的 Options 都可以设置不同的 KeepAlive，新的 KeepAlive 会替代旧的数值，譬如前几次的请求可以设置 KeepAlive=-1，让模型保留在内存中，直到最后一次的请求设置 KeepAlive=0，释放模型文件。

处理打包后 .Pak 中的模型文件

开启 Pak 打包后，项目的所有资源文件都会放在 .Pak 文件中，当然也包含了离线模型 gguf 文件。

由于 llama.cpp 无法支持直接读取 .Pak 文件，因此需要把 .Pak 文件中的离线模型文件拷贝出来文件系统中。

AIChatPlus 提供了一个功能函数可以自动把 .Pak 中的模型文件拷贝处理，并放在 Saved 文件夹中：

又或者你可以自己处理 .Pak 中的模型文件，关键就是需要把文件复制出来，因为 llama.cpp 无法正确读取 .Pak。

功能节点

Cllama 提供了一些功能节点方便获取当前环境下状态

"Cllama Is Valid"：判断 Cllama llama.cpp 是否正常初始化

"Cllama Is Support Gpu"：判断 llama.cpp 在当前环境下是否支持 GPU backend

"Cllama Get Support Backends": 获取当前 llama.cpp 支持的所有 backends

"Cllama Prepare ModelFile In Pak": 自动把 Pak 中的模型文件复制到文件系统中

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

DeepSeek

Thu, 06 Mar 2025 17:44:59 +0000

蓝图篇 - DeepSeek

因为 DeepSeek 兼容了 OpenAI 的 API 接口格式，所以我们可以很简单的使用 OpenAI 相关的节点来访问 DeepSeek，只要把相关的 url 修改成 DeepSeek 的 url 即可

文本聊天

创建 "OpenAI Chat Options" 节点，设置好 Model, Url, Api Key 参数

其他设置跟 OpenAI 相同，完整的蓝图看起来像这样：

运行即可在屏幕看看到 DeepSeek 的返回：

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Gemini

Thu, 06 Mar 2025 17:44:59 +0000

蓝图篇 - Gemini

文本聊天

创建 "Gemini Chat Options" 节点，设置参数 "Model", "Api Key"

创建 "Gemini Chat Request" 节点，并连接 "Options" 和 "Messages" 节点，点击运行，即可看到屏幕上打印 Gemini 返回的聊天信息，如图：

图片生成文字

同样创建 "Gemini Chat Options" 节点，设置参数 "Model", "Api Key"

从文件读取图片 flower.png，并设置到 "Messages" 上

创建 "Gemini Chat Request" 节点，点击运行，即可看到屏幕上打印 Gemini 返回的聊天信息，如图：

音频生成文字

Gemini 支持把音频转成文字

创建如下蓝图，设置加载音频，设置好 Gemini Options，点击运行，即可看到屏幕上打印 Gemini 处理音频后返回的聊天信息

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Get Started

Thu, 06 Mar 2025 17:44:59 +0000

蓝图篇 - Get Started

Get Started

下面以 OpenAI 为例，介绍蓝图的基本使用方法

文本聊天

使用 OpenAI 进行文本聊天

在蓝图中右键创建一个节点 Send OpenAI Chat Request In World

创建 Options 节点，并设置 Stream=true, Api Key="you api key from OpenAI"

创建 Messages，分别添加一条 System Message 和 User Message

创建 Delegate 接受模型输出的信息，并打印在屏幕上

完整的蓝图看起来是这样的，运行蓝图，即可看到游戏屏幕在打印大模型返回的消息

本文生成图片

使用 OpenAI 创建图片

在蓝图中右键创建一个节点 Send OpenAI Image Request，并设置 In Prompt="a beautiful butterfly"

创建 Options 节点，并设置 Api Key="you api key from OpenAI"

绑定 On Images 事件，并把图片保存到本地硬盘上

完整的蓝图看起来是这样的，运行蓝图，即可看到图片保存在指定的位置上

图片生成文字

使用 OpenAI Vision 分析图片

在蓝图中右键创建一个节点 Send OpenAI Image Request

创建 Options 节点，并设置 Api Key="you api key from OpenAI"，设置模型为 gpt-4o-mini

创建 Messages。 * 先创建节点 "Import File as Texture 2D" 从文件系统读取一张图片； * 通过节点 "Create AIChatPlus Texture From Texture2D" 把图片转换成插件可用的对象； * 通过 "Make Array" 节点把图片连接到节点 "AIChatPlus_ChatRequestMessage" 的 "Images" 字段上； * 设置 "Content" 字段内容为 "describe this image"。

如图：

完整的蓝图看起来是这样的，运行蓝图，即可看到结果显示在屏幕上

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Ollama

Thu, 06 Mar 2025 17:44:59 +0000

蓝图篇 - Ollama

获取 Ollama

可以通过 Ollama 官网获取安装包本地安装：ollama.com

可以通过其他人提供的 Ollama API 接口使用 Ollama。

本地使用 Ollama 下载模型：

> ollama run qwen:latest
> ollama run moondream:latest

文本聊天

创建 "Ollama Options" 节点，设置参数 "Model", "Base Url"，如果是本地运行的 Ollama，则 "Base Url" 一般是 "http://localhost:11434"

连接 "Ollama Request" 节点和 "Messages" 相关节点，点击运行，即可看到屏幕上打印 Ollama 返回的聊天信息。如图

图片生成文字 llava

Ollama 同样支持了 llava 库，提供了 Vision 的能力

首先获取 Multimodal 模型文件：

> ollama run moondream:latest

设置 "Options" 节点，"Model" 设置为 moondream:latest

读取图片 flower.png，并设置 Message

连接 "Ollama Request" 节点，点击运行，即可看到屏幕上打印 Ollama 返回的聊天信息。如图

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

OpenAI

Thu, 06 Mar 2025 17:44:59 +0000

蓝图篇 - OpenAI

在 Get Started 章节已经介绍过 OpenAI 的基本用法，我们在这里再给出详细的用法。

文本聊天

使用 OpenAI 进行文本聊天

在蓝图中右键创建一个节点 Send OpenAI Chat Request In World

创建 Options 节点，并设置 Stream=true, Api Key="you api key from OpenAI"

创建 Messages，分别添加一条 System Message 和 User Message

创建 Delegate 接受模型输出的信息，并打印在屏幕上

完整的蓝图看起来是这样的，运行蓝图，即可看到游戏屏幕在打印大模型返回的消息

本文生成图片

使用 OpenAI 创建图片

在蓝图中右键创建一个节点 Send OpenAI Image Request，并设置 In Prompt="a beautiful butterfly"

创建 Options 节点，并设置 Api Key="you api key from OpenAI"

绑定 On Images 事件，并把图片保存到本地硬盘上

完整的蓝图看起来是这样的，运行蓝图，即可看到图片保存在指定的位置上

图片生成文字

使用 OpenAI Vision 分析图片

在蓝图中右键创建一个节点 Send OpenAI Image Request

创建 Options 节点，并设置 Api Key="you api key from OpenAI"，设置模型为 gpt-4o-mini

如图：

完整的蓝图看起来是这样的，运行蓝图，即可看到结果显示在屏幕上

修改图片

OpenAI 支持对图片标记的区域进行修改

首先准备两张图片

一张是需要修改的图片 src.png

一张是把需要修改的区域标记出来的图片 mask.png，可以通过修改源图片，把修改区域的透明度设置成 0，即 Alpha 通道数值改成 0

分别读取以上两张照片，组合成数组

创建 "OpenAI Image Options" 节点，设置 ChatType = Edit，并修改 "End Point Url" = v1/images/edits

创建 "OpenAI Image Request"，设置 "Prompt" 为 "change into two butterfly"，连接 "Options" 节点和图片数组，并把生成的图片保存到文件系统中。

完整的蓝图看起来是这样的：

运行蓝图，生成的图片保存在指定的位置上

图片变种

OpenAI 支持根据输入的图片生成类似的变种 (Variation)

首先还是准备一张图片 src.png，并在蓝图中读取进来

创建 "OpenAI Image Options" 节点，设置 ChatType = Variation，并修改 "End Point Url" = v1/images/variations

创建 "OpenAI Image Request"，保留 "Prompt" 为空，连接 "Options" 节点和图片，并把生成的图片保存到文件系统中。

完整的蓝图看起来是这样的：

运行蓝图，生成的图片保存在指定的位置上

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

功能节点

Thu, 06 Mar 2025 17:44:59 +0000

蓝图篇 - 功能节点

插件额外提供了一些便利的蓝图功能节点

Cllama 相关

"Cllama Is Valid"：判断 Cllama llama.cpp 是否正常初始化

"Cllama Is Support Gpu"：判断 llama.cpp 在当前环境下是否支持 GPU backend

"Cllama Get Support Backends": 获取当前 llama.cpp 支持的所有 backends

"Cllama Prepare ModelFile In Pak": 自动把 Pak 中的模型文件复制到文件系统中

图像相关

"Convert UTexture2D to Base64": 把 UTexture2D 的图像转成 png base64 格式

"Save UTexture2D to .png file": 把 UTexture2D 保存成 png 文件

"Load .png file to UTexture2D": 读取 png 文件为 UTexture2D

"Duplicate UTexture2D": 复制 UTexture2D

音频相关

"Load .wav file to USoundWave": 读取 wav 文件为 USoundWave

"Convert .wav data to USoundWave": 把 wav 二进制数据转成 USoundWave

"Save USoundWave to .wav file": 把 USoundWave 保存为 .wav 文件

"Get USoundWave Raw PCM Data": 把 USoundWave 转成二进制音频数据

"Convert USoundWave to Base64": 把 USoundWave 转成 Base64 数据

"Duplicate USoundWave": 复制 USoundWave

"Convert Audio Capture Data to USoundWave": 把 Audio Capture 录音数据转成 USoundWave

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Get Started

Thu, 06 Mar 2025 17:44:59 +0000

编辑器篇 - Get Started

编辑器聊天工具

菜单栏 Tools -> AIChatPlus -> AIChat 可打开插件提供的编辑器聊天工具

工具支持文本生成、文本聊天、图像生成，图像分析。

工具的界面大致为：

主要功能

离线大模型：整合了 llama.cpp 库，支持本地离线执行大模型

文本聊天：点击左下角的 New Chat 按钮，创建新的文本聊天会话。

图像生成：点击左下角的 New Image Chat 按钮，创建新的图像生成会话。

图像分析：New Chat 的部分聊天服务支持发送图像，例如 Claude, Google Gemini。点击输入框上方的 🖼️ 或 🎨 按钮即可加载需要发送的图像。

音频处理：工具提供读取音频文件 (.wav) 和录音功能，可以使用获得的音频跟 AI 聊天。

设置当前聊天角色：聊天框上方的下拉框可以设置当前发送文本的角色，可以通过模拟不同的角色来调节 AI 聊天。

清空会话：聊天框上方的 ❌ 按可以清空当前会话的历史消息。

对话模版：内置几百种对话设置模版，方便处理常用的问题。

全局设置：点击左下角的 Setting 按钮，可以打开全局设置窗口。可以设置默认文本聊天，图像生成的 API 服务，并设置每种 API 服务的具体参数。设置会自动保存在项目的路径 $(ProjectFolder)/Saved/AIChatPlusEditor 下。

会话设置：点击聊天框上方的设置按钮，可以打开当前会话的设置窗口。支持修改会话名字，修改会话使用的 API 服务，支持独立设置每个会话使用 API 的具体参数。会话设置自动保存在 $(ProjectFolder)/Saved/AIChatPlusEditor/Sessions

聊天内容修改：鼠标悬停在聊天内容上，会出现当个聊天内容的设置按钮，支持重新生成内容、修改内容、复制内容、删除内容、在下方重新生成内容（对于角色是用户的内容）

图像浏览：对于图像生成，点击图像会打开图像查看窗口 (ImageViewer) ，支持图片另存为 PNG/UE Texture，Texture 可以直接在内容浏览器 (Content Browser) 查看，方便图片在编辑器内使用。另外还支持删除图片、重新生成图片、继续生成更多图片等功能。对于 Windows 下的编辑器，还支持复制图片，可以直接把图片复制到剪贴板，方便使用。会话生成的图片也会自动保存在每个会话文件夹下面，通常路径是 $(ProjectFolder)/Saved/AIChatPlusEditor/Sessions/${GUID}/images。

全局设置：

会话设置：

修改聊天内容：

图像查看器：

使用离线大模型

对话模版

编辑器工具使用离线模型 Cllama(llama.cpp)

以下说明如何在 AIChatPlus 编辑器工具中使用离线模型 llama.cpp

首先，从 HuggingFace 网站下载离线模型：Qwen1.5-1.8B-Chat-Q8_0.gguf

把模型放在某个文件夹下面，譬如放在游戏项目的目录 Content/LLAMA 下

E:/UE/projects/FP_Test1/Content/LLAMA
> ls
qwen1.5-1_8b-chat-q8_0.gguf*

打开 AIChatPlus 编辑器工具：Tools -> AIChatPlus -> AIChat，新建聊天会话，并打开会话设置页面

设置 Api 为 Cllama，开启 Custom Api Settings，并添加模型搜索路径，并选择模型

开始聊天！！

编辑器工具使用离线模型 Cllama(llama.cpp) 处理图片

从 HuggingFace 网站下载离线模型 MobileVLM_V2-1.7B-GGUF 同样放到目录 Content/LLAMA 下：ggml-model-q4_k.gguf 和 mmproj-model-f16.gguf。

设置会话的模型：

发送图片开始聊天

编辑器使用 OpenAI 聊天

打开聊天工具 Tools -> AIChatPlus -> AIChat，创建新的聊天会话 New Chat，设置会话 ChatApi 为 OpenAI, 设置接口参数

开始聊天：

切换模型为 gpt-4o / gpt-4o-mini，可以使用 OpenAI 的视觉功能分析图片

编辑器使用 OpenAI 处理图片（创建/修改/变种）

在聊天工具中创建新的图片会话 New Image Chat，修改会话设置为 OpenAI，并设置参数

创建图片

修改图片，把会话 Image Chat Type 修改为 Edit，并上传两张图片，一张是原图片，一张是 mask 其中透明的位置（alpha 通道为 0）表示需要修改的地方

图片变种，把会话 Image Chat Type 修改为 Variation，并上传一张图片，OpenAI 会返回一张原图片的变种

编辑器使用 Azure

新建会话（New Chat），把 ChatApi 改为 Azure，并设置 Azure 的 Api 参数

开始聊天

编辑器使用 Azure 创建图片

新建图片会话（New Image Chat），把 ChatApi 改为Azure，并设置 Azure 的 Api 参数，注意，如果是 dall-e-2 模型，需要把参数 Quality 和 Stype 设置成 not_use

开始聊天，让 Azure 创建图片

编辑器使用 Claude 聊天和分析图片

新建会话（New Chat），把 ChatApi 改为 Claude，并设置 Claude 的 Api 参数

开始聊天

编辑器使用 Ollama 聊天和分析图片

新建会话（New Chat），把 ChatApi 改为 Ollama，并设置 Ollama 的 Api 参数。如果是文本聊天，则设置模型为文本模型，如 llama3.1；如果需要处理图片，则设置模型为支持 vision 的模型，例如 moondream。

开始聊天

编辑器使用 Gemini

新建会话（New Chat），把 ChatApi 改为 Gemini，并设置 Gemini 的 Api 参数。

开始聊天

编辑器使用 Gemini 发送音频

选择从文件读取音频 / 从 Asset 读取音频 / 从麦克风录取音频，生成需要发送的音频

开始聊天

編輯器使用 Deepseek

新建会话（New Chat），把 ChatApi 改为 OpenAi，并设置 Deepseek 的 Api 参数。新增 Candidate Models 叫做 deepseek-chat，并把 Model 设置为 deepseek-chat

开始聊天

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Get Started

Thu, 06 Mar 2025 17:44:59 +0000

C++ 篇 - Get Started

模块介绍

插件分成以下几个模块：

AIChatPlusCommon: 运行时模块 (Runtime)，负责处理各种 AI API 接口发送请求和解析回复内容。
AIChatPlusEditor: 编辑器模块 (Editor)，负责实现编辑器 AI 聊天工具。
AIChatPlusCllama: 运行时模块 (Runtime)，负责封装 llama.cpp 的接口和参数，实现离线执行大模型。
Thirdparty/LLAMACpp: 运行时第三方模块 (Runtime)，整合了 llama.cpp 的动态库和头文件。

核心概念

在使用源码之前，需要了解几个核心类及其关系：

Request（请求）

UAIChatPlus_ChatRequestBase 是所有聊天请求的基类。每种 API Provider 都有对应的子类：

UAIChatPlus_OpenAIChatRequest - OpenAI 聊天请求
UAIChatPlus_AzureChatRequest - Azure 聊天请求
UAIChatPlus_ClaudeChatRequest - Claude 聊天请求
UAIChatPlus_GeminiChatRequest - Gemini 聊天请求
UAIChatPlus_OllamaChatRequest - Ollama 聊天请求
UAIChatPlus_CllamaChatRequest - Cllama 离线模型请求
UAIChatPlus_CllamaServerChatRequest - CllamaServer 本地服务器请求

Request 对象负责配置请求参数、发送请求、接收回调。

Handler（处理器）

UAIChatPlus_ChatHandlerBase 是一个可选的处理器类，用于统一管理请求的回调。

Handler 提供了以下委托：

OnStarted - 请求开始时触发
OnMessage - 收到流式消息时触发（流式输出）
OnUpdated - 收到更新时触发
OnFinished - 请求完成时触发
OnFailed - 请求失败时触发

何时使用 Handler？

需要将多个请求的回调逻辑统一管理时
需要在蓝图和 C++ 之间共享回调逻辑时
直接使用 Request 的委托（如 OnStartedListeners）同样可以实现回调监听

Options（选项）

每种 API Provider 都有对应的 Options 结构体，用于配置 API 参数：

FAIChatPlus_OpenAIChatRequestOptions - OpenAI 选项（ApiKey、Model、Temperature 等）
FAIChatPlus_ClaudeChatRequestOptions - Claude 选项
FAIChatPlus_GeminiChatRequestOptions - Gemini 选项
等等...

Options 包含了 API 连接所需的所有配置，如 API Key、端点 URL、模型名称、生成参数等。

Messages（消息）

FAIChatPlus_ChatRequestMessage 是发送给 AI 的消息结构体，包含：

Content - 文本内容
Role - 消息角色（System/User/Assistant/Developer/Tool）
Images - 图片数组（Vision 功能）
Audios - 音频数组（Audio 功能）
ToolCallUses - 工具调用请求
ToolCallResults - 工具调用结果

Response（响应）

每种 API Provider 都有对应的 ResponseBody 结构体：

FAIChatPlus_OpenAIChatResponseBody
FAIChatPlus_ClaudeChatResponseBody
等等...

ResponseBody 包含了 AI 返回的全部信息，包括：消息文本、Token 用量、工具调用、音频输出等。

基础使用流程（5 步模式）

使用 AIChatPlus 发送请求的基本流程如下：

#include "Common_OpenAI/AIChatPlus_OpenAIChatRequest.h"

void SendChatRequest()
{
    // ===== 步骤 1: 创建 Handler（可选）=====
    // Handler 用于统一管理回调，也可以直接使用 Request 的委托
    TWeakObjectPtr<UAIChatPlus_ChatHandlerBase> Handler = UAIChatPlus_ChatHandlerBase::New();

    // ===== 步骤 2: 配置 Options =====
    FAIChatPlus_OpenAIChatRequestOptions Options;
    Options.ApiKey = TEXT("your-api-key");
    Options.Model = TEXT("gpt-4o-mini");
    Options.bStream = true;  // 启用流式输出

    // ===== 步骤 3: 创建 Request =====
    TArray<FAIChatPlus_ChatRequestMessage> Messages;
    Messages.Add({TEXT("You are a helpful assistant."), EAIChatPlus_ChatRole::System});
    Messages.Add({TEXT("Hello, who are you?"), EAIChatPlus_ChatRole::User});

    auto Request = UAIChatPlus_OpenAIChatRequest::CreateWithOptionsAndMessages(Options, Messages);

    // ===== 步骤 4: 绑定回调 =====
    // 方式 A: 使用 Handler
    Handler->BindChatRequest(Request);
    Handler->OnMessage.AddLambda([](const FString& Message)
    {
        UE_LOG(LogTemp, Display, TEXT("Stream Message: %s"), *Message);
    });
    Handler->OnFinished.AddLambda([](const FAIChatPlus_ChatResponseBodyBase& Response)
    {
        UE_LOG(LogTemp, Display, TEXT("Request Finished"));
    });
    Handler->OnFailed.AddLambda([](const FAIChatPlus_ResponseErrorBase& Error)
    {
        UE_LOG(LogTemp, Error, TEXT("Request Failed: %s"), *Error.GetDescription());
    });

    // 方式 B: 直接使用 Request 的委托（不需要 Handler）
    // Request->OnMessageListeners.AddDynamic(this, &UMyClass::OnMessageReceived);
    // Request->OnFinishedListeners.AddDynamic(this, &UMyClass::OnRequestFinished);

    // ===== 步骤 5: 发送请求 =====
    Request->SendRequest();
}

简化写法

如果不需要精细的回调控制，可以使用更简洁的写法：

void SendSimpleChatRequest()
{
    FAIChatPlus_OpenAIChatRequestOptions Options;
    Options.ApiKey = TEXT("your-api-key");
    Options.Model = TEXT("gpt-4o-mini");
    Options.bStream = true;

    auto Request = UAIChatPlus_OpenAIChatRequest::CreateWithOptionsAndMessages(
        Options,
        {
            {TEXT("You are a helpful assistant."), EAIChatPlus_ChatRole::System},
            {TEXT("Hello!"), EAIChatPlus_ChatRole::User}
        });

    // 直接在 Request 上绑定 Lambda
    Request->OnMessageListeners.AddLambda([](const FString& Message)
    {
        UE_LOG(LogTemp, Display, TEXT("Message: %s"), *Message);
    });

    Request->OnFinishedListeners.AddLambda([](const FAIChatPlus_PointerWrapper& ResponseWrapper)
    {
        auto& Response = UAIChatPlus_OpenAIChatRequest::CastWrapperToResponse(ResponseWrapper);
        UE_LOG(LogTemp, Display, TEXT("Final Message: %s"), *Response.GetMessage());
    });

    Request->SendRequest();
}

通过 API Provider 枚举创建请求

如果需要根据配置动态选择 API Provider，可以使用工厂方法：

void CreateRequestByProvider(EAIChatPlus_ChatApiProvider Provider)
{
    // 根据枚举创建对应的 Request
    auto Request = UAIChatPlus_ChatRequestBase::CreateByApi(Provider);

    // 根据实际类型设置 Options
    switch (Provider)
    {
    case EAIChatPlus_ChatApiProvider::OpenAI:
        {
            auto OpenAIRequest = Cast<UAIChatPlus_OpenAIChatRequest>(Request);
            FAIChatPlus_OpenAIChatRequestOptions Options;
            Options.ApiKey = TEXT("your-api-key");
            OpenAIRequest->SetOptions(Options);
        }
        break;

    case EAIChatPlus_ChatApiProvider::Claude:
        {
            auto ClaudeRequest = Cast<UAIChatPlus_ClaudeChatRequest>(Request);
            FAIChatPlus_ClaudeChatRequestOptions Options;
            Options.ApiKey = TEXT("your-api-key");
            ClaudeRequest->SetOptions(Options);
        }
        break;
    // ... 其他 Provider
    }

    // 设置消息并发送
    TArray<FAIChatPlus_ChatRequestMessage> Messages;
    Messages.Add({TEXT("Hello!"), EAIChatPlus_ChatRole::User});
    Request->SetMessages(Messages);
    Request->SendRequest();
}

回调说明

主要回调委托

委托	触发时机	参数
`OnStarted`	请求开始发送时	无
`OnMessage`	收到流式消息时（每个 token）	`const FString& Message` - 累积的消息内容
`OnUpdated`	收到响应更新时	`const FAIChatPlus_ResponseBodyBase& Response`
`OnFinished`	请求成功完成时	`const FAIChatPlus_ResponseBodyBase& Response`
`OnFailed`	请求失败时	`const FAIChatPlus_ResponseErrorBase& Error`
`OnMessageFinished`	消息接收完成时	`const FAIChatPlus_MessageFinishedPayload& Payload`

流式输出 vs 非流式输出

流式输出 (bStream = true)：OnMessage 会多次触发，每次返回累积的消息内容
非流式输出 (bStream = false)：OnMessage 只在完成时触发一次，返回完整消息

下一步

更多详细用法请参考各 API Provider 的专题文档：

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

UE 实现各种图片 (UTexture2D) 操作（读取、保存、复制、剪贴板...）

Thu, 08 Aug 2024 15:41:08 +0000

UE 实现各种图片 (UTexture2D) 操作（读取、保存、复制、剪贴板...）

以下代码都是以 UE5.3 版本为例。

源码

更多源码细节可在 UE 商城获取插件：AIChatPlus

读取：UE 实现读取本地系统图片为 UTexture2D

通用方法

本方法在编辑器和 GamePlay 模式下都可行，支持的图片文件格式有 PNG, JPEG, BMP, ICO, EXR, ICNS, HDR, TIFF, DDS, TGA，基本能覆盖大部分的常用图片类型。

代码也很简洁：

#include <Engine/Texture2D.h>
#include <ImageUtils.h>

UTexture2D* LoadImage(const FString& InLoadPath)
{
    FImage ImageInfo;
    FImageUtils::LoadImage(*InLoadPath, ImageInfo);
    return FImageUtils::CreateTexture2DFromImage(ImageInfo);
}

返回的即是 UTexture2D。

编辑器专用方法

本方法可以额外支持更多的图片类型：UDIM 纹理贴图、IES 文件、PCX 、PSD。

代码实现上会更复杂一些：

#include <Engine/Texture2D.h>
#include <Misc/FileHelper.h>
#include <Misc/Paths.h>
#include <UObject/UObjectGlobals.h>

#if WITH_EDITOR
UTexture2D* LoadImage(const FString& InLoadPath)
{

    TArray64<uint8> Buffer;
    if (!FFileHelper::LoadFileToArray(Buffer, *InLoadPath))
    {
        return nullptr;
    }

    const FString TextureName;
    const FString Extension = FPaths::GetExtension(InLoadPath).ToLower();
    const uint8* BufferPtr = Buffer.GetData();

    auto TextureFact = NewObject<UTextureFactory>();
    UTexture2D* Ret = Cast<UTexture2D>(TextureFact->FactoryCreateBinary(
        UTexture2D::StaticClass(), GetTransientPackage(), *TextureName, RF_Transient,
        NULL, *Extension, BufferPtr, BufferPtr + Buffer.Num(), GWarn));

    return Ret;
}
#endif

实现是使用了 UTextureFactory 的 FactoryCreateBinary 函数，这个函数能够读取前面提到的额外文件类型。

复制：UE 实现复制 UTexture2D

有的时候需要复制一个 UTexture2D 出来，再对这个复制出来的图片进行修改，复制图片需要使用到引擎自带的函数 FImageCore::CopyImage，只要设置好两个图片的参数，调用这个接口即可

UTexture2D* CopyTexture2D(UTexture2D* InTexture, UObject* Outer, FName Name, EObjectFlags Flags)
{
    // src texture info, src ImageView
    FTextureMipDataLockGuard InTextureGuard(InTexture);
    uint8* SrcMipData = InTextureGuard.Lock(LOCK_READ_ONLY);        // Texture->GetPlatformData()->Mips[0].BulkData.Lock(InLockFlag)
    const int32 InSizeX = InTexture->GetSizeX();
    const int32 InSizeY = InTexture->GetSizeY();
    const EPixelFormat InFormat = InTexture->GetPixelFormat();
    const FImageView SrcMipImage(
        SrcMipData, InSizeX, InSizeY, 1, GetRawImageFormat(InFormat), InTexture->GetGammaSpace());

    // create dst texture
    UTexture2D* NewTexture = NewObject<UTexture2D>(Outer, Name, Flags);
    NewTexture->SetPlatformData(new FTexturePlatformData());
    NewTexture->GetPlatformData()->SizeX = InSizeX;
    NewTexture->GetPlatformData()->SizeY = InSizeY;
    NewTexture->GetPlatformData()->SetNumSlices(1);
    NewTexture->GetPlatformData()->PixelFormat = InFormat;

    // Allocate first mipmap.
    int32 NumBlocksX = InSizeX / GPixelFormats[InFormat].BlockSizeX;
    int32 NumBlocksY = InSizeY / GPixelFormats[InFormat].BlockSizeY;
    FTexture2DMipMap* Mip = new FTexture2DMipMap();
    Mip->SizeX = InSizeX;
    Mip->SizeY = InSizeY;
    Mip->SizeX = 1;
    NewTexture->GetPlatformData()->Mips.Add(Mip);
    Mip->BulkData.Lock(LOCK_READ_WRITE);
    Mip->BulkData.Realloc((int64)NumBlocksX * NumBlocksY * GPixelFormats[InFormat].BlockBytes);
    Mip->BulkData.Unlock();

    // dst texture ImageView
    uint8* DstMipData = static_cast<uint8*>(NewTexture->GetPlatformData()->Mips[0].BulkData.Lock(LOCK_READ_WRITE));
    const FImageView DstMipImage(
        DstMipData, InSizeX, InSizeY, 1, GetRawImageFormat(InFormat), InTexture->GetGammaSpace());

    // run CopyImage
    FImageCore::CopyImage(SrcMipImage,DstMipImage);

#if WITH_EDITORONLY_DATA
    NewTexture->Source.Init(
        InSizeX, InSizeY, 1, 1,
        FImageCoreUtils::ConvertToTextureSourceFormat(GetRawImageFormat(InFormat)), DstMipData);
#endif

    // cleanup
    NewTexture->GetPlatformData()->Mips[0].BulkData.Unlock();
    NewTexture->UpdateResource();

    return NewTexture;
}

保存：UE 实现保存 UTexture2D 到文件

核心是使用引擎函数 FImageUtils::SaveImageAutoFormat，实现起来比较简单，不过需要注意失败重试的情况

void SaveImage(UTexture2D* InImage, const FString& InSavePath)
{
    if (!InImage) return;
    FImage ImageInfo;
    if (FImageUtils::GetTexture2DSourceImage(InImage, ImageInfo))
    {
        FImageUtils::SaveImageAutoFormat(*InSavePath, ImageInfo);
    }
    else
    {
        // if prev save failed
        // use ConvertTextureToStandard to change InImage to Standard format, and try again
        // then revert InImage's origin format
        // this is what FTextureMipDataLockGuard does
        FTextureMipDataLockGuard InImageGuard(InImage);

        uint8* MipData = InImageGuard.Lock(LOCK_READ_ONLY);
        check( MipData != nullptr );

        const FImageView MipImage(
            MipData, InImage->GetSizeX(), InImage->GetSizeY(), 1,
            GetRawImageFormat(InImage->GetPixelFormat()), InImage->GetGammaSpace());

        FImageUtils::SaveImageAutoFormat(*InSavePath, MipImage);
    }
}

保存：UE 实现保存 UTexture2D 到 Asset

保存内存中的 UTexture2D 到 Asset 中，并可以在资源浏览器 (Content Browser) 中查看。

核心函数需要用到上面实现的 CopyTexture2D，我们需要先复制出来一个新的图片，然后再调用 UPackage::SavePackage 把图片所在的 Package 保存成 Asset。

void SaveTextureToAsset(UTexture2D* InTexture)
{
    if (!InTexture) return;

    // open save asset dialog, choose where/which to save
    FSaveAssetDialogConfig SaveAssetDialogConfig;

    SaveAssetDialogConfig.DefaultPath =  FEditorDirectories::Get().GetLastDirectory(ELastDirectory::NEW_ASSET);
    SaveAssetDialogConfig.AssetClassNames.Add(UTexture2D::StaticClass()->GetClassPathName());
    SaveAssetDialogConfig.ExistingAssetPolicy = ESaveAssetDialogExistingAssetPolicy::AllowButWarn;
    SaveAssetDialogConfig.DialogTitleOverride = FAIChatPlusEditor_Constants::FCText::SaveAsAsset;

    const FContentBrowserModule& ContentBrowserModule = FModuleManager::LoadModuleChecked<FContentBrowserModule>("ContentBrowser");
    const FString SaveObjectPath = ContentBrowserModule.Get().CreateModalSaveAssetDialog(SaveAssetDialogConfig);

    if (SaveObjectPath.IsEmpty()) return;

    // init save info
    const FString PackageName = FPackageName::ObjectPathToPackageName(SaveObjectPath);
    const FString PackageFileName = FPackageName::LongPackageNameToFilename(PackageName, FPackageName::GetAssetPackageExtension());
    const FString PackagePath = FPaths::GetPath(PackageFileName);
    const FString TextureName = FPaths::GetBaseFilename(PackageName);

    // create new UPackage to put the new texture in
    UPackage* const NewPackage = CreatePackage(*PackageName);
    NewPackage->FullyLoad();

    // copy texture
    UTexture2D* NewTexture = UAIChatPlus_Util::CopyTexture2D(
        InTexture, NewPackage, FName(TextureName), RF_Public | RF_Standalone | RF_Transactional);

    // Generate the thumbnail
    // if not doing so, the texture will not have thumbnail in content browser
    FObjectThumbnail NewThumbnail;
    ThumbnailTools::RenderThumbnail(
        NewTexture, NewTexture->GetSizeX(), NewTexture->GetSizeY(),
        ThumbnailTools::EThumbnailTextureFlushMode::NeverFlush, NULL,
        &NewThumbnail);
    ThumbnailTools::CacheThumbnail(NewTexture->GetFullName(), &NewThumbnail, NewPackage);

    // setting up new package and new texture
    NewPackage->MarkPackageDirty();
    FAssetRegistryModule::AssetCreated(NewTexture);
    FEditorDirectories::Get().SetLastDirectory(ELastDirectory::NEW_ASSET, FPaths::GetPath(PackageName));

    // save args
    FSavePackageArgs SaveArgs;
    SaveArgs.TopLevelFlags = RF_Public | RF_Standalone;
    SaveArgs.bForceByteSwapping = true;
    SaveArgs.bWarnOfLongFilename = true;

    // save it
    if (!UPackage::SavePackage(NewPackage, NewTexture, *PackageFileName, SaveArgs))
    {
        UE_LOG(AIChatPlusEditor, Error, TEXT("Failed to save Asset: [%s]\n"), *PackageFileName);
    }
}

剪贴板：UE 实现复制图片 (UTexture2D) 到 Windows 剪贴板 (Clipboard)

Windows 相关函数

我们会用到以下 Windows 操作剪贴板的相关函数：

OpenClipboard：打开剪贴板，获取剪贴板的 Handler 。
EmptyClipboard：清空剪贴板，并把剪贴板的所有权分配给当前的窗口。
SetClipboardData：设置剪贴板的数据，图片的数据是通过这个接口发送给剪贴板。
CloseClipboard：设置好数据之后，关闭剪贴板。

剪贴板的图片格式

标准剪贴板格式里面介绍了可用的剪贴板格式，其中 CF_DIBV5 即可以用来设置图片。

CF_DIBV5 要求的格式具体定义 BITMAPV5HEADER 结构，在这里我们选用以下配置

BITMAPV5HEADER Header;
Header.bV5CSType        = LCS_sRGB;
Header.bV5Compression   = BI_BITFIELDS;

UTexture2D 设置

我们在上面选择了剪贴板图片的颜色空间是 LCS_sRGB，即 sRGB 颜色空间，那么 UTexture2D 也需要先设置到对应的格式：

bool ConvertTextureToStandard(UTexture2D* InTexture)
{
    if (InTexture->CompressionSettings != TC_VectorDisplacementmap)
    {
        InTexture->CompressionSettings = TC_VectorDisplacementmap;
        IsChanged = true;
    }
    if (InTexture->SRGB != true)
    {
        InTexture->SRGB = true;
        IsChanged = true;
    }
    if (IsChanged)
    {
        InTexture->UpdateResource();
    }
}

ConvertTextureToStandard 就是负责把 UTexture2D 转换成标准格式：TC_VectorDisplacementmap (RGBA8) 和 SRGB 颜色空间。对齐了 UTexture2D 和 Windows 剪贴板的图片格式之后，我们就可以把图片的数据复制到剪贴板上。

具体代码

void CopyTexture2DToClipboard(UTexture2D* InTexture)
{
    if (!InTexture) return;

    FTextureMipDataLockGuard InTextureGuard(InTexture);
    // get InTexture info
    uint8* SrcMipData = InTextureGuard.Lock(LOCK_READ_ONLY);
    const int32 InSizeX = InTexture->GetSizeX();
    const int32 InSizeY = InTexture->GetSizeY();
    const EPixelFormat InFormat = InTexture->GetPixelFormat();
    const FImageView SrcMipImage(
        SrcMipData, InSizeX, InSizeY, 1, GetRawImageFormat(InTexture), InTexture->GetGammaSpace());

    // set clipboard Texture info
    const EPixelFormat OutFormat = PF_B8G8R8A8;
    const int32 NumBlocksX = InSizeX / GPixelFormats[OutFormat].BlockSizeX;
    const int32 NumBlocksY = InSizeY / GPixelFormats[OutFormat].BlockSizeY;
    const int64 BufSize = static_cast<int64>(NumBlocksX) * NumBlocksY * GPixelFormats[InFormat].BlockBytes;

    // set header info
    BITMAPV5HEADER Header;
    Header.bV5Size          = sizeof(BITMAPV5HEADER);
    Header.bV5Width         = InSizeX;
    Header.bV5Height        = -InSizeY;
    Header.bV5Planes        = 1;
    Header.bV5BitCount      = 32;
    Header.bV5Compression   = BI_BITFIELDS;
    Header.bV5SizeImage     = BufSize;
    Header.bV5XPelsPerMeter = 0;
    Header.bV5YPelsPerMeter = 0;
    Header.bV5ClrUsed       = 0;
    Header.bV5ClrImportant  = 0;
    Header.bV5RedMask       = 0x00FF0000;
    Header.bV5GreenMask     = 0x0000FF00;
    Header.bV5BlueMask      = 0x000000FF;
    Header.bV5AlphaMask     = 0xFF000000;
    Header.bV5CSType        = LCS_sRGB;
    // Header.bV5Endpoints;    // ignored
    Header.bV5GammaRed      = 0;
    Header.bV5GammaGreen    = 0;
    Header.bV5GammaBlue     = 0;
    Header.bV5Intent        = 0;
    Header.bV5ProfileData   = 0;
    Header.bV5ProfileSize   = 0;
    Header.bV5Reserved      = 0;

    HGLOBAL WinBuf = GlobalAlloc(GMEM_MOVEABLE, sizeof(BITMAPV5HEADER) + BufSize);
    if (WinBuf == NULL)
        return;

    HWND WinHandler = GetActiveWindow();
    if (!OpenClipboard(WinHandler)) {
        GlobalFree(WinBuf);
        return;
    }
    verify(EmptyClipboard());

    // copy InTexture into BGRA8 sRGB Standard Texture
    FTexture2DMipMap* DstMip = new FTexture2DMipMap();
    DstMip->SizeX = InSizeX;
    DstMip->SizeY = InSizeY;
    DstMip->SizeZ = 1;
    DstMip->BulkData.Lock(LOCK_READ_WRITE);
    uint8* DstMipData = static_cast<uint8*>(DstMip->BulkData.Realloc(BufSize));
    const FImageView DstMipImage(
        DstMipData, InSizeX, InSizeY, 1, ERawImageFormat::BGRA8, EGammaSpace::sRGB);

    FImageCore::CopyImage(SrcMipImage,DstMipImage);
    DstMip->BulkData.Unlock();

    // copy Standard Texture data into Clipboard
    void * WinLockedBuf = GlobalLock(WinBuf);
    if (WinLockedBuf) {
        memcpy(WinLockedBuf, &Header, sizeof(BITMAPV5HEADER));
        memcpy((char*)WinLockedBuf + sizeof(BITMAPV5HEADER), DstMipData, BufSize);
    }
    GlobalUnlock(WinLockedBuf);

    if (!SetClipboardData(CF_DIBV5, WinBuf))
    {
        UE_LOG(AIChatPlus_Internal, Fatal, TEXT("SetClipboardData failed with error code %i"), (uint32)GetLastError() );
    }

    // finish, close clipboard
    verify(CloseClipboard());

    delete DstMip;
}

UTexture2D 跟 Base64 之间的转换

这个实现起来比较简单，直接上代码

#include <Misc/Base64.h>
#include <ImageUtils.h>

UTexture2D* B64ToImage(const FString& B64)
{
    TArray<uint8> Data;
    FBase64::Decode(B64, Data);
    return FImageUtils::ImportBufferAsTexture2D(Data);
}

FString ImageToB64(UTexture2D* InTexture, const int32 InQuality)
{
    FTextureMipDataLockGuard InTextureGuard(InTexture);

    uint8* MipData = InTextureGuard.Lock(LOCK_READ_ONLY);
    check(MipData != nullptr);

    const FImageView InImage(
        MipData, InTexture->GetSizeX(), InTexture->GetSizeY(), 1,
        GetRawImageFormat(InTexture->GetPixelFormat()), InTexture->GetGammaSpace());

    TArray64<uint8> Buffer;
    FString Ret;
    if (FImageUtils::CompressImage(Buffer, TEXT("png"), InImage, InQuality))
    {
        Ret = FBase64::Encode(Buffer.GetData(), Buffer.Num());
    }
    return Ret;
}

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

UE 编辑器插件 UE.EditorPlus 说明文档

Sun, 04 Aug 2024 15:51:52 +0000

UE 编辑器插件 UE.EditorPlus 说明文档

介绍视频

插件源码

UE.EditorPlus

商城下载

EditorPlus

项目添加源码插件 EU.EditorPlus

参考文档：

中文：UE 通过插件源码添加插件
English: UE adds plugins through the plugin source code

插件说明

UE.EditorPlus 是一个 UE 编辑器插件，提供了一种方便的方式来扩展编辑器菜单，并支持高级方式来扩展，同时包含了一些实用的编辑器工具。本插件支持 UE5.3+。

扩展编辑器菜单

说明

支持多种方式扩展编辑器菜单：

路径方式：RegisterPathAction("/<MenuBar>Bar/<SubMenu>SubMenu/<Command>Action")
实例化方式：EP_NEW_MENU(FEditorPlusMenuBar)("Bar")
混合方式：RegisterPath("/<MenuBar>Bar/<SubMenu>SubMenu/<Command>Action",EP_NEW_MENU(FEditorPlusCommand)("Action")

路径方式

可以通过这样的方式来注册一个编辑器菜单指令：

FEditorPlusPath::RegisterPathAction(
    "/<MenuBar>Bar/<SubMenu>SubMenu/<Command>Action",
    FExecuteAction::CreateLambda([]
        {
            // do action
        })
);

这样就可以在编辑器菜单栏 Help 后面增加一个菜单栏 Bar，Bar 里面增加一个子菜单 SubMenu， SubMenu 里面增加一个命令 Action。

完整的路径格式会是这样的：/<Hook>HookName/<Type1>Name1/<Type2>Name2，第一个路径必须是 <Hook>，目前支持的类型和限制：

<Hook>：表示需要在哪个 Hook 的位置上生成菜单，后续路径不能有 <Hook>
<MenuBar>：菜单栏，后面路径不能有 <Hook>, <MenuBar>, <ToolBar>
<ToolBar>: 工具栏，后面路径不能有 <Hook>, <MenuBar>, <ToolBar>
<Section>：菜单分节，后面路径不能有 <Hook>, <MenuBar>, <Section>
<Separator>：菜单分隔符，后面路径不能有 <Hook>, <MenuBar>
<SubMenu>：子菜单，后面路径不能有 <Hook>, <MenuBar>
<Command>：菜单命令，后面不能有任何路径
<Widget>：更多可扩展定制的 Slate UI 组件，后面不能有任何路径

更简易的路径形式：/BarName/SubMenuName1/SubMenuName2/CommandName，如果不指定类型，默认路径的第一个是 <MenuBar>，中间的是 <SubMenu>，最后的是 <Command>。

如果没有指定 <Hook> 则自动最前面加上 <Hook>Help，表示在 Help 菜单后面添加菜单栏。

实例化方式

路径方式是自动把所有节点根据类型和默认参数实例化出来，我们也可以自己控制实例化，可以更细致控制扩展的内容。

EP_NEW_MENU(FEditorPlusMenuBar)("MyBar", "MyBar", LOCTEXT("MyBar", "MyBar"), LOCTEXT("MyBarTips", "MyBarTips"))
->RegisterPath()
->Content({
    EP_NEW_MENU(FEditorPlusSubMenu)("MySubMenu")
    ->Content({
        EP_NEW_MENU(FEditorPlusCommand)("MyAction")
        ->BindAction(FExecuteAction::CreateLambda([]
            {
                // do action
            })),
    })
});

实例化 MyBar 的时候可以传入 Hook 名字，本地化名字，本地化提示参数（"MyBar", LOCTEXT("MyBar", "MyBar"), LOCTEXT("MyBarTips", "MyBarTips")）。上面代码就相当于路径方式 /<Hook>Help/<MenuBar>MyBar/<SubMenu>MySubMenu/<Command>MyAction。

混合方式

当然还可以两种方式混合使用：

FEditorPlusPath::RegisterPath(
    "/<MenuBar>Bar/<SubMenu>SubMenu/<Command>Action",
    EP_NEW_MENU(FEditorPlusCommand)("Action")
    ->BindAction(FExecuteAction::CreateLambda([]
        {
            // do action
        })),
);

这种情况下，插件会自动实例化中间路径的节点，最后的路径使用用户自己实例化的节点。

接口说明

class EDITORPLUS_API FEditorPlusPath
{
public:

    static TSharedPtr<FEditorPlusMenuBase> RegisterPath(const FString& Path, const TSharedPtr<FEditorPlusMenuBase>& Menu=nullptr);
    static TSharedPtr<FEditorPlusMenuBase> RegisterPath(const FString& Path, const FText& FriendlyName, const FText& FriendlyTips);
    static TSharedPtr<FEditorPlusMenuBase> RegisterPathAction(
        const FString& Path, const FExecuteAction& ExecuteAction, const FName& Hook=EP_FNAME_HOOK_AUTO,
        const FText& FriendlyName=FText::GetEmpty(), const FText& FriendlyTips=FText::GetEmpty());

    static TSharedPtr<FEditorPlusMenuBase> RegisterChildPath(
        const TSharedRef<FEditorPlusMenuBase>& InParent, const FString& Path, const TSharedPtr<FEditorPlusMenuBase>& Menu=nullptr);
    static TSharedPtr<FEditorPlusMenuBase> RegisterChildPath(
        const TSharedRef<FEditorPlusMenuBase>& InParent, const FString& Path, const FText& FriendlyName, const FText& FriendlyTips);
    static TSharedPtr<FEditorPlusMenuBase> RegisterChildPathAction(
        const TSharedRef<FEditorPlusMenuBase>& InParent, const FString& Path, const FExecuteAction& ExecuteAction,
        const FName& Hook=EP_FNAME_HOOK_AUTO, const FText& FriendlyName=FText::GetEmpty(), const FText& FriendlyTips=FText::GetEmpty());

    static bool UnregisterPath(
        const FString& Path, const TSharedPtr<FEditorPlusMenuBase>& Leaf=nullptr);

    static TSharedPtr<FEditorPlusMenuBase> GetNodeByPath(const FString& Path);
};

RegisterPath：生成路径菜单
RegisterPathAction：生成路径菜单，并自动为末端 <Command> 节点绑定操作
RegisterChildPath：为指定节点继续生成子路径
RegisterChildPathAction：为指定节点继续生成子路径，并自动绑定操作
UnregisterPath：删除路径，Leaf 在有多个同名的末端节点可以指定严格匹配。删除的过程中，会回溯中间节点，一旦中间节点没有任何子节点也会被删除
GetNodeByPath：根据路径获取节点

节点类型

// base class of all node
class EDITORPLUS_API FEditorPlusMenuBase: public TSharedFromThis<FEditorPlusMenuBase> {}

class EDITORPLUS_API FEditorPlusHook: public TEditorPlusMenuBaseRoot {}

class EDITORPLUS_API FEditorPlusMenuBar: public TEditorPlusMenuBaseNode {}

class EDITORPLUS_API FEditorPlusToolBar: public TEditorPlusMenuBaseNode {}

class EDITORPLUS_API FEditorPlusSection: public TEditorPlusMenuBaseNode {}

class EDITORPLUS_API FEditorPlusSeparator: public TEditorPlusMenuBaseNode{}

class EDITORPLUS_API FEditorPlusSubMenu: public TEditorPlusMenuBaseNode {}

class EDITORPLUS_API FEditorPlusCommand: public TEditorPlusMenuBaseLeaf {}

class EDITORPLUS_API FEditorPlusWidget: public TEditorPlusMenuBaseLeaf {}

更多样例和接口说明请参考源码 UE.EditorPlus，测试用例 MenuTest.cpp

模块化管理

UE.EditorPlus 还提供了一个模块化管理扩展菜单的框架，支持插件加载和卸载的时候，自动加载和卸载扩展的菜单

让菜单类继承 IEditorPlusToolInterface，并覆写 OnStartup 和 OnShutdown 函数。OnStartup 负责创建菜单，OnShutdown 负责调用节点的 Destroy 函数清理菜单。单节点的引用数归0，则会执行自动清理。

class FMenuTest: public IEditorPlusToolInterface
{
public:
    virtual void OnStartup() override;
    virtual void OnShutdown() override;
}

void FMenuTest::OnStartup()
{
    BuildPathMenu();
    BuildCustomMenu();
    BuildMixMenu();
    BuildExtendMenu();
}

void FMenuTest::OnShutdown()
{
    for(auto Menu: Menus)
    {
        if(Menu.IsValid()) Menu->Destroy();
    }
    Menus.Empty();
}

菜单管理类继承 IEditorPlusToolManagerInterface，并覆写 AddTools 函数，在 AddTools 里面添加菜单类

class FEditorPlusToolsImpl: public IEditorPlusToolManagerInterface
{
public:
    virtual void AddTools() override;
}

void FEditorPlusToolsImpl::AddTools()
{
    if (!Tools.Num())
    {
        Tools.Emplace(MakeShared<FMenuTest>());
    }

}

插件加载和卸载的时候分别调用管理类的 StartupTools 和 ShutdownTools 函数

void FEditorPlusToolsModule::StartupModule()
{
    Impl = FEditorPlusToolsImpl::Get();
    Impl->StartupTools();

}
void FEditorPlusToolsModule::ShutdownModule()
{
    Impl->ShutdownTools();
}

完成以上适配，则可以自动在加载和卸载插件的时候，自动加载和卸载扩展的菜单。

编辑器工具

UE.EditorPlus 还提供了一些实用的编辑器工具

创建编辑器窗口

使用 EditorPlus，可以很简单的创建一个新的编辑器窗口

// register spawn tab
Tab = MakeShared<FEditorPlusTab>(LOCTEXT("ClassBrowser", "ClassBrowser"), LOCTEXT("ClassBrowserTip", "Open the ClassBrowser"));
Tab->Register<SClassBrowserTab>();

// register menu action to spawn tab
FEditorPlusPath::RegisterPathAction(
    "/EditorPlusTools/ClassBrowser",
    FExecuteAction::CreateSP(Tab.ToSharedRef(), &FEditorPlusTab::TryInvokeTab),
);

SClassBrowserTab 是一个自定义的 UI 控件

class SClassBrowserTab final : public SCompoundWidget
{
    SLATE_BEGIN_ARGS(SClassBrowserTab)
    {}
    SLATE_END_ARGS()
    // ...
}

ClassBrowser

ClassBrowser 是一个 UE Class 查看器，通过菜单 EditorPlusTools -> ClassBrowser 来打开

基于 UE 的反射来实现，可以很方便查看 UE 各种类型的成员信息，说明提示等，支持模糊搜索，并能跳转打开父类的信息。

MenuCollections

MenuCollections 是一个菜单命令快速查找和收藏工具，能够帮助你快速找到需要执行的菜单命令，并可以收藏常用命令，提升效率。

SlateResourceBrowser

SlateResourceBrowser 是一个可以快速查看 Slate UI 资源的工具，能够帮助你浏览和查找需要的编辑器资源，方便扩展编辑器。

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

说明文档

Sun, 04 Aug 2024 15:49:54 +0000

UE 插件 AIChatPlus 说明文档

插件商城

AIChatPlus

公共仓库

UE.AIChatPlus.Public

插件简介

最新版本 v2.0.0。

本插件支持 UE5.2 - UE5.7。

UE.AIChatPlus 是一个 UnrealEngine 插件，该插件实现了与各种 GPT AI 聊天服务进行通信，目前支持的服务有 OpenAI (ChatGPT, DALL-E)，Azure OpenAI (ChatGPT, DALL-E), Claude, Google Gemini, Ollama, llama.cpp 本地离线。未来还会继续支持更多服务提供商。它的实现基于异步 REST 请求，性能高效，方便 UE 开发人员接入这些 AI 聊天服务。

同时 UE.AIChatPlus 还包含了一个编辑器工具，可以直接在编辑器中使用这些 AI 聊天服务，生成文本和图像，分析图像等。

主要功能

全新！所有 API 支持 ToolCall。

全新！OpenAI/Azure 支持 speech-to-text 和 text-to-speech。

全新！蓝图支持 Json。

全新！离线 AI llama.cpp 升级至版本 b6792。

全新！离线 AI llama.cpp 支持 GPU Cuda 和 Metal。

全新！支持 Gemini 语音转文字。

API：支持 OpenAI、Azure OpenAI、Claude、Gemini、Ollama、llama.cpp、DeepSeek

离线实时 API：支持 llama.cpp 离线运行 AI，支持 GPU Cuda 和 Metal。

文本转文本：各种 API 支持文本生成。

文本转图像：OpenAI Dall-E

图像转文本：OpenAI Vision、Claude、Gemini、Ollama、llama.cpp

图像转图像：OpenAI Dall-E

语音转文本：Gemini

蓝图：所有 API 和功能都支持蓝图

编辑器聊天工具：功能丰富、精心打造的编辑器 AI 聊天工具

异步调用：所有的 API 都可以异步调用

实用工具：各种图像、音频工具

支持的 API：

离线 llama.cpp：与 llama.cpp 库集成，可以离线运行 AI 模型！还支持多模态模型（实验性）。支持 Win64/Mac/Android/IOS。支持 GPU CUDA 和 METAL。

OpenAI：/chat/completions、/completions、/images/generations、/images/edits、/images/variations

Azure OpenAI：/chat/completions、/images/generations

Claude：/messages、/complete

Gemini：:generateText、:generateContent、:streamGenerateContent

Ollama：/api/chat、/api/generate、/api/tags

DeepSeek：/chat/completions

使用说明

更改日志

更改日志

技术支持

评论：有任何问题欢迎在下面评论区留言

邮件：也可以通过邮箱给我发邮件 ( disenonec@gmail.com )

discord: 即将上线

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Python 杂谈 2 - Python3.12 热更新

Fri, 12 Jan 2024 06:37:04 +0000

Python 杂谈 2 - Python3.12 热更新

记录如何在 Python3.12 中实现热更新

热更新

热更新（Hot Reload）可以理解在不需要重启程序的情况下对其进行更新的技术。这项技术在游戏行业有广泛的应用，开发者对游戏问题进行修复的时候，为了不对玩家造成影响，往往需要采用一些静默更新的方式，也就是热更新。

Python 热更新

Python 本身是动态语言，一切皆是对象，是有能力做到热更新的。我们可以粗略把 Python 中的需要热更的对象分成两种：数据和函数。

数据，可以理解成游戏中的数值或者设定，譬如玩家的等级，装备等等一些数据，部分数据是不应该热更的（譬如玩家当前等级，玩家身上拥有哪些装备，这些数据的修改不应该通过热更来实现），部分数据是我们想要热更的（譬如装备的基础数值设定，技能的基础数值设定，UI 上的文字等等）。

函数，可以理解成游戏逻辑，这基本都是我们想要热更的，逻辑错误基本都需要通过热更新函数来实现。

下面我们来具体看看有什么方法可以对 Python3.12 执行热更新。

Hotfix

第一种方法我们叫做 Hotfix，通过让程序（客户端程序 / 服务端程序都可以）执行一段特定的 Python 代码，实现对数据和函数的热更新。一段简单的 Hotfix 代码可能是这样：

# hotfix code

# hotfix data
import weapon_data
weapon_data.gun.damage = 100

# hotfix func
import player
def new_fire_func(self, target):
    target.health -= weapon_data.gun.damage
    # ...
player.Player.fire_func = new_fire_func

以上代码简单展示 Hotfix 的写法，数据 / 函数修改之后，程序后续访问的时候就会读到新的数据 / 函数来执行。

如果你比较细致，你可能会有一个疑问：那如果其他代码里面引用住了这些需要修改数据和函数，会发生什么事情？

# attack.py module

player_fire = player.Player.fire_func

def player_attack_by_gun(player, target):
    player_fire(player, target)
    # ...

答案是，前面的 Hotfix 对这种情况是不生效的，fire_func 这个函数相当于在其他模块多了一份副本，该模块中调用的是函数的副本，我们修改函数本体对副本不生效。

所以需要注意，一般代码中尽量减少模块级别的数据引用和函数引用，避免出现这种 Hotfix 不生效的情况，如果代码已经是这样写的，Hotfix 需要多做一些工作：

# hotfix code
# ...

import attack
attack.player_fire = player.Player.fire_func

在对数据 / 函数本体 Hotfix 修改之后，再额外对引用的地方进行修改。这些额外的修改很容易被遗漏，所以我们还是建议，从代码规范上来尽量避免多处引用的写法。

综上，Hotfix 能满足热更的基本需求，同时存在以下问题：

如果数据/函数被其他模块明确引用住，需要额外对这些模块的引用 Hotfix
如果有大量的数据/函数需要 Hotfix，那么 Hotfix 的代码会变得很庞大，维护难度上升，也更容易出错

Reload

本章节源码可从这里获得：python_reloader

我们更想要的是自动热更新，不需要额外写 Hotfix，只需要更新代码文件，让程序执行一个 Reload 函数则会自动替换新的函数和新的数据。我们把这个自动热更新的功能叫做 Reload。

Python3.12 提供了 importlib.reload 函数，可以重新加载模块，但是却是全量加载，并且返回新的模块对象，对于其他模块中的引用，并不能自动修改，也就是其他模块如果 import 了 reload 的模块，那么访问的依然是旧的模块对象。这个功能比我们的 Hotfix 好不了多少，更何况是全量 reload 模块，不能由我们控制哪些数据应该保留。我们想要自己实现一个 Reload 功能，满足这些要求：

自动替换函数，同时旧函数的引用依然有效，并会执行新函数的内容
自动替换数据，同时可控制部分替换
保留旧模块的引用，通过旧模块就能访问到新的内容
需要 Reload 的模块可控

要完成这些要求，我们需要借助 Python 里面 meta_path 的机制，详细的介绍可以看官方文档 the-meta-path。

sys.meta_path 里面可以定义我们的元路径查找器对象，譬如我们把用于 Reload 的查找器叫做 reload_finder，reload_finder 需要实现一个函数 find_spec 并返回 spec 对象。Python 拿到 spec 对象后，会依次执行 spec.loader.create_module 和 spec.loader.exec_module 完成模块的导入。

如果我们在这个过程中，执行新的模块代码，并把新的模块里面的函数和需要的数据复制到旧模块中，则可以达到 Reload 的目的：

class MetaFinder:
    def __init__(self, reloader):
        self._reloader = reloader

    def find_spec(self, fullname, path, target=None):
        # find source file
        finder = importlib.machinery.PathFinder()
        spec = finder.find_spec(fullname, path)
        if not spec:
            return

        old_module = self._reloader.GetOldModule(fullname)
        if old_module:
            # run new code in old module dict
            code = spec.loader.get_code(fullname)
            exec(code, old_module.__dict__)
            module = old_module
        else:
            # if old module not exists, just create a new one
            module = import_util.module_from_spec(spec)
            spec.loader.exec_module(module)

        try:
            self._reloader.ReloadModule(module)
        except:
            sys.excepthook(*sys.exc_info())

        return import_util.spec_from_loader(fullname, MetaLoader(module))


class MetaLoader:
    def __init__(self, module):
        self._module = module

    def create_module(self, spec):
        return self._module

    def exec_module(self, module):
        # restore __spec__
        module.__spec__ = module.__dict__.pop('__backup_spec__')
        module.__loader__ = module.__dict__.pop('__backup_loader__')

如上，find_spec 加载最新的模块源码，并在旧模块的 __dict__ 里面执行新模块的代码，之后我们调用 ReloadModule 来处理类 / 函数 / 数据的引用和替换。MetaLoader 的目的是适配 meta_path 机制，给 Python 虚拟机返回我们处理过的模块对象。

处理完加载的流程，再来看 ReloadModule 的大致实现

# ...
def ReloadModule(self, module):
    old_module_info = self._old_module_infos.get(module.__name__)
    if not old_module_info:
        return

    self.ReloadDict(module, old_module_info, module.__dict__)

def ReloadDict(self, module, old_dict, new_dict, _reload_all_data=False, _del_func=False):
    dels = []

    for attr_name, old_attr in old_dict.items():

        if attr_name in self.IGNORE_ATTRS:
            continue

        if attr_name not in new_dict:
            if _del_func and (inspect.isfunction(old_attr) or inspect.ismethod(old_attr)):
                dels.append(attr_name)
            continue

        new_attr = new_dict[attr_name]

        if inspect.isclass(old_attr):
            new_dict[attr_name] = self.ReloadClass(module, old_attr, new_attr)

        elif inspect.isfunction(old_attr):
            new_dict[attr_name] = self.ReloadFunction(module, old_attr, new_attr)

        elif inspect.ismethod(old_attr) or isinstance(old_attr, classmethod) or isinstance(old_attr, staticmethod):
            self.ReloadFunction(module, old_attr.__func__, new_attr.__func__)
            new_dict[attr_name] = old_attr

        elif inspect.isbuiltin(old_attr) \
                or inspect.ismodule(old_attr) \
                or inspect.ismethoddescriptor(old_attr) \
                or isinstance(old_attr, property):
            # keep new
            pass

        elif not _reload_all_data and not self.NeedUpdateData(module, new_dict, attr_name):
            # keep old data
            new_dict[attr_name] = old_attr

    if dels:
        for name in dels:
            old_dict.pop(name)
# ...

ReloadDict 里面会区分处理不同类型的对象

如果是 class，则调用 ReloadClass，会返回旧模块的引用，并更新 class 的成员
如果是 function / method ，则调用 ReloadFunction，会返回旧模块的引用，并更新函数的内部数据
如果是数据，并且需要保留，则会回滚 new_dict[attr_name] = old_attr
其余的都保持新的引用
删除新模块不存在的函数

ReloadClass，ReloadFunction 的具体代码这里不再展开分析，有兴趣可以直接看源码。

整个 Reload 的过程，可以概括为：旧瓶装新酒。为了保持模块/模块的函数/模块的类/模块的数据有效，我们需要保留原来的这些对象的引用（躯壳），转而去更新它们内部的具体数据，譬如对于函数，更新 __code__，__dict__ 等数据，函数执行的时候，就会转而执行新的代码。

总结

本文详细介绍了 Python3 的两种热更新方式，每种都有相应的应用场景，希望能对你有帮助。有任何疑问欢迎随时交流。

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

UE 设置本地化多语言

Thu, 28 Dec 2023 18:06:38 +0000

UE 设置本地化多语言

记录如何在 UE 中实现本地化多语言

如果不熟悉 UE 扩展菜单，建议先简单看下：UE 扩展编辑器菜单，ue-使用路径形式扩展菜单

本文代码基于插件：UE.EditorPlus

功能介绍

UE 自带工具可以实现本地化多语言，譬如我们可以为编辑器菜单实现本地化：

中文菜单：

英文菜单：

代码声明

为了实现菜单本地化，我们需要在代码中明确声明需要 UE 处理的字符串，使用 UE 定义好的宏 LOCTEXT 和 NSLOCTEXT：

文件全局定义方式，先开始定义一个叫做 LOCTEXT_NAMESPACE 的宏，内容是当前多语言文本所在的名字空间，之后文件中的文本就可以用 LOCTEXT 来定义，文件最后取消宏 LOCTEXT_NAMESPACE：

// #define LOCTEXT(InKey, InTextLiteral)

#define LOCTEXT_NAMESPACE "EditorPlusTools"
LOCTEXT("Key", "Content");
#undef LOCTEXT_NAMESPACE

局部定义方式，使用 NSLOCTEXT，定义文本的时候带上名字空间参数：

// #define NSLOCTEXT(InNamespace, InKey, InTextLiteral)

NSLOCTEXT("EditorPlusTools", "Key", "Content");

UE 工具通过查找宏 LOCTEXT 和 NSLOCTEXT 的出现来收集出所有需要翻译的文本。

使用工具翻译文本

假设我们有如下代码定义文本：

#define LOCTEXT_NAMESPACE "EditorPlusTools"
// register path node loctext
FEditorPlusPath::GetNodeByPath("/MenuTest")->SetFriendlyName(LOCTEXT("MenuTest", "MenuTest"))->SetFriendlyTips(LOCTEXT("MenuTestTips", "MenuTestTips"));
FEditorPlusPath::GetNodeByPath("/MenuTest/<SubMenu>SubMenu1")->SetFriendlyName(LOCTEXT("SubMenu1", "SubMenu1"))->SetFriendlyTips(LOCTEXT("SubMenu1Tips", "SubMenu1Tips"));
FEditorPlusPath::GetNodeByPath("/MenuTest/<SubMenu>SubMenu1/<SubMenu>SubMenu1")->SetFriendlyName(LOCTEXT("SubMenu1", "SubMenu1"))->SetFriendlyTips(LOCTEXT("SubMenu1Tips", "SubMenu1Tips"));
FEditorPlusPath::GetNodeByPath("/<Hook>Help/<MenuBar>MenuTest/<SubMenu>SubMenu1/<Section>Section1")->SetFriendlyName(LOCTEXT("Section1", "Section1"))->SetFriendlyTips(LOCTEXT("Section1Tips", "Section1Tips"));
#undef LOCTEXT_NAMESPACE

首先开启翻译工具，打开编辑器设置 编辑 - 编辑器偏好设置，勾选 通用 - 试验性功能 - Tools - 翻译选取器：

然后打开翻译工具 工具 - 本地化控制板：

新建一个目标（在默认的 Game 下面也行，新建一个是为了方便管理和移动这些翻译文本）

配置目标的参数，我这里名字改为 EditorPlusTools，加载政策是 编辑器，从文本收集，并加上插件目录，目标依赖性是 Engine, Editor，其他配置保持不变：

添加语系，保证有中文（简体）和英文两个语系，确认鼠标放在语言名字上分别显示 zh-Hans 和 en，并选中英语（因为我们代码里面是用英文定义的文本，我们这里需要收集这些英语文本）：

点击收集文本：

会弹出收集进度框，等待收集成功，会显示绿色对钩：

关掉收集进度框，回到翻译工具可以看到英文一行有显示收集到的数量，本身英文的我们不需要翻译，点开中文一行的翻译按钮：

打开后我们可以看到未翻译一栏有内容，在英文文本的右边一栏输入翻译后的内容，翻译内容都完成之后，保存退出窗口：

点击统计字数，结束后能看到中文一栏显示了翻译的数量：

最后编译文本：

翻译的数据会放在 Content\Localization\EditorPlusTools 里面，每种语言一个文件夹，在 zh-Hans 里面能看到两个文件，.archive 是收集和翻译的文本，.locres 则是编译之后的数据：

翻译好的文本放入插件目录中

我们上面给插件生成的翻译文本放在了项目目录下面，我们需要把这些文本移动到插件里面，方便随着插件一起发布。

把 Content\Localization\EditorPlusTools 目录移动到插件目录 Content 下面，我这里是 Plugins\UE.EditorPlus\Content\Localization\EditorPlusTools。

修改项目的配置文件 DefaultEditor.ini，加上新路径：

[Internationalization]
+LocalizationPaths=%GAMEDIR%Plugins/UE.EditorPlus/Content/Localization/EditorPlusTools

这样，其他项目拿到插件后，只要修改 DefaultEditor.ini 则可以直接使用翻译文本，不需要重新配置翻译。

注意事项

在生成翻译数据的过程中，遇到过一些问题，以下总结出来注意的事项：

代码里面定义文本必须要用宏 LOCTEXT 和 NSLOCTEXT，文本需要是字符串常量，这样 UE 才是收集出来。
翻译目标名字不能带有符号 .，Content\Localiztion\ 下的目录名字不能带有 .，UE 只会截取 . 前面的名字。会导致 UE 在读取翻译文本的时候，由于名字错误，读取失败。
对于编辑器插件，需要判断如果是命令行模式 IsRunningCommandlet() 则不生成菜单和 SlateUI ，因为命令行模式下没有 Slate 模块，会导致收集文本的时候报错 Assertion failed: CurrentApplication.IsValid()。如果你也遇到类似的报错，可以尝试加上这个判断。具体报错信息：

Assertion failed: CurrentApplication.IsValid() [File:E:\UE\ue5.3_git\Engine\Source\Runtime\Slate\Public\Framework\Application\SlateApplication.h] [Line: 255]

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

UE 使用路径形式扩展菜单

Thu, 28 Dec 2023 09:35:18 +0000

记录如何在 UE 中实现路径形式扩展菜单

如果不熟悉 UE 扩展菜单，建议先简单看下：UE 扩展编辑器菜单

本文代码基于插件：UE.EditorPlus

节点管理

把菜单按照树的结构来管理，父节点可以包含孩子：

class EDITORPLUS_API FEditorPlusMenuBase: public TSharedFromThis<FEditorPlusMenuBase>
{
protected:
    // sub menus
    TArray<TSharedRef<FEditorPlusMenuBase>> Children;
}

在创建父节点的同时创建子节点：

void FEditorPlusMenuBase::Register(FMenuBuilder& MenuBuilder)
{
    for (const auto Menu: Children)
    {
        Menu->Register(MenuBuilder);
    }
}

当然每个节点的具体创建行为会有点不同，覆写虚函数来实现：

// Menubar
void FEditorPlusMenuBar::Register(FMenuBarBuilder& MenuBarBuilder)
{
    MenuBarBuilder.AddPullDownMenu(
        GetFriendlyName(),
        GetFriendlyTips(),
        // Delegate to call Register
        FEditorPlusMenuManager::GetDelegate<FNewMenuDelegate>(GetUniqueId()),       
        Hook);
}

// Section
void FEditorPlusSection::Register(FMenuBuilder& MenuBuilder)
{
    MenuBuilder.BeginSection(Hook, GetFriendlyName());
    FEditorPlusMenuBase::Register(MenuBuilder);
    MenuBuilder.EndSection();
}

// Separator
void FEditorPlusSeparator::Register(FMenuBuilder& MenuBuilder)
{
    MenuBuilder.AddMenuSeparator(Hook);
    FEditorPlusMenuBase::Register(MenuBuilder);
}

// SubMenu
void FEditorPlusSubMenu::Register(FMenuBuilder& MenuBuilder)
{
    MenuBuilder.AddSubMenu(
        GetFriendlyName(),
        GetFriendlyTips(),
        FNewMenuDelegate::CreateSP(this, &FEditorPlusSubMenu::MakeSubMenu),
        false,
        FSlateIcon(),
        true,
        Hook
    );
}

// Command
void FEditorPlusCommand::Register(FMenuBuilder& MenuBuilder)
{
    MenuBuilder.AddMenuEntry(
        CommandInfo->Label, CommandInfo->Tips, CommandInfo->Icon,
        CommandInfo->ExecuteAction, CommandInfo->Hook, CommandInfo->Type);
}

// ......

通过路径生成节点

按照树形结构组织好菜单，路径格式就可以定义一条菜单的树形结构：

"/<Hook>Help/<MenuBar>BarTest/<SubMenu>SubTest/<Command>Action"

以上路径即可以定义一系列菜单的创建：

<Hook>Help：位置在 Hook 名字为 Help 的菜单后
<MenuBar>BarTest：创建类型 MenuBar 的菜单，名字为 BarTest
<SubMenu>SubTest：创建子节点，类型 SubMenu, 名字 SubTest
<Command>Action：最后创建一个命令

接口调用形式可以很简洁：

const FString Path = "/<Hook>Help/<MenuBar>BarTest/<SubMenu>SubTest/<Command>Action";
FEditorPlusPath::RegisterPathAction(
    Path, 
    FExecuteAction::CreateLambda([]
    {
        // do action
    })
);

自定义形式生成节点

我们依然保留了笨重的方式来创建菜单，笨重的方式可以允许有更详细的设置，代码的组织形式跟 UE 的 SlateUI 写法有些像：

EP_NEW_MENU(FEditorPlusMenuBar)("BarTest")
->RegisterPath()
->Content({
    EP_NEW_MENU(FEditorPlusSubMenu)("SubTest")
    ->Content({
        EP_NEW_MENU(FEditorPlusCommand)("Action")
        ->BindAction(FExecuteAction::CreateLambda([]
            {
                // do action
            })),
    })
});

混合形式

当然，本身路径形式和自定义生成的菜单，都是相同的，它们之间可以混用，有很大的灵活性：

FEditorPlusPath::RegisterPath(
    "/<MenuBar>BarTest/<SubMenu>SubMenu/<Command>Action1", 
    EP_NEW_MENU(FEditorPlusCommand)("Action1")
    ->BindAction(FExecuteAction::CreateLambda([]
        {
            // do action
        })),
);

FEditorPlusPath::RegisterPath(
    "/<MenuBar>BarTest/<SubMenu>SubMenu/<Command>Action2", 
    EP_NEW_MENU(FEditorPlusCommand)("Action2")
    ->BindAction(FExecuteAction::CreateLambda([]
        {
            // do action
        })),
);

多个地方定义的菜单，会合并到同一个树形结构中，名字相同的节点会认为是同一个节点。换言之，路径是唯一的，同一个路径可以唯一确定一个菜单节点。于是我们也可以把节点找出来，重新做一些设置和修改：

// set Name and Tips
FEditorPlusPath::GetNodeByPath("/<MenuBar>BarTest")->SetFriendlyName(LOCTEXT("MenuTest", "MenuTest"))->SetFriendlyTips(LOCTEXT("MenuTestTips", "MenuTestTips"));

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

UE 扩展编辑器菜单

Mon, 25 Dec 2023 17:20:26 +0000

UE 扩展编辑器菜单

记录 UE 如何扩展编辑器菜单

Hook

Hook 可以理解为扩展菜单的锚点，我们可以设置新加的菜单命令在 Hook 的前面或者后面，UE 自带的编辑器菜单命令基本都带有 Hook，UE5 下打开 编辑 - 编辑器偏好设置 - 通用 - 其他 - 显示 UI 扩展点 来显示所有菜单的 Hook：

模块依赖

需要在项目 .Build.cs 文件里面加上依赖的模块 LevelEditor, Slate, SlateCore, EditorStyle, EditorWidgets, UnrealEd, ToolMenus：

PrivateDependencyModuleNames.AddRange(
    new string[]
    {
        "Core",
        "Engine",
        "CoreUObject",
        "LevelEditor",
        "Slate",
        "SlateCore",
        "EditorStyle",
        "EditorWidgets",
        "UnrealEd",
        "ToolMenus",
    }
    );

添加菜单栏

直接上代码

auto MenuExtender = MakeShared<FExtender>();

MenuExtender->AddMenuBarExtension(
    "Help", EExtensionHook::After,      // Create After Help
    nullptr,
    FMenuBarExtensionDelegate::CreateLambda([](FMenuBarBuilder& MenuBarBuilder)
    {
        MenuBarBuilder.AddPullDownMenu(
            TEXT("MenuTest"),       // Name
            TEXT("MenuTest"),       // Tips
            FNewMenuDelegate::CreateLambda([](FMenuBuilder& MenuBuilder)
            {
                // create sub menus
            }),
            TEXT("MenuText"));      // New Hook
    })
);
FModuleManager::LoadModuleChecked<FLevelEditorModule>("LevelEditor").GetMenuExtensibilityManager()->AddExtender(MenuExtender);

执行以上代码可以看到在帮助后面加上了一个菜单栏 MenuTest:

添加命令

使用接口 MenuBuilder.AddMenuEntry：

// Inside MenuTest Lambda
MenuBuilder.AddMenuEntry(
    FText::FromName("MenuTestAction"), FText::FromName("MenuTestAction"),
    FSlateIcon(), FUIAction(FExecuteAction::CreateLambda([]()
    {
        // do action
    })));

把以上代码放到 CreateLambda 里面，即可生成菜单命令：

菜单分节

使用 MenuBuilder.BeginSection 和 MenuBuilder.EndSection：

MenuBuilder.BeginSection(NAME_None, FText::FromName("MenuTestSection"));
// code to create action
MenuBuilder.EndSection();

分隔符

MenuBuilder.AddMenuSeparator();

子菜单

子菜单类似菜单栏，需要在 Lambda 里面定义：

MenuBuilder.AddSubMenu(
    FText::FromName("MenuTestSub"), 
    FText::FromName("MenuTestSub"), 
    FNewMenuDelegate::CreateLambda([](FMenuBuilder& MenuBuilder)
    {
        MenuBuilder.AddMenuEntry(
            FText::FromName("MenuTestSubAction"), FText::FromName("MenuTestSubAction"),
            FSlateIcon(), FUIAction(FExecuteAction::CreateLambda([]()
            {
                // do action
            })));
    }));

SlateUI 控件

还可以添加 UI 控件：

MenuBuilder.AddWidget(
    SNew(SHorizontalBox)
        + SHorizontalBox::Slot()
        .AutoWidth()
        [
            SNew(SEditableTextBox)
            .MinDesiredWidth(50)
            .Text(FText::FromName("MenuTestWidget"))
        ]

        + SHorizontalBox::Slot()
        .AutoWidth()
        .Padding(5, 0, 0, 0)
        [
        SNew(SButton)
        .Text(FText::FromName("ExtendWidget"))
        .OnClicked(FOnClicked::CreateLambda([]()
        {
            // do action
            return FReply::Handled();
        }))
        ],
    FText::GetEmpty()
);

Slate UI 相关的内容这里不详细展开，有兴趣可以去另外找文章看。

Hook 增加菜单

譬如在 工具 - 编程 里面增加一个命令：

MenuExtender->AddMenuExtension(
    "Programming", EExtensionHook::After,
    nullptr,
    FMenuExtensionDelegate::CreateLambda([](FMenuBuilder& MenuBuilder)
    {
        MenuBuilder.AddMenuEntry(
        FText::FromName("MenuTestAction"), FText::FromName("MenuTestAction"),
        FSlateIcon(), FUIAction(FExecuteAction::CreateLambda([]()
        {
            // do action
        })));
    })
);

同理可以添加其他菜单类型。

完整代码

void BuildTestMenu()
{
    auto MenuExtender = MakeShared<FExtender>();

    MenuExtender->AddMenuBarExtension(
        "Help", EExtensionHook::After,
        nullptr,
        FMenuBarExtensionDelegate::CreateLambda([](FMenuBarBuilder& MenuBarBuilder)
        {
            MenuBarBuilder.AddPullDownMenu(
                FText::FromName("MenuTest"),
                FText::FromName("MenuTest"),
                FNewMenuDelegate::CreateLambda([](FMenuBuilder& MenuBuilder)
                {
                    MenuBuilder.BeginSection(NAME_None, FText::FromName("MenuTestSection"));
                    MenuBuilder.AddMenuSeparator();
                    MenuBuilder.AddMenuEntry(
                        FText::FromName("MenuTestAction"), FText::FromName("MenuTestAction"),
                        FSlateIcon(), FUIAction(FExecuteAction::CreateLambda([]()
                        {
                            // do action
                        })));

                    MenuBuilder.AddSubMenu(
                        FText::FromName("MenuTestSubb"),
                        FText::FromName("MenuTestSubb"),
                        FNewMenuDelegate::CreateLambda([](FMenuBuilder& MenuBuilder)
                        {
                            MenuBuilder.AddMenuEntry(
                                FText::FromName("MenuTestSubAction"), FText::FromName("MenuTestSubAction"),
                                FSlateIcon(), FUIAction(FExecuteAction::CreateLambda([]()
                                {
                                    // do action
                                })));
                        }));
                    MenuBuilder.EndSection();

                    MenuBuilder.AddWidget(
                    SNew(SHorizontalBox)
                         + SHorizontalBox::Slot()
                         .AutoWidth()
                         [
                             SNew(SEditableTextBox)
                             .MinDesiredWidth(50)
                             .Text(FText::FromName("MenuTestWidget"))
                         ]
                         + SHorizontalBox::Slot()
                         .AutoWidth()
                         .Padding(5, 0, 0, 0)
                         [
                            SNew(SButton)
                            .Text(FText::FromName("ExtendWidget"))
                            .OnClicked(FOnClicked::CreateLambda([]()
                            {
                                // do action
                                return FReply::Handled();
                            }))
                         ],
                     FText::GetEmpty()
                    );
                }),
                "MenuTest");
        })
    );

    MenuExtender->AddMenuExtension(
        "Programming", EExtensionHook::After,
        nullptr,
        FMenuExtensionDelegate::CreateLambda([](FMenuBuilder& MenuBuilder)
        {
            MenuBuilder.AddMenuEntry(
            FText::FromName("MenuTestAction"), FText::FromName("MenuTestAction"),
            FSlateIcon(), FUIAction(FExecuteAction::CreateLambda([]()
            {
                // do action
            })));
        })
    );

    FModuleManager::LoadModuleChecked<FLevelEditorModule>("LevelEditor").GetMenuExtensibilityManager()->AddExtender(MenuExtender);
}

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Contact and Subscribe

Sat, 02 Dec 2023 05:09:54 +0000

Contact and Subscribe

Sat, 02 Dec 2023 05:09:54 +0000

Contact and Subscribe

Sat, 02 Dec 2023 05:09:54 +0000

Contact and Subscribe

Sat, 02 Dec 2023 05:09:54 +0000

Contact and Subscribe

Sat, 02 Dec 2023 05:09:54 +0000

Contact and Subscribe

Sat, 02 Dec 2023 05:09:54 +0000

Contact and Subscribe

Sat, 02 Dec 2023 05:09:54 +0000

使用 FASTBuild 编译 UE4 和 UE5

Fri, 01 Dec 2023 00:00:00 +0000

本文方法经测试支持 UE4.27 - UE5.3，其他版本未测试过，可以尝试。

前言

FASTBuild 是一个免费开源的分布式编译工具，UE 本身编译比较耗时，如果可以用上 FASTBuild，能够大大减少耗时。

UE 从 4.x 开始能够支持 FASTBuild，官方源码自带了魔改过的 FASTBuild 工具，基于 FASTBuild 0.99 版本，位置在 Engine\Extras\ThirdPartyNotUE\FASTBuild，UE5.3 同样使用的是这个版本。这个已经是比较久以前的版本了，截止本文创建时间，FASTBuild 官方最新版本是 1.11，有了更多新的功能支持和 bug 修复。本文着重记录如何使用 1.11 版本同时支持 UE4 和 UE5。

简易配置

要达到目的，我们需要对 FASTBuild 1.11 和 UE 源码做一些修改。在这里，其实我已经都修改完了，于是我们可以直接用我修改完的版本来使用。

FASTBuild 下载我提交的最新版本里面的执行文件 FBuild.exe, FBuildCoordinator.exe, FBuildWorker.exe。为了清晰表达，下面把使用 FBuild.exe 来进行编程的机器叫做本机，其他提供 CPU 参与编辑的远程机器叫做远程机。

本机配置

把 FBuild.exe 所在目录加入系统环境变量 Path 中，保证 cmd 里面能直接执行 FBuild.exe。

配置 Cache 共享目录（如果不需要生成 Cache 的话，可以不配置）：把一个空目录设置成共享路径，并确认远程机可以访问。

打开本机 UE4 / UE5 的源码项目，修改编译配置文件 Engine\Saved\UnrealBuildTool\BuildConfiguration.xml 如下：

<?xml version="1.0" encoding="utf-8" ?>
<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
    <BuildConfiguration>
        <bAllowFASTBuild>true</bAllowFASTBuild>
    </BuildConfiguration>
    <FASTBuild>
        <bEnableDistribution>true</bEnableDistribution>
        <bEnableCaching>true</bEnableCaching>
        <FBuildCachePath>\\127.0.0.1\Cache\</FBuildCachePath>
        <FBuildCoordinator>127.0.0.1</FBuildCoordinator>
    </FASTBuild>
</Configuration>

本机运行之前下载的 FBuildCoordinator.exe。

远程机配置

同样配置 Cache，只是 ip 需要指定到本机 ip，这里假定为 192.168.1.100

FASTBUILD_CACHE_PATH: \192.168.1.100\Cache
FASTBUILD_CACHE_MODE: rw

同样配置 Coordinator ip

FASTBUILD_COORDINATOR: 192.168.1.100

配置完如下图

远程机上运行 FBuildWorker.exe，如果配置成功，可以看到本机的 FBuildCoordinator.exe 上会打印日志（这里 192.168.1.101 是远程机的 ip）：

FBuildCoordinator - v1.11-UE
[2023-12-01-20:06:38] Listening on port 31392
[2023-12-01-20:06:38] current [0] workers: []
[2023-12-01-20:06:42] New worker available: 192.168.1.101
[2023-12-01-20:06:42] current [1] workers: [192.168.1.101]

测试 UE 编译

用 VisualStudio 打开 UE 源码工程 sln，选一个 C++ 的项目，点击 Rebuild。如果配置正常，可以看到类似如下的日志

11>FBuild Command Line Arguments: '-monitor -summary -dist -cache -ide -j12 -clean -config "E:\UE\ue5.3_git\Engine\Intermediate\Build\fbuild.bff" -nostoponerror
11>FBuild Executable: 'd:\libs\FASTBuild\bin\FBuild.exe
11>FBuild Coordinator: '127.0.0.1
11>FBuild BrokeragePath: '\\127.0.0.1\Brokerage\
11>FBuild CachePath: '\\127.0.0.1\Cache\
11>BFF file 'E:\UE\ue5.3_git\Engine\Intermediate\Build\fbuild.bff' has changed (reparsing will occur).
11>Using Coordinator: 127.0.0.1
11>Requesting worker list from Corrdinator
11>Get Worker List from Coordinator.
11>2 workers in payload: [192.168.1.101]
11>Worker list received: 1 workers
11>Distributed Compilation : 1 Workers in pool '127.0.0.1'

FASTBuild 能找到远程机的 ip，并开始给远程机发送编译。在远程机的 FBuildWorker 上也能看到当前有编译任务在执行。

进阶配置

支持更久版本的 UE

如果你发现自己的 UE 没有 FASTBuild 工具（Engine\Extras\ThirdPartyNotUE\FASTBuild），并且项目 UnrealBuildTool 里面没有 FASTBuild.cs 文件，那么很大概率是你的 UE 版本还不支持 FASTBuild。

那么你需要参考 UE4.27 的源码，也创建一个类似的 FASTBuild.cs，并补上其他相关代码的修改，这里不详述。

编译自己的 FASTBuild

如果你对 FASTBuild 本身也感兴趣，或者想要做一些修改，可以尝试用 FASTBuild 来编译 FASTBuild。

下载我的最新源码，并解压

修改 External\SDK\VisualStudio\VS2019.bff，把 .VS2019_BasePath 和 .VS2019_Version 修改成你本机对应的内容，Version 可以在 .VS2019_BasePath\Tools\MSVC 目录下面看，例如

.VS2019_BasePath        = 'C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional\VC'    // <-- Set path here
.VS2019_Version         = '14.29.30133' // <-- Set version here
.VS2019_MSC_VER         = '1929' // <-- Set MSC_VER here

修改 External\SDK\Windows\Windows10SDK.bff 的 .Windows10_SDKBasePath 和 .Windows10_SDKVersion，版本可以在 .Windows10_SDKBasePath/bin 里面看：

.Windows10_SDKBasePath        = 'C:\Program Files (x86)\Windows Kits/10'    // <-- Set path here
.Windows10_SDKVersion         = '10.0.19041.0' // <-- Set version here

修改 External\SDK\Clang\Windows\Clang11.bff 的 .Clang11_BasePath 和 .Clang11_Version，路径在 .VS2019_BasePath\Tools\Tools/LLVM/x64

.Clang11_BasePath = 'C:/Program Files (x86)/Microsoft Visual Studio/2019/Professional/VC/Tools/LLVM/x64'    // <-- Set path here
.Clang11_Version  = '12.x.x'

进入 Code 目录，在 cmd 执行 FBuild.exe All-x64-Release，如果配置正常，可以看到编译成功，在 tmp\x64-Release\Tools\FBuild\FBuild 能看到 FBuild.exe。

FBuild.exe All-x64-Release -dist -coordinator=127.0.0.1 可以开启分布式编译。

FBuild 更多选项

我提供的 FBuild 本身支持以下常用的选项：

coordinator: 指定 Coordinator ip 地址（可以覆盖系统环境变量的值）
brokerage: 指定 Brokerage 地址（可以覆盖系统环境变量的值）
nocache：强制不使用 cache
dist：开启分布式编译
forceremote：强制在远程机编译
summary: 编辑结束后输出统计报告

等等，更多选项可以运行 FBuild.exe -help 来看。

FBuildWorker 常用的选项有：

coordinator: 指定 Coordinator ip 地址（可以覆盖系统环境变量的值）
brokerage: 指定 Brokerage 地址（可以覆盖系统环境变量的值）
nocache：强制不使用 cache
cpus: 指定分配多少个核参与编译

更多选项可以运行 FBuildWorder.exe -help 来看。

修改 UE 自带的 FASTBuild.cs

UE 自带的 FASTBuild.cs 并没有很好的处理系统环境变量，跟 BuildConfiguration.xml 指定的参数的关系，很多参数是优先读取了系统环境变量，这显然跟 BuildConfiguration.xml 的使用逻辑是相反的。

为此，可以把相关的代码改成这样，这里以 UE5.3 为例：

private bool ExecuteBffFile(string BffFilePath, ILogger Logger)
{
    string CacheArgument = "";

    if (bEnableCaching)
    {
        switch (CacheMode)
        {
            case FASTBuildCacheMode.ReadOnly:
                CacheArgument = "-cacheread";
                break;
            case FASTBuildCacheMode.WriteOnly:
                CacheArgument = "-cachewrite";
                break;
            case FASTBuildCacheMode.ReadWrite:
                CacheArgument = "-cache";
                break;
        }
    }
    else
    {
        CacheArgument = "-nocache";
    }

    string DistArgument = bEnableDistribution ? "-dist" : "";
    string ForceRemoteArgument = bForceRemote ? "-forceremote" : "";
    string NoStopOnErrorArgument = bStopOnError ? "" : "-nostoponerror";
    string IDEArgument = IsApple() ? "" : "-ide";
    string MaxProcesses = "-j" + ((ParallelExecutor)LocalExecutor).NumParallelProcesses;

    // Interesting flags for FASTBuild:
    // -nostoponerror, -verbose, -monitor (if FASTBuild Monitor Visual Studio Extension is installed!)
    // Yassine: The -clean is to bypass the FASTBuild internal
    // dependencies checks (cached in the fdb) as it could create some conflicts with UBT.
    // Basically we want FB to stupidly compile what UBT tells it to.
    string FBCommandLine = $"-monitor -summary {DistArgument} {CacheArgument} {IDEArgument} {MaxProcesses} -clean -config \"{BffFilePath}\" {NoStopOnErrorArgument} {ForceRemoteArgument}";

    Logger.LogInformation("FBuild Command Line Arguments: '{FBCommandLine}", FBCommandLine);

    string FBExecutable = GetExecutablePath()!;
    Logger.LogInformation("FBuild Executable: '{FBExecutable}", FBExecutable);

    string WorkingDirectory = Path.GetFullPath(Path.Combine(Unreal.EngineDirectory.MakeRelativeTo(DirectoryReference.GetCurrentDirectory()), "Source"));

    ProcessStartInfo FBStartInfo = new ProcessStartInfo(FBExecutable, FBCommandLine);
    FBStartInfo.UseShellExecute = false;
    FBStartInfo.WorkingDirectory = WorkingDirectory;
    FBStartInfo.RedirectStandardError = true;
    FBStartInfo.RedirectStandardOutput = true;

    string? Coordinator = GetCoordinator();
    if (!String.IsNullOrEmpty(Coordinator))
    {
        Logger.LogInformation("FBuild Coordinator: '{Coordinator}", Coordinator);
        FBStartInfo.EnvironmentVariables["FASTBUILD_COORDINATOR"] = Coordinator;
    }

    string? BrokeragePath = GetBrokeragePath();
    if (!String.IsNullOrEmpty(BrokeragePath))
    {
        Logger.LogInformation("FBuild BrokeragePath: '{BrokeragePath}", BrokeragePath);
        FBStartInfo.EnvironmentVariables["FASTBUILD_BROKERAGE_PATH"] = BrokeragePath;
    }

    string? CachePath = GetCachePath();
    if (!String.IsNullOrEmpty(CachePath))
    {
        Logger.LogInformation("FBuild CachePath: '{CachePath}", CachePath);
        FBStartInfo.EnvironmentVariables["FASTBUILD_CACHE_PATH"] = CachePath;
    }
...

BuildConfiguration.xml 进阶配置

<?xml version="1.0" encoding="utf-8" ?>
<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
    <ProjectFileGenerator>
        <!-- 指定vs版本 -->
        <Format>VisualStudio2022</Format>
    </ProjectFileGenerator>
    <BuildConfiguration>
        <!-- 开启 FASTBuild -->
        <bAllowFASTBuild>true</bAllowFASTBuild>
        <!-- 指定本机参与编译的 cpu 核数 -->
        <MaxParallelActions>12</MaxParallelActions>
        <!-- 关闭 Incredibuild -->
        <bAllowXGE>false</bAllowXGE>
    </BuildConfiguration>
    <FASTBuild>
        <!-- 指定 FBuild 路径 -->
        <FBuildExecutablePath>d:\libs\FASTBuild\bin\FBuild.exe</FBuildExecutablePath>
        <!-- 开启分布式编译 -->
        <bEnableDistribution>true</bEnableDistribution>
        <!-- 指定 brokerage 路径 -->
        <FBuildBrokeragePath>\\127.0.0.1\Brokerage\</FBuildBrokeragePath>
        <!-- 指定 cache 路径 -->
        <FBuildCachePath>\\127.0.0.1\Cache\</FBuildCachePath>
        <!-- 开启 cache -->
        <bEnableCaching>true</bEnableCaching>
        <!-- cache 的读写权限 Read/Write/ReadWrite -->
        <CacheMode>ReadWrite</CacheMode>
        <!-- 指定 coordinator ip -->
        <FBuildCoordinator>127.0.0.1</FBuildCoordinator>
        <!-- 强制远程编译 -->
        <!-- <bForceRemote>true</bForceRemote> -->
    </FASTBuild>
</Configuration>

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

UE 通过插件源码添加插件

Fri, 01 Dec 2023 00:00:00 +0000

UE 通过插件源码添加插件

添加插件

简单记录一下如何在拥有插件源码的情况下添加插件.

以插件 UE.EditorPlus 为例

（这一步可以不执行）修改项目 .uproject 文件，Plugins 字段下增加：

    "Plugins": [
    {
        "Name": "EditorPlus",
        "Enabled": true,
        "TargetAllowList": [
            "Editor"
        ]
    }

右键 uproject 文件，执行 "Generate Visual Studio Project Files"，更新 sln 项目文件
打开 sln 文件，编译项目

设置多语言

修改项目的配置文件 DefaultEditor.ini，加上新路径：

[Internationalization]
+LocalizationPaths=%GAMEDIR%Plugins/UE.EditorPlus/Content/Localization/EditorPlusTools

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Home

Thu, 30 Nov 2023 20:09:36 +0000

Disenone's Wiki

无止境

Hi there~ 欢迎来到我的知识库。

为了避免遗忘、便于分享，我在这里收录知识。请随意浏览～

编程技术游戏开发

UE.AIChatPlus

C/C++ 宏编程解析

Thu, 30 Nov 2023 20:09:36 +0000

本文的目的是要讲清楚 C/C++ 的宏编程的规则和实现方法，让你不再惧怕看到代码里面的宏。我会首先说说 C++ 标准 14 里面提到的关于宏展开的规则，然后通过修改 Clang 的源码来观察宏展开，最后基于这些知识来聊聊宏编程的实现。

本文的代码全部都在这里：下载，在线演示。

引子

我们可以通过执行命令 gcc -P -E a.cpp -o a.cpp.i 来让编译器对文件 a.cpp 只执行预处理并保存结果到 a.cpp.i 中。

首先我们先来看一些例子:

递归重入（Reentrancy）

#define ITER(arg0, arg1) ITER(arg1, arg0)

ITER(1, 2)          // -> ITER(2, 1)

宏 ITER 交换了 arg0, arg1 的位置。宏展开之后，得到的是 ITER(2, 1)。

可以看到，arg0 arg1 的位置成功交换，在这里宏成功展开了一次，但也只展开了一次，不再递归重入。换言之，宏的展开过程中，是不可自身递归重入的，如果在递归的过程中发现相同的宏在之前的递归中已经展开过，则不再展开，这是宏展开的其中一条重要的规则。禁止递归重入的原因也很简单，就是为了避免无限递归。

字符串拼接

#define CONCAT(arg0, arg1) arg0 ## arg1

CONCAT(Hello, World)                // -> HelloWorld
CONCAT(Hello, CONCAT(World, !))     // ->　HelloCONCAT(World, !)

宏 CONCAT 目的是拼接 arg0 arg1。宏展开之后，CONCAT(Hello, World) 能够得到正确的结果 HelloWorld。但是 CONCAT(Hello, CONCAT(World, !)) 却只展开了外层的宏，内层的 CONCAT(World, !) 并没有展开而是直接跟 Hello 拼接在一起了，这跟我们预想的不一样，我们真正想要的结果是 HelloWorld!。这就是宏展开的另外一条重要的规则：跟在 ## 操作符后面的宏参数，不会执行展开，而是会直接跟前面的内容先拼接在一起。

通过上面两个例子可以看出来，宏展开的规则有一些是反直觉的，如果不清楚具体的规则，有可能写出来的宏跟我们想要的效果不一致。

宏展开规则

通过引子的两个例子，我们了解到了宏展开是有一套标准的规则的，这套规则定义在 C/C++ 标准里面，内容不多，建议先仔细读几遍，我这里顺带给下标准 n4296 版本的链接，宏展开在 16.3 节：传送门。下面我挑出 n4296 版本中几条重要的规则，这些规则会决定如何正确编写宏（还是建议抽时间把标准里面的宏展开细读下）。

参数分隔

宏的参数要求是用逗号分隔，而且参数的个数需要跟宏定义的个数一致，传递给宏的参数中，额外用括号包住的内容视为一个参数，参数允许为空：

#define ADD_COMMA(arg1, arg2) arg1, arg2

ADD_COMMA(a, b)             // -> a, b
ADD_COMMA(a)                // 报错 "macro "MACRO" requires 2 arguments, but only 1 given"
ADD_COMMA((a, b), c)        // -> (a, b), c
ADD_COMMA(, b)              // -> , b

ADD_COMMA((a, b), c) 中 (a, b) 视为第一个参数。ADD_COMMA(, b) 中，第一个参数为空，于是展开为 , b。

宏参数展开

在对宏进行展开的时候，如果宏的参数也是可以展开的宏，会先把参数完全展开，再展开宏，例如

ADD_COMMA(ADD_COMMA(1, 2), ADD_COMMA(3, 4))     // -> 1, 2, 3, 4

一般情况下的宏展开，都可以认为是先对参数求值，再对宏求值，除非遇到了 # 和 ## 操作符。

`#` 操作符

# 操作符后面跟的宏参数，不会进行展开，会直接字符串化，例如：

#define STRINGIZE(arg0) # arg0

STRINGIZE(a)                // -> "a"
STRINGIZE(STRINGIZE(a))     // -> "STRINGIZE(a)"

根据这条规则 STRINGIZE(STRINGIZE(a)) 只能展开为 "STRINGIZE(a)"。

`##` 操作符

## 操作符前后的宏参数，都不会进行展开，会先直接拼接起来，例如：

#define CONCAT(arg0, arg1) arg0 ## arg1

CONCAT(Hello, World)                        // -> HelloWorld
CONCAT(Hello, CONCAT(World, !))             // -> HelloCONCAT(World, !)
CONCAT(CONCAT(Hello, World) C, ONCAT(!))    // -> CONCAT(Hello, World) CONCAT(!)

CONCAT(CONCAT(Hello, World) C, ONCAT(!)) 只能是先拼接在一起，得到 CONCAT(Hello, World) CONCAT(!)。

重复扫描

预处理器执行完一次宏展开之后，会重新扫描得到的内容，继续展开，直到没有可以展开的内容为止。

一次宏展开，可以理解为先把参数完全展开（除非遇到 # 和 ##），再根据宏的定义，把宏和完全展开后的参数按照定义进行替换，再处理定义中的所有 # 和 ## 操作符。

#define CONCAT(arg0, arg1) arg0 ## arg1
#define STRINGIZE(arg0) # arg0

CONCAT(STRING, IZE(Hello))        // -> STRINGIZE(Hello) -> "Hello"

CONCAT(STRING, IZE(Hello)) 第一次扫描展开得到 STRINGIZE(Hello)，然后执行第二次扫描，发现 STRINGIZE 可以继续展开，最后得到 "Hello"。

禁止递归重入

在重复扫描的过程中，禁止递归展开相同的宏。可以把宏展开理解为树形的结构，根节点就是一开始要展开的宏，每个宏展开之后的内容作为该宏的子节点连接到树上，那么禁止递归就是在展开子节点的宏时，如果该宏跟任意祖先节点的宏相同，则禁止展开。来看一些例子：

#define CONCAT(arg0, arg1) arg0 ## arg1
#define CONCAT_SPACE(arg0, arg1) arg0 arg1
#define IDENTITY(arg0) IDENTITY_IMPL(arg0)
#define IDENTITY_IMPL(arg0) arg0

CONCAT(CON, CAT(a, b))                  // -> CONCAT(a, b)
IDENTITY_IMPL(CONCAT(CON, CAT(a, b)))   // -> CONCAT(a, b)
IDENTITY(CONCAT(CON, CAT(a, b)))        // -> IDENTITY_IMPL(CONCAT(a, b)) -> CONCAT(a, b)

CONCAT(CON, CAT(a, b))：由于 CONCAT 是用 ## 拼接两个参数，根据 ## 的规则，不会展开参数，直接拼接。所以第一次展开得到了 CONCAT(a, b)，由于 CONCAT 已经展开过了不会再递归展开，所以停止。

IDENTITY_IMPL(CONCAT(CON, CAT(a, b)))：IDENTITY_IMPL 可以理解为对参数 arg0 求值，这里的参数 arg0 求值得到了 CONCAT(a, b)，并由于递归被标记为了禁止重入，之后 IDENTITY_IMPL 展开完成，进行第二次扫描的时候，发现是禁止重入的 CONCAT(a, b)，于是停止展开。在这里 CONCAT(a, b) 是由参数 arg0 展开而得到的，但在后续展开的时候，也会保持禁止重入的标记，可以理解为父节点是参数 arg0，一直保持着禁止重入的标记。

IDENTITY(CONCAT(CON, CAT(a, b)))：这个例子主要是为了加强对父子节点的理解，参数自己展开的时候，是自身作为父节点，展开的内容作为子节点去判断递归，展开后的参数传到宏定义之后，禁止重入的标记会继续保留（如果传到宏定义之后没有改变参数展开后的宏）。可以把参数的展开过程看成是另外一棵树，参数的展开结果就是树的最底层子节点，这个子节点传给宏来执行展开的同时，依然是保留着禁止重入的特性。

例如这里，在第一次完全展开之后得到 IDENTITY_IMPL(CONCAT(a, b))，CONCAT(a, b) 被标记为禁止重入，即使 IDENTITY_IMPL 是对参数求值的，但参数已经禁止展开，所以参数就原封不动的传到定义里，最后我们还是得到 CONCAT(a, b)。

以上我只是列出了一些我认为比较重要的，或者觉得不太好理解的规则，详细的宏展开规则，还是建议花点时间直接去看标准文档。

通过 Clang 观察展开过程

我们可以给 Clang 源码加上一些打印信息来观察宏展开的过程，我无意深入解释 Clang 的源码，在这里给一份修改过的文件 diff，有兴趣的可以自己编译 Clang 来研究。这里我是用的 llvm 版本 11.1.0 （传送门），修改过的文件（传送门）。下面简单通过例子来验证我们之前介绍的宏展开规则：

例子1

#define CONCAT(arg0, arg1) arg0 ## arg1

CONCAT(C, ONCAT(a, b))      // CONCAT(a, b)

使用修改过的 Clang 来预处理以上代码： clang -P -E a.cpp -o a.cpp.i，得到下面的打印信息：

HandleIdentifier:
MacroInfo 0x559e57496900
    #define <macro>[2813:CONCAT](arg0, arg1) arg0 ## arg1
Macro is ok to expand

EnterMacro: 0

Enter ExpandFunctionArguments:
MacroInfo 0x559e57496900 used
    #define <macro>[2813:CONCAT](arg0, arg1) arg0 ## arg1
Token: 0
identifier: arg0
Args: [identifier: C]
Token: 1
hashhash:
Token: 2
identifier: arg1
Args: [identifier: ONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ]
Leave ExpandFunctionArguments: [identifier: C][hashhash: ][identifier: ONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ]

LeaveMacro: 0

HandleIdentifier:
MacroInfo 0x559e57496900 disabled used
    #define <macro>[2813:CONCAT](arg0, arg1) arg0 ## arg1
Macro is not ok to expand

第 1 行 HandleIdentifier 遇到宏的时候会打印，接着打印宏的信息（第 2-4 行），宏没有禁用，所以可以按照定义来展开 Macro is ok to expand，之后进入宏 EnterMacro。

真正执行宏展开的函数是 ExpandFunctionArguments，之后再次打印待展开的宏信息，注意到此时宏已经被标记为 used （第 9 行）。之后根据宏的定义，进行逐个 Token 的展开（Token 是 Clang 预处理里面的概念，这里不深入说明）。

第 0 个 Token 是形参 arg0, 对应的实参是 C，判断不需要展开，于是直接复制到结果上（第 11-13 行）。

第 1 个 Token 是 hashhash，也就是 ## 操作符，继续复制到结果上（第 14-15 行）。

第 2 个 Token 是形参 arg1，对应的实参是 ONCAT(a, b)，预处理器也会把实参处理成一个个的 Token，所以可以看到打印的结果用中括号包住了实参的每个 Token（第 18 行），由于 ## 的原因这个实参依然不需要展开，所以还是直接复制到结果上（第 16-18 行）。

最后 Leave ExpandFunctionArguments 打印本次扫描展开得到的结果（第 19 行），把结果的 Token 都翻译过来就是 C ## ONCAT(a, b)，之后预处理器就执行 ## 操作符来生成新的内容。

## 执行之后得到 CONCAT(a, b)，遇到宏 CONCAT，预处理还是先进入 HandleIdentifier，打印宏的信息，发现该宏状态是 disable used，是已经展开过的，禁止再重入了，显示 Macro is not ok to expand，预处理器不再展开，最终得到的结果就是 CONCAT(a, b)。

例子2

#define CONCAT(arg0, arg1) arg0 ## arg1
#define IDENTITY(arg0) arg0

IDENTITY(CONCAT(C, ONCAT(a, b)))

Clang 打印信息（点击展开）：

HandleIdentifier:
MacroInfo 0x562a148f5a60
    #define <macro>[2853:IDENTITY](arg0) arg0
Macro is ok to expand

HandleIdentifier:
MacroInfo 0x562a148f5930
    #define <macro>[2813:CONCAT](arg0, arg1) arg0 ## arg1

EnterMacro: 0

Enter ExpandFunctionArguments:
MacroInfo 0x562a148f5a60 used
    #define <macro>[2853:IDENTITY](arg0) arg0
Token: 0
identifier: arg0
Args: [identifier: CONCAT][l_paren: ][identifier: C][comma: ][identifier: ONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ][r_paren: ]
getPreExpArgument: [identifier: CONCAT][l_paren: ][identifier: C][comma: ][identifier: ONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ][r_paren: ][eof: ]

HandleIdentifier:
MacroInfo 0x562a148f5930
    #define <macro>[2813:CONCAT](arg0, arg1) arg0 ## arg1
Macro is ok to expand

EnterMacro: 1

Enter ExpandFunctionArguments:
MacroInfo 0x562a148f5930 used
    #define <macro>[2813:CONCAT](arg0, arg1) arg0 ## arg1
Token: 0
identifier: arg0
Args: [identifier: C]
Token: 1
hashhash:
Token: 2
identifier: arg1
Args: [identifier: ONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ]
Leave ExpandFunctionArguments: [identifier: C][hashhash: ][identifier: ONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ]

LeaveMacro: 1

HandleIdentifier:
MacroInfo 0x562a148f5930 disabled used
    #define <macro>[2813:CONCAT](arg0, arg1) arg0 ## arg1
Macro is not ok to expand
ResultArgToks: [identifier: CONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ]
Leave ExpandFunctionArguments: [identifier: CONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ]

LeaveMacro: 0

HandleIdentifier:
MacroInfo 0x562a148f5930 used
    #define <macro>[2813:CONCAT](arg0, arg1) arg0 ## arg1
Macro is not ok to expand

第 12 行开始展开 IDENTITY，发现参数 Token 0 是 CONCAT(...)，也是一个宏，于是先对该参数进行求值。

第 27 行开始展开参数宏 CONCAT(...)，跟例子 1 一样，多次扫描展开完成后得到 CONCAT(a, b) （第 46 行）。

第 47 结束对 IDENTITY 的展开，得到的结果是 CONCAT(a, b)。

第 51 行重新扫描 CONCAT(a, b)，发现虽然是宏，但在之前的参数展开过程中已经被设置成了 used，不再递归展开，直接作为最终结果。

例子 3

#define CONCAT(arg0, arg1) arg0 ## arg1
#define IDENTITY_IMPL(arg0) arg0
#define IDENTITY(arg0) IDENTITY_IMPL(arg0)

IDENTITY(CONCAT(C, ONCAT(a, b)))

Clang 打印信息（点击展开）：

HandleIdentifier:
MacroInfo 0x55e824457a80
    #define <macro>[2853:IDENTITY_IMPL](arg0) arg0

HandleIdentifier:
MacroInfo 0x55e824457ba0
    #define <macro>[2886:IDENTITY](arg0) IDENTITY_IMPL(arg0)
Macro is ok to expand

HandleIdentifier:
MacroInfo 0x55e824457950
    #define <macro>[2813:CONCAT](arg0, arg1) arg0 ## arg1

EnterMacro: 0

Enter ExpandFunctionArguments:
MacroInfo 0x55e824457ba0 used
    #define <macro>[2886:IDENTITY](arg0) IDENTITY_IMPL(arg0)
Token: 0
identifier: IDENTITY_IMPL
Token: 1
l_paren:
Token: 2
identifier: arg0
Args: [identifier: CONCAT][l_paren: ][identifier: C][comma: ][identifier: ONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ][r_paren: ]
getPreExpArgument: [identifier: CONCAT][l_paren: ][identifier: C][comma: ][identifier: ONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ][r_paren: ][eof: ]

HandleIdentifier:
MacroInfo 0x55e824457950
    #define <macro>[2813:CONCAT](arg0, arg1) arg0 ## arg1
Macro is ok to expand

EnterMacro: 1

Enter ExpandFunctionArguments:
MacroInfo 0x55e824457950 used
    #define <macro>[2813:CONCAT](arg0, arg1) arg0 ## arg1
Token: 0
identifier: arg0
Args: [identifier: C]
Token: 1
hashhash:
Token: 2
identifier: arg1
Args: [identifier: ONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ]
Leave ExpandFunctionArguments: [identifier: C][hashhash: ][identifier: ONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ]

LeaveMacro: 1

HandleIdentifier:
MacroInfo 0x55e824457950 disabled used
    #define <macro>[2813:CONCAT](arg0, arg1) arg0 ## arg1
Macro is not ok to expand
ResultArgToks: [identifier: CONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ]
Token: 3
r_paren:
Leave ExpandFunctionArguments: [identifier: IDENTITY_IMPL][l_paren: ][identifier: CONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ][r_paren: ]

LeaveMacro: 0

HandleIdentifier:
MacroInfo 0x55e824457a80
    #define <macro>[2853:IDENTITY_IMPL](arg0) arg0
Macro is ok to expand

HandleIdentifier:
MacroInfo 0x55e824457950 used
    #define <macro>[2813:CONCAT](arg0, arg1) arg0 ## arg1

EnterMacro: 2

Enter ExpandFunctionArguments:
MacroInfo 0x55e824457a80 used
    #define <macro>[2853:IDENTITY_IMPL](arg0) arg0
Token: 0
identifier: arg0
Args: [identifier: CONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ]
getPreExpArgument: [identifier: CONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ][eof: ]

HandleIdentifier:
MacroInfo 0x55e824457950 used
    #define <macro>[2813:CONCAT](arg0, arg1) arg0 ## arg1
Macro is not ok to expand
ResultArgToks: [identifier: CONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ]
Leave ExpandFunctionArguments: [identifier: CONCAT][l_paren: ][identifier: a][comma: ][identifier: b][r_paren: ]

LeaveMacro: 2

HandleIdentifier:
MacroInfo 0x55e824457950 used
    #define <macro>[2813:CONCAT](arg0, arg1) arg0 ## arg1
Macro is not ok to expand

第 16 行开始展开 IDENTITY，同理预处理器看到 Token 2 （也即是 arg0）是宏，于是先展开 CONCAT(C, ONCAT(a, b))。

展开 arg0 后得到 CONCAT(a, b) （第 23-54 行）

IDENTITY 最终展开为 IDENTITY_IMPL(CONCAT(a, b))（第 57 行）

重新扫描，继续展开 IDENTITY_IMPL（第 61-72 行），发现此时的 Token 0 是宏 CONCAT(a, b)，但处于 used 状态，中止展开并返回（第 75-84行），最终得到的结果还是 CONCAT(a, b)（第 85 行）。

重新扫描结果，发现宏 CONCAT(a, b) 的状态是 used，停止展开并得到最终的结果。

通过以上三个简单的例子，我们可以大致的理解预处理器展开宏的过程，这里不再对预处理器进行更深入的探讨，有兴趣可以对照我提供的修改文件来研究。

宏编程实现

下面我们开始进入到了主题（前面那一大段目的是为了更好的理解宏展开规则），宏编程实现。

基本符号

首先可以先定义宏的特殊符号，做求值和拼接的时候会用到

#define PP_LPAREN() (
#define PP_RPAREN() )
#define PP_COMMA() ,
#define PP_EMPTY()
#define PP_HASHHASH # ## #      // 表示 ## 字符串，但只是作为字符串，不会当作 ## 操作符来处理

求值

利用参数优先展开的规则，可以写出一个求值宏：

#define PP_IDENTITY(arg0) arg0

PP_COMMA PP_LPAREN() PP_RPAREN()                // -> PP_COMMA ( )
PP_IDENTITY(PP_COMMA PP_LPAREN() PP_RPAREN())   // -> PP_COMMA() -> ,

如果只是写 PP_COMMA PP_LPAREN() PP_RPAREN()，预处理器只会分别处理每个宏，对展开的结果不会再合并处理。加上 PP_IDENTITY 之后，预处理器可以对展开得到的 PP_COMMA() 再进行求值，得到 ,。

拼接

由于 ## 拼接的时候，是不会展开左右两边的参数，为了让参数可以先求值再拼接，可以这样写：

#define PP_CONCAT(arg0, arg1) PP_CONCAT_IMPL(arg0, arg1)
#define PP_CONCAT_IMPL(arg0, arg1) arg0 ## arg1

PP_CONCAT(PP_IDENTITY(1), PP_IDENTITY(2))         // -> 12
PP_CONCAT_IMPL(PP_IDENTITY(1), PP_IDENTITY(2))    // -> PP_IDENTITY(1)PP_IDENTITY(2) -> 报错

这里 PP_CONCAT 用到的方法叫做延迟拼接，在展开为 PP_CONCAT_IMPL 的时候，arg0 和 arg1 都会先展开求值，之后再由 PP_CONCAT_IMPL 执行真正的拼接操作。

逻辑运算

借助 PP_CONCAT 可以实现逻辑运算。首先定义 BOOL 值：

#define PP_BOOL(arg0) PP_CONCAT(PP_BOOL_, arg0)
#define PP_BOOL_0 0
#define PP_BOOL_1 1
#define PP_BOOL_2 1
#define PP_BOOL_3 1
// ...
#define PP_BOOL_256 1

PP_BOOL(3)              // -> PP_BOOL_3 -> 1

用PP_CONCAT 先把 PP_BOOL_ 和 arg0 拼接在一起，再对拼接结果进行求值。这里的 arg0 要求是求值之后得到 [0, 256] 范围的数字，拼接在 PP_BOOL_ 后面求值，就能得到布尔值。与或非运算：

#define PP_NOT(arg0) PP_CONCAT(PP_NOT_, PP_BOOL(arg0))
#define PP_NOT_0 1
#define PP_NOT_1 0

#define PP_AND(arg0, arg1) PP_CONCAT(PP_AND_, PP_CONCAT(PP_BOOL(arg0), PP_BOOL(arg1)))
#define PP_AND_00 0
#define PP_AND_01 0
#define PP_AND_10 0
#define PP_AND_11 1

#define PP_OR(arg0, arg1) PP_CONCAT(PP_OR_, PP_CONCAT(PP_BOOL(arg0), PP_BOOL(arg1)))
#define PP_OR_00 0
#define PP_OR_01 1
#define PP_OR_10 1
#define PP_OR_11 1

PP_NOT(PP_BOOL(2))      // -> PP_CONCAT(PP_NOT_, 1) -> PP_NOT_1 -> 0
PP_AND(2, 3)            // -> PP_CONCAT(PP_AND_, 11) -> PP_AND_11 -> 1
PP_AND(2, 0)            // -> PP_CONCAT(PP_AND_, 10) -> PP_AND_10 -> 0
PP_OR(2, 0)             // -> PP_CONCAT(PP_OR_, 10) -> PP_OR_10, -> 1

先用 PP_BOOL 对参数求值，之后再根据 0 1 的组合来拼接逻辑运算的结果。如果不用 PP_BOOL 来求值，那么参数就只能支持 0 1 两种数值，适用性大大降低。同理也可以写出异或，或非等操作，有兴趣可以自己尝试。

条件选择

利用 PP_BOOL 和 PP_CONCAT，还可以写出条件选择语句：

#define PP_IF(if, then, else) PP_CONCAT(PP_IF_, PP_BOOL(if))(then, else)
#define PP_IF_1(then, else) then
#define PP_IF_0(then, else) else

PP_IF(1, 2, 3)      // -> PP_IF_1(2, 3) -> 2
PP_IF(0, 2, 3)      // -> PP_IF_0(2, 3) -> 3

if 求值如果是 1，用 PP_CONCAT 拼接成 PP_IF_1，最后展开为 then 的值；同理若 if 求值为 0，得到 PP_IF_0。

递增递减

整数递增递减：

#define PP_INC(arg0) PP_CONCAT(PP_INC_, arg0)
#define PP_INC_0 1
#define PP_INC_1 2
#define PP_INC_2 3
#define PP_INC_3 4
// ...
#define PP_INC_255 256
#define PP_INC_256 256

#define PP_DEC(arg0) PP_CONCAT(PP_DEC_, arg0)
#define PP_DEC_0 0
#define PP_DEC_1 0
#define PP_DEC_2 1
#define PP_DEC_3 2
// ...
#define PP_DEC_255 254
#define PP_DEC_256 255

PP_INC(2)                   // -> PP_INC_2 -> 3
PP_DEC(3)                   // -> PP_DEC_3 -> 2

跟 PP_BOOL 类似，整数的递增递减也是有范围限制的，这里范围设置为 [0, 256]，递增到 256 之后，安全起见，PP_INC_256 会返回自身 256 作为边界，同理 PP_DEC_0 也是返回 0。

变长参数

宏可以接受变长参数，格式是：

#define LOG(format, ...) printf("log: " format, __VA_ARGS__)

LOG("Hello %s\n", "World")      // -> printf("log: " "Hello %s\n", "World");
LOG("Hello World")              // -> printf("log: " "Hello World", ); 多了个逗号，编译报错

由于变长参数有可能为空，空的情况下会导致编译失败，因此 C++ 20 引入了 __VA_OPT__，如果变长参数是空，则返回空，否则返回原参数：

#define LOG2(format, ...) printf("log: " format __VA_OPT__(,) __VA_ARGS__)

LOG2("Hello %s\n", "World")      // -> printf("log: " "Hello %s\n", "World");
LOG2("Hello World")              // -> printf("log: " "Hello World" ); 没有逗号，正常编译

但可惜只有 C++ 20 以上标准才有这个宏，下文中我们将会给出 __VA_OPT__ 的实现方法。

惰性求值

考虑这种情况：

PP_IF(1, PP_COMMA(), PP_LPAREN())     // -> PP_IF_1(,,)) -> 报错 unterminated argument list invoking macro "PP_IF_1"

我们知道，宏展开的时候会对先参数进行求值。PP_COMMA() 和 PP_LPAREN() 求值之后再传给 PP_IF_1，得到 PP_IF_1(,,))，导致预处理出错。此时，可以采用一种叫做惰性求值方法：

PP_IF(1, PP_COMMA, PP_LPAREN)()       // -> PP_IF_1(PP_COMMA, PP_LPAREN)() -> PP_COMMA() -> ,

改成这种写法，只传宏的名字，让 PP_IF 选出需要的宏名字之后，再跟括号 () 拼接在一起组成完成的宏，最后再展开。惰性求值在宏编程里面也是很常见的。

以括号开始

判断变长参数是否以括号开始：

#define PP_IS_BEGIN_PARENS(...) \
    PP_IS_BEGIN_PARENS_PROCESS( \
        PP_IS_BEGIN_PARENS_CONCAT( \
            PP_IS_BEGIN_PARENS_PRE_, PP_IS_BEGIN_PARENS_EAT __VA_ARGS__ \
        ) \
    )

#define PP_IS_BEGIN_PARENS_PROCESS(...) PP_IS_BEGIN_PARENS_PROCESS_0(__VA_ARGS__)
#define PP_IS_BEGIN_PARENS_PROCESS_0(arg0, ...) arg0

#define PP_IS_BEGIN_PARENS_CONCAT(arg0, ...) PP_IS_BEGIN_PARENS_CONCAT_IMPL(arg0, __VA_ARGS__)
#define PP_IS_BEGIN_PARENS_CONCAT_IMPL(arg0, ...) arg0 ## __VA_ARGS__

#define PP_IS_BEGIN_PARENS_PRE_1 1,
#define PP_IS_BEGIN_PARENS_PRE_PP_IS_BEGIN_PARENS_EAT 0,
#define PP_IS_BEGIN_PARENS_EAT(...) 1

PP_IS_BEGIN_PARENS(())              // -> 1
PP_IS_BEGIN_PARENS((()))            // -> 1
PP_IS_BEGIN_PARENS(a, b, c)         // -> 0
PP_IS_BEGIN_PARENS(a, ())           // -> 0
PP_IS_BEGIN_PARENS(a())             // -> 0
PP_IS_BEGIN_PARENS(()aa(bb()cc))    // -> 1
PP_IS_BEGIN_PARENS(aa(bb()cc))      // -> 0

PP_IS_BEGIN_PARENS 可以用来判断传入的参数是否以括号开始，在需要处理括号参数的时候会需要用到（譬如后面说到的 __VA_OPT__ 实现）。看上去有点复杂，核心思想就是构建出一个宏，若变长参数以括号开始，则可以跟括号连在一起求值得到一种结果，否则就另外求值得到另一种结果。我们来慢慢看：

PP_IS_BEGIN_PARENS_PROCESS 和 PP_IS_BEGIN_PARENS_PROCESS_0 组成的宏功能是先对传入的不定参数求值，然后取第 0 个参数。

PP_IS_BEGIN_PARENS_CONCAT(PP_IS_BEGIN_PARENS_PRE_, PP_IS_BEGIN_PARENS_EAT __VA_ARGS__) 是先对 PP_IS_BEGIN_PARENS_EAT __VA_ARGS__ 求值，在把求值结果跟 PP_IS_BEGIN_PARENS_PRE_ 拼接在一起。

PP_IS_BEGIN_PARENS_EAT(...) 宏会吞掉所有参数，返回1，如果上一步 PP_IS_BEGIN_PARENS_EAT __VA_ARGS__ 中，__VA_ARGS__ 是以括号开始的，那么就会匹配到对 PP_IS_BEGIN_PARENS_EAT(...) 的求值，然后返回 1；相反，如果不是以括号开始，则没有匹配上，PP_IS_BEGIN_PARENS_EAT __VA_ARGS__ 会保留不变。

若 PP_IS_BEGIN_PARENS_EAT __VA_ARGS__ 求值得到 1，PP_IS_BEGIN_PARENS_CONCAT(PP_IS_BEGIN_PARENS_PRE_, 1) -> PP_IS_BEGIN_PARENS_PRE_1 -> 1,，注意 1 后面是有个逗号的，把 1, 传给 PP_IS_BEGIN_PARENS_PROCESS_0，取第 0 个参数，最后得到 1，表示参数是以括号开始。

若 PP_IS_BEGIN_PARENS_EAT __VA_ARGS__ 求值得到不是 1，而是保持不变，则 PP_IS_BEGIN_PARENS_CONCAT(PP_IS_BEGIN_PARENS_PRE_, PP_IS_BEGIN_PARENS_EAT __VA_ARGS__) -> PP_IS_BEGIN_PARENS_PRE_PP_IS_BEGIN_PARENS_EAT __VA_ARGS__ -> 0, __VA_ARGS__，传给 PP_IS_BEGIN_PARENS_PROCESS_0 得到的是 0，表示参数不是以括号开始。

变长参数空

判断变长参数是否为空也是一个常用的宏，在实现 __VA_OPT__ 的时候需要用到，我们在这里利用 PP_IS_BEGIN_PARENS，可以先写出不完整的版本：

#define PP_IS_EMPTY_PROCESS(...) \
    PP_IS_BEGIN_PARENS(PP_IS_EMPTY_PROCESS_EAT __VA_ARGS__ ())
#define PP_IS_EMPTY_PROCESS_EAT(...) ()

PP_IS_EMPTY_PROCESS()       // -> 1
PP_IS_EMPTY_PROCESS(1)      // -> 0
PP_IS_EMPTY_PROCESS(1, 2)   // -> 0
PP_IS_EMPTY_PROCESS(())     // -> 1

PP_IS_EMPTY_PROCESS 的作用是判断 PP_IS_EMPTY_PROCESS_EAT __VA_ARGS__ () 是否以括号开始。

如果 __VA_ARGS__ 是空，PP_IS_EMPTY_PROCESS_EAT __VA_ARGS__ () -> PP_IS_EMPTY_PROCESS_EAT() -> ()，得到的是一对括号 ()，再传给 PP_IS_BEGIN_PARENS 返回 1，表示参数是空。

否则，PP_IS_EMPTY_PROCESS_EAT __VA_ARGS__ () 保持不变地传给 PP_IS_BEGIN_PARENS，返回 0，表示非空。

留意第 4 个例子 PP_IS_EMPTY_PROCESS(()) -> 1，PP_IS_EMPTY_PROCESS 不能正确处理以括号开始的变长参数，因为这时变长参数带来的括号会匹配 PP_IS_EMPTY_PROCESS_EAT 导致求值得到 ()。为了解决这个问题，我们需要区别对待参数是否以括号开始的情况：

#define PP_IS_EMPTY(...) \
    PP_IS_EMPTY_IF(PP_IS_BEGIN_PARENS(__VA_ARGS__)) \
        (PP_IS_EMPTY_ZERO, PP_IS_EMPTY_PROCESS)(__VA_ARGS__)

#define PP_IS_EMPTY_IF(if) PP_CONCAT(PP_IS_EMPTY_IF_, if)
#define PP_IS_EMPTY_IF_1(then, else) then
#define PP_IS_EMPTY_IF_0(then, else) else

#define PP_IS_EMPTY_ZERO(...) 0

PP_IS_EMPTY()       // -> 1
PP_IS_EMPTY(1)      // -> 0
PP_IS_EMPTY(1, 2)   // -> 0
PP_IS_EMPTY(())     // -> 0

PP_IS_EMPTY_IF 根据 if 条件来返回第 0 或者第 1 个参数。

如果传入的变长参数以括号开始，PP_IS_EMPTY_IF 返回 PP_IS_EMPTY_ZERO，最后返回 0，表示变长参数非空。

反之 PP_IS_EMPTY_IF 返回 PP_IS_EMPTY_PROCESS，最后由 PP_IS_EMPTY_PROCESS 来判断变长参数是否非空。

下标访问

获取变长参数指定位置的元素：

#define PP_ARGS_ELEM(I, ...) PP_CONCAT(PP_ARGS_ELEM_, I)(__VA_ARGS__)
#define PP_ARGS_ELEM_0(a0, ...) a0
#define PP_ARGS_ELEM_1(a0, a1, ...) a1
#define PP_ARGS_ELEM_2(a0, a1, a2, ...) a2
#define PP_ARGS_ELEM_3(a0, a1, a2, a3, ...) a3
// ...
#define PP_ARGS_ELEM_7(a0, a1, a2, a3, a4, a5, a6, a7, ...) a7
#define PP_ARGS_ELEM_8(a0, a1, a2, a3, a4, a5, a6, a7, a8, ...) a8

PP_ARGS_ELEM(0, "Hello", "World")   // -> PP_ARGS_ELEM_0("Hello", "World") -> "Hello"
PP_ARGS_ELEM(1, "Hello", "World")   // -> PP_ARGS_ELEM_1("Hello", "World") -> "World"

PP_ARGS_ELEM 的第一个参数是元素下标 I，后面是变长参数。利用 PP_CONCAT 拼接 PP_ARGS_ELEM_ 和 I，即可以得到返回相应位置元素的宏 PP_ARGS_ELEM_0..8，再把变长参数传给该宏，展开返回下标对应位置的元素。

PP_IS_EMPTY2

利用 PP_ARGS_ELEM 也可以实现另一版本的 PP_IS_EMPTY：

#define PP_IS_EMPTY2(...) \
    PP_AND( \
        PP_AND( \
            PP_NOT(PP_HAS_COMMA(__VA_ARGS__)), \
            PP_NOT(PP_HAS_COMMA(__VA_ARGS__())) \
        ), \
        PP_AND( \
            PP_NOT(PP_HAS_COMMA(PP_COMMA_ARGS __VA_ARGS__)), \
            PP_HAS_COMMA(PP_COMMA_ARGS __VA_ARGS__ ()) \
        ) \
    )

#define PP_HAS_COMMA(...) PP_ARGS_ELEM(8, __VA_ARGS__, 1, 1, 1, 1, 1, 1, 1, 0)
#define PP_COMMA_ARGS(...) ,

PP_IS_EMPTY2()              // -> 1
PP_IS_EMPTY2(a)             // -> 0
PP_IS_EMPTY2(a, b)          // -> 0
PP_IS_EMPTY2(())            // -> 0
PP_IS_EMPTY2(PP_COMMA)      // -> 0

借用 PP_ARGS_ELEM 实现判断参数是否含有逗号 PP_HAS_COMMA。PP_COMMA_ARGS 会吞掉传入的任意参数，返回一个逗号。

判断变长参数是否为空的基础逻辑是 PP_COMMA_ARGS __VA_ARGS__ () 返回一个逗号，也就是 __VA_ARGS__ 为空，PP_COMMA_ARGS 和 () 拼接在一起求值，具体的写法就是 PP_HAS_COMMA(PP_COMMA_ARGS __VA_ARGS__ ())。

但是会有例外的情况：

__VA_ARGS__ 本身有可能会带来逗号；
__VA_ARGS__ () 拼接在一起发生求值带来逗号；
PP_COMMA_ARGS __VA_ARGS__ 拼接在一起发生求值带来逗号；

针对上面说到的三种例外情况，需要做排除，所以最后的写法等价于对以下 4 个条件执行与逻辑：

PP_NOT(PP_HAS_COMMA(__VA_ARGS__)) &&
PP_NOT(PP_HAS_COMMA(__VA_ARGS__())) &&
PP_NOT(PP_HAS_COMMA(PP_COMMA_ARGS __VA_ARGS__)) &&
PP_HAS_COMMA(PP_COMMA_ARGS __VA_ARGS__ ())

`__VA_OPT__`

利用 PP_IS_EMPTY 终于可以来实现类似 __VA_OPT__ 的宏：

#define PP_REMOVE_PARENS(tuple) PP_REMOVE_PARENS_IMPL tuple
#define PP_REMOVE_PARENS_IMPL(...) __VA_ARGS__

#define PP_ARGS_OPT(data_tuple, empty_tuple, ...) \
    PP_ARGS_OPT_IMPL(PP_IF(PP_IS_EMPTY(__VA_ARGS__), empty_tuple, data_tuple))
#define PP_ARGS_OPT_IMPL(tuple) PP_REMOVE_PARENS(tuple)

PP_ARGS_OPT((data), (empty))        // -> empty
PP_ARGS_OPT((data), (empty), 1)     // -> data
PP_ARGS_OPT((,), (), 1)             // -> ,

PP_ARGS_OPT 接受两个固定参数和变长参数，变长参数非空时返回 data，否则返回 empty。为了让 data 和 empty 支持逗号，要求两者都要用括号包住实际的参数，最后用 PP_REMOVE_PARENS 来移除外层的括号。

有了 PP_ARGS_OPT 可以实现 LOG3 来模拟 LOG2 实现的功能：

#define LOG3(format, ...) \
    printf("log: " format PP_ARGS_OPT((,), (), __VA_ARGS__) __VA_ARGS__)

LOG3("Hello");                  // -> printf("log: " "Hello" );
LOG3("Hello %s", "World");      // -> printf("log: " "Hello %s" , "World");

data_tuple 是 (,)，如果变长参数非空，则会返回 data_tuple 里面的所有元素，在这里就是逗号 ,。

求参数个数

获取变长参数的个数：

#define PP_ARGS_SIZE_IMCOMPLETE(...) \
    PP_ARGS_ELEM(8, __VA_ARGS__, 8, 7, 6, 5, 4, 3, 2, 1, 0)

PP_ARGS_SIZE_IMCOMPLETE(a)             // -> 1
PP_ARGS_SIZE_IMCOMPLETE(a, b)          // -> 2
PP_ARGS_SIZE_IMCOMPLETE(PP_COMMA())    // -> 2
PP_ARGS_SIZE_IMCOMPLETE()              // -> 1

计算变长参数的个数，是通过数参数的位置来获得的。__VA_ARGS__ 会导致后续的参数全体往右移动，用宏 PP_ARGS_ELEM 来获取第 8 个位置的参数，如果 __VA_ARGS__ 只有一个参数，则第 8 个参数等于 1；同理如果 __VA_ARGS__ 有两个参数，则第 8 个参数就变为 2，刚好等于变长参数的个数。

这里给的例子只最高支持个数 8 的变长参数，这是依赖于 PP_ARGS_ELEM 所能支持的最大长度。

但是这个宏还不完整，在变长参数为空的情况下，这个宏会错误返回 1。如果需要处理空的变长参数，则需要用到我们前面说到的 PP_ARGS_OPT 宏：

#define PP_COMMA_IF_ARGS(...) PP_ARGS_OPT((,), (), __VA_ARGS__)
#define PP_ARGS_SIZE(...) PP_ARGS_ELEM(8, __VA_ARGS__ PP_COMMA_IF_ARGS(__VA_ARGS__) 8, 7, 6, 5, 4, 3, 2, 1, 0, 0, 0)

PP_ARGS_SIZE(a)             // -> 1
PP_ARGS_SIZE(a, b)          // -> 2
PP_ARGS_SIZE(PP_COMMA())    // -> 2
PP_ARGS_SIZE()              // -> 0
PP_ARGS_SIZE(,,,)           // -> 4

问题的关键就是逗号 ,，在 __VA_ARGS__ 为空的时候，把逗号隐去就能正确返回 0。

遍历访问

类似 C++ 的 for_each，我们可以实现宏的 PP_FOR_EACH：

#define PP_FOR_EACH(macro, contex, ...) \
    PP_CONCAT(PP_FOR_EACH_, PP_ARGS_SIZE(__VA_ARGS__))(0, macro, contex, __VA_ARGS__)

#define PP_FOR_EACH_0(index, macro, contex, ...)
#define PP_FOR_EACH_1(index, macro, contex, arg, ...) macro(index, contex, arg)

#define PP_FOR_EACH_2(index, macro, contex, arg, ...) \
    macro(index, contex, arg) \
    PP_FOR_EACH_1(PP_INC(index), macro, contex, __VA_ARGS__)

#define PP_FOR_EACH_3(index, macro, contex, arg, ...) \
    macro(index, contex, arg) \
    PP_FOR_EACH_2(PP_INC(index), macro, contex, __VA_ARGS__)
// ...
#define PP_FOR_EACH_8(index, macro, contex, arg, ...) \
    macro(index, contex, arg) \
    PP_FOR_EACH_7(PP_INC(index), macro, contex, __VA_ARGS__)

#define DECLARE_EACH(index, contex, arg)    PP_IF(index, PP_COMMA, PP_EMPTY)() contex arg

PP_FOR_EACH(DECLARE_EACH, int, x, y, z);    // -> int x, y, z;
PP_FOR_EACH(DECLARE_EACH, bool, a, b);      // -> bool a, b;

PP_FOR_EACH 接收两个固定参数： macro 可以理解为遍历的时候调用的宏，contex 可以作为固定值参数传给 macro。PP_FOR_EACH 先通过 PP_ARGS_SIZE 获取变长参数的长度 N，再用 PP_CONCAT 拼接得到 PP_FOR_EACH_N，之后 PP_FOR_EACH_N 会迭代调用 PP_FOR_EACH_N-1 来实现跟变长参数个数相同的遍历次数。

例子里我们声明了 DECLARE_EACH 作为参数 macro，DECLARE_EACH 的作用就是返回 contex arg，如果 contex 是类型名字，arg 是变量名字，DECLARE_EACH 就可以用来声明变量。

条件循环

有了 FOR_EACH 之后，我们还可以用类似的写法写出 PP_WHILE：

#define PP_WHILE PP_WHILE_1

#define PP_WHILE_1(pred, op, val) PP_WHILE_1_IMPL(PP_BOOL(pred(val)), pred, op, val)
#define PP_WHILE_1_IMPL(cond, pred, op, val) \
    PP_IF(cond, PP_WHILE_2, val PP_EMPTY_EAT)(pred, op, PP_IF(cond, op, PP_EMPTY_EAT)(val))

#define PP_WHILE_2(pred, op, val) PP_WHILE_2_IMPL(PP_BOOL(pred(val)), pred, op, val)
#define PP_WHILE_2_IMPL(cond, pred, op, val) \
    PP_IF(cond, PP_WHILE_3, val PP_EMPTY_EAT)(pred, op, PP_IF(cond, op, PP_EMPTY_EAT)(val))

#define PP_WHILE_3(pred, op, val) PP_WHILE_3_IMPL(PP_BOOL(pred(val)), pred, op, val)
#define PP_WHILE_3_IMPL(cond, pred, op, val) \
    PP_IF(cond, PP_WHILE_4, val PP_EMPTY_EAT)(pred, op, PP_IF(cond, op, PP_EMPTY_EAT)(val))

#define PP_WHILE_4(pred, op, val) PP_WHILE_4_IMPL(PP_BOOL(pred(val)), pred, op, val)
#define PP_WHILE_4_IMPL(cond, pred, op, val) \
    PP_IF(cond, PP_WHILE_5, val PP_EMPTY_EAT)(pred, op, PP_IF(cond, op, PP_EMPTY_EAT)(val))
// ...

#define PP_WHILE_8(pred, op, val) PP_WHILE_8_IMPL(PP_BOOL(pred(val)), pred, op, val)
#define PP_WHILE_8_IMPL(cond, pred, op, val) \
    PP_IF(cond, PP_WHILE_8, val PP_EMPTY_EAT)(pred, op, PP_IF(cond, op, PP_EMPTY_EAT)(val))

#define PP_EMPTY_EAT(...)

#define SUM_OP(xy_tuple) SUM_OP_OP_IMPL xy_tuple
#define SUM_OP_OP_IMPL(x, y) (PP_DEC(x), y + x)

#define SUM_PRED(xy_tuple) SUM_PRED_IMPL xy_tuple
#define SUM_PRED_IMPL(x, y) x

#define SUM(max_num, origin_num) \
    PP_IDENTITY(SUM_IMPL PP_WHILE(SUM_PRED, SUM_OP, (max_num, origin_num)))
#define SUM_IMPL(ignore, ret) ret

PP_WHILE(SUM_PRED, SUM_OP, (2, a))      // -> (0, a + 2 + 1)
SUM(2, a)                               // -> a + 2 + 1

PP_WHILE 接受三个参数： pred 条件判断函数，op 操作函数，val 初始值；循环的过程中不断用 pred(val) 来做循环终止判断，把 op(val) 得到的值传给后续的宏，可以理解为执行以下代码：

while (pred(val)) {
    val = op(val);
}

PP_WHILE_N 首先用 pred(val) 得到条件判断结果，把条件结果 cond 和其余参数再传给 PP_WHILE_N_IMPL。 PP_WHILE_N_IMPL 可以分两部分看：后半部分 (pred, op, PP_IF(cond, op, PP_EMPTY_EAT)(val)) 是作为前半部分的参数，PP_IF(cond, op, PP_EMPTY_EAT)(val) 是如果 cond 为真，则求值 op(val)，否则求值 PP_EMPTY_EAT(val) 得到空。前半部分 PP_IF(cond, PP_WHILE_N+1, val PP_EMPTY_EAT)，如果 cond 为真，则返回 PP_WHILE_N+1，结合后半部分的参数继续执行循环；否则返回 val PP_EMPTY_EAT，此时 val 就是最终的计算结果，而 PP_EMPTY_EAT 会吞掉后半部分的结果。

SUM 实现 N + N-1 + ... + 1。初始值 (max_num, origin_num)；SUM_PRED 取值的第一个元素 x，判断是否大于 0；SUM_OP 对 x 执行递减操作 x = x - 1，对 y 执行 + x 操作 y = y + x。直接用 SUM_PRED 和 SUM_OP 传给 PP_WHILE，返回的结果是一个元组，我们真正想要的结果是元组的第 2 个元素，于是再用 SUM 取第 2 个元素的值。

递归重入

到目前为止，我们的遍历访问和条件循环都运作的很好，结果符合预期。还记得我们在讲宏展开规则的时候提到的禁止递归重入么，当我们想要执行两重循环的时候就不幸遇到到了禁止递归重入：

#define SUM_OP2(xy_tuple) SUM_OP_OP_IMPL2 xy_tuple
#define SUM_OP_OP_IMPL2(x, y) (PP_DEC(x), y + SUM(x, 0))

#define SUM2(max_num, origin_num) \
    PP_IDENTITY(SUM_IMPL PP_WHILE(SUM_PRED, SUM_OP2, (max_num, origin_num)))

SUM2(1, a)      // -> a + SUM_IMPL PP_WHILE_1(SUM_PRED, SUM_OP, (1, a))

SUM2 把参数 op 改用 SUM_OP2，SUM_OP2 里面会调用到 SUM，而 SUM 展开还会是 PP_WHILE_1，相当于 PP_WHILE_1 递归调用到了自身，预处理器停止展开。

为了解决这个问题，我们可以用一种自动推导递归的方法（Automatic Recursion）：

#define PP_AUTO_WHILE PP_CONCAT(PP_WHILE_, PP_AUTO_REC(PP_WHILE_PRED))

#define PP_AUTO_REC(check) PP_IF(check(2), PP_AUTO_REC_12, PP_AUTO_REC_34)(check)
#define PP_AUTO_REC_12(check) PP_IF(check(1), 1, 2)
#define PP_AUTO_REC_34(check) PP_IF(check(3), 3, 4)

#define PP_WHILE_PRED(n) \
    PP_CONCAT(PP_WHILE_CHECK_, PP_WHILE_ ## n(PP_WHILE_FALSE, PP_WHILE_FALSE, PP_WHILE_FALSE))
#define PP_WHILE_FALSE(...) 0

#define PP_WHILE_CHECK_PP_WHILE_FALSE 1

#define PP_WHILE_CHECK_PP_WHILE_1(...) 0
#define PP_WHILE_CHECK_PP_WHILE_2(...) 0
#define PP_WHILE_CHECK_PP_WHILE_3(...) 0
#define PP_WHILE_CHECK_PP_WHILE_4(...) 0
// ...
#define PP_WHILE_CHECK_PP_WHILE_8(...) 0

PP_AUTO_WHILE       // -> PP_WHILE_1

#define SUM3(max_num, origin_num) \
    PP_IDENTITY(SUM_IMPL PP_AUTO_WHILE(SUM_PRED, SUM_OP, (max_num, origin_num)))

#define SUM_OP4(xy_tuple) SUM_OP_OP_IMPL4 xy_tuple
#define SUM_OP_OP_IMPL4(x, y) (PP_DEC(x), y + SUM3(x, 0))

#define SUM4(max_num, origin_num) \
    PP_IDENTITY(SUM_IMPL PP_AUTO_WHILE(SUM_PRED, SUM_OP4, (max_num, origin_num)))

SUM4(2, a)          // -> a + 0 + 2 + 1 + 0 + 1

PP_AUTO_WHILE 就是 PP_WHILE 的自动推导递归版本，核心的宏是 PP_AUTO_REC(PP_WHILE_PRED)，这个宏可以找出当前可用的 PP_WHILE_N 版本的数字 N。

推导的原理很简单，就是搜索所有版本，找出能够正确展开的版本，返回该版本的数字，为了提升搜索的速度，一般的做法是使用二分查找，这就是 PP_AUTO_REC 在做的事情。PP_AUTO_REC 接受一个参数 check，check 负责检查版本可用性，这里给出的是支持搜索版本范围 [1, 4]。PP_AUTO_REC 会首先检查 check(2)，如果 check(2) 为真，则调用 PP_AUTO_REC_12 搜索范围 [1, 2]，否则用 PP_AUTO_REC_34 搜索 [3, 4]。PP_AUTO_REC_12 检查 check(1) 如果为真，说明版本 1 可用，否则用版本 2，PP_AUTO_REC_34 同理。

check 宏要怎么写才能知道版本是否可用呢？在这里，PP_WHILE_PRED 会展开成两部分的拼接，我们来看后部分 PP_WHILE_ ## n(PP_WHILE_FALSE, PP_WHILE_FALSE, PP_WHILE_FALSE)：如果 PP_WHILE_ ## n 可用，由于 PP_WHILE_FALSE 固定返回 0，这部分会展开得到 val 参数的值，也就是 PP_WHILE_FALSE；否则这部分宏会保持不变，依然是 PP_WHILE_n(PP_WHILE_FALSE, PP_WHILE_FALSE, PP_WHILE_FALSE)。

把后部分的结果跟前部分 PP_WHILE_CHECK_ 拼接起来，得到两种结果：PP_WHILE_CHECK_PP_WHILE_FALSE 或者 PP_WHILE_CHECK_PP_WHILE_n(PP_WHILE_FALSE, PP_WHILE_FALSE, PP_WHILE_FALSE)，于是我们让 PP_WHILE_CHECK_PP_WHILE_FALSE 返回 1 表明可用，PP_WHILE_CHECK_PP_WHILE_n 返回 0 表示不可用。至此，我们完成了自动推导递归的功能。

算术比较

不相等：

#define PP_NOT_EQUAL(x, y) PP_NOT_EQUAL_IMPL(x, y)
#define PP_NOT_EQUAL_IMPL(x, y) \
    PP_CONCAT(PP_NOT_EQUAL_CHECK_, PP_NOT_EQUAL_ ## x(0, PP_NOT_EQUAL_ ## y))

#define PP_NOT_EQUAL_CHECK_PP_EQUAL_NIL 1
#define PP_NOT_EQUAL_CHECK_PP_NOT_EQUAL_0(...) 0
#define PP_NOT_EQUAL_CHECK_PP_NOT_EQUAL_1(...) 0
#define PP_NOT_EQUAL_CHECK_PP_NOT_EQUAL_2(...) 0
#define PP_NOT_EQUAL_CHECK_PP_NOT_EQUAL_3(...) 0
#define PP_NOT_EQUAL_CHECK_PP_NOT_EQUAL_4(...) 0
// ...
#define PP_NOT_EQUAL_CHECK_PP_NOT_EQUAL_8(...) 0

#define PP_NOT_EQUAL_0(cond, y) PP_IF(cond, PP_EQUAL_NIL, y(1, PP_EQUAL_NIL))
#define PP_NOT_EQUAL_1(cond, y) PP_IF(cond, PP_EQUAL_NIL, y(1, PP_EQUAL_NIL))
#define PP_NOT_EQUAL_2(cond, y) PP_IF(cond, PP_EQUAL_NIL, y(1, PP_EQUAL_NIL))
#define PP_NOT_EQUAL_3(cond, y) PP_IF(cond, PP_EQUAL_NIL, y(1, PP_EQUAL_NIL))
#define PP_NOT_EQUAL_4(cond, y) PP_IF(cond, PP_EQUAL_NIL, y(1, PP_EQUAL_NIL))
// ...
#define PP_NOT_EQUAL_8(cond, y) PP_IF(cond, PP_EQUAL_NIL, y(1, PP_EQUAL_NIL))

PP_NOT_EQUAL(1, 1)          // -> 0
PP_NOT_EQUAL(3, 1)          // -> 1

判断数值是否相等，用到了禁止递归重入的特性，把 x 和 y 递归拼接成 PP_NOT_EQUAL_x PP_NOT_EQUAL_y 宏，如果 x == y，则不会展开 PP_NOT_EQUAL_y 宏，跟 PP_NOT_EQUAL_CHECK_ 拼接成 PP_NOT_EQUAL_CHECK_PP_NOT_EQUAL_y 返回 0；反之，两次都成功展开最后得到 PP_EQUAL_NIL，拼接得到 PP_NOT_EQUAL_CHECK_PP_EQUAL_NIL 返回 1。

相等：

#define PP_EQUAL(x, y) PP_NOT(PP_NOT_EQUAL(x, y))

PP_EQUAL(1, 1)              // -> 1
PP_EQUAL(1, 3)              // -> 0

小于等于：

#define PP_LESS_EQUAL(x, y) PP_NOT(PP_SUB(x, y))

PP_LESS_EQUAL(2, 1)         // -> 0
PP_LESS_EQUAL(1, 1)         // -> 1
PP_LESS_EQUAL(1, 2)         // -> 1

小于：

#define PP_LESS(x, y) PP_AND(PP_LESS_EQUAL(x, y), PP_NOT_EQUAL(x, y))

PP_LESS(2, 1)               // -> 0
PP_LESS(1, 2)               // -> 1
PP_LESS(2, 2)               // -> 0

另外还有大于，大于等于等等算术比较，这里不再赘述。

算术运算

利用 PP_AUTO_WHILE 我们可以实现基础的算术运算了，而且支持嵌套运算。

加法：

#define PP_ADD(x, y) \
    PP_IDENTITY(PP_ADD_IMPL PP_AUTO_WHILE(PP_ADD_PRED, PP_ADD_OP, (x, y)))
#define PP_ADD_IMPL(x, y) x

#define PP_ADD_PRED(xy_tuple) PP_ADD_PRED_IMPL xy_tuple
#define PP_ADD_PRED_IMPL(x, y) y

#define PP_ADD_OP(xy_tuple) PP_ADD_OP_IMPL xy_tuple
#define PP_ADD_OP_IMPL(x, y) (PP_INC(x), PP_DEC(y))

PP_ADD(1, 2)                  // -> 3
PP_ADD(1, PP_ADD(1, 2))       // -> 4

减法：

#define PP_SUB(x, y) \
    PP_IDENTITY(PP_SUB_IMPL PP_AUTO_WHILE(PP_SUB_PRED, PP_SUB_OP, (x, y)))
#define PP_SUB_IMPL(x, y) x

#define PP_SUB_PRED(xy_tuple) PP_SUB_PRED_IMPL xy_tuple
#define PP_SUB_PRED_IMPL(x, y) y

#define PP_SUB_OP(xy_tuple) PP_SUB_OP_IMPL xy_tuple
#define PP_SUB_OP_IMPL(x, y) (PP_DEC(x), PP_DEC(y))

PP_SUB(2, 1)                // -> 1
PP_SUB(3, PP_ADD(2, 1))     // -> 0

乘法：

#define PP_MUL(x, y) \
    IDENTITY(PP_MUL_IMPL PP_AUTO_WHILE(PP_MUL_PRED, PP_MUL_OP, (0, x, y)))
#define PP_MUL_IMPL(ret, x, y) ret

#define PP_MUL_PRED(rxy_tuple) PP_MUL_PRED_IMPL rxy_tuple
#define PP_MUL_PRED_IMPL(ret, x, y) y

#define PP_MUL_OP(rxy_tuple) PP_MUL_OP_IMPL rxy_tuple
#define PP_MUL_OP_IMPL(ret, x, y) (PP_ADD(ret, x), x, PP_DEC(y))

PP_MUL(1, 1)                // -> 1
PP_MUL(2, PP_ADD(0, 1))     // -> 2

乘法实现这里增加了一个参数 ret，初始值为 0，每次迭代会执行 ret = ret + x。

除法：

#define PP_DIV(x, y) \
    IDENTITY(PP_DIV_IMPL PP_AUTO_WHILE(PP_DIV_PRED, PP_DIV_OP, (0, x, y)))
#define PP_DIV_IMPL(ret, x, y) ret

#define PP_DIV_PRED(rxy_tuple) PP_DIV_PRED_IMPL rxy_tuple
#define PP_DIV_PRED_IMPL(ret, x, y) PP_LESS_EQUAL(y, x)

#define PP_DIV_OP(rxy_tuple) PP_DIV_OP_IMPL rxy_tuple
#define PP_DIV_OP_IMPL(ret, x, y) (PP_INC(ret), PP_SUB(x, y), y)

PP_DIV(1, 2)                // -> 0
PP_DIV(2, 1)                // -> 2
PP_DIV(2, PP_ADD(1, 1))     // -> 1

除法利用了 PP_LESS_EQUAL，只有 y <= x 的情况下才继续循环。

数据结构

宏也可以有数据结构，其实我们在前面的也稍微用到了一种数据结构 tuple，PP_REMOVE_PARENS 就是可以去掉 tuple 的外层括号，返回里面的元素。我们这里就以 tuple 为例子讨论相关的实现，其他的数据结构 list, array 等有兴趣可以去看 Boost 的实现。

tuple 定义为用括号包住的逗号分开的元素集合：(a, b, c)。

#define PP_TUPLE_REMOVE_PARENS(tuple) PP_REMOVE_PARENS(tuple)

// 获取指定下标的元素
#define PP_TUPLE_ELEM(i, tuple) PP_ARGS_ELEM(i, PP_TUPLE_REMOVE_PARENS(tuple))

// 吞掉整个 tuple 返回空
#define PP_TUPLE_EAT() PP_EMPTY_EAT

// 获取大小
#define PP_TUPLE_SIZE(tuple) PP_ARGS_SIZE(PP_TUPLE_REMOVE_PARENS(tuple))

// 添加元素
#define PP_TUPLE_PUSH_BACK(elem, tuple) \
    PP_TUPLE_PUSH_BACK_IMPL(PP_TUPLE_SIZE(tuple), elem, tuple)
#define PP_TUPLE_PUSH_BACK_IMPL(size, elem, tuple) \
    (PP_TUPLE_REMOVE_PARENS(tuple) PP_IF(size, PP_COMMA, PP_EMPTY)() elem)

// 插入元素
#define PP_TUPLE_INSERT(i, elem, tuple) \
    PP_TUPLE_ELEM( \
        3, \
        PP_AUTO_WHILE( \
            PP_TUPLE_INSERT_PRED, \
            PP_TUPLE_INSERT_OP, \
            (0, i, elem, (), tuple) \
        ) \
    )
#define PP_TUPLE_INSERT_PRED(args) PP_TUPLE_INSERT_PERD_IMPL args
#define PP_TUPLE_INSERT_PERD_IMPL(curi, i, elem, ret, tuple) \
    PP_NOT_EQUAL(PP_TUPLE_SIZE(ret), PP_INC(PP_TUPLE_SIZE(tuple)))
#define PP_TUPLE_INSERT_OP(args) PP_TUPLE_INSERT_OP_IMPL args
#define PP_TUPLE_INSERT_OP_IMPL(curi, i, elem, ret, tuple) \
    ( \
    PP_IF(PP_NOT_EQUAL(PP_TUPLE_SIZE(ret), i), PP_INC(curi), curi), \
    i, elem, \
    PP_TUPLE_PUSH_BACK(\
        PP_IF( \
            PP_NOT_EQUAL(PP_TUPLE_SIZE(ret), i), \
            PP_TUPLE_ELEM(curi, tuple), elem \
        ), \
        ret \
    ), \
    tuple \
    )

// 删除末尾元素
#define PP_TUPLE_POP_BACK(tuple) \
    PP_TUPLE_ELEM( \
        1, \
        PP_AUTO_WHILE( \
            PP_TUPLE_POP_BACK_PRED, \
            PP_TUPLE_POP_BACK_OP, \
            (0, (), tuple) \
        ) \
    )
#define PP_TUPLE_POP_BACK_PRED(args) PP_TUPLE_POP_BACK_PRED_IMPL args
#define PP_TUPLE_POP_BACK_PRED_IMPL(curi, ret, tuple) \
    PP_IF( \
        PP_TUPLE_SIZE(tuple), \
        PP_NOT_EQUAL(PP_TUPLE_SIZE(ret), PP_DEC(PP_TUPLE_SIZE(tuple))), \
        0 \
    )
#define PP_TUPLE_POP_BACK_OP(args) PP_TUPLE_POP_BACK_OP_IMPL args
#define PP_TUPLE_POP_BACK_OP_IMPL(curi, ret, tuple) \
    (PP_INC(curi), PP_TUPLE_PUSH_BACK(PP_TUPLE_ELEM(curi, tuple), ret), tuple)

// 删除元素
#define PP_TUPLE_REMOVE(i, tuple) \
    PP_TUPLE_ELEM( \
        2, \
        PP_AUTO_WHILE( \
            PP_TUPLE_REMOVE_PRED, \
            PP_TUPLE_REMOVE_OP, \
            (0, i, (), tuple) \
        ) \
    )
#define PP_TUPLE_REMOVE_PRED(args) PP_TUPLE_REMOVE_PRED_IMPL args
#define PP_TUPLE_REMOVE_PRED_IMPL(curi, i, ret, tuple) \
    PP_IF( \
        PP_TUPLE_SIZE(tuple), \
        PP_NOT_EQUAL(PP_TUPLE_SIZE(ret), PP_DEC(PP_TUPLE_SIZE(tuple))), \
        0 \
    )
#define PP_TUPLE_REMOVE_OP(args) PP_TUPLE_REMOVE_OP_IMPL args
#define PP_TUPLE_REMOVE_OP_IMPL(curi, i, ret, tuple) \
    ( \
    PP_INC(curi), \
    i, \
    PP_IF( \
        PP_NOT_EQUAL(curi, i), \
        PP_TUPLE_PUSH_BACK(PP_TUPLE_ELEM(curi, tuple), ret), \
        ret \
    ), \
    tuple \
    )

PP_TUPLE_SIZE(())               // -> 0

PP_TUPLE_PUSH_BACK(2, (1))      // -> (1, 2)
PP_TUPLE_PUSH_BACK(2, ())       // -> (2)

PP_TUPLE_INSERT(1, 2, (1, 3))   // -> (1, 2, 3)

PP_TUPLE_POP_BACK(())           // -> ()
PP_TUPLE_POP_BACK((1))          // -> ()
PP_TUPLE_POP_BACK((1, 2, 3))    // -> (1, 2)

PP_TUPLE_REMOVE(1, (1, 2, 3))   // -> (1, 3)
PP_TUPLE_REMOVE(0, (1, 2, 3))   // -> (2, 3)

这里稍微解释一下插入元素的实现，其他删除元素等操作也是通过类似的原理来实现的。PP_TUPLE_INSERT(i, elem, tuple) 可以在 tuple 的位置 i 插入元素 elem，为了完成这个操作，先把位置小于 i 的元素都先用 PP_TUPLE_PUSH_BACK 放到一个新的 tuple 上（ret），然后在位置 i 放入元素 elem，之后再把原 tuple 位置大于等于 i 的元素放到 ret 后面，最后 ret 就得到我们想要的结果。

小结

本文的目的是想要阐述清楚 C/C++ 宏编程的原理和基本实现，在记录我本人的一些理解和认识的同时，希望能够对其他人能带来一些解惑和启发。需要注意的是，尽管本文篇幅有点长，但还是有一些关于宏编程的技巧和用法是没有涉及到的，譬如 CHAOS_PP 提出的基于延迟展开的递归调用方法，BOOST_PP 里面的 REPEAT 相关宏等等，有兴趣的可以自行查阅资料。

宏编程的调试是一个痛苦的过程，我们可以：

用 -P -E 选项输出预处理结果；
用前面提到的我自己修改的 clang 版本仔细研究展开过程；
把复杂的宏拆解，查看中间宏的展开结果；
屏蔽无关的头文件和宏；
最后就是要脑补宏展开的过程了，熟悉宏展开之后调试的效率也会提升。

本文中的宏是我自己在理解了原理之后重新实现出来的，有部分宏借鉴了 Boost 的实现和引用里面的文章，有任何错误之处，欢迎随时指正，也欢迎找我来讨论相关的问题。

本文的代码全部都在这里：下载，在线演示。

引用

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

C/C++ 的命令行参数处理总结

Thu, 30 Nov 2023 20:09:36 +0000

前一阵子翻 Linux 内核代码的时候看到了内核对模块参数 (moduleparam) 的处理，觉得挺精妙，让我不禁想研究下 C 下的命令行参数要怎样更好地处理。本文所用代码都在这里 aparsing 。代码支持在 Windows 、 Linux 、 Mac OS X 下编译运行，详细的编译指南在 README.md 里面。

getenv

标准库为我们提供了一个函数 getenv ，按照字面意思，这个函数是用来获取环境变量的，那么只要我们预先设置好需要的环境变量，在程序里面拿出来，就间接地把参数传到程序里面啦。我们来看下面这段代码：

#include <stdlib.h>
#include <stdio.h>

//char *getenv( const char *name );
//GETENV_ADD=abc GETENV_NUM=2 ./getenv_test 

int main (int argc, char **argv)
{
    char *add, *num;
    if((add = getenv("GETENV_ADD")))
        printf("GETENV_ADD = %s\n", add);
    else
        printf("GETENV_ADD not found\n");

    if((num = getenv("GETENV_NUM")))
    {
        int numi = atoi(num);
        printf("GETENV_NUM = %d\n", numi);
    }
    else
        printf("GETENV_NUM not found\n");
}

getenv 函数声明如第 4 行，传入想要获取的变量名字，返回该变量的值，如果找不到变量，则返回0。10 和 15 行就是分别获取两个环境变量的值，如果变量有效则打印变量值。需要注意的是 getenv 返回的都是字符串，需要使用者手动转换数值类型的，所以使用起来不够方便。编译运行:

Windows 下：

set GETENV_ADD=abc & set GETENV_NUM=1 & .\getenv_test.exe

Linux 下：

GETENV_ADD=abc GETENV_NUM=2 ./getenv_test

输出：

GETENV_ADD = abc
GETENV_NUM = 2

getopt

Linux 给我们提供了一组函数 getopt, getopt_long, getopt_long_only 来处理命令行传递进来的函数，这三个函数的声明分别是：

extern char *optarg;
extern int optind, opterr, optopt;

int getopt(int argc, char * const argv[],
                  const char *optstring);

int getopt_long(int argc, char * const argv[],
            const char *optstring,
            const struct option *longopts, int *longindex);

int getopt_long_only(int argc, char * const argv[],
            const char *optstring,
            const struct option *longopts, int *longindex);

getopt 只能处理短参数（即单字符参数），getopt_long, getopt_long_only 则可以处理长参数。详细的函数解释可以去翻 Linux 下的手册，下面我们通过例子来说明 getopt 和 getopt_long 的用法。

需要注意的是， Windows 下是没有提供这一组函数的，所以我找了一份可以在 Windows 下编译的源码，做了小小的改动，代码都在这里。

// test getopt

#include <getopt.h>
#include <stdio.h>
#include <string.h>

static struct option long_options[] =
{
    {"add", required_argument, 0, 'a'},
    {"append", no_argument, 0, 0},
    {"delete", required_argument, 0, 0},
    {"verbose", optional_argument, 0, 0},
    {"create", no_argument, 0, 0},
    {"file", required_argument, 0, 0},
    {"help", no_argument, 0, 0},
    {0, 0, 0, 0}
};

static char simple_options[] = "a:bc::d:0123456789";

int main (int argc, char **argv)
{

    int c;
    int digit_optind = 0;

    while (1)
    {
        int this_option_optind = optind ? optind : 1;
        int longindex = -1;

        c = getopt_long(argc, argv, simple_options, long_options, &longindex);
        if (c == -1)
        break;

        switch (c)
        {
            // long option
            case 0:
                   printf("option %s", long_options[longindex].name);
                   if (optarg)
                       printf(" with arg %s", optarg);
                   printf("\n");
                   break;

                break;

            case '0':
            case '1':
            case '2':
            case '3':
            case '4':
            case '5':
            case '6':
            case '7':
            case '8':
            case '9':
                if(digit_optind != 0 && digit_optind != this_option_optind)
                    printf("digits occur in two different argv-elements.\n");

                digit_optind = this_option_optind;
                printf("option %c\n", c);
                break;

            case 'a':
                printf("option a with value '%s'\n", optarg);
                break;

            case 'b':
                printf("option b\n");
                break;

            case 'c':
                if(optarg)
                    printf("option c with value '%s'\n", optarg);
                else
                    printf("option c\n");
                break;

            case '?':
                break;

            default:
                printf("?? getopt returned character code 0%o ??\n", c);
        } // switch
    } // while

    if (optind < argc)
    {
        printf("non-option ARGV-elements: ");
        while (optind < argc)
        printf("%s ", argv[optind++]);
        printf("\n");
    }

    return 0;
}

我们来着重分析 getopt_long 的用法，getopt_long 的前三个参数跟 getopt 是一样的，分别是：命令行参数个数 argc ，命令行参数数组 argv，短参数具体形式 optstring。otpstring 的格式就是一个个的短参数字符，后面加冒号 : 表示带参数，两个冒号 :: 表示可选参数，譬如第 19 行，就是声明短参数的形式，b 参数不带额外参数， a 参数带额外参数，c 带可选参数。

getopt_long 后两个参数是用来处理长参数的，其中 option 的结构是：

struct option {
    const char *name;       // 长参数名字
    int         has_arg;    // 是否带额外参数
    int        *flag;       // 设置如何返回函数调用结果
    int         val;        // 返回的数值
};

虽然说是长参数，但 name 还是可以设置为单字符长度的。

has_arg 可以设置为 no_argument, required_argument, optional_argument，分别表示不带参数，带参数，带可选参数。

flag 和 val 是配合使用的，如果 flag = NULL，getopt_long 会直接返回 val ，否则如果 flag 为有效指针，getopt_long 会执行类似 *flag = val 的操作，把 flag 指向的变量设置为 val 的数值。

如果 getopt_long 找到匹配的短参数，会返回该短参数的字符值，如果找到匹配的长参数，会返回 val（ flag = NULL ）或者返回 0 （ flag != NULL; *flag = val; ）；如果遇到非参数的字符，会返回 ?；如果所有参数都处理完毕，则返回 -1 。

利用返回值的特性，我们可以做出用长参跟短参含义相同的效果，譬如 long_options 的第一个参数 add，其 val 值设置为短参数的字符 'a'，那么判断返回时，--add 和 -a 会进入相同的处理分支，被当作相同的含义来处理了。

拼图的最后一块就是 optind 和 optarg 的用法，optind 是下一个待处理参数在 argv 中的位置， optarg 则指向额外参数字符串。

编译运行代码：

$ .\getopt_test -a 1 -b -c4 --add 2 --verbose --verbose=3 -123 -e --e
option a with value '1'
option b
option c with value '4'
option a with value '2'
option verbose
option verbose with arg 3
option 1
option 2
option 3
.\getopt_test: invalid option -- e
.\getopt_test: unrecognized option `--e'

-a 和 --add 的含义相同，短参数的可选参数直接跟在后面，譬如 -c4，而长参数的可选参数需要有等号，譬如 --verbose=3。

mobuleparam

ok，终于来到最初引发这篇文章的方法，Linux 内核用了一种很取巧的方法来给内核模块传递参数，这个方法就是 moduleparam 。我在这里先简单解释 Linux 内核的 moduleparam 的做法，更详细的解释可以去看代码。虽然我借鉴了一些 moduleparam 的处理方法，但和 Linux 内核的 moduleparam 有一些不同，为了区分，我会把我的方法叫做 small moduleparam ， Linux 内核的依然叫做 moduleparam 。

先来看看 moduleparam 的用法，在模块里面声明：

int enable_debug = 0;
module_param(enable_debug, int, 0);

然后加载模块时输入参数：

$ insmod mod enable_debug=1

变量 enable_debug 就被正确地设置为 1，使用起来很方便，需要增加的代码也很少，代码可以写得很简短优雅，不用像 getenv 和 getopt 那样写很多循环判断，而且还自带类型转换，所以我看到就想，要是能把这个方法拿来处理命令行参数，那就更好了。

接着来看看 moduleparam 的核心实现：

struct kernel_param {
    const char *name;           // 变量名字
    u16 perm;                   // 变量访问权限
    u16 flags;                  // 变量是否 bool 类型
    param_set_fn set;           // str -> 变量值
    param_get_fn get;           // 变量值 -> str
    union {
        void *arg;              // 变量指针
        const struct kparam_string *str;
        const struct kparam_array *arr;
    };
};

#define __module_param_call(prefix, name, set, get, arg, isbool, perm)  \
    /* Default value instead of permissions? */         \
    static int __param_perm_check_##name __attribute__((unused)) =  \
    BUILD_BUG_ON_ZERO((perm) < 0 || (perm) > 0777 || ((perm) & 2))  \
    + BUILD_BUG_ON_ZERO(sizeof(""prefix) > MAX_PARAM_PREFIX_LEN);   \
    static const char __param_str_##name[] = prefix #name;      \
    static struct kernel_param __moduleparam_const __param_##name   \
    __used                              \
        __attribute__ ((unused,__section__ ("__param"),aligned(sizeof(void *)))) \
    = { __param_str_##name, perm, isbool ? KPARAM_ISBOOL : 0,   \
        set, get, { arg } }

#define module_param_call(name, set, get, arg, perm)                  \
    __module_param_call(MODULE_PARAM_PREFIX,                  \
                name, set, get, arg,                  \
                __same_type(*(arg), bool), perm)

#define module_param_named(name, value, type, perm)            \
    param_check_##type(name, &(value));                \
    module_param_call(name, param_set_##type, param_get_##type, &value, perm); \
    __MODULE_PARM_TYPE(name, #type)

#define module_param(name, type, perm)              \
    module_param_named(name, name, type, perm)

module_param 是一个宏，它实际做的事情是建立了一个可以反射到传入变量的结构 kernel_param ，该结构保存了足够访问和设置变量的信息，即第 20-24 行，并且把结构放在叫做 __param 的 section 中（ __section__ ("__param") ）。结构保存好之后，内核会在加载模块时，找出 elf 文件的 section __param 的位置和结构数量，在根据名字和 param_set_fn 分别设置每个参数的数值。找出特定名字 section 的方法是平台相关的，Linux 内核实现的是对 elf 文件的处理，Linux 提供了指令 readelf 来查看 elf 文件的信息，有兴趣的可以查看 readelf 的帮助信息。

上面说道 Linux 内核的做法是平台相关的，而我想要的平台无关的处理参数的方法，所以我们就要改一改原始的 moduleparam 的做法，把 __section__ ("__param") 声明去掉，毕竟我们并不像去很麻烦地读取 elf 文件的 section 。先来看看修改后的用法：

#include "moduleparam.h"
#include <stdio.h>

static int test = 0;
static bool btest = 0;
static unsigned int latest_num = 0;
static long latest[10] = {0};
static char strtest[20] = "\0";

void usage()
{
    char *msg = "usage: moduleparam_test [test=int] [btest[=bool]] [latest=int array] [strtest=string]\n";
    printf(msg);
}

int unknown_handler(char *param, char *val)
{
    printf("find unknown param: %s\n", param);
    return 0;
}

int main (int argc, char **argv)
{
    init_module_param(4);
    module_param(test, int);
    module_param_bool(btest);
    module_param_array(latest, long, &latest_num);
    module_param_string(strtest, strtest, sizeof(strtest));

    int ret = parse_params(argc, argv, unknown_handler);

    if(ret != 0)
    {
        usage();
        return 0;
    }

    char buf[1024];
    for(int i=0; i < MODULE_INIT_VARIABLE_NUM; ++i)
    {
        MODULE_INIT_VARIABLE[i].get(buf, &MODULE_INIT_VARIABLE[i]);
        printf("%s = %s\n", MODULE_INIT_VARIABLE[i].name, buf);
    }
    return 0;
}

那么为了保存每一个反射的结构，我就增加了一个宏 init_module_param(num) ，来声明保存结构的空间， num 是参数的个数，如果实际声明的参数个数超出 num ，程序会触发断言错误。module_param 的声明跟原始的稍有不同，去掉了最后一个表示访问权限的参数，不做权限的控制。另外新增了宏 module_param_bool 来处理表示 bool 的变量，这在 Linux 的版本是不需要的，因为它用到了 gcc 内建函数 __builtin_types_compatible_p 来判断变量的类型，很遗憾，MSVC 是没有这个函数的，所以我只能把这个功能去掉，增加一个宏。 module_param_array 和 module_param_string 就是对数组和字符串的处理，这两个功能在原始的版本也是有的。

声明参数完毕，就是处理传入的参数了，使用宏 parse_params ，传入 argc, argv，第 3 个参数是对未知参数的处理回调函数指针，可以传 NULL ，则入到位置参数会中断处理参数，返回错误码。

编译运行代码：

.\moduleparam_test.exe error=0 test=101 btest=1 latest=1,2,3 strtest=\"Hello World!\"
Parsing ARGS: error=0 test=101 btest=1 latest=1,2,3 strtest="Hello World!"
find unknown param: error
test = 101
btest = Y
latest = 1,2,3
strtest = Hello World!

可以看到数值，数组和字符串都能正确读入并转换格式，如果遇到不能转换格式的参数，会返回错误码并打印相关信息。我们可以很简单地添加几行代码，就完成参数的读入和转换处理，用起来很优雅。更详细实现可以直接看代码，在这里。

总结

这次我们总结了一下 C/C++ 下三种处理命令行参数的方法，分别是 getenv ，getopt 和 moduleparam。三种方法有各自的特点，以后有需要可以根据实际的需求来选择合适的方法：

getenv 是原生多平台就支持的，可以直接使用，但也过于原始，并使用的是环境变量，对环境有一定的污染，每次使用前最好清除不必要的环境变量防止上次的设置存留污染
getopt 是 Linux 平台原生支持的，Windows 不支持，所以需要包含实现的代码才能跨平台使用。参数的传递符合 Linux 的命令传参标准，支持可选参数，但使用起来略微麻烦，通常需要循环和条件判断来处理不同的参数，并对数值类型的参数不友好。
moduleparam 是参考 Linux 内核的 moduleparam 实现的命令行参数处理工具，支持跨平台使用，使用简单，能对不同类型的参数进行类型转换，缺点就是每个参数都需要一个相应的变量存储。

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

KCP 源码剖析

Thu, 30 Nov 2023 20:09:36 +0000

阅读本文之前，如果没听说过 KCP ，或者一点都不了解 KCP，麻烦抽一点时间先看看 KCP 项目的说明文档：传送门。本文的目的是深入 KCP 的实现细节去理解 KCP 。

什么是 KCP

KCP 是一个快速可靠协议，能够以比 TCP 更低的延迟来传送数据，数据重传更快，等待时间更短。

TCP是为流量设计的（每秒内可以传输多少KB的数据），讲究的是充分利用带宽。而 KCP是为流速设计的（单个数据包从一端发送到一端需要多少时间），以10%-20%带宽浪费的代价换取了比 TCP快30%-40%的传输速度。TCP信道是一条流速很慢，但每秒流量很大的大运河，而KCP是水流湍急的小激流

以上是 KCP 文档上面写的，关键词是带宽和流速，KCP 会损耗带宽，带来的好处是更大更均衡的传输速率。更多的说明参考 KCP 自身的文档。

KCP 数据结构

KCP 源码在 ikcp.h 和 ikcp.c 里面，ikcp.h 核心的是数据结构的声明，首先是 SEGMENT 数据包，是 KCP 协议处理数据的最小单位：

SEGMENT 结构（点击展开代码）

//=====================================================================
// SEGMENT 一个 SETMENT 就是一个数据包
//=====================================================================
struct IKCPSEG
{
    // 链表节点，发送和接受队列都是这里的链表的结构
    struct IQUEUEHEAD node;

    // 会话编号，同一个会话编号相同
    IUINT32 conv;

    // 数据包类型，譬如 DATA 或者 ACK
    IUINT32 cmd;

    // 由于 MTU 的限制，大数据包会拆分成多个小数据包，这个是小数据包的编号
    IUINT32 frg

    // 每个数据包，都会附带上发送方的接受窗口大小
    IUINT32 wnd;

    // 发送时间，如果是 ACK 包，会设置为源数据包的 ts
    IUINT32 ts;

    // 唯一标识数据包的编号
    IUINT32 sn;

    // 代表小于 una 的数据包都接收成功，跟 TCP 含义一致：oldest unacknowledged sequence number SND
    IUINT32 una;

    // 数据长度
    IUINT32 len;

    // 超时重传时间
    IUINT32 resendts;

    // 下次超时等待时间
    IUINT32 rto;

    // 快速重传，收到本数据包之后的数据包的数量，大于一定数量就触发快速重传
    IUINT32 fastack;

    // 发送次数
    IUINT32 xmit;

    // 数据
    char data[1];
};

看完 SEGMENT 的注释，大致能看出 KCP 的核心也是一个 ARQ 协议，通过自动超时重传来保证数据的送达。接着再来看看 KCP 结构 KCPCB 的定义：

KCP 结构（点击展开代码）

//---------------------------------------------------------------------
// IKCPCB
//---------------------------------------------------------------------
struct IKCPCB
{
    // conv: 会话编号
    // mtu, mss: 最大传输单元，最大报文段大小
    // state: 会话状态，0 有效，-1 断开
    IUINT32 conv, mtu, mss, state;

    // snd_una: 等待 ACK 的包编号
    // snd_nxt: 下一个等待发送的数据包编号
    // rcv_nxt: 下一个等待接收的数据包编号
    IUINT32 snd_una, snd_nxt, rcv_nxt;

    // ts_recent, ts_lastack: 未用到
    // ssthresh: 拥塞控制慢启动阈值
    IUINT32 ts_recent, ts_lastack, ssthresh;

    // rx_rto: rto (retransmission timeout)，超时重传时间
    // rx_rttval, rx_srtt, rx_minrto: 计算 rto 的中间变量
    IINT32 rx_rttval, rx_srtt, rx_rto, rx_minrto;

    // snd_wnd, rcv_wnd: 最大发送和接收窗口大小
    // rmt_wnd: remote wnd ，对端剩余接受窗口大小
    // cwnd: 可发送窗口大小
    // probe: 是否要发送控制报文的标志
    IUINT32 snd_wnd, rcv_wnd, rmt_wnd, cwnd, probe;

    // current: 当前时间
    // interval: 更新间隔
    // ts_flush: 下次需要更新的时间
    // xmit: 发送失败次数
    IUINT32 current, interval, ts_flush, xmit;

    // 对应链表的长度
    IUINT32 nrcv_buf, nsnd_buf;
    IUINT32 nrcv_que, nsnd_que;

    // nodelay: 控制超时重传的 rto 增长速度
    // updated: 是否调用过 ikcp_update
    IUINT32 nodelay, updated;

    // ts_probe, probe_wait: 对端接收窗口长时间为 0 时主动定期发起询问
    IUINT32 ts_probe, probe_wait;

    // deal_link: 对端长时间无应答
    // incr: 参与计算发送窗口大小
    IUINT32 dead_link, incr;

    // queue: 跟用户层接触的数据包
    // buf: 协议缓存的数据包
    struct IQUEUEHEAD snd_queue;
    struct IQUEUEHEAD rcv_queue;
    struct IQUEUEHEAD snd_buf;
    struct IQUEUEHEAD rcv_buf;

    // 需要发送 ack 的数据包信息
    IUINT32 *acklist;

    // 需要 ack 的包数量
    IUINT32 ackcount;

    // acklist 内存大小
    IUINT32 ackblock;

    // 用户层传进来的数据
    void *user;

    // 存放一个 kcp 包的空间
    char *buffer;

    // 触发快速重传的 fastack 次数
    int fastresend;

    // 快速重传最大次数
    int fastlimit;

    // nocwnd: 不考虑慢启动的发送窗口大小
    // stream: 流模式
    int nocwnd, stream;

    // debug log
    int logmask;

    // 发送数据接口
    int (*output)(const char *buf, int len, struct IKCPCB *kcp, void *user);

    void (*writelog)(const char *log, struct IKCPCB *kcp, void *user);
};

逐一把 KCP 结构里面的字段注释上，可以初步感觉到，整套 KCP 的协议不太复杂，细细去分析代码，你我都能读懂并理解 KCP 协议

KCP 的 ARQ 实现

KCP 本质上是一个 ARQ (Auto Repeat-reQuest，自动重传) 协议，最基本的是要保证可靠的传输。那么我们可以先来关注 KCP 的基本 ARQ 部分，KCP 是怎么实现可靠传输的。

ARQ 顾名思义，当我们认为对端接收数据包失败时，自动重新发送对应的数据包，它是通过确认接收和超时重传两个机制，来实现可靠传输。具体的代码实现上， KCP 给每个数据包（就是上一节提到的 SEGMENT ）分配唯一的 sn 标识符，一旦对端接收到数据包，会回复一个 ACK 包（同样是 SEGMENT），ACK 包的 sn 跟接收到的数据包 sn 相同，通知接收到此数据包已经接收成功。SEGMENT 上还有一个 una 字段，表示下一个期待接收的数据包的编号，换句话说，即是所有在该编号之前的数据包都已经接收完，相当于一个全量的 ACK 包，发送端可以更快的更新发送缓冲和发送窗口。

我们可以通过跟踪 KCP 包的发送和接受代码，来理解最基本的 ARQ 实现：

发送

发送的过程是 ikcp_send -> ikcp_update -> ikcp_output，上层调用 ikcp_send 把数据传给 KCP，KCP 在 ikcp_update 中处理数据的发送。

ikcp_send（点击展开代码）

//---------------------------------------------------------------------
// 发送数据接口，用户调用 ikcp_send 来让 kcp 发送数据
// user/upper level send, returns below zero for error
//---------------------------------------------------------------------
int ikcp_send(ikcpcb *kcp, const char *buffer, int len)
{
    IKCPSEG *seg;
    int count, i;

    // mss 不能小于1
    assert(kcp->mss > 0);
    if (len < 0) return -1;

    // append to previous segment in streaming mode (if possible)
    if (kcp->stream != 0) {
        // 处理流模式
        // ......
    }

    // 计算分包，如果数据长度 len 大于 mss，需要分成多个包发送，对端接受到之后再拼起来
    if (len <= (int)kcp->mss) count = 1;
    else count = (len + kcp->mss - 1) / kcp->mss;

    if (count >= (int)IKCP_WND_RCV) return -2;

    if (count == 0) count = 1;

    // 分包
    for (i = 0; i < count; i++) {
        // 计算包的数据长度，并分配对应的 seg 结构
        int size = len > (int)kcp->mss ? (int)kcp->mss : len;
        seg = ikcp_segment_new(kcp, size);
        assert(seg);
        if (seg == NULL) {
            return -2;
        }

        // 设置 seg 的 数据信息，frg 表示分包编号
        if (buffer && len > 0) {
            memcpy(seg->data, buffer, size);
        }
        seg->len = size;
        seg->frg = (kcp->stream == 0)? (count - i - 1) : 0;

        // 加到 snd_queue 的末尾，nsnd_qua 加一
        iqueue_init(&seg->node);
        iqueue_add_tail(&seg->node, &kcp->snd_queue);
        kcp->nsnd_que++;
        if (buffer) {
            buffer += size;
        }
        len -= size;
    }

    return 0;
}

ikcp_send 是由 KCP 的上层来调用的发送数据接口，所有让 KCP 发送的数据，都应该通过这个接口。 ikcp_send 做的事情很简单，主要就是把数据，根据 kcp->mss （一个包最大数据长度）来分成多个包，并设置分包编号，最后放到发送链表 snd_queue 的末尾。流模式就是把多次调用 ikcp_send 的数据都看成一个流，会先自动填充未满的 SEGMENT 再分配新的，详细实现本文不讨论，感兴趣的，相信看完本文，再对应看看代码就能理解。

ikcp_send 调用完成之后，数据放在的 KCP 的 snd_queue 中，那么后面 KCP 需要找个时机，把待发送的数据发送出去，这块代码都放在 ikcp_update 和 ikcp_flush 里面：

ikcp_update（点击展开代码）

//---------------------------------------------------------------------
// ikcp_update 是给上层定期调用的接口，用来更新 kcp 的状态，发送数据
// update state (call it repeatedly, every 10ms-100ms), or you can ask 
// ikcp_check when to call it again (without ikcp_input/_send calling).
// 'current' - current timestamp in millisec. 
//---------------------------------------------------------------------
void ikcp_update(ikcpcb *kcp, IUINT32 current)
{
    IINT32 slap;

    kcp->current = current;

    // ikcp_flush 会检查这个，上层必须调用过 ikcp_update 才能调用 ikcp_flush，建议只使用 ikcp_update
    if (kcp->updated == 0) {
        kcp->updated = 1;
        kcp->ts_flush = kcp->current;
    }

    slap = _itimediff(kcp->current, kcp->ts_flush);

    if (slap >= 10000 || slap < -10000) {
        kcp->ts_flush = kcp->current;
        slap = 0;
    }

    if (slap >= 0) {
        // 下次 flush 的时间
        kcp->ts_flush += kcp->interval;
        if (_itimediff(kcp->current, kcp->ts_flush) >= 0) {
            kcp->ts_flush = kcp->current + kcp->interval;
        }
        ikcp_flush(kcp);
    }
}

ikcp_update 做的事情很简单，判断一下 ts_flush 的时间，符合条件则调用 ikcp_flush，主要的处理逻辑都在 ikcp_flush 里面了，因为 ikcp_flush 内容复杂一点，我们目前只关注跟 ARQ 发送相关的部分：

发送数据（点击展开代码）

//---------------------------------------------------------------------
// ikcp_flush
//---------------------------------------------------------------------
void ikcp_flush(ikcpcb *kcp)
{
    IUINT32 current = kcp->current;

    // buffer 是要传给 ikcp_output 的数据，初始化为 3 倍数据包大小
    char *buffer = kcp->buffer;
    char *ptr = buffer;
    int count, size, i;
    IUINT32 resent, cwnd;
    IUINT32 rtomin;
    struct IQUEUEHEAD *p;
    int change = 0;
    int lost = 0;
    IKCPSEG seg;

    // 'ikcp_update' haven't been called.
    if (kcp->updated == 0) return;

    seg.conv = kcp->conv;
    seg.cmd = IKCP_CMD_ACK;
    seg.frg = 0;

    // seg.wnd 是表示当前可接收窗口大小
    seg.wnd = ikcp_wnd_unused(kcp);
    seg.una = kcp->rcv_nxt;
    seg.len = 0;
    seg.sn = 0;
    seg.ts = 0;

    // 发送 ack
    // 计算 发送窗口
    //...

    // 把数据包从 snd_queue 移动到 snd_buf
    // 移动是需要满足 发送窗口 大小，发送窗口满了，就停止移动
    // 放在 snd_buf 的里面的数据，就是可以直接调用 ikcp_output 给对端发送的数据
    while (_itimediff(kcp->snd_nxt, kcp->snd_una + cwnd) < 0) {
        IKCPSEG *newseg;
        if (iqueue_is_empty(&kcp->snd_queue)) break;

        newseg = iqueue_entry(kcp->snd_queue.next, IKCPSEG, node);

        iqueue_del(&newseg->node);
        iqueue_add_tail(&newseg->node, &kcp->snd_buf);
        kcp->nsnd_que--;
        kcp->nsnd_buf++;

        newseg->conv = kcp->conv;
        newseg->cmd = IKCP_CMD_PUSH;
        newseg->wnd = seg.wnd;
        newseg->ts = current;

        // seg 唯一序号，其实就是一个递增的 kcp->snd_nxt
        newseg->sn = kcp->snd_nxt++;

        // una 在这里设置，通知对端下一个等待接收的包序号
        newseg->una = kcp->rcv_nxt;
        newseg->resendts = current;
        newseg->rto = kcp->rx_rto;
        newseg->fastack = 0;
        newseg->xmit = 0;
    }

    // 计算快速重传标志，超时等待时间
    // ...

    // 发送 snd_buf
    for (p = kcp->snd_buf.next; p != &kcp->snd_buf; p = p->next) {
        IKCPSEG *segment = iqueue_entry(p, IKCPSEG, node);
        int needsend = 0;
        if (segment->xmit == 0) {
            // 首次发送
            // set->xmit 表示发送次数
            // resendts 超时重传的等待时间
            needsend = 1;
            segment->xmit++;
            segment->rto = kcp->rx_rto;
            segment->resendts = current + segment->rto + rtomin;
        }
        else if (_itimediff(current, segment->resendts) >= 0) {
            // 超时重传
            // ...
        }
        else if (segment->fastack >= resent) {
            // 快速重传
            // ...
        }

        if (needsend) {
            int need;
            segment->ts = current;
            segment->wnd = seg.wnd;
            segment->una = kcp->rcv_nxt;

            size = (int)(ptr - buffer);
            need = IKCP_OVERHEAD + segment->len;

            // 每当 buffer 中的数据超过 mtu ，那就先发出去，尽量避免底层再分包
            if (size + need > (int)kcp->mtu) {
                ikcp_output(kcp, buffer, size);
                ptr = buffer;
            }

            // 把 seg 控制数据复制到 buffer 上，kcp 自己来处理大小端问题
            ptr = ikcp_encode_seg(ptr, segment);

            // 再复制数据
            if (segment->len > 0) {
                memcpy(ptr, segment->data, segment->len);
                ptr += segment->len;
            }


            if (segment->xmit >= kcp->dead_link) {
                kcp->state = (IUINT32)-1;
            }
        }
    }

    // flash remain segments
    size = (int)(ptr - buffer);
    if (size > 0) {
        ikcp_output(kcp, buffer, size);
    }

    // 计算 ssthresh，更新慢启动窗口
    // ...
}

我们目前只关注 ikcp_flush 里面有关发送数据的逻辑：

首先 KCP 会根据对端的接收窗口大小，把 snd_queue 上的数据移动到 snd_buf 上面，计算移动数量的公式是 num = snd_nxt - (snd_una + cwnd)，也就是：已发送成功的最大包序号 snd_una 加上滑动窗口大小 cwnd 大于下个待发送的包序号snd_nxt，则可以继续再发送新的数据包。移动 SEG 的同时，设置控制字段。

遍历 snd_buf，如果需要发送数据包，则把数据复制到 buffer 上，复制的同时用 ikcp_encode_seg 处理控制字段数据的大小端问题。

最后调用 ikcp_output 把 buffer 上的数据发送出去

至此， KCP 完成数据的发送。

接收

接收的过程是跟发送相反的：ikcp_input -> ikcp_update -> ikcp_recv，用户接收到网络上的数据之后，需要调用 ikcp_input 传给 KCP 解析，调用 ikcp_update 的时候会给发送端回复 ACK 包，上层通过调用 ikcp_recv 来接收 KCP 解析之后的数据。

接收数据（点击展开代码）

//---------------------------------------------------------------------
// input data
//---------------------------------------------------------------------
int ikcp_input(ikcpcb *kcp, const char *data, long size)
{
    IUINT32 prev_una = kcp->snd_una;
    IUINT32 maxack = 0, latest_ts = 0;
    int flag = 0;

    // 合法性检查
    if (data == NULL || (int)size < (int)IKCP_OVERHEAD) return -1;

    // data 可能是多个 KCP 包，循环处理
    while (1) {
        IUINT32 ts, sn, len, una, conv;
        IUINT16 wnd;
        IUINT8 cmd, frg;
        IKCPSEG *seg;

        // 不够一个 KCP 包，退出
        if (size < (int)IKCP_OVERHEAD) break;

        // 先把控制字段解析出来
        data = ikcp_decode32u(data, &conv);
        if (conv != kcp->conv) return -1;

        data = ikcp_decode8u(data, &cmd);
        data = ikcp_decode8u(data, &frg);
        data = ikcp_decode16u(data, &wnd);
        data = ikcp_decode32u(data, &ts);
        data = ikcp_decode32u(data, &sn);
        data = ikcp_decode32u(data, &una);
        data = ikcp_decode32u(data, &len);

        size -= IKCP_OVERHEAD;

        if ((long)size < (long)len || (int)len < 0) return -2;

        // 数据包类型检查
        if (cmd != IKCP_CMD_PUSH && cmd != IKCP_CMD_ACK &&
            cmd != IKCP_CMD_WASK && cmd != IKCP_CMD_WINS) 
            return -3;

        kcp->rmt_wnd = wnd;

        // 这里的 una 是发送方的 kcp->rcv_nxt，根据这个数据，可以去掉已确认接收的数据包
        ikcp_parse_una(kcp, una);
        // 去掉已确认接收的包后，更新 snd_una 下一个要发送的序号
        ikcp_shrink_buf(kcp);

        if (cmd == IKCP_CMD_ACK) {
            // ack 包
            // ...
        }
        else if (cmd == IKCP_CMD_PUSH) {
            // 数据包
            // 如果接收到的数据包序号 sn，在接收窗口内，则正常处理，否则直接丢弃，等重传
            if (_itimediff(sn, kcp->rcv_nxt + kcp->rcv_wnd) < 0) {

                // 接收到的每个数据包，都要回一个 ack 包，记录下来
                ikcp_ack_push(kcp, sn, ts);

                // 接收的数据调用 ikcp_parse_data 处理
                if (_itimediff(sn, kcp->rcv_nxt) >= 0) {
                    seg = ikcp_segment_new(kcp, len);
                    seg->conv = conv;
                    seg->cmd = cmd;
                    seg->frg = frg;
                    seg->wnd = wnd;
                    seg->ts = ts;
                    seg->sn = sn;
                    seg->una = una;
                    seg->len = len;

                    if (len > 0) {
                        memcpy(seg->data, data, len);
                    }

                    ikcp_parse_data(kcp, seg);
                }
            }
        }
        else if (cmd == IKCP_CMD_WASK) {
            // 查询窗口包
            // ...
        }
        else if (cmd == IKCP_CMD_WINS) {
            // 查询窗口的回复包
            // ...
        }
        else {
            return -3;
        }

        data += len;
        size -= len;
    }

    // 处理快速重传逻辑
    // ...

    // 更新发送窗口
    // ...

    return 0;
}

ikcp_input 循环处理每一个 SEG 包，先检查数据包的合法性和类型，因为每个数据包都会带上 una，存放的是发送端等待接收的包序号，需要小于 una 的包对端都已经接受成功，所以可以把 snd_buff 中需要小于 una 的都删掉，并更新 snd_nxt，这一部分由 ikcp_parse_una 和 ikcp_shrink_buf 来处理。接收到的每个数据包，都需要回复 ACK 包，由 ikcp_ack_push 记录下来，最后调用 ikcp_parse_data 处理数据。

解析数据（点击展开代码）

void ikcp_parse_data(ikcpcb *kcp, IKCPSEG *newseg)
{
    struct IQUEUEHEAD *p, *prev;
    IUINT32 sn = newseg->sn;
    int repeat = 0;

    // 序号检查
    if (_itimediff(sn, kcp->rcv_nxt + kcp->rcv_wnd) >= 0 ||
        _itimediff(sn, kcp->rcv_nxt) < 0) {
        ikcp_segment_delete(kcp, newseg);
        return;
    }

    // 找出 newseg 应该放置的位置，因为接收到的 seg 可能是乱序的
    for (p = kcp->rcv_buf.prev; p != &kcp->rcv_buf; p = prev) {
        IKCPSEG *seg = iqueue_entry(p, IKCPSEG, node);
        prev = p->prev;
        if (seg->sn == sn) {
            // 重复收到
            repeat = 1;
            break;
        }
        if (_itimediff(sn, seg->sn) > 0) {
            break;
        }
    }

    // 把 newseg 放到 rcv_buf 正确的位置上
    if (repeat == 0) {
        iqueue_init(&newseg->node);
        iqueue_add(&newseg->node, p);
        kcp->nrcv_buf++;
    }    else {
        ikcp_segment_delete(kcp, newseg);
    }

    // 把数据从 rcv_buf 移动到 rcv_queue
    while (! iqueue_is_empty(&kcp->rcv_buf)) {
        IKCPSEG *seg = iqueue_entry(kcp->rcv_buf.next, IKCPSEG, node);
        // 如果 seg 序号是等待接收的序号，移动到 rcv_queue
        if (seg->sn == kcp->rcv_nxt && kcp->nrcv_que < kcp->rcv_wnd) {
            iqueue_del(&seg->node);
            kcp->nrcv_buf--;
            iqueue_add_tail(&seg->node, &kcp->rcv_queue);
            kcp->nrcv_que++;
            kcp->rcv_nxt++;
        }    else {
            break;
        }
    }
}

ikcp_parse_data 主要的工作就是把 newseg 放置到 kcp->rcv_buf 合适的位置上，并把数据从 rcv_buf 移动到 rcv_queue。rcv_buf 合适的位置的意思是，rcv_buf 是按照 sn 的递增顺序排列的，newseg 需要根据自己的 sn 大小查找合适的位置。rcv_buf 上的数据要移动到 rcv_queue，条件是 rcv_buf 上的数据包序号，等于 KCP 在等待接收的包序号 kcp->rcv_nxt ，移动一个数据包之后，需要更新 kcp->rvc_nxt，再处理下一个数据包。

ikcp_input 之后，上层调用 ikcp_update 时候会发送 ACK 包，调用 ikcp_recv 会给上层返回有效数据。ikcp_update 和 ikcp_recv 互相独立，没有调用顺序要求，视上层的调用时机而定。我们先来看 ikcp_update 里面有关 ACK 发送的部分：

回复 ACK（点击展开代码）

// 前面说过，ikcp_update 最终是调用 ikcp_flush
void ikcp_flush(ikcpcb *kcp, IUINT32 current)
{
    // ...

    // 回复 ACK 包
    count = kcp->ackcount;
    for (i = 0; i < count; i++) {
        size = (int)(ptr - buffer);
        if (size + (int)IKCP_OVERHEAD > (int)kcp->mtu) {
            ikcp_output(kcp, buffer, size);
            ptr = buffer;
        }
        ikcp_ack_get(kcp, i, &seg.sn, &seg.ts);
        ptr = ikcp_encode_seg(ptr, &seg);
    }

    kcp->ackcount = 0;

    // ...
}

ACK 包的之前已经由 ikcp_ack_push 保存起来了，所以这里只需要 ikcp_ack_get 获取每个 ACK 包的信息，发送给对方。上层可以使用 ikcp_recv 从 KCP 获取数据：

ikcp_recv（点击展开代码）

//---------------------------------------------------------------------
// user/upper level recv: returns size, returns below zero for EAGAIN
//---------------------------------------------------------------------
int ikcp_recv(ikcpcb *kcp, char *buffer, int len)
{
    struct IQUEUEHEAD *p;
    int ispeek = (len < 0)? 1 : 0;
    int peeksize;
    int recover = 0;
    IKCPSEG *seg;
    assert(kcp);

    // 一些有效性检查
    if (iqueue_is_empty(&kcp->rcv_queue))
        return -1;
    if (len < 0) len = -len;

    // 计算能返回的数据长度
    peeksize = ikcp_peeksize(kcp);

    if (peeksize < 0)
        return -2;
    if (peeksize > len)
        return -3;

    // 判断下接收窗口
    if (kcp->nrcv_que >= kcp->rcv_wnd)
        recover = 1;

    // 遍历 rcv_queue，把数据复制到 buffer 上
    for (len = 0, p = kcp->rcv_queue.next; p != &kcp->rcv_queue; ) {
        int fragment;
        seg = iqueue_entry(p, IKCPSEG, node);
        p = p->next;

        if (buffer) {
            memcpy(buffer, seg->data, seg->len);
            buffer += seg->len;
        }

        len += seg->len;

        // 判断分包
        fragment = seg->frg;

        // 移除数据包
        if (ispeek == 0) {
            iqueue_del(&seg->node);
            ikcp_segment_delete(kcp, seg);
            kcp->nrcv_que--;
        }

        // 所有分包都复制完，退出循环
        if (fragment == 0)
            break;
    }

    assert(len == peeksize);

    // rcv_queue 又空了一些，尝试继续从 rcv_buf 移动到 rcv_queue
    while (! iqueue_is_empty(&kcp->rcv_buf)) {
        seg = iqueue_entry(kcp->rcv_buf.next, IKCPSEG, node);
        if (seg->sn == kcp->rcv_nxt && kcp->nrcv_que < kcp->rcv_wnd) {
            iqueue_del(&seg->node);
            kcp->nrcv_buf--;
            iqueue_add_tail(&seg->node, &kcp->rcv_queue);
            kcp->nrcv_que++;
            kcp->rcv_nxt++;
        }    else {
            break;
        }
    }

    return len;
}

ikcp_recv 一次调用只会返回一个完整的数据包，上层可以循环调用直到没有数据返回为止，函数的逻辑比较简单，就是从 rcv_queue 中复制数据到上层传进来的 buffer 里面，至此接收方对于接收到的数据包已经处理完毕。

接收方处理数据包的时候，给发送方发送了 ACK 包，我们再来看看发送方接受 ACK 包的处理：

处理 ACK 包（点击展开代码）

int ikcp_input(ikcpcb *kcp, const char *data, long size)
{
    // ...
    IUINT32 maxack = 0, latest_ts = 0;
    // ...
    while (1) {
        // ...
        // ts 是对端的 kcp-> current
        data = ikcp_decode32u(data, &ts);
        data = ikcp_decode32u(data, &sn);

        if (cmd == IKCP_CMD_ACK) {
            // 更新 rot
            if (_itimediff(kcp->current, ts) >= 0) {
                ikcp_update_ack(kcp, _itimediff(kcp->current, ts));
            }
            // 更新 snd_buf
            ikcp_parse_ack(kcp, sn);
            ikcp_shrink_buf(kcp);

            // maxack = 这次 input 的所有 ACK 包中最大的 sn
            if (flag == 0) {
                flag = 1;
                maxack = sn;
                latest_ts = ts;
            }    else {
                if (_itimediff(sn, maxack) > 0) {
                #ifndef IKCP_FASTACK_CONSERVE
                    maxack = sn;
                    latest_ts = ts;
                #else
                    if (_itimediff(ts, latest_ts) > 0) {
                        maxack = sn;
                        latest_ts = ts;
                    }
                #endif
                }
            }
        }
        // ...
    }

    // 如果有收到 ACK 包，记录用来做快速重传
    if (flag != 0) {
        ikcp_parse_fastack(kcp, maxack, latest_ts);
    }
}

可以看到接收到 ACK 包后同样会需要 ikcp_parse_ack 和 ikcp_shrink_buf 来更新 snd_buf，另外还需要调用 ikcp_update_ack 来计算更新 rto （retransmission timeout，超时重传时间）。ikcp_input 计算收到的 ACK 包中最大序号，来记录做快速重传用。就这样，发送方收到 ACK 包，把发送数据从 snd_buf 中移除，该数据包可靠地送达到了接收方，一次完整的 ARQ 确认接收过程结束。

超时重传

前面介绍的是 KCP 实现的 ARQ 中的确认接收机制，ARQ 还需要一个超时重传来保证可靠性，下面我们来看看 KCP 是怎么做超时重传的。

让我们回到 ikcp_flush 函数：

超时重传（点击展开代码）

void ikcp_flush(ikcpcb *kcp)
{
    // ...
    // 发送 snd_buf
    for (p = kcp->snd_buf.next; p != &kcp->snd_buf; p = p->next) {
        IKCPSEG *segment = iqueue_entry(p, IKCPSEG, node);
        int needsend = 0;
        if (segment->xmit == 0) {
            // 首次发送
            needsend = 1;
            segment->xmit++;
            // 设置 segment->rto
            // 通过 segment->rto 计算 segment->resendts 超时重传时间
            segment->rto = kcp->rx_rto;
            segment->resendts = current + segment->rto + rtomin;
        }
        else if (_itimediff(current, segment->resendts) >= 0) {
            // 超时重传
            needsend = 1;
            segment->xmit++;
            kcp->xmit++;
            // nodelay 控制下一次超时重传时间的计算
            if (kcp->nodelay == 0) {
                segment->rto += kcp->rx_rto;
            }    else {
                segment->rto += kcp->rx_rto / 2;
            }
            segment->resendts = current + segment->rto;
            lost = 1;
        }
        else if (segment->fastack >= resent) {
            // 快速重传
            // ...
        }
        if (needsend) {
            // 发送数据
            // ...
        }
    // ...
}

一旦当前时间 current 大于 segment->resendts 超时重传时间，说明在这段时间内，都没有收到接收方的 ACK 包，触发超时重传机制，needsend = 1，重新发送数据。

有了确认接收和超时重传机制，KCP 就可以保证基础的可靠数据传输了。但是为了能够保持更稳定的数据流速，KCP 还做了更多的事情，下面我们一起看看 KCP 还做了那些优化。

KCP 提升流速的策略

快速重传

发送方发送了序号为 sn 和 sn + 1 两个数据包，如果只收到了 sn + 1 的 ACK 包，那可能是因为 sn 的 ACK 包在网路中还没到达，又或者 ACK 包丢了，又或者 sn 数据包丢了，如果此时还没到超时重传的时间，网络也还不太拥堵，只是因为某种原因而突发丢包，那么发送方主动提前发送 sn 数据包，可以帮助接收方更快地接收数据，提高流速。

KCP 里面也相应实现了快速重传机制，也在 ikcp_flush 里面：

快速重传（点击展开代码）

void ikcp_flush(ikcpcb *kcp)
{
    // ...
    resent = (kcp->fastresend > 0)? (IUINT32)kcp->fastresend : 0xffffffff;

    // 发送 snd_buf
    for (p = kcp->snd_buf.next; p != &kcp->snd_buf; p = p->next) {
        IKCPSEG *segment = iqueue_entry(p, IKCPSEG, node);
        int needsend = 0;
        if (segment->xmit == 0) {
            // ...
        }
        else if (_itimediff(current, segment->resendts) >= 0) {
            // ...
        }
        else if (segment->fastack >= resent) {
            // 快速重传
            if ((int)segment->xmit <= kcp->fastlimit ||
                kcp->fastlimit <= 0) {
                needsend = 1;
                segment->xmit++;
                segment->fastack = 0;
                segment->resendts = current + segment->rto;
                change++;
            }
        }
        if (needsend) {
            // 发送数据
            // ...
        }
    // ...
}

要出发快速重传，有两个条件： * segment->fastack >= resent，resent 是可配置的参数 kcp->fastresend，配置为 0 会关闭快速重传。segment->fastack 是在函数 ikcp_parse_fastack 里面设置的，这个函数是在 ikcp_input 里面调用，会根据 ikcp_input 算出的 maxack 来给所有 sn 小于 maxack 的 segment->fastack 加一，所以 segment->fastack 就是表示收到比 sn 大的包的次数。 * segment->xmit <= kcp->fastlimit || kcp->fastlimit <= 0，setgment->xmit 是发送次数，kcp->fastlimit 是可配置的最大快速重传次数，发送次数需要小于最大快速重传次数

一旦满足快速重传的以上条件，KCP 就会执行快速重传，要注意快速重传并不会重置超时重传时间，原来的超时时间依然会生效。

缩短超时重传时间

超时重传是个很好的机制，但就是太花时间了，按照 TCP 的策略，每次超时重传时间翻倍，等待时间膨胀得很快，在等待时间内，很可能由于接收端的接收窗口已耗尽，无法接收新数据，而等待重传的包序号是在最前面，接收方要接收到重传的包才能把所有数据返回给上层，这种情况，整个网路的流速几乎为 0。KCP 增加了配置可以减缓等待的时间增长，而且也不会是翻倍，通过配置 kcp->nodelay 控制每次等待时间只会增长 1 倍的 RTO 或者 0.5 倍的 RTO，有效减缓等待时间的增长，帮助网路尽快恢复流速。

更新发送窗口

发送窗口表示的是同时传输的数据包数量，窗口越大，同时传输的数据越多，流速越大，但窗口过大，会导致网络拥塞，丢包率上升，数据重传增多，流速下降。所以发送窗口需要根据网络情况不断更新，慢慢趋近最优。 KCP 中关于发送窗口的代码：

发送窗口（点击展开代码）

ikcpcb* ikcp_create(IUINT32 conv, void *user)
{
    // ...
    // snd_wnd，rcv_wnd 发送和接受的缓冲区大小
    kcp->snd_wnd = IKCP_WND_SND;    // 32
    kcp->rcv_wnd = IKCP_WND_RCV;    // 128
    // 对端接收窗口大小              // 128
    kcp->rmt_wnd = IKCP_WND_RCV
    // 发送窗口 cwnd 初始化 0
    kcp->cwnd = 0;
    // 发送窗口字节数大小，参与计算 cwnd
    kcp->incr = 0
    // 慢启动阈值，slow start threshold
    kcp->ssthresh = IKCP_THRESH_INIT;
    // nocwnd 是可配置参数，1 不考虑 cwnd
    kcp->nocwnd = 0;
    // ...
}

void ikcp_flush(ikcpcb *kcp)
{
    // ...
    // 发送数据时先计算 发送窗口大小，是发送缓冲区大小和对方接收窗口大小的小值
    cwnd = _imin_(kcp->snd_wnd, kcp->rmt_wnd);
    // 默认还需要考虑 kcp->cwnd，即是不断更新的发送窗口
    if (kcp->nocwnd == 0) cwnd = _imin_(kcp->cwnd, cwnd);

    // 根据 cwnd 大小，snd_queue 移动到 snd_buf
    while (_itimediff(kcp->snd_nxt, kcp->snd_una + cwnd) < 0) {
    }
    // 发送数据
    resent = (kcp->fastresend > 0)? (IUINT32)kcp->fastresend : 0xffffffff;
    // 触发超时重传 lost = 1
    // 触发快速重传 change++

    // 更新慢启动阈值和发送窗口
    if (change) {
        // 如果有触发快速重传，ssthresh 设置为网络上正在传输的数据包数量的一半
        IUINT32 inflight = kcp->snd_nxt - kcp->snd_una;
        kcp->ssthresh = inflight / 2;
        if (kcp->ssthresh < IKCP_THRESH_MIN)
            kcp->ssthresh = IKCP_THRESH_MIN;

        // 发送窗口为阈值再加上快速重传相关的 resent
        kcp->cwnd = kcp->ssthresh + resent;
        kcp->incr = kcp->cwnd * kcp->mss;
    }

    if (lost) {
        // 如果有超时重传，触发慢启动, ssthresh 阈值为发送窗口的一半
        kcp->ssthresh = cwnd / 2;
        if (kcp->ssthresh < IKCP_THRESH_MIN)
            kcp->ssthresh = IKCP_THRESH_MIN;
        // 发送窗口回到 1，重新慢启动增长
        kcp->cwnd = 1;
        kcp->incr = kcp->mss;
    }

    if (kcp->cwnd < 1) {
        // 因为初始化为 0，来到这里会再设置成 1
        kcp->cwnd = 1;
        kcp->incr = kcp->mss;
    }
}

int ikcp_input(ikcpcb *kcp, const char *data, long size)
{
    IUINT32 prev_una = kcp->snd_una;
    // 处理接收的数据

    while (1) {
        // ...
        data = ikcp_decode16u(data, &wnd)
        // rmt_wnd 是对方的接收窗口大小
        kcp->rmt_wnd = wnd
        // ...
        // 处理数据
    }

    // 最后更新发送窗口
    // kcp->snd_una - prev_una > 0，表示本次 input 有接受到 ACK 并且发送缓冲 snd_buf 有变化
    if (_itimediff(kcp->snd_una, prev_una) > 0) {
        // 再判断对方的接收窗口
        if (kcp->cwnd < kcp->rmt_wnd) {
            IUINT32 mss = kcp->mss;

            if (kcp->cwnd < kcp->ssthresh) {
                // 小于慢启动阈值，双倍增长
                kcp->cwnd++;
                kcp->incr += mss;

            }    else {
                // 大于慢启动阈值之后，通过公式更新 incr ，进而计算 cwnd
                if (kcp->incr < mss) kcp->incr = mss;
                kcp->incr += (mss * mss) / kcp->incr + (mss / 16);
                if ((kcp->cwnd + 1) * mss <= kcp->incr) {
                    kcp->cwnd++;
                }
            }
            // 更新出来的值还要再比较下 rmt_wnd
            if (kcp->cwnd > kcp->rmt_wnd) {
                kcp->cwnd = kcp->rmt_wnd;
                kcp->incr = kcp->rmt_wnd * mss;
            }
        }
    }
}

计算发送窗口 kcp->cwnd 的大小涉及的代码片段会稍微多一些，因为在发送和接收数据的时候，都会需要更新。kcp->cwnd 初始化为 0，之后会在第一次调用 ikcp_flush 的时候，判断小于 1 ，便修改成 1。之后发送方根据发送窗口大小，发送出相应数量的数据包，等待 ACK 回复包。ACK 包在 kcp->input 中进行处理，kcp->input 中如果判断有 ACK 包，并有清除发送缓冲中的发送数据包，说明有数据包已经完成送达，kcp->cwnd++。实际上很可能是一次 kcp->input 只处理到一个 ACK 包，可以理解为，每收到一个 ACK 包都会有 kcp->cwnd++，这句自增实现的是翻倍的效果，譬如当前 kcp->cwnd = 2，发送两个数据包，收到两个 ACK 包，触发了两次自增，最后就是 kcp->cwnd = 4 翻倍。

cwnd 可以一直指数增长，直到超过慢启动阈值，或者发生拥堵超时重传，快速重传的情况。发生了超时重传之后，会触发慢启动，慢启动阈值 ssthresh = kcp->cwnd / 2，发送窗口 kcp->cwnd = 1，回到最初重新指数增长。如果发生了快速重传，KCP 先提前减少 ssthresh，也即是减少了 cwnd 指数增长的空间，降低增长速度，提前减缓拥堵的情况。

KCP 还增加了一个配置 nocwnd，当 nocwnd = 1，发送数据是不再考虑发送窗口大小，直接让最大能发送的数量发送数据包，满足高速模式下的要求。

小结

本文简单地分析了 KCP 的源码，并讨论了 KCP 上 ARQ 的实现，和一些 KCP 提升流速的策略。还有很多细节没有提到，感兴趣的可以自己翻 KCP 的源码对照着看，相信也能有不少的收获。

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

编写 Windows 下的 Memory Leak Detector

Thu, 30 Nov 2023 20:09:36 +0000

前言

这一阵子读完了《程序员的自我修养：链接、装载与库》（后面简称《链接》），收获良多，寻思着能不能做些相关的小代码出来。刚好知道 Windows 下有个内存泄露检测工具 Visual Leak Detector，这个工具是通过替换 Windows 下负责内存管理的 dll 接口来实现跟踪内存分配释放。所以决定参考 Visual Leak Detector （后面简称 VLD）来做个简易的内存泄露检测工具，理解 dll 链接。

预备知识

《链接》一书详细解释了在 Linux 和 Windows 下可执行文件的链接原理，其中 Windows 下的可执行文件格式叫做 PE（Portable Executable）文件。而 DLL 文件的解释是这样的：

DLL 即动态链接库（Dynamic-Link Library）的缩写，它相当于 Linux 下的共享对象。Windows 系统中大量采用了这种 DLL 机制，甚至包括 Windows 的内核的结构都很大程度依赖于 DLL 机制。Windows 下的 DLL 文件和 EXE 文件实际上是一个概念，它们都是有 PE 格式的二进制文件，稍微有些不同的是 PE 文件头部中有个符号位表示该文件是 EXE 或是 DLL，而 DLL 文件的扩展名不一定是 .dll，也有可能是别的比如 .ocx（OCX控件）或是 .CPL（控制面板程序）。

还有比如 Python 的扩展文件 .pyd。而 DLL 中有关我们这里内存泄露检测的概念是符号导出导入表。

符号导出表

当一个 PE 需要将一些函数或变量提供给其他 PE 文件使用时，我们把这种行为叫做符号导出（Symbol Exporting）

简单地理解，在 Windows PE 中，所有导出的符号被集中存放在被称作导出表（Export Table）的结构中，它提供了一个符号名与符号地址的映射关系。需要导出的符号需要加上修饰符__declspec(dllexport)。

符号导入表

符号导入表就是我们这里的关键概念，它跟符号导出表相对应，先来看概念解释：

如果我们在某个程序中使用到了来自 DLL 的函数或者变量，那么我们就把这种行为叫做符号导入（Symbol Importing）。

Windows PE 中保存模块需要导入的变量和函数的符号以及所在的模块等信息的结构叫做导入表（Import Table）。Windows 加载 PE 文件时，其中一个要做的事情就是将所有需要导入的函数地址确定并将导入表中的元素调整到正确的地址，使得运行时候，程序通过查询导入表来定位实际函数的地址，并进行调用。导入表中最重要的结构是导入地址数组（Import Address Table，IAT），里面存放的就是导入的函数实际地址。

看到这里是不是已经猜到我们要实现的内存泄露检测是怎么做 :)。没错就是 hack 导入表，具体地说就是把需要检测的模块的导入表中，关于内存申请和释放的函数的地址改成我们自定义的函数，那么我们就可以知道模块每一次的内存申请和释放情况了，可以尽情做我们想做的检测。

有关 DLL 链接的更详细知识可以自行查阅《链接》或者其他资料。

Memory Leak Detector

知道了原理，下面就是根据原理来实现内存泄露检测。下面的讲解将基于我自己的实现，我放在了我的 Github 上：LeakDetector。

替换函数

先来看关键的函数，位于RealDetector.cpp：

/* 把 importModule 中的 IAT (Import Address Table) 的某个函数替换成别的函数，
 * importModule 会调用到别的 module 的函数，这个函数就是需要 patch 的函数，
 * 我们要做的就是让 import module 改成调用我们自定义的函数。
 *
 * - importModule (IN): 要处理的 module，这个 module 调用到别的 module 的需要 patch 的函数
 *
 * - exportModuleName (IN): 需要 patch 的函数来自的 module 名字
 *
 * - exportModulePath (IN): export module 所在的路径，首先尝试用 path 来加载 export module，
 *          如果失败，则用 name 来加载
 * - importName (IN): 函数名
 *
 * - replacement (IN): 替代的函数指针
 *
 * Return Valur: 成功 true，否则 false
*/
bool RealDetector::patchImport(
    HMODULE importModule,
    LPCSTR exportModuleName,
    LPCSTR exportModulePath,
    LPCSTR importName,
    LPCVOID replacement)
{
    HMODULE                  exportmodule;
    IMAGE_THUNK_DATA        *iate;
    IMAGE_IMPORT_DESCRIPTOR *idte;
    FARPROC                  import;
    DWORD                    protect;
    IMAGE_SECTION_HEADER    *section;
    ULONG                    size;

    assert(exportModuleName != NULL);

    idte = (IMAGE_IMPORT_DESCRIPTOR*)ImageDirectoryEntryToDataEx((PVOID)importModule, 
        TRUE, IMAGE_DIRECTORY_ENTRY_IMPORT, &size, &section);
    if (idte == NULL) 
    {
        logMessage("patchImport failed: idte == NULL\n");
        return false;
    }
    while (idte->FirstThunk != 0x0) 
    {
        if (strcmp((PCHAR)R2VA(importModule, idte->Name), exportModuleName) == 0) 
        {
            break;
        }
        idte++;
    }
    if (idte->FirstThunk == 0x0) 
    {
        logMessage("patchImport failed: idte->FirstThunk == 0x0\n");
        return false;
    }

    if (exportModulePath != NULL) 
    {
        exportmodule = GetModuleHandleA(exportModulePath);
    }
    else 
    {
        exportmodule = GetModuleHandleA(exportModuleName);
    }
    assert(exportmodule != NULL);
    import = GetProcAddress(exportmodule, importName);
    assert(import != NULL);

    iate = (IMAGE_THUNK_DATA*)R2VA(importModule, idte->FirstThunk);
    while (iate->u1.Function != 0x0) 
    {
        if (iate->u1.Function == (DWORD_PTR)import) 
        {
            VirtualProtect(&iate->u1.Function, sizeof(iate->u1.Function), 
                PAGE_READWRITE, &protect);
            iate->u1.Function = (DWORD_PTR)replacement;
            VirtualProtect(&iate->u1.Function, sizeof(iate->u1.Function), 
                protect, &protect);
            return true;
        }
        iate++;
    }

    return false;
}

我们来分析一下这个函数，就像注释所说的，这个函数实现的功能就是把 IAT 里面的某函数的地址改成另一个函数的地址。先来看第 34-35 行：

idte = (IMAGE_IMPORT_DESCRIPTOR*)ImageDirectoryEntryToDataEx((PVOID)importModule, 
    TRUE, IMAGE_DIRECTORY_ENTRY_IMPORT, &size, &section);

ImageDirectoryEntryToDataEx 函数可以返回模块的文件头的某结构的地址，IMAGE_DIRECTORY_ENTRY_IMPORT 指定要导入表结构，所以返回的 idte 就指向了模块导入表了。

36-40 行就是检查 idte 有效。41 行 idte->FirstThunk 指向的就是实际的 IAT 了。所以 41-48 行就是在根据模块名字查找需要替换的函数的模块，如果找不到，说明没有调用到该模块的函数，只能提示错误并返回。

找到模块后，自然地，我们需要找到替换的那个函数，55-62 行打开函数所属的模块，64 行找到函数地址。因为 IAT 没有保存名字，所以需要先根据原来的函数地址，定位到函数，再修改该函数地址，68-80 行就是在做这个事情。成功找到函数之后，就简单地把地址修改成 replacement 的地址。

至此，我们就成功地替换了 IAT 中的函数了。

模块和函数名字

虽然我们已经实现了替换 IAT 函数 patchImport，但这个函数需要指定模块名字和函数名字呀，那我们怎么知道程序的内存分配和释放用了什么模块和函数呢？为了搞清楚这个问题，我们需要借助 Windows 下的工具 Dependency Walker。Visual Studio 下新建一个工程，在 main 函数里面使用 new 来申请内存，编译 Debug 版，之后使用 depends.exe 来打开编译出来的 exe 文件，可以看到一下类似的界面（以我的工程 LeakDetectorTest 为例）：

可以看到 LeakDetectorTest.exe 使用了 uscrtbased.dll 里面的 malloc 和 _free_dbg （没有在图中显示出来），这两个函数就是我们需要替换的函数了。要注意实际的模块函数名字可能跟你的 Windows 和 Visual Studio 版本有关，我的是 Windows 10 和 Visual Studio 2015，你需要做的就是用 depends.exe 看看实际调用的是什么函数。

分析调用栈

记录内存分配需要记录当时的调用栈信息，这里我不打算详细介绍 Windows 下如何拿到当前的调用栈信息，相关的函数是 RtlCaptureStackBackTrace，网上有许多相关的资料，也可以看看我的代码里面的函数 printTrace 。

检测内存泄露

至此，我们已经把龙珠都收集全了，下面正式召唤神龙。

我想做成可以局部检测内存泄露（这是跟 VLD 不同的地方，VLD 做的是全局的检测，并支持多线程）。所以我在实际替换函数的类RealDetector上又封装了一层LeakDetector，并把LeakDetector的接口暴露给使用者。使用时只需构造LeakDetector，即完成函数的替换并开始检测内存泄露，LeakDetector析构时会恢复原来的函数，中止内存泄露检测，并打印内存泄露检测结果。

用下面代码测试一下：

#include "LeakDetector.h"
#include <iostream>
using namespace std;

void new_some_mem()
{
    char* c = new char[12];
    int* i = new int[4];
}

int main()
{
    auto ld = LDTools::LeakDetector("LeakDetectorTest.exe");
    new_some_mem();
    return 0;
}

代码直接 new 了一些内存出来，没有释放掉就直接退出，程序打印的结果：

============== LeakDetector::start ===============
LeakDetector init success.
============== LeakDetector::stop ================
Memory Leak Detected: total 2

Num 1:
    e:\program\github\leakdetector\leakdetector\realdetector.cpp (109): LeakDetector.dll!LDTools::RealDetector::_malloc() + 0x1c bytes
    f:\dd\vctools\crt\vcstartup\src\heap\new_scalar.cpp (19): LeakDetectorTest.exe!operator new() + 0x9 bytes
    f:\dd\vctools\crt\vcstartup\src\heap\new_array.cpp (15): LeakDetectorTest.exe!operator new[]() + 0x9 bytes
    e:\program\github\leakdetector\leakdetectortest\leakdetectortest.cpp (12): LeakDetectorTest.exe!new_some_mem() + 0x7 bytes
    e:\program\github\leakdetector\leakdetectortest\leakdetectortest.cpp (19): LeakDetectorTest.exe!main()
    f:\dd\vctools\crt\vcstartup\src\startup\exe_common.inl (74): LeakDetectorTest.exe!invoke_main() + 0x1b bytes
    f:\dd\vctools\crt\vcstartup\src\startup\exe_common.inl (264): LeakDetectorTest.exe!__scrt_common_main_seh() + 0x5 bytes
    f:\dd\vctools\crt\vcstartup\src\startup\exe_common.inl (309): LeakDetectorTest.exe!__scrt_common_main()
    f:\dd\vctools\crt\vcstartup\src\startup\exe_main.cpp (17): LeakDetectorTest.exe!mainCRTStartup()
    KERNEL32.DLL!BaseThreadInitThunk() + 0x24 bytes
    ntdll.dll!RtlUnicodeStringToInteger() + 0x253 bytes
    ntdll.dll!RtlUnicodeStringToInteger() + 0x21e bytes

Num 2:
    e:\program\github\leakdetector\leakdetector\realdetector.cpp (109): LeakDetector.dll!LDTools::RealDetector::_malloc() + 0x1c bytes
    f:\dd\vctools\crt\vcstartup\src\heap\new_scalar.cpp (19): LeakDetectorTest.exe!operator new() + 0x9 bytes
    f:\dd\vctools\crt\vcstartup\src\heap\new_array.cpp (15): LeakDetectorTest.exe!operator new[]() + 0x9 bytes
    e:\program\github\leakdetector\leakdetectortest\leakdetectortest.cpp (11): LeakDetectorTest.exe!new_some_mem() + 0x7 bytes
    e:\program\github\leakdetector\leakdetectortest\leakdetectortest.cpp (19): LeakDetectorTest.exe!main()
    f:\dd\vctools\crt\vcstartup\src\startup\exe_common.inl (74): LeakDetectorTest.exe!invoke_main() + 0x1b bytes
    f:\dd\vctools\crt\vcstartup\src\startup\exe_common.inl (264): LeakDetectorTest.exe!__scrt_common_main_seh() + 0x5 bytes
    f:\dd\vctools\crt\vcstartup\src\startup\exe_common.inl (309): LeakDetectorTest.exe!__scrt_common_main()
    f:\dd\vctools\crt\vcstartup\src\startup\exe_main.cpp (17): LeakDetectorTest.exe!mainCRTStartup()
    KERNEL32.DLL!BaseThreadInitThunk() + 0x24 bytes
    ntdll.dll!RtlUnicodeStringToInteger() + 0x253 bytes
    ntdll.dll!RtlUnicodeStringToInteger() + 0x21e bytes

程序正确地找出有两个地方申请的内存没有释放，并且打印出了完整的调用栈信息，我们需要的功能至此已经完成了。

结语

当你还不了解程序链接、装载与库的时候，你可能会对如何找到共享链接库的函数一头雾水，更不要说要把链接库的函数替换成我们自己的函数了。这里就以检测内存泄露为例子，探讨下了如何替换 Windows DLL 的函数，更详细的实现可以参考 VLD 的源码。

另外想说的是，《程序员的自我修养：链接、装载与库》真是本不错的书呢，纯感慨非软广。

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Python 杂谈 1 - 探究 builtins

Thu, 30 Nov 2023 20:09:36 +0000

引子

我们知道，__builtins__ 本身是在全局命名空间中就有的一个对象，是 Python 故意暴露出来给代码层的，在代码的任意地方都可以直接使用。但是有点冷的知识是，__builtins__ 在 main 模块（也就是 __main__，指的都是同一个模块，后文可能会混用）里面是 __builtin__ 这个模块，但在其他模块里面，它表示的是 __builtin__.__dict__，这就有点让人莫名其妙了。虽然官方不推荐直接使用 __builtins__，但你给我搞两种情况是怎么回事？本文我们就来盘一盘这个设定的由来，在这个过程中，我们还可以找到这些问题的答案：__builtin__ 跟 __builtins__ 有什么区别？__builtins__ 在 main 模块跟其他模块为什么会设定成不同？__builtins__ 是在哪里定义的？

`builtin`

在探讨 __builtins__ 之前，我们需要先看看 __builtin__ 是什么。__builtin__ 是存放所有内建对象的模块，我们平常可以直接使用的 Python 内建对象，本质上都是 __builtin__ 模块里的对象，即放在 __builtin__.__dict__ 里，对应着的是 Python 的内建名字空间。记住这个关键知识点：__buintin__ 是一个模块 module。我们可以在 Python 源码中找到 __builtin__ 模块的定义和使用（注意，下文提到的 Python 源码，都是指 CPython-2.7.18 源码）：

// pythonrun.c
void
Py_InitializeEx(int install_sigs)
{
    PyInterpreterState *interp;
    ...
    // 初始化 __builtin__
    bimod = _PyBuiltin_Init();
    // interp->builtins = __builtin__.__dict__
    interp->builtins = PyModule_GetDict(bimod);
    ...
}

// bltinmodule.c
PyObject *
_PyBuiltin_Init(void)
{
    PyObject *mod, *dict, *debug;
    mod = Py_InitModule4("__builtin__", builtin_methods,
                         builtin_doc, (PyObject *)NULL,
                         PYTHON_API_VERSION);
    if (mod == NULL)
        return NULL;
    dict = PyModule_GetDict(mod);

    // 给 dict 加上内建的对象
    ...
}

// ceval.c
// 获取 builtins
PyObject *
PyEval_GetBuiltins(void)
{
    PyFrameObject *current_frame = PyEval_GetFrame();
    if (current_frame == NULL)
        return PyThreadState_GET()->interp->builtins;
    else
        return current_frame->f_builtins;
}

Python 初始化的时候会调用 _PyBuiltin_Init 来创建 __builtin__ 模块，并在里面添加上内建的对象，解释器本身会引用住 interp->builtins = __buintin__.__dict__，当前执行的栈帧结构同时也会引用一份 current_frame->f_builtins。那么很自然地，当执行代码需要根据名字寻找对象的时候，Python 会去 current_frame->f_builtins 里面来找，自然就能拿到所有的内建对象：

// ceval.c
TARGET(LOAD_NAME)
{
    // 先在 f->f_locals 名字空间里面找
    ...
    if (x == NULL) {
        // 再找找全局空间
        x = PyDict_GetItem(f->f_globals, w);
        if (x == NULL) {
            // 这里就去内建空间找
            x = PyDict_GetItem(f->f_builtins, w);
            if (x == NULL) {
                format_exc_check_arg(
                            PyExc_NameError,
                            NAME_ERROR_MSG, w);
                break;
            }
        }
        Py_INCREF(x);
    }
    PUSH(x);
    DISPATCH();
}

最后，由于 __builtin__ 这个名字实在是太有迷惑性了，Python3 中已经改名为 builtins。

`builtins`

__builtins__ 的表现是有点奇怪的： * 在 main 模块中（main 模块，或者叫最高层级代码运行所在环境，是用户指定最先启动运行的 Python 模块，也就是通常我们在命令行执行 python xxx.py 时，xxx.py 这个模块），__builtins__ = __builtin__； * 在其他模块中 __builtins__ = __builtin__.__dict__。

相同的名字，但在不同的模块下表现却是不相同的，这样的设定很容易让人疑惑。不过只要知道这个设定，就足够支持你在 Python 中使用 __builtins__，疑惑并不会影响你写出足够安全的代码，诸如：

def SetBuiltins(builtins, key, val):
    if isinstance(builtins, dict):
        builtins[key] = val
    else:
        setattr(builtins, key, val)

SetBuiltins(__builtins__, 'test', 1)

需要注意，其实并不建议使用 __builtins__：

CPython implementation detail: Users should not touch __builtins__; it is strictly an implementation detail. Users wanting to override values in the builtins namespace should import the __builtin__ (no ‘s’) module and modify its attributes appropriately.

当然，这样的疑惑，总有一天会让你心痒难耐，我这里就决定继续探究下去，也因为这样，才有了这篇文章。我们下面的内容会深入到 CPython implementation detail 中去。

Restricted Execution

Restricted Execution 可以理解为有限制地执行不安全的代码，所谓有限制，可以是限制网络、io 等等，把代码限制在一定的执行环境中，控制代码的执行权限，防止代码影响到外部的环境和系统。常见的用例就是一些在线代码执行网站，譬如这个：pythonsandbox。

跟你猜想的一样，Python 对 __builtins__ 的设定是跟 Restricted Execution 有关。Python 在 2.3 版本之前，曾经提供过类似的功能 Restricted Execution，只是由于后来被证实为不可行的，只好把这个功能作废了，但代码在 2.7.18 版本还保留着，所以我们可以来考古。

首先来看 Python 源码里面对 __builtins__ 的设置：

// pythonrun.c
static void initmain(void)
{
    PyObject *m, *d;
    // 获取 __main__ 模块
    m = PyImport_AddModule("__main__");
    if (m == NULL)
        Py_FatalError("can't create __main__ module");

    // d = __main__.__dict__
    d = PyModule_GetDict(m);

    // 设置 __main__.__dict__['__builtins__']，如果已有，则跳过
    if (PyDict_GetItemString(d, "__builtins__") == NULL) {
        PyObject *bimod = PyImport_ImportModule("__builtin__");
        if (bimod == NULL ||
            PyDict_SetItemString(d, "__builtins__", bimod) != 0)
            Py_FatalError("can't add __builtins__ to __main__");
        Py_XDECREF(bimod);
    }
}

在 initmain 中，Python 会给 __main__ 模块设置 __builtins__ 属性，默认等于 __builtin__ 模块，但如果已有，则跳过不会重新设置。利用这个特点，我们就可以通过修改 __main__.__builtins__ 来修改内建的一些功能，以达到限制代码执行权限的目的，具体的方法先按下不表，我们看看 __builtins__ 是怎么被传递的。

`builtins` 的传递

在创建新的栈帧的时候：

PyFrameObject *
PyFrame_New(PyThreadState *tstate, PyCodeObject *code, PyObject *globals,
            PyObject *locals)
{
    ...
    if (back == NULL || back->f_globals != globals) {
        // 取 globals['__builtins__'] 作为新栈帧的 __builtins__
        // builtin_object 就是字符串 '__builtins__'
        builtins = PyDict_GetItem(globals, builtin_object);
        if (builtins) {
            if (PyModule_Check(builtins)) {
                builtins = PyModule_GetDict(builtins);
                assert(!builtins || PyDict_Check(builtins));
            }
            else if (!PyDict_Check(builtins))
                builtins = NULL;
        }
        ...

    }
    else {
        /* If we share the globals, we share the builtins.
           Save a lookup and a call. */
        // 或者直接继承上一层栈帧的 f_builtins
        builtins = back->f_builtins;
        assert(builtins != NULL && PyDict_Check(builtins));
        Py_INCREF(builtins);
    }
    ...
    f->f_builtins = builtins;
    f->f_globals = globals;
}

创建新的栈帧时，对于 __builtins__ 的处理主要有两种情况：一种是没有上层栈帧的情况下，取 globals['__builtins__']；另一种是直接取上层栈帧的 f_builtins。联合起来看的话，可以理解为，一般情况下，在 __main__ 中设置好的 __builtins__，会一直继承给后面的栈帧，相当于共用同一份。

import 模块时：

static PyObject *
load_compiled_module(char *name, char *cpathname, FILE *fp)
{
    long magic;
    PyCodeObject *co;
    PyObject *m;
    ...
    co = read_compiled_module(cpathname, fp);
    ...
    m = PyImport_ExecCodeModuleEx(name, (PyObject *)co, cpathname);
    ...
}


PyObject *
PyImport_ExecCodeModuleEx(char *name, PyObject *co, char *pathname)
{
    ...
    m = PyImport_AddModule(name);
    ...
    // d = m.__dict__
    d = PyModule_GetDict(m);

    // 在这里设置新加载模块的 __builtins__ 属性
    if (PyDict_GetItemString(d, "__builtins__") == NULL) {
        if (PyDict_SetItemString(d, "__builtins__",
                                 PyEval_GetBuiltins()) != 0)
            goto error;
    }
    ...
    // globals = d, locals = d
    v = PyEval_EvalCode((PyCodeObject *)co, d, d);
    ...
}

PyObject *
PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals)
{
    return PyEval_EvalCodeEx(co,
                      globals, locals,
                      (PyObject **)NULL, 0,
                      (PyObject **)NULL, 0,
                      (PyObject **)NULL, 0,
                      NULL);
}

import 其他模块的时候，会把该模块的 __builtins__ 设置为 PyEval_GetBuiltins() 的返回结果，这个函数我们已经说过，大部分情况下相当于 current_frame->f_builtins。对于 __main__ 模块的里面的 import，current_frame 就是 __main__ 模块的栈帧，current_frame->f_builtins = __main__.__dict__['__builtins__']（上文 PyFrame_New 的第一种情况）。

加载的新模块，会使用 PyEval_EvalCode 来执行新模块中的代码，可以看到，传给 PyEval_EvalCode 的参数 globals、locals 其实都是模块自身的 __dict__，并且模块 m.__dict__['__builtins__'] = PyEval_GetBuiltins() 。

综合来看，我们可以得知，从 __main__ 模块开始 import 的模块，也会继承 __main__ 中的 __builtins__，并会在内部的 import 中传递下去，这样就可以确保，所有从 __main__ 加载的模块和子模块，都能共用同一份来自 __main__ 的 __builtins__。

那么如果是在模块中调用的函数呢？对于模块中的函数，创建和调用时：

// ceval.c
// 创建函数
TARGET(MAKE_FUNCTION)
{
    v = POP(); /* code object */

    // 这里的 f->f_globals，相当于模块自身的 globals，由上文可知，也相当于 m.__dict__
    x = PyFunction_New(v, f->f_globals);
    ...
}

PyObject *
PyFunction_New(PyObject *code, PyObject *globals)
{
    PyFunctionObject *op = PyObject_GC_New(PyFunctionObject,
                                        &PyFunction_Type);
    ...
    // 这里相当于 op->func_globals = globals = f->f_globals
    op->func_globals = globals;
}

// 调用函数
static PyObject *
fast_function(PyObject *func, PyObject ***pp_stack, int n, int na, int nk)
{
    PyCodeObject *co = (PyCodeObject *)PyFunction_GET_CODE(func);
    // globals = func->func_globals
    PyObject *globals = PyFunction_GET_GLOBALS(func);
    ...
    // globals 传给 PyEval_EvalCodeEx，里面就会传给 PyFrame_New 来创建新的栈帧
    return PyEval_EvalCodeEx(co, globals,
                             (PyObject *)NULL, (*pp_stack)-n, na,
                             (*pp_stack)-2*nk, nk, d, nd,
                             PyFunction_GET_CLOSURE(func));
}

创建函数时，会把 f->f_globals 存到函数结构体变量 func_globals 里面，而对于模块 m，f->f_globals = m.__dict__。函数执行的时候，传给 PyFrame_New 的 globals 参数，就是创建时候保存起来的 func_globals，__builtins__ 自然就可以在 func_globals 中获取。

至此，__builtins__ 的传递是能保证一致性的，所有模块、子模块、函数，栈帧等都能引用到同一个，也就是拥有相同的内建名字空间。

指定 `main` 模块执行

我们已经知道 __main__ 模块自身的 __builtins__ 可以传递给所有子模块、函数和栈帧，而在命令行执行 python a.py 时，Python 会把 a.py 作为 __main__ 模块来执行，那这是如何做到的呢：

// python.c
int
main(int argc, char **argv)
{
    ...
    return Py_Main(argc, argv);
}

// main.c
int
Py_Main(int argc, char **argv)
{
    ...
    // 尝试用模块的 importer 来执行代码
    if (filename != NULL) {
        sts = RunMainFromImporter(filename);
    }
    ...
    // 一般我们自己的 py 文件，会使用这个来执行
    sts = PyRun_AnyFileExFlags(
            fp,
            filename == NULL ? "<stdin>" : filename,
            filename != NULL, &cf) != 0;
    }
    ...
}

// pythonrun.c
int
PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit,
                     PyCompilerFlags *flags)
{
    ...
    return PyRun_SimpleFileExFlags(fp, filename, closeit, flags);
}


int
PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit,
                        PyCompilerFlags *flags)
{
    ...
    m = PyImport_AddModule("__main__");
    d = PyModule_GetDict(m);
    ...
    // 设置 __file__ 属性
    if (PyDict_SetItemString(d, "__file__", f) < 0) {
        ...
    }
    ...
    // globals = locals = d = __main__.__dict__
    v = run_pyc_file(fp, filename, d, d, flags);
    ...
}

static PyObject *
run_pyc_file(FILE *fp, const char *filename, PyObject *globals,
             PyObject *locals, PyCompilerFlags *flags)
{
    ...
    // 从 pyc 文件读取代码对象 co ，并执行代码
    // PyEval_EvalCode 里面也同样会调用 PyFrame_New 创建新栈帧
    v = PyEval_EvalCode(co, globals, locals);
    ...
}

当执行 python a.py 时，一般情况下会走到 PyRun_SimpleFileExFlags，PyRun_SimpleFileExFlags 里面会取出来 __main__.__dict__，作为代码执行时的 globals 和 locals，最终也会传到 PyFrame_New 中创建新的栈帧来执行 a.py。结合我们上文提到的 __builtins__ 在模块和函数中传递，就可以让后续执行的代码都能共用同一份 current_frame->f_builtins = __main__.__builtins__.__dict__。

再论 Restricted Execution

Python 在 2.3 版本之前，曾经提供过的 Restricted Execution，就是基于 __builtins__ 的特性来制作的。或者可以认为，__builtins__ 之所以设计成在 __main__ 模块中是一个模块对象，而在其他模块中是一个 dict 对象，就是为了可以实现 Restricted Execution。

考虑这种情况：如果我们可以自由定制自己的 __builtin__ 模块，并设置成 __main__.__builtins__，那就相当于后续所有执行的代码，都会使用我们定制的模块，我们可以定制特定版本的 open、__import__、file 等内建函数和类型，更进一步，这种方式是不是可以帮助我们限制执行代码的权限，防止代码做一些不安全的函数调用，或者访问一些不安全的文件？

Python 当时就做过这种尝试，实现这个功能的模块就叫做: rexec。

`rexec`

我无意太深入讲解 rexec 的实现，因为原理其实上文已经讲清楚了，并且这个模块本身就已经废弃，我这些仅简单做一些关键代码的摘要，方便查阅。

# rexec.py
class RExec(ihooks._Verbose):
    ...
    nok_builtin_names = ('open', 'file', 'reload', '__import__')

    def __init__(self, hooks = None, verbose = 0):
        ...
        self.modules = {}
        ...
        self.make_builtin()
        self.make_initial_modules()
        self.make_sys()
        self.loader = RModuleLoader(self.hooks, verbose)
        self.importer = RModuleImporter(self.loader, verbose)

    def make_builtin(self):
        m = self.copy_except(__builtin__, self.nok_builtin_names)
        m.__import__ = self.r_import
        m.reload = self.r_reload
        m.open = m.file = self.r_open

    def add_module(self, mname):
        m = self.modules.get(mname)
        if m is None:
            self.modules[mname] = m = self.hooks.new_module(mname)
        m.__builtins__ = self.modules['__builtin__']
        return m

    def r_exec(self, code):
        m = self.add_module('__main__')
        exec code in m.__dict__

    def r_eval(self, code):
        m = self.add_module('__main__')
        return eval(code, m.__dict__)

    def r_execfile(self, file):
        m = self.add_module('__main__')
        execfile(file, m.__dict__)

r_execfile 函数会把文件当作 __main__ 模块来执行，只是 __main__ 是定制过的。self.add_module('__main__') 里面，会设置模块的 m.__builtins__ = self.modules['__builtin__']，这个 __builtin__ 是由 make_builtin 来定制生成的，在里面替换了 __import__、reload、open 函数，并删除了 file 类型。这样，我们就能控制要执行的代码对内建命名空间的访问了。

对于一些内建模块，rexec 也做了定制，保护不安全的访问，譬如 sys 模块，只保留了一部分的对象，并且通过定制的 self.loader、self.importer，来实现 import 的时候，优先加载定制的模块。

如果对代码细节感兴趣，请自行查阅相关源码。

`rexec` 的失败

上文提到，Python 2.3 之后，rexec 就已经废弃了，因为这种方式已经被证实为不可行。带着好奇心，我们来简单溯源一下：

在社区有人报告了 Bug，并引发了开发者之间的讨论：

it's never going to be safe, and I doubt it's very useful as long as it's not safe.

Every change is a potential security hole.

it's hard to predict what change is going to break it.

I don't expect you'll ever reach the point where it'll be wise to advertise this as safe. I certainly won't.

this is only a useful occupation if you expect to eventually reach a point where you expect that there aren't any security flaws left. Jeremy & I both doubt that Python will ever reach that level, meaning that the whole exercise of fixing security flaws is a waste of time (if you know you can't make it safe, don't waste time trying).

I agree (but I have said that in past) the best thing is to deprecate/rip out rexec.

The code will still be in older versions if someone decides to pick it up and work on it as a separate project.

该 Bug 的起因是 Python 引入了新式类（new-style class） object，导致 rexec 不能正常工作。于是开发者表示，在可预见的未来，这种情况都很难避免，任意的修改都会可能导致 rexec 出现漏洞，不能正常工作，或者被突破权限的限制，基本上无法实现没有漏洞地去提供一个安全环境的愿景，开发者需要不断地修修补补，浪费大量的时间。最终，rexec 这个模块就被废弃掉了，Python 也没有再提供类似的功能。但关于 __builtins__ 的设定，由于兼容性等问题，就继续保留下来了。

后面在大概 2010 年的时候，有位程序员推出了 pysandbox，致力于提供可以替代 rexec 的 Python 沙盒环境。但是 3 年后，作者主动放弃了这个项目，并详细说明了为什么作者认为这个项目是失败的：The pysandbox project is broken，也有其他作者撰文总结了这个项目的失败：The failure of pysandbox。如果感兴趣的话，可以具体去翻翻原文，我这里也给一些摘要来帮助了解：

After having work during 3 years on a pysandbox project to sandbox untrusted code, I now reached a point where I am convinced that pysandbox is broken by design. Different developers tried to convinced me before that pysandbox design is unsafe, but I had to experience it myself to be convineced.

I now agree that putting a sandbox in CPython is the wrong design. There are too many ways to escape the untrusted namespace using the various introspection features of the Python language. To guarantee the [safety] of a security product, the code should be [carefully] audited and the code to review must be as small as possible. Using pysandbox, the "code" is the whole Python core which is a really huge code base. For example, the Python and Objects directories of Python 3.4 contain more than 126,000 lines of C code.

The security of pysandbox is the security of its weakest part. A single bug is enough to escape the whole sandbox.

pysandbox cannot be used in practice. To protect the untrusted namespace, pysandbox installs a lot of different protections. Because of all these protections, it becomes hard to write Python code. Basic features like "del dict[key]" are denied. Passing an object to a sandbox is not possible to sandbox, pysandbox is unable to proxify arbitary objects. For something more complex than evaluating "1+(2*3)", pysandbox cannot be used in practice, because of all these protections.

pysandbox 的作者认为，在 Python 里面放一个沙盒环境是错误的设计，有太多的方式可以从沙盒中逃逸出去，Python 提供的语言特性很丰富，CPython 源码的代码量很大，基本不可能保证有足够的安全性。而 pysandbox 的开发过程就是在不断地打补丁，补丁太多，限制太多，以至于作者认为 pysandbox 已经没法实际使用，因为很多的语法特性和功能都被限制不能使用了，譬如简单的 del dict[key]。

Restricted Execution 出路在哪

既然 rexec 和 pysandbox 这种通过 Patch Python 来提供沙盒环境的方法（这里姑且把这种方法称作 Patch Python）已经走不通了，那我不禁好奇：要怎么才能给 Python 提供一个能用的沙盒环境？

在这里我继续收集了一些其他的实现方法或者案例，方便参考和查阅：

PyPy 有一个分支提供了沙盒的功能，结合额外的 sandboxlib，可以自行编译出带沙盒环境版本的 PyPy。如果感兴趣，可以尝试自行配置，参考这里的一些说明。PyPy 实现的原理是创建一个子进程，子进程的所有输入输出和系统调用，都会重定向到外部进程，由外部进程控制这些权限，另外也可以控制内存和 CPU 的使用量。需要注意的是，这个分支也有段时间没有新的提交了，请谨慎使用。

借助操作系统提供的沙盒环境工具。seccomp 是 Linux 内核提供的计算安全工具，libsecoomp 提供了 Python 绑定，可以内嵌到代码里面使用；或者使用基于 seccomp 实现的工具来执行代码，譬如 Firejail。AppArmor 是一个 Linux 内核安全模块，允许管理员控制程序能访问的系统资源和功能，保护操作系统。codejail 是基于 AppArmor 实现的 Python 沙盒环境，有兴趣可以尝试。还有很多类似的工具，这里不一一列举。

使用沙盒虚拟环境或者容器。Windows 沙盒，LXC, Docker 等等，这里不再详述。

总结

本文篇幅有点长，感谢看到这里，文章一开始所列出的疑问，相信都已经解答完毕。

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

使用 Visual Studio 2015 编译 Python 2.7.11

Thu, 30 Nov 2023 20:09:36 +0000

原因

Python 2.7 的官方版本支持 Visual Studio 2010 以下版本来编译，参考 PCbuild\readme.txt：

1.  Install Microsoft Visual Studio 2008, any edition.
2.  Install Microsoft Visual Studio 2010, any edition, or Windows SDK 7.1 and any version of Microsoft Visual Studio newer than 2010.

如果你想在 Windows 下自己倒腾 Python，譬如编译个 Debug 版本、自己改改源代码等，那么最简单的方法就是装一个 VS2010。但是对我个人来说，我更想要用 VS2015 来编译 Python，原因主要有：

VS2010 实在有点过时，使用起来功能和体验比 VS2015 要差得多。一直用着 VS2015，要我再装个 VS2010 实在不愿意。
由于一直用 VS2015，你会使用它来写一些自己的程序，如果你想要把 Python 嵌入进去，那你就需要使用相同版本的 VS 来编译你的程序，如果使用不同版本的 VS，那会出现各种无法预料的事情。这里有更详细的解释。

所以我开始着手用 VS2015 搞定 Python 2.7.11 版本（当前的 Python 2.7 最新版本）。

要注意，Python 3.x 已经支持用 VS2015 来编译。

源码下载

Python 的版本当然就是 2.7.11，另外还有一些第三方的模块，具体可以运行 Python 源码目录下 PCbuild\get_externals.bat 脚本获取所有编译需要的模块，注意你需要安装 svn ，把 svn.exe 添加到系统 PATH 里面。

下载可能很不稳定，并且整个过程都有可能因为网络问题而终止，所以还是推荐直接在我的github上下载externals目录：我的 Python 版本

编译过程

第三方模块

首先要解决的是第三方的模块，主要是 tcl, tk, tcltk。

修改文件 externals/tcl-8.5.15.0/win/makefile.vc，把 434 行改成

- cdebug = -Zi -WX $(DEBUGFLAGS)
+ cdebug = -Zi -WX- $(DEBUGFLAGS)

关于选项 WX，可以看微软的官方文档：/WX (Treat Linker Warnings as Errors)

再来改PCbuild/tk.vcxproj，用文本编辑器打开，修改 63, 64 行

- <TkOpts>msvcrt</TkOpts>
- <TkOpts Condition="$(Configuration) == 'Debug'">symbols,msvcrt</TkOpts>
+ <TkOpts>msvcrt,noxp</TkOpts>
+ <TkOpts Condition="$(Configuration) == 'Debug'">symbols,msvcrt,noxp</TkOpts>

改PCbuild/tcltk.props，用文本编辑器打开，修改41行

- <BuildDirTop>$(BuildDirTop)_VC9</BuildDirTop>
+ <BuildDirTop>$(BuildDirTop)_VC13</BuildDirTop>

由于 VS2015 取消了 timezone 的定义，改为 _timezone，所以代码里面用到 timezone 的地方都要改成 _timezone，第三方模块只需要改文件externals/tcl-8.5.15.0/win/tclWinTime.c，在文件的前面加上：

#if defined _MSC_VER && _MSC_VER >= 1900
#define timezone _timezone
#endif

改 Python 源码

timezone的问题在 Python 的模块 time 里面也有，修改 767 行

- #ifdef __CYGWIN__
+ #if defined(__CYGWIN__) || defined(_MSC_VER) && _MSC_VER >= 1900

另外由于在 Windows 下 Python 用了一种特殊的方法来检查文件句柄的有效性，而这种方法在 VS2015 中被彻底禁止了，会出现编译错误，所以先改掉。文件 Include/fileobject.h，73、80 行：

73 - #if defined _MSC_VER && _MSC_VER >= 1400
73 + #if defined _MSC_VER && _MSC_VER >= 1400 && _MSC_VER < 1900

80 - #elif defined _MSC_VER && _MSC_VER >= 1200
80 + #elif defined _MSC_VER && _MSC_VER >= 1200 && _MSC_VER < 1400

文件Modules/posixmodule.c，532 行：

- #if defined _MSC_VER && _MSC_VER >= 1400
+ #if defined _MSC_VER && _MSC_VER >= 1400 && _MSC_VER < 1900

至此，Python 就可以编译通过。更具体的修改可以看我 commit 的内容：modify to build by vs2015

检查无效句柄

虽然编译通过了，但由于是粗暴地忽略无效文件句柄，直接导致的后果是一旦访问无效的句柄（譬如对同一个文件close两次），Python 就会直接 assert failed，程序 crash，这样的 Python 根本没法用啊。Python 就是用了一种很特殊的方法来避免这种情况，可惜在 VS2015 里面不能用了，注释是这样解释的：

Microsoft CRT in VS2005 and higher will verify that a filehandle is valid and raise an assertion if it isn't.

幸好已经有了解决方法，我是在 Python 的 issue 里面看到的，地址在这里：issue23524, issue25759。这种方法也是用在现在 Python 3.x 里面。

具体地说就是在使用文件句柄的时候禁止掉 Windows 的 assert crash 机制，改为检查错误码。那要怎么禁止 Windows 的 assert 机制呢？答案就是用自己的错误处理函数替代 Windows 默认的处理函数，关键的代码：

新建文件PC/invalid_parameter_handler.c，定义我们自己的错误处理函数，可以暂时忽略发生的错误

#ifdef _MSC_VER

#include <stdlib.h>

#if _MSC_VER >= 1900
/* pyconfig.h uses this function in the _Py_BEGIN_SUPPRESS_IPH/_Py_END_SUPPRESS_IPH
 * macros. It does not need to be defined when building using MSVC
 * earlier than 14.0 (_MSC_VER == 1900).
 */

static void __cdecl _silent_invalid_parameter_handler(
    wchar_t const* expression,
    wchar_t const* function,
    wchar_t const* file,
    unsigned int line,
    uintptr_t pReserved) 
{}

_invalid_parameter_handler _Py_silent_invalid_parameter_handler = _silent_invalid_parameter_handler;

#endif

#endif

定义两个宏方便更换错误处理函数，要注意是暂时的更换，之后是需要换回系统默认的

#if defined _MSC_VER && _MSC_VER >= 1900

extern _invalid_parameter_handler _Py_silent_invalid_parameter_handler;
#define _Py_BEGIN_SUPPRESS_IPH { _invalid_parameter_handler _Py_old_handler = \
    _set_thread_local_invalid_parameter_handler(_Py_silent_invalid_parameter_handler);
#define _Py_END_SUPPRESS_IPH _set_thread_local_invalid_parameter_handler(_Py_old_handler); }

#else

#define _Py_BEGIN_SUPPRESS_IPH
#define _Py_END_SUPPRESS_IPH

#endif /* _MSC_VER >= 1900 */

之后在有可能触发 Windows 文件句柄错误的地方，前后分别加上宏_Py_BEGIN_SUPPRESS_IPH 和 _Py_END_SUPPRESS_IPH，之后再检查错误码就可以了，需要修改到的地方不少，参考别人的 commit 来修改：在这里

结束

至此 Python 2.7.11 就可以在 VS2015 里面正常编译和运行了，不过由于 Python 官方是不推荐这样设置

***WARNING***
Building Python 2.7 for Windows using any toolchain that doesn't link
against MSVCRT90.dll is *unsupported* as the resulting python.exe will
not be able to use precompiled extension modules that do link against
MSVCRT90.dll.

所以使用的时候最好要注意一下。

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Unity人物控制

Thu, 30 Nov 2023 20:09:36 +0000

人物的动作控制是游戏里面很重要的一部分，操作性强的游戏能够很好的吸引玩家。这里我就尝试做一个简单的人物操作控制，人物能够完成基本的移动，包括行走，跳跃。

需求

先来考虑一下，我们的人物操作具体的需求：

行走，能够在刚体的表面行走，由按键上下左右输入来控制，暂不考虑加速减速过程
行走的速度在不同方向上可以不同，例如后退应该比前进慢
跳跃，由jump按键控制，人物以一定初速度从上离开地面，并慢慢回落到地面

那么大致的思路就是：用速度来描述人物的运动，速度每个方向上的分量可以分别计算，最后速度乘以时间就是人物的位置偏移了。

人物组件设置

在为人物写脚本来操作控制前，需要一些准备工作，把人物的相关组件先配置好：

为了控制人物并使人物有一些刚性物理上的表现需要为人物添加一个Character Controller Component
为了结构更分明一些，先把关于人物的操作输入分出来，读取输入并初步处理后把结果传给人物控制器，把这部分的脚本命名为MyThirdPersonInput.cs；
真正控制人物移动的脚本命名为MyThirdPersonController.cs

配置后的结果是这样：

输入

输入就是上下左右和跳跃，方向需要做一个归一化的处理：

// get movement from input
var direction = new Vector3(Input.GetAxis("Horizontal"), 0, 
    Input.GetAxis("Vertical"));
if (direction != Vector3.zero)
{
    // constrain length to [0, 1]
    var directionLength = direction.magnitude;
    directionLength = Math.Min(1, directionLength);
    direction = direction.normalized * directionLength;
}
person.inputMoveDirction = direction;
person.inputJump = Input.GetButton("Jump");
````

##描述移动和跳跃
我们需要用一些变量来描述人物的动作，例如移动速度，跳跃速度等，移动用下面变量描述：

```c#    
[System.Serializable]
public class Movement
{
    public float forwardSpeed = 5F;
    public float backwardSpeed = 5F;
    public float sidewardSpeed = 5F;
}
public Movement movement = new Movement();

[System.Serializable]是为了让这些参数暴露到Inspector上。跳跃的描述如下：

[System.Serializable]
public class Jumping 
{
    public bool enable = true;      // true if can jump
    public float jumpSpeed = 5F;    // original speed when jump
    public float gravity = 10F;
    public float maxFallSpeed = 20F;
    public bool jumping = false;    // true if now in the air
}
public Jumping jumping = new Jumping();

分解速度

为了方便描述不同方向的移动，把方向分成三个分量：前后、左右、上下，分别求解。

前后速度不同，根据数值的正负判断：

if (velocity.z > 0)
    velocity.z *= movement.forwardSpeed;
else
    velocity.z *= movement.backwardSpeed;

左右速度一致：

velocity.x = inputMoveDirction.x * movement.sidewardSpeed;

跳跃麻烦一点，要判断当前人物的状态：

如果已经在空中，用重力计算速度
如果在地上：
- 如果按下跳跃键，速度为跳跃初始速度
- 否则y方向速度为0

if (!isOnGround)
{
    yVelocity = Math.Max(yVelocity - jumping.gravity * Time.deltaTime, 
        -jumping.maxFallSpeed);
}
else
{
    if (jumping.enable && inputJump)
    {
        yVelocity = jumping.jumpSpeed;
    }
    else
        yVelocity = 0F;
}

更新人物位置

计算出来的速度假定为从本帧开始的速度，那么本帧计算位置的速度应该是前一帧计算出来的，因此在更新速度前，先计算人物的新位置：

// move to new position
var collisionFlag = controller.Move(velocity * Time.deltaTime);
isOnGround = (collisionFlag & CollisionFlags.CollidedBelow) != 0;

controller.Move会返回CollisionFlags来表示碰撞的状态，通过这个状态就可以知道人物是不是站在地面上。

完整代码：

MyThirdPersonInput.cs:

using UnityEngine;
using System;
using System.Collections;
[RequireComponent(typeof(MyThirdPersonController))]

public class MyThirdPersonInput : MonoBehaviour {

    private MyThirdPersonController person;

    void Awake()
    {
        person = GetComponent<MyThirdPersonController>();
    }

    // Update is called once per frame
    void Update () 
    {
        // get movement from input
        var direction = new Vector3(Input.GetAxis("Horizontal"), 0, 
            Input.GetAxis("Vertical"));

        if (direction != Vector3.zero)
        {
            // constrain length to [0, 1]
            var directionLength = direction.magnitude;

            directionLength = Math.Min(1, directionLength);

            direction = direction.normalized * directionLength;

        }

        person.inputMoveDirction = direction;
        person.inputJump = Input.GetButton("Jump");

    }
}

MyThirdPersonController.cs:

using UnityEngine;
using System;
using System.Collections;

public class MyThirdPersonController : MonoBehaviour {

    // The current global direction we want the character to move in.
    [System.NonSerialized]
    public Vector3 inputMoveDirction = Vector3.zero;

    // Is the jump button held down? We use this interface instead of checking
    // for the jump button directly so this script can also be used by AIs.
    [System.NonSerialized]
    public bool inputJump = false;

    [System.Serializable]
    public class Movement
    {
        public float forwardSpeed = 5F;
        public float backwardSpeed = 5F;
        public float sidewardSpeed = 5F;
    }
    public Movement movement = new Movement();

    [System.Serializable]
    public class Jumping 
    {
        public bool enable = true;      // true if can jump
        public float jumpSpeed = 5F;    // original speed when jump
        public float gravity = 10F;     
        public float maxFallSpeed = 20F;
        public bool jumping = false;    // true if now in the air
    }
    public Jumping jumping = new Jumping();

    private CharacterController controller;
    private Vector3 velocity = Vector3.zero;
    private bool isOnGround = true;
    // Use this for initialization
    void Start () 
    {
        controller = GetComponent<CharacterController>();
    }

    // Update is called once per frame
    void FixedUpdate() 
    {
        // move to new position
        var collisionFlag = controller.Move(velocity * Time.deltaTime);
        isOnGround = (collisionFlag & CollisionFlags.CollidedBelow) != 0;

        // update velocity
        float yVelocity = velocity.y;
        velocity = Vector3.zero;

        // x-z plane velocity
        if (inputMoveDirction != Vector3.zero)
        {
            velocity.z = inputMoveDirction.z;
            if (velocity.z > 0)
                velocity.z *= movement.forwardSpeed;
            else
                velocity.z *= movement.backwardSpeed;

            velocity.x = inputMoveDirction.x * movement.sidewardSpeed;
        }

        // y velocity
        if (!isOnGround)
        {
            yVelocity = Math.Max(yVelocity - jumping.gravity * Time.deltaTime, 
                -jumping.maxFallSpeed);
        }
        else
        {
            if (jumping.enable && inputJump)
            {
                yVelocity = jumping.jumpSpeed;
            }
            else
                yVelocity = 0F;
        }

        velocity = transform.rotation * velocity;
        velocity.y = yVelocity;
    }
}

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Unity实现体积光照散射 (Volumetric Light Scattering，云隙光)

Thu, 30 Nov 2023 20:09:36 +0000

原理

Volumetric Light Scattering 的原理可以参考《GPU Gems 3》第13章，书上有效果图：

好看吧，那好，我们的目标就是实现这种效果。

书上介绍了原理，一条关键的公式是：

\[ L(s, \theta, \phi) = exposure \times \sum_{i=0}^n decay^i \times weight \times \frac{L( s_i, \theta_i )}{n} \]

我的理解是，对于图像上的每个像素，光线都有可能照射到，那么对该像素到光源(在投影到图像上的位置)的连线进行采样(对应公式上$i$)，采样出的结果进行加权平均(对应公式上$\sum$)并作为该像素的新的颜色值。另外还有关键的后置像素着色器，但是如果只是用那个着色器来对相机渲染的结果进行处理，会产生明显的人工痕迹，有许多的条纹：

那么书上的效果是怎么做出来的？其实书上已经给出了答案，可以用一组图来阐述：

图a 就是粗糙的效果，细心地可以看到有许多条纹，并且没有遮挡不够真实，b、c、 d就是为了获得好的效果需要进行的步骤：

b. 把灯光辐射效果渲染到图像上，并加上物体的遮挡

c. 对b执行 Volumetric Light Scattering 像素着色器，得到遮挡后的效果

d. 添加上把真实场景的颜色

那么下面我们就来一步一步地实现。

画遮挡物体

在实际的操作中，我先用RenderWithShader来把会发生遮挡的物体画成黑色，其他地方为白色，因为这需要对每个面片进行渲染，因此对于复杂的场景，会带来一定的性能消耗。场景中的物体有不透明和透明的，我们希望不透明的物体产生完全的光线遮挡，而透明的物体应该产生部分的遮挡，那么我们就需要针对不同RenderType的物体写不同的Shader，RenderType是SubShader的Tag，不清楚的话可以看这里，写好之后调用：

camera.RenderWithShader(objectOcclusionShader, "RenderType");

RenderWithShader的第二个参数就是要求根据RenderType来替换Shader，简单来说，同一个物体的替换的Shader的RenderType要跟替换前一致，这样我们就可以为不同的RenderType的物体使用不同的Shader：

Shader "Custom/ObjectOcclusion" 
{
    Properties 
    {
        _MainTex ("Base (RGB)", 2D) = "white" {}
    }
    SubShader 
    {
        Tags 
        {
            "Queue" = "Geometry"
            "RenderType" = "Opaque"
        }
        LOD 200
        Pass
        {
            Lighting Off
            ZTest Always Cull Off ZWrite Off
            Fog { Mode off }
            CGPROGRAM
            #pragma vertex vert
            #pragma fragment frag
            #include "UnityCG.cginc"

            uniform sampler2D _MainTex;

            v2f_img vert(appdata_img i)
            {
                v2f_img o;
                o.pos = mul (UNITY_MATRIX_MVP, i.vertex);
                return o;
            }

            half4 frag(v2f_img i): COLOR
            {
                return half4(0, 0, 0, 1);
            }
            ENDCG
        }

    }
        SubShader 
    {
        Tags 
        {
            "Queue" = "Geometry"
            "RenderType" = "Transparent"
        }
        LOD 200
        Pass
        {
            Lighting Off
            ZTest Always Cull Off ZWrite Off
            Fog { Mode off }
            Blend SrcAlpha OneMinusSrcAlpha     // blend for transparent objects
            CGPROGRAM
            #pragma vertex vert
            #pragma fragment frag
            #include "UnityCG.cginc"

            uniform sampler2D _MainTex;

            v2f_img vert(appdata_img i)
            {
                v2f_img o;
                o.pos = mul (UNITY_MATRIX_MVP, i.vertex);
                o.uv = MultiplyUV( UNITY_MATRIX_TEXTURE0, i.texcoord );
                return o;
            }

            half4 frag(v2f_img i): COLOR
            {
                half3 output = (1, 1, 1);
                half4 color = tex2D(_MainTex, i.uv);
                half alpha = color.a;
                return half4(output *(1-alpha), alpha);
            }
            ENDCG
        }

    }

    FallBack "Diffuse"
}

注意不透明和透明物体的Shader间的差别：不透明的物体直接画成黑色；不透明物体需要执行blending，获取物体纹理上的alpha通道，并基于这个alpha进行blending。上面代码只是列举了Opaque和Transparent，另外还有TreeOpaque (Shader跟Opaque一样，只是改变RenderType) ，TreeTransparentCutout (同Transparent) 等。由于指定了RenderType，所以为了全面，需要尽可能穷尽场景中的会发生遮挡的物体，我这里就只有前面提到的四种。结果大致如下：

结合物体遮挡画光源辐射

画光源的辐射不难，需要注意的是需要根据屏幕的大小做一些处理，使得光源的辐射状是圆形的：

Shader "Custom/LightRadiate" 
{
    Properties 
    {
        _MainTex ("Base (RGB)", RECT) = "white" {}
        _LightPos ("Light Pos In Screen Space(XY)", Vector) = (0, 0, 0, 1)
        _LightRadius ("Light radiation radius (Pixel)", Float) = 50
    }
    SubShader 
    {
        Tags { "RenderType"="Opaque" }
        LOD 200
        Pass
        {
            ZTest Always Cull Off ZWrite Off
            Fog { Mode off }
            CGPROGRAM
            #pragma vertex vert
            #pragma fragment frag
            #include "UnityCG.cginc"

            uniform sampler2D _MainTex;
            float4 _LightPos;
            float _LightRadius;

            v2f_img vert(appdata_img i)
            {
                v2f_img o;
                o.pos = mul (UNITY_MATRIX_MVP, i.vertex);
                o.uv = MultiplyUV( UNITY_MATRIX_TEXTURE0, i.texcoord );
                return o;
            }

            half4 frag(v2f_img i): COLOR
            {
                half2 deltaTexCoord = (i.uv - _LightPos.xy) * half2(_ScreenParams.x, _ScreenParams.y);
                float dis = dot(deltaTexCoord, deltaTexCoord);
                const float maxDis = _LightRadius * _LightRadius;
                dis = saturate((maxDis-dis) / maxDis * 0.5);
                return half4(dis, dis, dis, 1) * half4(tex2D(_MainTex, i.uv).rgb, 1);               
            }

            ENDCG
        }
    } 
    FallBack "Diffuse"
}

这个Shader需要输入光源在屏幕上的位置(可以用camera.WorldToViewportPoint来计算，得到的是uv坐标)，然后根据指定的半径画一个亮度往外衰减的圆，并把结果跟前面得到的物体遮挡图像(放在_MainTex里)结合，结果大致为：

Light Scattering处理，并结合真实颜色

这里就要用到书上提供的Pixel Shader，我的版本：

Shader "Custom/LightScattering" 
{
    Properties 
    {
        _MainTex ("Base (RGB)", 2D) = "white" {}
        _LightRadTex("Light Radiate Tex (RGB)", 2D) = "white" {}
        _LightPos ("Light Pos In Screen Space(XY)", Vector) = (0, 0, 0, 1)
        _Params("Density Weight Decay Exposure", Vector) = (1.0, 1.0, 1.0, 1.0)
    }
    SubShader 
    {
        LOD 200
        Pass
        {
            ZTest Always Cull Off ZWrite Off
            Fog { Mode off }    
            CGPROGRAM
            #pragma vertex vert
            #pragma fragment frag
            #pragma target 3.0
            #include "UnityCG.cginc"

            uniform sampler2D _MainTex;
            uniform sampler2D _LightRadTex;
            uniform float4 _LightPos;
            uniform float4 _Params;

            v2f_img vert(appdata_img i)
            {
                v2f_img o;
                o.pos = mul (UNITY_MATRIX_MVP, i.vertex);
                o.uv = MultiplyUV( UNITY_MATRIX_TEXTURE0, i.texcoord );
                return o;
            }

            half4 frag(v2f_img i): COLOR
            {   
                // Calculate vector from pixel to light source in screen space
                float2 deltaTexCoord = (i.uv - _LightPos.xy);

                // Divide by number of samples and scale by control factor, here I use 32 samples
                deltaTexCoord *= 1.0f / 32 * _Params.x; //density;

                // Store color.
                half3 color = tex2D(_MainTex, i.uv).rgb;

                // Store initial sample.
                half3 light = tex2D(_LightRadTex, i.uv).rgb;

                // Set up illumination decay factor.
                half illuminationDecay = 1.0f;

                for(int j = 0; j < 31; ++j)
                {
                    // Step sample location along ray.
                    i.uv -= deltaTexCoord;

                    // Retrieve sample at new location.
                    half3 sample = tex2D(_LightRadTex, i.uv).rgb;

                    // Apply sample attenuation scale/decay factors.
                    sample *= illuminationDecay * 0.03125 * _Params.y ; //weight;

                    // Accumulate combined light.
                    light += sample;

                    // Update exponential decay factor.
                    illuminationDecay *= _Params.z;             //decay;
                }

                // Output final color with a further scale control factor.
                return half4(color+(light * _Params.w), 1); // exposure
            }

            ENDCG       
        }

    } 
    FallBack "Diffuse"
}

大体上跟书上的一致，只是我的参数需要在程序中传进来，并且结合了真实的颜色图和Light Scattering图，结果：

完整代码

代码在这里，把cs脚本添加到相机上。

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Unity画深度图(Depth Map)和边缘检测(Edge Detection)

Thu, 30 Nov 2023 20:09:36 +0000

刚接触Unity没多久，对Unity的ShaderLab一直很感兴趣，感觉它可以快速地实现各种各样的显示效果，很有意思。嘛，作为一个门都还没入的人，我就来搞一搞深度图和边缘检测吧。

小地图设置

因为我只是做了一个小雏形，所以我不打算详细地讲如何去在场景上画小地图，大致上说我做了以下一些事情：

获取场景的 bounding box，这个在设置相机的参数和位置时有用
把小地图相机配置成正交投影，根据 bounding box 设置相机的近平面和远平面
为该相机增加一个人物目标，目标会显示在地图的中心
每次更新相机的位置，根据目标的位置，还有场景的最大 y 值

具体的配置可以参考后面给出的代码。

获取深度图

depthTextureMode 来获取深度图

相机自己可以保存DepthBuffer或者一个DepthNormalBuffer(可用来做边缘检测)，只需要设置

Camera.depthTextureMode = DepthTextureMode.DepthNormals;

然后在Shader里面引用

sampler2D _CameraDepthNormalsTexture;

就可以了，具体的做法可以参考我后面给出的代码。关于在Z-Buffer里面保存的深度值跟真实世界的深度的关系可以参考这两篇文章： Learning to Love your Z-buffer,Linearize depth。另外 Unity 也提供了一些函数来计算深度: Linear01Depth, LinearEyeDepth 等。

这不是我这里讨论的重点，我想说的是，本来我的相机设置为正交投影，深度应该是线性的，但我测试出来却不是线性。然后我用上面链接介绍的方法来计算真实世界的深度，也一直都不正确，以至于一直计算不出真实的线性深度，不知道是Unity的Z_Buffer的问题还是什么，那位朋友知道的请教教我。当然，如果不需要真实的深度值，单单是比较深度的大小之类的，用上面的方法就足够了，而且很简单。但是对于我这里来说，我想要把真实深度映射为颜色值，需要获得真实的线性的深度值（虽然也是[0, 1]），我只好用另外一种用 RenderWithShader 方法了。

RenderWithShader 来获取深度图

这种方法其实就是用Unity Reference里面的一个例子：Rendering with Replaced Shaders。需要理解的是，RenderWithShader会把场景中的相应的Mesh画一遍。

创建一个 Shader :

Shader "Custom/DepthByReplaceShader" 
{
SubShader 
{
    Tags { "RenderType"="Opaque" }
    Pass {
        Fog { Mode Off }
        CGPROGRAM
        #pragma vertex vert
        #pragma fragment frag
        #include "UnityCG.cginc"

        struct v2f {
            float4 pos : SV_POSITION;
            float2 depth : TEXCOORD0;
        };

        v2f vert (appdata_base v) {
            v2f o;
            o.pos = mul (UNITY_MATRIX_MVP, v.vertex);
            UNITY_TRANSFER_DEPTH(o.depth);
            return o;
        }

        float4 frag(v2f i) : COLOR {
            //UNITY_OUTPUT_DEPTH(i.depth);
            float d = i.depth.x/i.depth.y;
            return float4(d, d, d, 1);
        }
        ENDCG
    }
}
}

为你的小地图相机(没有的话创建之)添加一个脚本，把相机配置成正交投影等，并且在 Update() 里面使用这个 Shader 来渲染场景：

camera.targetTexture = depthTexture;
camera.RenderWithShader(depthShader, "");

渲染的结果就会保存在 depthTexture里面，很简单吧。

把深度映射成颜色

要完成这个工作，首先需要一张颜色图，这张图可以用 Matlab 很简单地生成，例如我用的是 Matlab 里面的 jet 图：

把这张图放到项目目录 Assets\Resources 里面，就可以在程序中读取：

colorMap = Resources.Load<Texture2D>("colormap");

需要注意的是，这张图片的 Wrap Mode 应该是 Clamp，防止在两边缘的颜色值之间进行插值。

之后就需要使用 OnRenderImage 和 Graphics.Blit 函数，函数的原型为：

void OnRenderImage(RenderTexture src, RenderTexture dst);
static void Blit(Texture source, RenderTexture dest, Material mat, int pass = -1);

这个函数的 src 是相机渲染的结果，dst 是处理后传回给相机的结果，因此这个函数通常是用来在相机渲染完成后做图片的一些效果，例如我们这里的对深度做颜色映射，还有边缘检测。做法就是在OnRenderImage中调用Graphics.Blit，传入特定的Material：

depthEdgeMaterial.SetTexture("_DepthTex", src);
Graphics.Blit(src, dst, depthEdgeMaterial);
return;

需要注意的是，Graphics.Blit实际上做了这样一件事情：在相机前面画一个跟屏幕大小一样的平面，把src作为这个平面的_MainTex传进Shader中，然后把结果放到dst里面，而不是把实际场景中的Mesh重新画一遍。

对颜色映射其实就是把深度 [0, 1] 看成图片的 uv，因为我想距离相机近的为红色，所以我对深度取了反：

half4 color = tex2D(_ColorMap, float2(saturate(1-depth), 0.5));

边缘检测

边缘检测需要用到了相机自己的 _CameraDepthNormalsTexture，主要是用 Normal 的值，深度还是用之前计算出来的。在 _CameraDepthNormalsTexture 的每个像素 (x, y, z, w) 中，(x, y) 是法向，(z, w)是深度，法向是用了一种方法来存放的，有兴趣可以自己搜索。

代码是参考了 Unity 自带的 Image Effect 里面的边缘检测，需要做的事情就是，比较当前像素的法向深度和邻近像素的差别，足够大我们就认为存在边缘：

inline half CheckSame (half2 centerNormal, half2 sampleNormal, float centerDepth, float sampleDepth)
{
    // difference in normals
    // do not bother decoding normals - there's no need here
    half2 diff = abs(centerNormal - sampleNormal);
    half isSameNormal = (diff.x + diff.y) < 0.5;

    // difference in depth
    float zdiff = abs(centerDepth-sampleDepth);
    // scale the required threshold by the distance
    half isSameDepth = (zdiff < 0.09 * centerDepth) || (centerDepth < 0.1);

    // return:
    // 1 - if normals and depth are similar enough
    // 0 - otherwise
    return isSameNormal * isSameDepth;
}

完整的 Shader 如下：

Shader "Custom/DepthColorEdge" {

Properties 
{
    _DepthTex ("Depth Tex", 2D) = "white" {}
    _ColorMap ("Color Map", 2D) = "white" {}
}
    SubShader 
    {
        Tags { "RenderType"="Opaque" }
        LOD 200
        Pass
        {
            ZTest Always Cull Off ZWrite Off
            Fog { Mode off }
            CGPROGRAM
            #pragma vertex vert
            #pragma fragment frag
            #include "UnityCG.cginc"
            sampler2D _CameraDepthNormalsTexture;
            sampler2D _DepthTex;
            uniform float4 _DepthTex_TexelSize;
            sampler2D _ColorMap;
            float _ZNear;
            float _ZFar;

            struct v2f 
            {
                float4 pos : SV_POSITION;
                float2 uv[3] : TEXCOORD0;
            };

            v2f vert (appdata_base v)
            {
                v2f o;
                o.pos = mul (UNITY_MATRIX_MVP, v.vertex);
                o.uv[0] = MultiplyUV( UNITY_MATRIX_TEXTURE0, v.texcoord );
                o.uv[1] = o.uv[0] + float2(-_DepthTex_TexelSize.x, -_DepthTex_TexelSize.y);
                o.uv[2] = o.uv[0] + float2(+_DepthTex_TexelSize.x, -_DepthTex_TexelSize.y);
                return o;
            }


            inline half CheckSame (half2 centerNormal, half2 sampleNormal, float centerDepth, float sampleDepth)
            {
                // difference in normals
                // do not bother decoding normals - there's no need here
                half2 diff = abs(centerNormal - sampleNormal);
                half isSameNormal = (diff.x + diff.y) < 0.5;

                // difference in depth
                float zdiff = abs(centerDepth-sampleDepth);
                // scale the required threshold by the distance
                half isSameDepth = (zdiff < 0.09 * centerDepth) || (centerDepth < 0.1);

                // return:
                // 1 - if normals and depth are similar enough
                // 0 - otherwise
                return isSameNormal * isSameDepth;
            }

            half4 frag(v2f i) : COLOR 
            {
                // get color based on depth
                float depth = tex2D (_DepthTex, i.uv[0]).r;
                half4 color = tex2D(_ColorMap, float2(saturate(1-depth), 0.5));

                // detect normal diff
                half2 centerNormal = tex2D(_CameraDepthNormalsTexture, i.uv[0]).xy;
                half2 sampleNormal1 = tex2D (_CameraDepthNormalsTexture, i.uv[1]).xy;
                half2 sampleNormal2 = tex2D (_CameraDepthNormalsTexture, i.uv[2]).xy;
                float sampleDepth1 = tex2D (_DepthTex, i.uv[1]).r;
                float sampleDepth2 = tex2D (_DepthTex, i.uv[2]).r;
                color *= CheckSame(centerNormal, sampleNormal1, depth, sampleDepth1);
                color *= CheckSame(centerNormal, sampleNormal2, depth, sampleDepth2);

                return color;
            }
            ENDCG
        }

    }
    FallBack "Diffuse"
}

结果类似于这个：

混合真实世界图像

单单是深度的颜色图可能有点无趣，那么我们可以混合上真实场景的颜色图，只需要再建一个 Shader，传入前面的图像和相机的真实图像，在 OnRenderImage 中进行混合：

Shader "Custom/ColorMixDepth" {
    Properties {
        _MainTex ("Base (RGBA)", 2D) = "white" {}
        _DepthTex ("Depth (RGBA)", 2D) = "white" {}
    }
    SubShader {
        Tags { "RenderType"="Opaque" }
        LOD 200

        CGPROGRAM
        #pragma surface surf Lambert

        sampler2D _MainTex;
        sampler2D _DepthTex;

        struct Input {
            float2 uv_MainTex;
            float2 uv_DepthTex;
        };

        void surf (Input IN, inout SurfaceOutput o) {
            half4 c = tex2D (_MainTex, IN.uv_MainTex);
            half4 d = tex2D (_DepthTex, IN.uv_DepthTex);
            //d = d.x == 1? 0 : d;
            o.Albedo = c.rgb*0.1 + d.rgb*0.9;
            o.Alpha = 1;
        }
        ENDCG
    } 
    FallBack "Diffuse"
}

上面的代码就是完成这个工作，需要理解的是，我们在调用 RenderWithShader 的时候，

OnRen

href="#__codelineno-11-1">void OnRenderImage(RenderTexture src, RenderTexture dst) span> // if now rendering depth map if (isRenderDepth) { depthEdgeMaterial.SetTexture("_DepthTex", src); if(isUseColorMap) Graphics.Blit(src, dst, depthEdgeMaterial); else Graphics.Blit(src, dst); return; } // else rendering real color scene, mix the real color with depth map else { mixMaterial.SetTexture("_MainTex", src); mixMaterial.SetTexture("_DepthTex", depthTexture); Graphics.Blit(src, dst, mixMaterial); ReleaseTexture(); } } derImage

也会被调用，也就是这个函数被调用了两次，而两次调用需要完成的功能是不同的，所以我这里用一个变量来指示当前的渲染状态是做深度图还是混合。

完整的代码

代码文件有点多，就放到这里了depth-minimap。

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Unity第三人称相机构建(上)

Thu, 30 Nov 2023 20:09:36 +0000

我想在Unity中创建一个第三人称相机，相机的行为参考《魔兽世界》的第三人称相机，具体的需求是：

鼠标左键：控制相机围绕人物旋转，人物不旋转
鼠标右键：控制相机围绕人物旋转，人物的前方向(Unity中的tranform.forward)相应旋转，人物上方向不变
鼠标左键旋转后，再右键旋转，角色前方向马上根据左键的旋转做调整，再根据右键旋转，此时等价于两次都是右键旋转
鼠标滚轮：控制相机远近
相机不能穿过任何刚性物体
相机在离开碰撞的刚性物体后，慢慢回到原来的距离上
如果相机在碰到物体时，使用鼠标滚轮操作相机拉近，相机需要马上反应，此后第6点不再发生
相机在旋转中碰到地面，停止围绕人物上下旋转，改为围绕自身上下旋转，左右旋转依然是围绕人物

这个需求可以先分成两部分：相机旋转，相机刚性。简单起见，这里先来解决相机旋转的问题，也就是需求的前3点。

相机位置表示

在正式解决相机操作前，还有一个问题需要解决：相机位置的表示。这可以用多种方式：

相机的世界坐标
相机相对于人物的坐标
相机在人物坐标系中的方向和距离

因为在我们的需求中，相机是根据人物位置进行变换的，所以我这里使用第三种方式，而且在控制中相机一直瞄准人物，所以在相机内只需要保存距离信息：

float curDistance = 5F;

相机旋转

继续细分相机旋转的行为，可以分成左键旋转和右键旋转，下面我们来一步一步地完成这两个旋转。首先我把相机设为人物的子物体(children)，这样人物的一些基本的移动相机都会自动的跟踪。

左键旋转

单单看左键旋转，需求很简单：相机旋转，人物不旋转，这就相当于一个观察模型的相机，相机可以任意角度观察中心物体。

在Unity中获取鼠标左键状态使用语句：Input.GetMouseButton(0)（注：后面涉及到代码的地方，都是使用C#），明显，右键就是Input.GetMouseButton(1)。获取鼠标光标的移动位置（可以理解为帧之间光标在X-Y上的偏移量）信息是：Input.GetAxis("Mouse X"); Input.GetAxis("Mouse Y")。那么我们可以先来获取鼠标左键按下后光标的移动信息：

if (Input.GetMouseButton(0))
{
    float x = Input.GetAxis("Mouse X");
    float y = Input.GetAxis("Mouse Y");
}

代码很简单，那下面就是关键的地方：如何控制相机来旋转。要理解旋转，这里需要一些关于四元数的知识（网上资料很多，这里就不列举了），四元数重要的一点是它可以很简单地构造旋转，特别是围绕某个向量的旋转，理解四元数后，实现相机围绕人物的旋转就不难了。

另外还有一点要注意的是，四元数旋转轴只是一个向量，以原点为出发点，如果要以世界坐标系中的某点O为原点，以该点为出发点的向量V为旋转轴，就需要进行坐标系的变换，简单地说，就是把需要旋转的点P变换到，以O为原点的坐标系中，根据V旋转，再变换会世界坐标系。根据这些操作，可以写出一个功能函数：

Vector3 MyRotate(Vector3 oldPosition, float angle, Vector3 axis, Vector3 axisPosition)
{
    // 构造一个四元数，以axis为旋转轴，这是在人物坐标系中的旋转
    Quaternion rotation = Quaternion.AngleAxis(angle, axis);
    // 这里做的就是坐标系的变换，把相机的世界坐标变换到人物坐标系下的坐标
    Vector3 offset = oldPosition - axisPosition;
    // 计算旋转并变换回世界坐标系中
    return axisPosition + (rotation * offset);
}

Quaternion是Unity中表示四元数的类型，加上之前鼠标左键的检测，就可以完成左键控制相机左右旋转。

鼠标左右移动控制相机左右旋转的代码就可以直接给出：

newForward = MyRotate(newForward, x, up, Vector3.zero);

因为这里只有前向量做旋转，没有涉及到坐标系的转换，所以第四个参数为Vector3.zero。

控制上下旋转比左右旋转难理解一点，因为此时的旋转轴是会一直变化的(这里假设人物的up一直是Y轴的正方向)。注意的相机也是一直在旋转，并且视点中心一直对准人物，那么相机的右方向(right)就是我们想要围绕着旋转的轴了(把相机right想象成人物的right)，这样理解，那么上下旋转的代码也很简单了：

newForward = MyRotate(newForward, -y, transform.right, Vector3.zero);

右键旋转

做了左键旋转，右键旋转就很简单了，只需要在左右旋转的时候设置人物的前方向：

player.forward = Vector3.Normalize(new Vector3(oldForward.x, 0, oldForward.z));

上下旋转跟左键的代码一样。

先左键，后右键

上面虽然可以分别左键旋转，右键旋转，但是一旦先用左键旋转，再用右键操作的时候，问题就会出现：人物的前方向和相机的前方向不同了！那么相机和人物的正方向就从此分离，实际操作起来很奇怪。那么我们在用右键旋转的时候就要先把人物调整为跟相机的正方向一致：

player.forward = Vector3.Normalize(new Vector3(oldForward.x, 0, oldForward.z));

欧拉角万向锁

至此，相机的旋转差不多就完成，不过还有一个问题要注意：欧拉角万向锁。原理这里就不细讲，有兴趣的朋友可以自行搜索，针对这里相机的情况，就是当相机上下旋转到跟人物的上方向重合的时候，相机的视角会发生突变。这是因为相机到达人物的头顶或者脚底，相机的上方向会发生突变(因为相机的上方向的Y值一直都要大于零)，所以我们需要限制相机的上下旋转范围，防止发生万向锁。操作很简单，就是限制相机的前方向与人物的上方向的夹角的范围：

if ((Vector3.Dot(transform.forward, transform.parent.up) >= -0.95F || y > 0) &&
    (Vector3.Dot(transform.forward, transform.parent.up) <= 0.95F || y < 0))

完整代码

// rotate oldPosition around a axis starting at axisPosition
Vector3 MyRotate(Vector3 oldPosition, float angle, Vector3 axis, Vector3 axisPosition)
{
    Quaternion rotation = Quaternion.AngleAxis(angle, axis);
    Vector3 offset = oldPosition - axisPosition;
    return axisPosition + (rotation * offset);
}

// rotate oldForward, player forward may change when use mouse RB
Vector3 RotateIt(Vector3 oldForward, Vector3 up, Vector3 right, Transform player)
{
    Vector3 newForward = -oldForward;
    // mouse LB RB rotate camera and character
    if (Input.GetMouseButton(0) ^ Input.GetMouseButton(1))
    {
        float x = Input.GetAxis("Mouse X") * rotateSpeed;
        float y = Input.GetAxis("Mouse Y") * rotateSpeed;

        if (x != 0F)
        {
            newForward = MyRotate(newForward, x, up, Vector3.zero);

            // mouse RB, character rotate together
            if (Input.GetMouseButton(1))
            {
                player.forward = Vector3.Normalize(new Vector3(oldForward.x, 0, 
                    oldForward.z));
            }
        }

        if (y != 0F)
        {

            if ((Vector3.Dot(transform.forward, up) >= -0.95F || y > 0)
                && (Vector3.Dot(transform.forward, up) <= 0.95F || y < 0))
            {
                newForward = MyRotate(newForward, -y, transform.right, Vector3.zero);

            }
        }
    }

    return -newForward;
}

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Unity第三人称相机构建(下)

Thu, 30 Nov 2023 20:09:36 +0000

上一集讲完了相机的旋转，那么现在我们要解决的问题是相机的刚性，要怎么做呢？

相机刚性

回顾之前提的需求：

鼠标滚轮：控制相机远近
相机不能穿过任何刚性物体
相机在离开碰撞的刚性物体后，慢慢回到原来的距离上
如果相机在碰到刚体时，使用鼠标滚轮操作相机拉近，相机需要马上反应，此后第6点不再发生；碰撞地面后不能进行缩放操作
相机在旋转中碰到地面，停止围绕人物上下旋转，改为围绕自身上下旋转，左右旋转依然是围绕人物

这几点的意思是：相机在碰到刚性物体时，会被迫拉近跟人物的距离，那么我们想要相机在离开的时候，可以慢慢地回到原来的距离；但是如果在自动拉近距离后，用滚轮再手动拉近，说明相机离开碰撞的物体，那么这个拉近的距离就是相机的实际距离。下面我们来一点一点的解这些需求。

滚轮控制

鼠标滚轮控制很简单，只需要知道获取滚轮信息是Input.GetAxis("Mouse ScrollWheel")，并设定距离的最大值最小值就ok：

public float mouseWheelSensitivity = 2; // control zoom speed
public int mouseWheelZoomMin = 2;       // min distance
public int mouseWheelZoomMax = 10;      // max distance
float curDistance = 5F;
float zoom = Input.GetAxis("Mouse ScrollWheel");
if (zoom != 0F)
{
    float distance = curDistance;
    distance -= zoom * mouseWheelSensitivity;
    distance = Math.Min(mouseWheelZoomMax, Math.Max(mouseWheelZoomMin, distance));
    return distance;
}

这里playerTransform指向人物。

不能穿过任何刚性物体

这需要检测相机跟刚体的接触，有一个函数可以实现这个功能：

static bool Raycast(Ray ray, RaycastHit hitInfo, float distance = Mathf.Infinity, int layerMask = DefaultRaycastLayers);

具体用法参考Unity的Reference，我们可以这样实现碰撞的检测：

RaycastHit hitInfo;
if (Physics.Raycast(playerTransform.position, desiredPosition - playerTransform.position,
    out hitInfo, (playerTransform.position - desiredPosition).magnitude, 1))
{
    curDistance = hitInfo.distance;
}

targetPosition就是碰撞的位置，把相机的位置设到碰撞的位置就可以。

离开刚体后，慢慢回到原来的距离上

要完成这个功能，首先要分别记录下相机应该处于的距离(desiredDistance)和目前距离(curDistance)，把滚轮操作的结果用desiredDistance先存起来，再根据碰撞计算物体的新距离；在检测到相机离开刚体，或者碰撞到更远的刚体时候，不能直接把碰撞的位置赋值给相机，需要用一个移动速度来向新的距离移动。先来获取新的距离：

float newDistance = desiredDistance;
RaycastHit hitInfo;
if (Physics.Raycast(playerTransform.position, desiredPosition - playerTransform.position,
    out hitInfo, (playerTransform.position - desiredPosition).magnitude, 1))
{
    newDistance = hitInfo.distance;
}

那么怎么判断相机正在向更远的距离移动呢？可以用newDistances和当前的距离进行比较：

// 向更近的距离移动
if (newDistance < curDistance)
{
    curDistance = newDistance;
}
// 向更远的距离移动
else if(newDistance > curDistance)
{
}

那么判断到向更远距离移动后，就很直观了，直接加个速度来移动：

curDistance = Math.Min(curDistance + Time.deltaTime * autoZoomOutSpeed, newDistance);

相机的大致行为我们已经完成了，还有一些细节需要处理。

碰到刚体后滚轮拉近，地面不缩放

这里有两个要求：

碰到刚体后只能拉近，不能拉远
碰到地面后不能缩放

首先用变量来保存相机的碰撞状态：

bool isHitGround = false;       // 表示是否碰撞地面
bool isHitObject = false;       // 表示是否碰撞刚体(除开地面)

在判断滚轮缩放的时候加上条件判断：

if (zoom != 0F && (!isHitGround || (isHitObject && zoom > 0F)) )
{
    // calculate distance
}

碰到地面绕自身上下旋转

这个功能实现起来有点麻烦，需要因为这时候我们之前假设相机一直对准人物不成立了，这时分成两个向量：相机自身的朝向(desireForward)和人物到相机的方向(cameraToPlayer)，分别计算这两个向量的值，前者就决定相机的朝向，后者就决定相机的位置。为了方便，把上一集的旋转函数拆成X旋转(RotateX)和Y旋转(RotateY)，那么在计算cameraToPlayer的RotateY时加上条件：

if ((!isHitGround) || 
    (isHitGround && transform.forward.y <= cameraToPlayer.y && yAngle > 0))
{
    cameraToPlayer = RotateY(cameraToPlayer, playerTransform.up, 
        transform.right, yAngle);
}

这个条件有两部分：

没有碰到地面
碰到地面，但是准备离开地面

然后用cameraToPlayer计算相机的位置：

transform.position = playerTransform.position - cameraToPlayer * curDistance;

并且在有需要的时候(也就是碰到地面)计算相机的朝向：

if (!isHitGround)
{
    transform.LookAt(playerTransform);
}
else
{
    desireForward = RotateX(desireForward, playerTransform.up, xAngle);
    desireForward = RotateY(desireForward, playerTransform.up, transform.right, yAngle);
    transform.forward = desireForward;
}

这样相机的行为我们都实现了。

完整代码：

using UnityEngine;
using System;
using System.Collections;

// use a forward vector and distance to describe the camera position
public class MyThirdPersonCamera : MonoBehaviour {

    private Transform playerTransform;      // reference to player

    public float mouseWheelSensitivity = 3; // control zoom speed
    public int mouseWheelZoomMin = 2;       // min distance
    public int mouseWheelZoomMax = 10;      // max distance

    public float rotateSpeed = 5F;          // speed of rotate around player    
    public float autoZoomOutSpeed = 10F;    // speed of auto zoom out, camera will auto zoom out 
                                            // to pre distance when stop colliding object
    float curDistance = 5F;                 // distance to player
    float desiredDistance = 5F;             // distance should be      
    bool isHitGround = false;               // hit ground flag
    bool isHitObject = false;               // hit object(except ground) flag

    // Use this for initialization
    void Awake ()
    {
        playerTransform = transform.parent;
    }

    void Start () 
    {
        transform.position = playerTransform.position - playerTransform.forward 
            * curDistance;
        transform.LookAt(playerTransform);

    }

    // Update is called once per frame
    void Update () 
    {
        Vector3 cameraToPlayer = 
            (playerTransform.position - transform.position).normalized;

        Vector3 desireForward = transform.forward;

        // get new distance of zoom
        desiredDistance = ZoomIt(curDistance, desiredDistance);

        float xAngle, yAngle;
        bool isRightDown;

        // get mouse LB, RB status
        GetMouseButtonStatus(out xAngle, out yAngle, out isRightDown);

        // rotate camera by x-axis movement
        cameraToPlayer = RotateX(cameraToPlayer, playerTransform.up, xAngle);

        // if RB on, change player orientation
        if (isRightDown)
        {
            playerTransform.forward = Vector3.Normalize(new Vector3(cameraToPlayer.
                x, 0, cameraToPlayer.z));
        }

        // rotate camera by y-axis, if camera is not on ground or camera is going to leave ground
        if ((!isHitGround) 
        || (isHitGround && transform.forward.y <= cameraToPlayer.y && yAngle > 0))
        {
            cameraToPlayer = RotateY(cameraToPlayer, playerTransform.up, transform.
                right, yAngle);
        }

        // detect collision of camera to rigid body, get the distance camera should be
        float newDistance = DealWithCollision(playerTransform.position, 
            -cameraToPlayer, desiredDistance,ref isHitGround, ref isHitObject);

        // check the distance
        if (newDistance <= curDistance)
        {
            curDistance = newDistance;
        }
        else
        {
            // now moving to farther position, use a speed to move it
            curDistance = Math.Min(curDistance + Time.deltaTime * autoZoomOutSpeed, 
                newDistance);
        }

        // now calculate the position
        transform.position = playerTransform.position - cameraToPlayer * curDistance;

        // calculate the camera forward, if on ground, camera will rotate on self.Space
        if (!isHitGround)
        {
            transform.LookAt(playerTransform);
        }
        else
        {
            desireForward = RotateX(desireForward, playerTransform.up, xAngle);
            desireForward = RotateY(desireForward, playerTransform.up, transform.
                right, yAngle);
            transform.forward = desireForward;
        }
    }

    // zoom in and zoom out
    float ZoomIt(float curDistance, float desiredDistance)
    {
        float zoom = Input.GetAxis("Mouse ScrollWheel");

        //  zoom when hit rigid body and zoom in, or not on ground
        if (zoom != 0F && (!isHitGround || (isHitObject && zoom > 0F)) )
        {
            float distance = curDistance;

            distance -= zoom * mouseWheelSensitivity;
            distance = Math.Min(mouseWheelZoomMax, Math.Max(mouseWheelZoomMin, distance));

            return distance;
        }
        return desiredDistance;
    }

    // rotate oldPosition around a axis starting at axisPosition
    Vector3 RotateAroundAxis(Vector3 point, float angle, Vector3 axis, Vector3 axisPosition)
    {
        Quaternion rotation = Quaternion.AngleAxis(angle, axis);
        Vector3 offset = point - axisPosition;
        return axisPosition + (rotation * offset);
    }

    void GetMouseButtonStatus(out float x, out float y, out bool isRightDown)
    {
        x = y = 0F;
        isRightDown = false;
        if (Input.GetMouseButton(0) ^ Input.GetMouseButton(1))
        {
            x = Input.GetAxis("Mouse X") * rotateSpeed;
            y = -Input.GetAxis("Mouse Y") * rotateSpeed;
            if (Input.GetMouseButton(1))
            {
                isRightDown = true;
            }
        }
    }

    // rotate vectorP2C(player to camera) around up while mouse x is on, return true if do rotate
    Vector3 RotateX(Vector3 vectorP2C, Vector3 up, float angle)
    {
        Vector3 newVector = vectorP2C;
        if (angle != 0F)
        {
            newVector = RotateAroundAxis(newVector, angle, up, Vector3.zero);
        }
        return newVector;
    }

    // rotate vectorP2C(player to camera) around right while mouse y is on, return true is do rotate
    Vector3 RotateY(Vector3 vectorP2C, Vector3 up, Vector3 right, float angle)
    {
        Vector3 newVector = vectorP2C;
        if (angle != 0F)
        {
            if ((Vector3.Dot(vectorP2C, up) >= -0.99F || angle < 0)
                && (Vector3.Dot(vectorP2C, up) <= 0.99F || angle > 0))
            {
                newVector = RotateAroundAxis(newVector, angle, right, Vector3.zero);
            }
        }
        return newVector;
    }

    // return distance if no collision, else return distance to rigid body
    float DealWithCollision(Vector3 origin, Vector3 direction, float distance, 
        ref bool ishitGround, ref bool ishitObject)
    {
        // collision detection
        RaycastHit hitInfo;
        float newDistance = distance;
        if (Physics.Raycast(playerTransform.position, direction, out hitInfo, desiredDistance, 1))
        {
            if (hitInfo.collider is TerrainCollider)
            {
                ishitGround = true;
                ishitObject = false;
            }
            else
            {
                ishitObject = true;
                ishitGround = false;
            }
            newDistance = hitInfo.distance;
        }
        else
        {
            ishitGround = ishitObject = false;
        }

        return newDistance;
    }
}

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.

Home

Thu, 30 Nov 2023 20:09:36 +0000

Disenone's Wiki

无止境

Hi there~ 欢迎来到我的知识库。

为了避免遗忘、便于分享，我在这里收录知识。请随意浏览～

编程技术游戏开发

UE.AIChatPlus

Home

Thu, 30 Nov 2023 20:09:36 +0000

Disenone's Wiki

无止境

Hi there~ 欢迎来到我的知识库。

为了避免遗忘、便于分享，我在这里收录知识。请随意浏览～

编程技术游戏开发

UE.AIChatPlus

Home

Thu, 30 Nov 2023 20:09:36 +0000

Disenone's Wiki

无止境

Hi there~ 欢迎来到我的知识库。

为了避免遗忘、便于分享，我在这里收录知识。请随意浏览～

编程技术游戏开发

UE.AIChatPlus

Home

Thu, 30 Nov 2023 20:09:36 +0000

Disenone's Wiki

无止境

Hi there~ 欢迎来到我的知识库。

为了避免遗忘、便于分享，我在这里收录知识。请随意浏览～

编程技术游戏开发

UE.AIChatPlus

Home

Thu, 30 Nov 2023 20:09:36 +0000

Disenone's Wiki

无止境

Hi there~ 欢迎来到我的知识库。

为了避免遗忘、便于分享，我在这里收录知识。请随意浏览～

编程技术游戏开发

UE.AIChatPlus

Home

Thu, 30 Nov 2023 20:09:36 +0000

Disenone's Wiki

无止境

Hi there~ 欢迎来到我的知识库。

为了避免遗忘、便于分享，我在这里收录知识。请随意浏览～

编程技术游戏开发

UE.AIChatPlus

游戏 AOI 算法解析和性能实测

Thu, 18 Nov 2021 00:00:00 +0000

引子

AOI (Area Of Interest) 在多人在线游戏中是很基本的功能，玩家需要接收进入视野范围内的其他玩家或者实体 (Entity) 的信息。计算玩家视野范围内存在哪些实体，有哪些实体进入或离开视野的算法，我们一般称之为 AOI 算法。

本文讨论九宫格和十字链两种 AOI 算法，并给出两种算法的实测性能分析，让你用起来心中有数，遇事不慌。

文中会提到玩家和实体两种词，实体是游戏中物体的概念，玩家是拥有 AOI 的实体。

文中代码可在这里找到：AoiTesting。

九宫格

所谓九宫格，是把场景内所有实体的位置按照格子划分，譬如划分成边长 200 的正方形，要找出中心玩家 AOI 范围内的其他实体，就把这个范围内涉及到的格子内的玩家都做一遍比较。

例如场景每 100 毫秒会 Tick 一次，在 Tick 中我们可以这样更新玩家的 AOI：

以玩家位置为中心，AOI 半径计算涉及到的格子集合
对格子集合中的实体逐个计算跟玩家的距离
距离小于 AOI 半径的实体集合则是玩家的新的 AOI

九宫格算法做起来很简单，算法用几句话就能描述清楚了，具体的性能分析我们留到后面，先来看看十字链表算法。

十字链表

对于 3D 游戏，我们一般会给 X 轴和 Z 轴坐标分别构建有序的链表，每个实体在链表上都有一个节点，存放的是该坐标轴值，按照值递增的顺序来存放。但如果只是存放实体本身的坐标点，这两个链表做查询的效率依然很低。

真正关键的是，我们在链表上还会给拥有 AOI 的每个玩家增加左右两个哨兵节点。两个哨兵的坐标值跟玩家本身坐标正好相差了 AOI 半径，譬如玩家 P 坐标为 (a, b, c)，AOI 半径为 r ，那么在 X 轴上会有两个哨兵 left_x, right_x，坐标值分别为 a - r 和 a + r。由于有哨兵的存在，我们通过跟踪哨兵跟其他实体节点的移动来更新 AOI。继续前面的例子，一个实体 E 移动导致在 X 轴上的节点从 left_x 的右边想左跨过 left_x 来到 left_x 的左边，那么说明 E 肯定是离开了 P 的 AOI；同理如果向右跨过了 right_x 也是离开了 AOI。相反，如果是向右跨过 left_x，或者向左跨过 right_x，说明有可能会进入到 P 的 AOI 中。

可以看到，十字链表算法要比九宫格复杂得多，我们需要维护两条有序的链表，并且在每个实体坐标更新的时候，同步移动链表上的节点，并且在移动跨过其他节点时更新 AOI。

九宫格的实现

因为涉及到实测的性能，所以我们先来稍微深入一点九宫格算法的实现细节：

struct Sensor {
  // ...
  Nuid sensor_id;
  float radius;
  float radius_square;
  PlayerPtrList aoi_players[2];
};

struct PlayerAoi {
  // ...    
  Nuid nuid;
  SquareId square_id;
  int square_index;
  Pos pos;
  Pos last_pos;
  Uint32 flags;
  std::vector<Sensor> sensors;
};

PlayerAoi 存放玩家的数据，其中有一个 sensors 数组，sensors 就是用来计算一定范围内的实体，每次 Tick 之后把计算出来的实体计划放在 aoi_players。aoi_players 是存放了两个数组，用于上一次 Tick 结果做比较，求出进入和离开玩家。 Tick 的大致流程是这样：

AoiUpdateInfos SquareAoi::Tick() {
  AoiUpdateInfos update_infos;
  PlayerPtrList remove_list;

  for (auto& elem : player_map_) {
    auto& player = *elem.second;
    // ...
    // 对有 sensors 的玩家计算 Aoi
    if (!player.sensors.empty()) {
      auto update_info = _UpdatePlayerAoi(cur_aoi_map_idx_, &player);
      if (!update_info.sensor_update_list.empty()) {
        update_infos.emplace(update_info.nuid, std::move(update_info));
      }
    }
    // ...
  }

  // ...
  // 记录玩家上次的位置
  for (auto& elem : player_map_) {
    auto& player = *elem.second;
    player.last_pos = player.pos;
  }
  cur_aoi_map_idx_ = 1 - cur_aoi_map_idx_;
  return update_infos;
}

Tick 做的事情很简单，遍历有 sensors 的玩家，逐个计算 sensor 范围内的实体，即为 AOI。last_pos 是用来参与判断实体是否有进入或者离开 AOI，_UpdatePlayerAoi 的代码如下：

AoiUpdateInfo SquareAoi::_UpdatePlayerAoi(Uint32 cur_aoi_map_idx, PlayerAoi* pptr) {
  AoiUpdateInfo aoi_update_info;
  aoi_update_info.nuid = pptr->nuid;
  Uint32 new_aoi_map_idx = 1 - cur_aoi_map_idx;

  for (auto& sensor : pptr->sensors) {
    auto& old_aoi = sensor.aoi_players[cur_aoi_map_idx];
    auto& new_aoi = sensor.aoi_players[new_aoi_map_idx];
    (this->*calc_aoi_players_func_)(*pptr, sensor, &new_aoi);

    SensorUpdateInfo update_info;

    auto& enters = update_info.enters;
    auto& leaves = update_info.leaves;
    float radius_square = sensor.radius_square;

    _CheckLeave(pptr, radius_square, old_aoi, &leaves);
    _CheckEnter(pptr, radius_square, new_aoi, &enters);

    if (enters.empty() && leaves.empty()) {
      continue;
    }

    update_info.sensor_id = sensor.sensor_id;
    aoi_update_info.sensor_update_list.push_back(std::move(update_info));
  }

  return aoi_update_info;
}

old_aoi 是上一个 Tick 计算出来的 AOI，new_aoi 是本次 Tick 需要计算的 AOI。new_aoi 通过遍历 AOI 范围内的所有格子的实体，选出跟玩家距离小于 AOI 半径来获得。之后用 _CheckLeave 和 _CheckEnter 两个函数，计算本次 Tick 离开和进入 AOI 的实体，譬如如果 new_aoi 中的实体 last_pos 不在 AOI范围内，说明该实体是在本次 Tick 进入到了 AOI 范围。具体的代码可以看源文件，这里不再赘述。

十字链表的实现

相比起九宫格，十字链表实现起来更复杂，先来看基本的数据结构：

struct CoordNode {
  // ...
  Uint8 type;
  float value;
  CoordNode *prev = nullptr;
  CoordNode *next = nullptr;
  PlayerAoi *pplayer;
  Sensor *psensor;

};

KHASH_MAP_INIT_INT64(SensorHashMap, PlayerAoi*);

struct Sensor {
  // ...
  Nuid sensor_id;
  float radius;
  float radius_square;
  PlayerAoi *pplayer;
  CoordNode left_x;
  CoordNode right_x;
  CoordNode left_z;
  CoordNode right_z;
  PlayerPtrList aoi_players[2];

  std::shared_ptr<khash_t(SensorHashMap)> aoi_player_candidates;
};

struct PlayerAoi {
  // ...
  Nuid nuid;
  Pos pos;
  Pos last_pos;
  Uint32 flags;
  CoordNode node_x;
  CoordNode node_z;
  std::vector<Sensor> sensors;
  std::shared_ptr<boost::unordered_map<Nuid, std::vector<Nuid>>> detected_by;
};

Sensor 和 PlayerAoi 跟九宫格有部分相似，不过多了链表相关的节点结构 CoordNode。CoordNode 就是链表上的一个节点，记录了本身节点的类型和数值，类型有三种：玩家节点，Sensor 左节点，Sensor 右节点。

十字链表的大部分工作都是在维持链表的有序：

玩家加入时需要把玩家节点移动到有序的位置上，并且在移动玩家节点的同时，处理进入或者离开其他玩家 AOI 事件。
玩家移动到正确的位置后，Sensor 左右节点从玩家前后位置出发，移动到正确的位置，并处理跨过其他玩家节点时触发的进入和离开事件。
玩家移动时，更新玩家的坐标，并移动玩家节点和 Sensor 左右节点，处理 AOI 进入离开。

移动节点的代码如下，每跨过一个节点，都会调用一次 MoveCross 函数，由 MoveCross 函数根据移动方向，移动节点和跨过节点的类型来决定是进入还是离开 AOI。

void ListUpdateNode(CoordNode **list, CoordNode *pnode) {
  float value = pnode->value;

  if (pnode->next && pnode->next->value < value) {
    // move right
    auto cur_node = pnode->next;
    while (1) {
      MoveCross(MOVE_DIRECTION_RIGHT, pnode, cur_node);
      if (!cur_node->next || cur_node->next->value >= value) break;
      cur_node = cur_node->next;
    }

    ListRemove(list, pnode);
    ListInsertAfter(list, cur_node, pnode);

  } else if (pnode->prev && pnode->prev->value > value) {
    // move left
    auto cur_node = pnode->prev;
    while (1) {
      MoveCross(MOVE_DIRECTION_LEFT, pnode, cur_node);
      if (!cur_node->prev || cur_node->prev->value <= value) break;
      cur_node = cur_node->prev;
    }

    ListRemove(list, pnode);
    ListInsertBefore(list, cur_node, pnode);
  }
}

链表的移动很慢，是 O(n) 的复杂度，特别是在玩家新加入场景时，玩家需要从无穷远的地方，逐步移动到正确的位置上，为此需要大量遍历的节点，消耗很大。为了优化性能，我们可以在场景中固定位置放置灯塔，这种灯塔处理上跟玩家大致相同，只是比玩家多记录了一份 detected_by 数据，detected_by 是用来记录该哨兵实体处在哪些 Sensor 范围内。玩家首次进入场景时，不再从最远处开始移动，而是找到一个最近的灯塔，把节点插入到灯塔旁边，并通过灯塔身上的 detected_by 数据，快速进入到跟灯塔一致的其他玩家的 AOI 范围内，然后开始移动到正确的位置上，当然移动的时候也要处理进入和离开。同理，对于 Sensor，也可以通过先继承灯塔的数据，然后从灯塔的位置上移动到正确位置上。通过这两种优化能够提升一倍以上的插入玩家性能。

Sensor 身上还有一个名叫 aoi_player_candidates 的 HashMap（这里为了性能，使用了khash）。节点移动触发的 AOI 事件，其实只能检测到 X-Z 坐标轴上边长为 2r 的正方形区域，不是我们严格意义上的圆形区域的 AOI，这个正方形的区域内的实体都被记录在 aoi_player_candidates 上，并在 Tick 中遍历计算圆形区域内的 AOI 范围，所以称为 candidates。

所有十字链表的操作都是为了一直维护正方形区域内的实体 candidates，十字链表中 Tick 做的操作跟九宫格几乎一致，只是遍历计算 AOI 的 candidates 不相同。九宫格的 candidates 是 AOI 圆形区域所覆盖到的格子的实体，而十字链表则是由 Sensor 左右节点所界定的边长为 2r 的正方形区域中的实体。定性的来说，十字链表的 candidates 一般都要比九宫格少，所以在 Tick 中的遍历次数少，性能更优，只是十字链表还有大量额外的性能消耗在了维护链表上，这两者整体的性能到底孰优孰劣，我们接下来实测看看。

性能实测

我这里分别测了玩家加入场景（Add Player），计算 AOI 进出事件（Tick），玩家更新坐标位置（Update Pos）三种情况的时间消耗。

玩家初始位置在地图范围内随机生成，然后把玩家加入场景。player_num 是玩家数量，map_size 则是地图 X-Z 坐标轴范围，玩家的位置在此范围内均匀随机生成，每个玩家都有一个半径 100 的 Sensor 作为 AOI，计算时间用的是 boost::timer::cpu_timer。player_num 分别选了 100, 1000, 10000 三种情况，而 map_size 则选了 [-50, 50], [-100, 100], [-1000, 1000], [-10000, 10000] 四种情况。

更新玩家位置会让玩家固定随机方向，以 6m/s 的速度移动。

本次测试环境为：

CPU: Intel(R) Core(TM) i5-4590 CPU @ 3.30GHz
系统: Debian GNU/Linux 10 (buster)
gcc 版本: gcc version 8.3.0 (Debian 8.3.0-6)
boost 版本: boost_1_75_0

九宫格实测

九宫格的测试结果如下：

===Begin Milestore: player_num = 100, map_size = (-50.000000, 50.000000)
Add Player (1 times) 0.000081s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Tick (1 times) 0.000452s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Update Pos (10 times) 0.000230s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
===End Milestore

===Begin Milestore: player_num = 100, map_size = (-100.000000, 100.000000)
Add Player (1 times) 0.000070s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Tick (1 times) 0.000338s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Update Pos (10 times) 0.000185s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
===End Milestore

===Begin Milestore: player_num = 100, map_size = (-1000.000000, 1000.000000)
Add Player (1 times) 0.000084s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Tick (1 times) 0.000103s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Update Pos (10 times) 0.000187s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
===End Milestore

===Begin Milestore: player_num = 100, map_size = (-10000.000000, 10000.000000)
Add Player (1 times) 0.000084s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Tick (1 times) 0.000080s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Update Pos (10 times) 0.000185s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
===End Milestore

===Begin Milestore: player_num = 1000, map_size = (-50.000000, 50.000000)
Add Player (1 times) 0.000673s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Tick (1 times) 0.035298s wall, 0.030000s user + 0.000000s system = 0.030000s CPU (85.0%)
Update Pos (10 times) 0.001841s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
===End Milestore

===Begin Milestore: player_num = 1000, map_size = (-100.000000, 100.000000)
Add Player (1 times) 0.000664s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Tick (1 times) 0.025806s wall, 0.030000s user + 0.000000s system = 0.030000s CPU (116.3%)
Update Pos (10 times) 0.001842s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
===End Milestore

===Begin Milestore: player_num = 1000, map_size = (-1000.000000, 1000.000000)
Add Player (1 times) 0.000721s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Tick (1 times) 0.001793s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Update Pos (10 times) 0.001849s wall, 0.010000s user + 0.000000s system = 0.010000s CPU (540.8%)
===End Milestore

===Begin Milestore: player_num = 1000, map_size = (-10000.000000, 10000.000000)
Add Player (1 times) 0.000885s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Tick (1 times) 0.000804s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Update Pos (10 times) 0.001855s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
===End Milestore

===Begin Milestore: player_num = 10000, map_size = (-50.000000, 50.000000)
Add Player (1 times) 0.006454s wall, 0.010000s user + 0.000000s system = 0.010000s CPU (154.9%)
Tick (1 times) 3.822028s wall, 3.800000s user + 0.020000s system = 3.820000s CPU (99.9%)
Update Pos (10 times) 0.018402s wall, 0.020000s user + 0.000000s system = 0.020000s CPU (108.7%)
===End Milestore

===Begin Milestore: player_num = 10000, map_size = (-100.000000, 100.000000)
Add Player (1 times) 0.006439s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Tick (1 times) 2.805551s wall, 2.760000s user + 0.040000s system = 2.800000s CPU (99.8%)
Update Pos (10 times) 0.018489s wall, 0.010000s user + 0.000000s system = 0.010000s CPU (54.1%)
===End Milestore

===Begin Milestore: player_num = 10000, map_size = (-1000.000000, 1000.000000)
Add Player (1 times) 0.006698s wall, 0.010000s user + 0.000000s system = 0.010000s CPU (149.3%)
Tick (1 times) 0.093759s wall, 0.100000s user + 0.000000s system = 0.100000s CPU (106.7%)
Update Pos (10 times) 0.018350s wall, 0.010000s user + 0.000000s system = 0.010000s CPU (54.5%)
===End Milestore

===Begin Milestore: player_num = 10000, map_size = (-10000.000000, 10000.000000)
Add Player (1 times) 0.009046s wall, 0.010000s user + 0.000000s system = 0.010000s CPU (110.6%)
Tick (1 times) 0.012091s wall, 0.010000s user + 0.000000s system = 0.010000s CPU (82.7%)
Update Pos (10 times) 0.019033s wall, 0.020000s user + 0.000000s system = 0.020000s CPU (105.1%)
===End Milestore

九宫格在玩家数量 100 时，三种操作耗时都很小，极限情况 map_size = [-50, 50]，所有玩家互相都处于 AOI 范围内，Tick 耗时大概 0.4ms。玩家加入场景和更新坐标都是线性复杂度 O(player_num)，性能表现都不错。在 player_num = 10000, map_size = [-50, 50] 玩家人数达到 1 万的时候，Add Player 和 Update Pos 由于都是线性，几毫秒内就能完成，但 Tick 耗时就去到 3.8s，需要消耗大量 CPU，属于不可用了。人数 1 万，地图大小 [-1000, 1000]，情况下，Tick 时间消耗大概 94ms，如果能够降低 Tick 频率的话，譬如一秒两次，还是勉强属于可用的范围内。

十字链表实测

十字链表的测试结果如下：

===Begin Milestore: player_num = 100, map_size = (-50.000000, 50.000000)
Add Player (1 times) 0.002057s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Tick (1 times) 0.000330s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Update Pos (10 times) 0.000232s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
===End Milestore

===Begin Milestore: player_num = 100, map_size = (-100.000000, 100.000000)
Add Player (1 times) 0.001201s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Tick (1 times) 0.000222s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Update Pos (10 times) 0.000272s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
===End Milestore

===Begin Milestore: player_num = 100, map_size = (-1000.000000, 1000.000000)
Add Player (1 times) 0.000288s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Tick (1 times) 0.000048s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Update Pos (10 times) 0.000200s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
===End Milestore

===Begin Milestore: player_num = 100, map_size = (-10000.000000, 10000.000000)
Add Player (1 times) 0.000194s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Tick (1 times) 0.000041s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Update Pos (10 times) 0.000192s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
===End Milestore

===Begin Milestore: player_num = 1000, map_size = (-50.000000, 50.000000)
Add Player (1 times) 0.130766s wall, 0.130000s user + 0.000000s system = 0.130000s CPU (99.4%)
Tick (1 times) 0.028091s wall, 0.020000s user + 0.000000s system = 0.020000s CPU (71.2%)
Update Pos (10 times) 0.005369s wall, 0.010000s user + 0.000000s system = 0.010000s CPU (186.2%)
===End Milestore

===Begin Milestore: player_num = 1000, map_size = (-100.000000, 100.000000)
Add Player (1 times) 0.103015s wall, 0.100000s user + 0.000000s system = 0.100000s CPU (97.1%)
Tick (1 times) 0.019545s wall, 0.020000s user + 0.000000s system = 0.020000s CPU (102.3%)
Update Pos (10 times) 0.009208s wall, 0.010000s user + 0.000000s system = 0.010000s CPU (108.6%)
===End Milestore

===Begin Milestore: player_num = 1000, map_size = (-1000.000000, 1000.000000)
Add Player (1 times) 0.010150s wall, 0.010000s user + 0.000000s system = 0.010000s CPU (98.5%)
Tick (1 times) 0.000845s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Update Pos (10 times) 0.003023s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
===End Milestore

===Begin Milestore: player_num = 1000, map_size = (-10000.000000, 10000.000000)
Add Player (1 times) 0.004950s wall, 0.010000s user + 0.000000s system = 0.010000s CPU (202.0%)
Tick (1 times) 0.000427s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
Update Pos (10 times) 0.002234s wall, 0.000000s user + 0.000000s system = 0.000000s CPU (n/a%)
===End Milestore

===Begin Milestore: player_num = 10000, map_size = (-50.000000, 50.000000)
Add Player (1 times) 21.606402s wall, 21.040000s user + 0.570000s system = 21.610000s CPU (100.0%)
Tick (1 times) 3.696885s wall, 3.680000s user + 0.030000s system = 3.710000s CPU (100.4%)
Update Pos (10 times) 0.434396s wall, 0.430000s user + 0.000000s system = 0.430000s CPU (99.0%)
===End Milestore

===Begin Milestore: player_num = 10000, map_size = (-100.000000, 100.000000)
Add Player (1 times) 18.499235s wall, 18.470000s user + 0.020000s system = 18.490000s CPU (100.0%)
Tick (1 times) 2.292608s wall, 2.290000s user + 0.000000s system = 2.290000s CPU (99.9%)
Update Pos (10 times) 1.522617s wall, 1.530000s user + 0.000000s system = 1.530000s CPU (100.5%)
===End Milestore

===Begin Milestore: player_num = 10000, map_size = (-1000.000000, 1000.000000)
Add Player (1 times) 1.642519s wall, 1.640000s user + 0.000000s system = 1.640000s CPU (99.8%)
Tick (1 times) 0.042767s wall, 0.050000s user + 0.000000s system = 0.050000s CPU (116.9%)
Update Pos (10 times) 0.202949s wall, 0.200000s user + 0.000000s system = 0.200000s CPU (98.5%)
===End Milestore

===Begin Milestore: player_num = 10000, map_size = (-10000.000000, 10000.000000)
Add Player (1 times) 0.571257s wall, 0.570000s user + 0.000000s system = 0.570000s CPU (99.8%)
Tick (1 times) 0.006325s wall, 0.010000s user + 0.000000s system = 0.010000s CPU (158.1%)
Update Pos (10 times) 0.042568s wall, 0.040000s user + 0.000000s system = 0.040000s CPU (94.0%)
===End Milestore

如我们分析一致，十字链表在 Add Player 和 Update Pos 上耗时更长，特别是 Add Player，相比九宫格性能差了几百甚至上万倍（100, [-50, 50] 十字链耗时 2ms，而九宫格只有 0.08ms；10000, [-50, 50] 十字链 21.6s，九宫格只有 6ms。Update Pos 的耗时也最多会有百倍的差距，10000, [-100, 100] 十字链更新玩家位置耗时 1.5s，而九宫格是 18ms。可以看出，十字链在 Add Player 和 Update Pos 耗时的上下限范围比九宫格要大，受人数和地图大小影响更大，在玩家密集的区域，这两个操作的性能会急速下降，直至不可用。

反观十字链的 Tick 操作，整体性能确实是比九宫格好，最好的情况耗时大概只有九宫格的一半左右（ 1000, [-1000, 1000] 下十字链耗时 0.8ms，九宫格 1.8ms），但是最差的情况十字链会退化到跟九宫格的性能接近（10000, [-10000, 10000] 下十字链耗时 3.7s，九宫格 3.8s。这是因为由于场景小，玩家互相都在彼此的 AOI 范围内，十字链 Tick 遍历的 candidates 数量, 其实已经跟九宫格很接近了。

十字链使用起来要达到比九宫格性能更优，需要一些更强的假设，譬如 player_num = 1000, map_size = [-1000, 1000] 情况下，Tick 耗时十字链为 0.8ms 九宫格 1.8ms，Update Pos 十字链为 0.3ms 九宫格 0.18ms（注意测试 Update Pos 时间为执行了 10 次的时间总和）。Tick + Update Pos 总时间下，十字链如果要比九宫格更少，那 Update Pos 的次数不能超过 Tick 的 8 倍，或者说两个 Tick 之间，Update Pos 的次数需要小于 8 次。另外因为十字链 Add Player 耗时巨大，不适用于玩家短时间频繁出入场景或者在场景内大范围传送的情况，另外如果短时间内有大量玩家进入场景，也很容易导致性能下降，大量占用 CPU。

对于十字链表，在一个前提之下还能做一个优化：干掉 Tick，前提是游戏能接受正方形的 AOI，并且需要实测正方形 AOI 带来的其他诸如网络等消耗是能接受的。其实前提是比较苛刻的，因为在游戏中 AOI 计费能占用的 CPU 通常占比是不大的，但把圆形 AOI 改成方形 AOI 导致 AOI 范围面积增大，范围内的玩家数量也增多，均匀分布下玩家数量可能会增多到原来的 1.27 倍。但是，一旦能满足前提，十字链表可以做到不需要 Tick 来定期更新 AOI 事件，因为实现上十字链表的 candidates 就维护了一份方形下 AOI，原来只是为了计算圆形 AOI，而不得不在 Tick 中再遍历计算距离。在这种情况下，十字链是有可能能够达到很好的性能，因为十字链表 Update Pos 的性能可以跟 Tick 相差几倍到几十倍。

最后给出两者的对比柱状图：

总结

本文我们介绍了两种 AOI 算法（九宫格和十字链）的原理和基本实现，并通过实测的数据分析了这两种算法的性能优劣，希望能够给读者带来一些帮助或者启发。

总的来说，九宫格法实现简单，性能均衡不容易拉胯，非常适合 AOI 不是性能瓶颈的游戏来使用，九宫格法的性能波动范围是在可预期的范围内，性能下限比较高，也不容易导致瓶颈，但另一方面可优化空间也不大，时间复杂度比较固定。反观十字链法，实现要更复杂，性能下限比九宫格法低，但是如果能够满足一些假设和前提，十字链可优化空间更高，换句话说是上限是可以更高。这两种方法各有优劣，游戏业界内也有不同的引擎分别选择了两者之一，各取所需，见仁见智。

本人能力有限，文中内容仅代表本人想法，如有不足不妥之处欢迎留言讨论。

原文地址：https://wiki.disenone.site

本篇文章受 CC BY-NC-SA 4.0 协议保护，转载请注明出处。

Visitors. Total Visits. Page Visits.