Modding, 或称为“模组制作”, is the act of modifying the behavior of the base game (often referred as vanilla), either for personal use, or to release publicly to other players, for instance via the Steam Workshop.

就所有p社游戏而言,ck2的模组制作有很大开放性,可以很显著的延伸游戏的内容,增强游戏的可玩性。 mod制作者的动机各不相同:更好的翻译成母语,更多的事件及决议,更棒的地图,亦或游戏整体大修改等等。



  • 为您的修改创建mod:即使是小的更改也要创建个人mod,并且切勿直接修改Steam CKII文件夹中的游戏文件,因为它们可能会在没有警告的情况下被覆盖。
  • 使用优质的文本编辑器 来编辑文件并搜索多个文件。请参见文本编辑器
  • 验证你的mod 使用The Validator,它将为您节省许多麻烦和时间,以解决崩溃和错误。
  • 尽量减少对Vanilla文件的覆盖 通过添加单独的文件或尽可能地从文件夹加载,以改善mod兼容性和维护。
  • 使用适当的合并工具 以便在文件夹之间合并,并将修改后的Vanilla文件更新为新的Vanilla补丁。
  • 备份您的工作 以避免丢失一切。如果是一个MOD制作组,请考虑使用诸如GitHub之类的源代码控制系统充当备份并管理协作。
  • 使用ANSI(Windows-1252)编码 用于文本文件。
  • 适当缩进 以轻松发现未闭合的花括号。Vanilla使用1个制表符来缩进而不是空格。
  • 使用注释 以#字符开头,来记住编写棘手内容的原因。




mod文件被放置在 ~\Paradox Interactive\Crusader Kings II\mod, 里面必须包含:

  • .mod 文件, 告诉启动器如何加载你的mod
  • 包含mod数据好的文件夹或者是zip压缩包。mod数据的文件结构必须和本体file and folder structure相同,注意文件夹和文件的名称大小写在Mac和Linux上市敏感的,这意味着 Abc 和 abc 会被视为两个mod。

.mod 文件的文件名不能包含任何空格,否则在启动器重启的时候,不会被自动选中。

.mod 文件的内容如下所示:

关键字 必需? 效果 例子
name Yes 你的mod显示在启动器中的名称 name = "My Mod"
path Yes 定义那个文件夹是你的mod文件夹。 其路径是相对于~\Documents\Paradox Interactive\Crusader Kings II\ . path = "mod/MyMod"
user_dir No 告诉启动器存储游戏或临时文件到特定的文件夹。 这对能改善mod的兼容性(例如新的标题,旗帜,宗教,文化,建筑之类的),让文件不会混淆在一起。

警告:不要给主mod的子mod设置 user_dir,因为所有激活mod的user_dir会连接在一起。

user_dir = "MyMod"
archive No 定义一个zip压缩包来代替文件夹。设置它的路径,路径是相对于 ~\Documents\Paradox Interactive\Crusader Kings II\ 的。这是从Steam Workshop下载的mod使用的格式,但是在将mod上传到Workshop时,必须使用path结构。 archive = "mod/mymod.zip"
replace_path No 告诉启动器覆盖对应文件夹得所有内容,并且只从mod中的指定路径加载。 This is the only way to effectively remove stuff from vanilla, and is most often used for total conversion mods.


  • replace_path works with folders, not files. To overwrite a file, just create a file with the same name in the mod.
  • replace_path only affects files in the specified folder, not files in sub-folders within that folder. For instance, replacing "history" does not replace "history/characters" as well.
  • To reduce mod size and improve mod compatibility, it is usually best to minimize the amount of folders that are replace_path.
  • replace_path is ignored when installing mod in the old Crusader Kings II\mod folder, hence why user mod folder must be used.
  • Unless you are sure you do need replace_path, you almost certainly don't.
replace_path = "history"

replace_path = "history/characters"

