使用 p 语言编写 Crusader Kings 3 模组

获取文档¶

CK3 官方维基，其中包含一些有关 modding 的内容。

以调试模式启动游戏，在控制台输入 script_docs，将在 Documents/Paradox Interactive/Crusader Kings III/logs 中生成以下 .log 文件：

文件名	描述
`Effects.log`	包含所有非脚本化（硬编码）效果的列表，它们的使用方式以及它们的潜在参数
`Triggers.log`	包含游戏中找到的每个非脚本化触发器的列表，以及它们支持的作用域和目标
`Modifiers.log`	可以在脚本化修正中使用的每个修正的列表，以及它们的适用类型
`event_scopes.log`	每个有效的作用域类型
`event_targets.log`	识别的每个可能的事件目标

在游戏安装目录的 game 文件夹中的每一个 .info 文件。例如 game/common/character_interactions/_character_interactions.info 包含了所有角色互动的定义和简易文档。
在游戏安装目录中的 game 文件夹下，可以找到游戏中几乎所有的功能的实现，从中可以寻找用例。可以事先使用 git 进行版本控制，当不慎修改游戏本体文件时，可以方便地进行回滚。

术语约定¶

英文	中文
`effect`	效果
`trigger`	触发器
`modifier`	修正
`scope`	作用域

语法¶

用于编写 CK3 模组的 P 语言文件必须以 UTF-8 with BOM 编码。

作用域¶

作用域是对一个对象的引用，可以调用对象的方法和属性。作用域可以是一个角色、国家、事件等。作用域的类型决定了可以调用的方法和属性。

作用域通过 save_as_scope 和 save_as_temporary_scope 拷贝。save_as_scope 保存的作用域可以在整个脚本中使用，而 save_as_temporary_scope 保存的作用域只能在当前作用域中使用。

游戏提供 ROOT、this、prev 等特殊作用域。

TODO：特殊作用域的用例

基本语法¶

P 语言使用 = 来表示判断、赋值、调用等一系列操作；使用 {} 组织层级关系或表示作用域；使用 scope:xxx 来引用作用域，限定影响范围。使用 # 进行注释。

对作用域 alice，使用 scope:alice 引用该作用域。

使用 scope:alice.<method> 或者 scope:alice = { <method> } 调用该作用域的方法。

使用 scope:alice.<property> 或者 scope:alice = { <property> } 调用该作用域的属性。

逻辑运算¶

游戏提供逻辑运算符 NOT、AND、OR、NOR、NAND。逻辑运算符对布尔值进行操作，返回布尔值，例如：

AND = {
    scope:alice = { is_female = yes }
    NOT = { scope:bob = { is_female = yes } }
}

将返回 yes。

流程控制¶

游戏提供 if 语句进行条件判断，其语法如下：

if = {
    limit = { <condition> }
    <effect>
}
else_if = {
    limit = { <condition> }
    <effect>
}
else = {
    <effect>
}

遍历¶

游戏提供 every_xxx 、ordered_xxx、random_xxx 等效果关键字进行遍历。

提供 any_xxx 效果关键字进行遍历与判断。

可以从 effects.log 和 triggers.log 中查找到所有用于遍历的关键字。

参数调用¶

P 语言使用 $arg$ 来进行参数调用。参数可以传递给脚本化的效果、触发器、修正等。

在本地化文本中，使用 $key$ 可以引用其它已经存在的本地化键值。

在本地化文本中，使用 [] 调用一个数据类型以动态地输出特定的文本字符串。这些数据类型通过对作用域使用内置的 GetXxx 方法得到。此外，对于不同游戏内容，分别提供了不同的作用域可供本地化文件访问。例如，在互动中，使用 [recipient.GetShortUIName] 可以输出互动的目标的简短 UI 名称；使用 [GetTrait('beauty_good_3').GetName( GetNullCharacter )] 输出三级美貌特质的默认名称。

在游戏内容的本地化文字加载过程中，将 [] 替换为对应的文本【早于】将本地化文件加载到脚本中【早于】将 $key$ 替换为对应的文本。

脚本化效果、修正、触发器¶

类似于函数。

TODO：脚本化效果、修正、触发器的用例

调试¶

以调试模式进入游戏，可以显示更多信息，例如在角色交互中，各个作用域指向的对象。

通过在代码中添加 error_log = {" ... "} 来进行插桩。

查看游戏的错误日志，可以在 Documents/Paradox Interactive/Crusader Kings III/logs/error.log 中找到。在错误日志中检索正在编写的脚本名。

用户界面¶

TODO：UI