dependencies No Tells the launcher that another mod has to be loaded before this one. The other mod will be loaded first, allowing the 2nd mod to override some files (otherwise the 1st mod would win). A dependency is not a hard requirement; you do not need a dependency loaded if the mod has one set. This is simply a way for the mod file to tell the launcher which files should be loaded first. dependencies = { "Another Mod" "Yet Another Mod" }
picture No Image under mod folder to serve as banner for Steam Workshop (will be displayed as 268px × 268px JPEG) picture = "MyMod.jpg"
tags No List of tags for Steam Workshop. Warning: don't forget quotes for tags that contain spaces. tags = { "Tag1" "Tag 2" }
supported_checksums No List of expected checksums for which scripting condition supported_checksums will evaluate to true. This can be used in event modding to display a warning to the player. supported_checksums = { ABCD EFGH }

Below are some examples mod files, depending on the category of the mod:


小型 mod更常见一些,为了保证和其它小型mod 的兼容性,请不要使用user_dir或者是replace_path

 name = "Small Mod"
 path = "mod/SmallMod"
 picture = "SmallMod.jpg"
 tags = { "Mods" "Small" }


Overhaul mods typically use user_dir as saves wouldn't be loadable outside of the mod anyway. For total conversion mods, replace_path can be used to completely ignore vanilla directories that don't make sense in the context of the mod (history, flags, ...)

 name = "Big Mod"
 path = "mod/BigMod"
 user_dir = "BigMod"
 replace_path = "history/provinces" 
 picture = "BigMod.jpg"
 tags = { "Mods" "Big" }


主mod 的子mod 通常用 dependencies 来覆盖主mod 的文件。

 name = "Sub Mod"
 path = "mod/SubMod"
 dependencies = { "Main Mod" }
 picture = "SubMod.jpg"
 tags = { "Mods" "Main Mod" }



The game data is composed of hierarchy of folders, containing game files.

A mod follows the same folder structure as the base game, so that when loading the game the engine will combine files from vanilla and mod(s). In most folders, the engine will load all the files within, which allows a mod to add new definitions (titles, religions, ...) without having to copy and modify vanilla files. To make use of this, it is important to understand how the scripts are loaded both at file level and definition level.

The behavior when loading a mod is the following:

  • Engine processes folders and files based on some hardcoded load order.
  • If current folder is defined as replace_path, all vanilla files in that folder will be ignored, and only mod files will be loaded (if any).
  • If the mod folder and vanilla folder both contain files with same names, vanilla files will be ignored and mod version will be used.
  • Inside a given folder, the order in which files are processed is usually alphanumerical on combined vanilla and mod file names, though some folders may have a different behavior.
  • When encountering more than once the same definition (title, religion, decision, ...), the duplicate definition may:
    • be ignored (first definition wins)
    • fully override the previous definition (last definition wins)
    • partially override the previous definition (definitions are merged/additive, which only makes sense if there is actually something to merge: hierarchy, list, etc.)
    • coexist/break both (in which case duplicate IDs must be avoided)

Below is a list of CKII game files and folders, with associated modding guide, and loading behavior.

For loading behavior, the cell colours highlight whether the behaviour is the expected one, strange or requiring some attention, or unexpected and to be avoided.

File/Folder What it contains How to mod Loading behavior
  • achievements.txt
  • defines.lua
  • defines.txt
  • hints.txt
  • region_colors.txt
  • static_modifiers.txt
  • technology.txt
General information
  • Defines Steam Achievements
  • POP, general, diplomatic, economic and military variables
  • Defines playable start- and end-date
  • Defines the displayed hints
  • RGB code for each region
  • All difficulty, rank and standard modifiers
  • Technology data


Static modifiers
Technology modding

.\common\alternate_start\ Alternate start modding [?] Merge
.\common\artifact_spawns\ Artifact modding Merge.
.\common\artifacts\ Definitions of artifacts Artifact modding Merge.
.\common\bloodlines\ Bloodline modding
.\common\bookmarks\ Bookmarks are configured here (scenarios/start dates) Bookmark modding Merge. Bookmarks are listed chronologically in-game, whatever the order in files.
.\common\buildings\ Buildings folder, all buildings are stored here. Building modding [?] Merge
.\common\cb_types\ Casus Belli folder, all Casus-belli are stored here. Casus Belli modding Merge, but override of casus belli by re-using same name does not work (creates duplicate casus belli)
.\common\combat_tactics\ Combat tactics definitions. Unit modding [?] Merge
.\common\council_positions\ Conditions for an A.I. councillor to adopt a certain category of voting behavior. Councillor modding [?]
.\common\council_voting\ A.I. rules for how councillors from a behavior category will vote Councillor modding [?]
.\common\cultures\ Cultures folder, all cultures are stored here. Culture modding Merge. Since patch 2.4 cultures are merged like religions, and a new culture may be added to a vanilla culture_group via a separate file.
.\common\death\ Death definitions Death modding
.\common\death_text\ Flavor text for succession screen Death modding
.\common\defines\ Defines. Defines [?] Merge. Entries in files override common/defines.lua values.
.\common\disease\ Diseases definitions. Disease modding [?] Merge
.\common\dynasties\ Dynasties folder, all dynasties are stored here. Dynasty modding. Merge. Duplicate dynasties loaded before vanilla (i.e., 000_ prefix) will overwrite dynasty shields. Duplicates loaded after (i.e., z_ prefix) will overwrite dynasty names. To overwrite both, use duplicate files, one with a preceding prefix and one with a succeeding prefix.
.\common\event_modifiers\ Event_modifiers folder, all event modifiers are stored here Modifiers Merge.
.\common\execution_methods\ Execution methods Death modding [?]
.\common\game_rules\ Game rules definitions Game rules modding Merge. The rules are displayed in UI based on order of files (alphanumerical on file name), then order of rules within the file.
.\common\government_flavor\ Government naming definitions Government modding [?]
.\common\governments\ Government definitions Government modding Merge. It is possible to define governments of the same government group in different files.
.\common\graphicalculturetypes\ Graphicalculturetypes folder, all graphical culture types are stored here [?] Merge
.\common\heir_text\ Flavor text for succession screen Death modding
.\common\holding_types\ Conditions for being allowed to build each holding type. Government modding [?]. It is not possible to add new holding types.
.\common\job_actions\ Defines councillors actions Councillor modding Merge.
.\common\job_titles\ Defines councillors titles Councillor modding [?]
.\common\landed_titles\ Landed_titles folder, all landed titles are stored here. Title modding Merge. Merging behaviour is "complicated and might not have been designed that way intentionally"[1]
.\common\laws\ Law modding Merge. A law with the same name as an existing law will append conditions to the allow section, but not the potential section.
.\common\mercenaries\ Mercenaries folder, all mercenaries are stored here [?] Merge
.\common\minor_titles\ Minor_titles folder, all minor (i.e. honorary) titles are stored here Minor title modding Cannot be overridden, attempts to do so will result in multiple minor titles with the same tags, like traits
.\common\modifier_definitions\ Defines dynamically defined modifiers, in particular special units modifiers. Unit modding [?] Merge
.\common\nicknames\ Nicknames folder, all nicknames are stored here Merge.
.\common\objectives\ Objectives folder, all objectives (i.e. ambitions, factions, and plots) are stored here. Objective modding [?] Merge
  • policies\
  • statuses\
Defines nations not represented on the map, but with a significant influence over it. Offmap power modding [?] Merge. Does NOT require Jade Dragon DLC.
.\common\on_actions\ On_actions folder, all on_actions are stored here Event modding Merge. Since patch 2.4 on_actions are merged, with new events being added to the previous list for a particular on_action, instead of replacing the list.
.\common\opinion_modifiers\ Opinion modifiers folder, all opinion modifiers are stored here Modifiers [?] Merge
.\common\province_setup\ Deprecated since patch 3.0.
.\common\religion_features\ Religion modding [?] Merge, but features with the same key get duplicated
.\common\religion_modifiers\ Religion_modifiers folder, all religion modifiers are stored here. Modifiers [?] Merge
.\common\religions\ Religions folder, all religions are stored here. Religion modding
Merge. Vanilla religions can be overridden, without needing to duplicate the whole religion group. Restrictions: need to define reformed religion before the non-reformed.
.\common\religious_titles\ Religious_titles folder, all religious titles are stored here [?] Merge
.\common\retinue_subunits\ Retinue subunits folder, all retinue subunits are stored here [?] Merge, but retinues with the same key get duplicated
.\common\save_conversion\ Save game compatibility [?]
.\common\scripted_effects\ Scripted effects [?] Merge
.\common\scripted_score_value\ Scripted score value [?] Merge
.\common\scripted_triggers\ Scripted triggers Merge, but scripted triggers with same name append their conditions rather than replacing the original one.
.\common\societies\ Definition of societies Society modding Merge, but override of societies by re-using same name does not work (creates duplicate societies)
.\common\special_troops\ Special units definitions Unit modding [?] Merge
.\common\stories\ Not used. N/A
.\common\succession_voting\ Succession modding [?] Merge
.\common\trade_routes\ Trade route definitions. Trade route modding [?]
.\common\traits\ Traits folder, all traits are stored here. Trait modding Merge, but traits with same name will co-exist, and generated characters may get both versions of the trait at the same time. The last definition gets assigned to a character when using commands.
.\common\tributary_types\ Tributary relationship definitions. Tributary modding [?]
.\common\triggered_modifiers\ Defines global modifiers that trigger under certain conditions Triggered modifiers [?] Merge
.\connectui\ Appears to be leftover interface for the discontinued Paradox Connect service (used in older Clausewitz games CK2 is based on). Unusable
.\decisions\ Decisions folder, all decisions are stored here Decision modding Merge, but override of decision by re-using same name does not work (breaks the decision effect, that does nothing)
.\dlc\ Contains DLC information and zipped content files DLC files N/A
.\dlc_metadata\ ? ?
.\eu4_converter\ Europa Universalis 4 Save Converter folder, all files related to the EUIV converter are stored here.

Note: vanilla files were moved inside /dlc/dlc030.zip

EU4 Converter modding [?]
.\events\ Events folder, all events are stored here. Event modding Merge. If redefining an event in a file loaded alphabetically after the original file, the event will be fully overridden.

Developers have discouraged this practice, as that engine behavior is not guaranteed to remain in the future (source ?)

  • ambitions\
  • characters\
  • coats_of_arms\
  • cursors\
  • eurfonts\
  • event_pictures\
  • flags\
  • fonts\
  • FX\
  • interface\
  • loadingscreens\
  • mapitems\
  • models\
  • polishfonts\
  • titles\
  • traits\
Graphics folder, all graphics are stored here. Graphics modding

Graphics are mapped to a logical name (GFX_xxx) inside .\interface\*.gfx files
Warning: a missing flag for a title in flags\ will cause wrong flags to appear for most titles, due to a shift.

.\history\ Historical data for characters, titles, provinces and wars for the possible start dates. This is a likely the text export of an internal database, which is sometime mentioned in the patch notes.[2] History modding N/A
.\history\characters\ Historical characters, optionally associated to a dynasty from \common\dynasties\ folder. Character modding [?] Merge. Duplicate character IDs break the character history and must be avoided.
.\history\diplomacy\ Not used N/A N/A
.\history\offmap_powers\ History of offmap powers (holder, status, ...) Offmap power modding [?] Merge
.\history\provinces\ History of provinces (holdings built, change of culture or religion) Province modding [?] Merge
.\history\technology\ Initial technology of provinces, depending on the start date. Technology modding [?]
.\history\titles\ History of titles (list of successive holders) Note: titles that should be deactivated at game start (ex: reformed religion heads) must have an history file that disables the title. [?] Merge
.\history\wars\ Important on-going wars (attacker, defender, Casus Belli, war score, ...), usually for historical bookmarks. [?] Merge
  • generalstuff.gfx
  • sound.sfx
Interface graphics Interface modding
  • Loading of *.gfx files is in alphanumerical order. Last spriteType definition loaded overrides previous ones with same name, if any (i.e. use zz_ file prefix to override vanilla sprites).
  • Only sound.sfx is taken into account, other .sfx files are ignored.
.\interface\coat_of_arms\ Coats of arms modding Coat of arms definitions can be split across multiple files. No support for appending existing definitions from a different file.
.\interface\portrait_offsets\ .txt files with external offsets for portrait frames Portrait modding
.\interface\portrait_properties\ Dynamic rules to select portrait properties values Portrait modding [?]
.\interface\portrait\ Definitions of spriteType and portraitType elements for portraits. Portrait modding Merge
.\launcher\ Launcher graphics and configuration N/A
.\localisation\ All text data for things like country names and event description, has options for other languages Localisation Full override. If duplicates are in different files, first file loaded wins (i.e. use 00_ file prefix to override vanilla keys). If in same file, last duplicate in file wins. Warning: files must end with .csv extension, or they will not be taken into account.
.\localisation\customizable_localisation\ Custom localisation commands definitions Localisation#Custom commands [?] Merge.
  • adjacencies.csv
  • default.map
  • definition.csv
  • geographical_region.txt
  • positions.txt
  • provinces.bmp
  • rivers.bmp
  • terrain.bmp
  • topology.bmp
  • trees.bmp
  • world_normal_height.bmp
Map settings, province shapes, continents, regions etc. Map modding N/A
.\map\statics Map external frame size, and positions of fixed 3D map elements (wonders, etc.) Map modding
.\map\terrain Map modding
.\mod\ Dummy mod folder, do not store mods here, use local mod folder Mod file Breaks mods, as configurations like replace_path are ignored.
.\music\ Music used by the game Music modding [?] All .txt files song elements are loaded.
.\sound\ All sounds except music [?]
.\tutorial\ Tutorial configuration [?]


Only includes guides not already linked in the "How to mod" column above or otherwise.


这些是modder用的实用工具。 玩家使用的请看utilities.


  • For the bigger mods using a source control management tool (Git, ...), it is handy to create a symbolic link between CKII mod folder and the working directory of the local repository, especially if the mod also has sub-mods. Note that you'll still need to copy the .mod file(s) manually, but they rarely change. Run the following command from the parent directory of main git folder, replacing:
    • <mod_path_name> by the value of path attribute from .mod file
    • <git_mod_folder> by the name of the sub-folder that contain mod data (folders common, decisions, events, etc...)
mklink /J "%HOMEDRIVE%%HOMEPATH%\Documents\Paradox Interactive\Crusader Kings II\mod\<mod_path_name>" ".\<git_mod_folder>"



  • observe - 让你进入观察者模式。此时你不再控制任何特定的角色——这会让游戏不受打断地自动运行。同时,所有隐藏特质、秘密信仰等对观察者都是可见的。
  • run <filename.txt> - 直接运行特定脚本。脚本将从当前玩家控制角色的作用域开始执行。这个功能有助于测试复杂的脚本——你可以直接打开一个窗口编辑脚本,保存,重新载入,调整——省下重新打开游戏的时间。
  • reloadevents - 重新载入和编译每一个事件(可能花费一会时间,取决于你的硬件)。对调试事件很有帮助,同样为你省下重新打开游戏的时间。
  • reloadloc - 重新载入本地化文件,有助于确定文本是否显示在正确的位置上。