合併指南

This guide describes the steps to retrofit the changes from a vanilla patch, for a mod that modifies some vanilla files.

It is best to avoid copying and modifying vanilla files inside a mod (by loading from folders), but sometimes this is unavoidable.

If you do, there is some extra work needed for every vanilla patch, to merge changes with your own, and make the mod compatible with the new patch:

'Base' file (vanilla version N) ----------------> 'Destination' file (vanilla version N+1)
  |                                New patch             |
  | Copied and modified                                  | Propagating vanilla changes
  |                                                      |
  v                                                      v
'Source' file (mod version N)   ----------------> 'Result' file (mod version N+1)
                             Keeping mod changes

Merge tool

Ideally you should use a 3-way merge tool, with 3-way folder merging capability:

• 3-way text merging will resolve most conflicts automatically, allowing to complete much faster and with less risks of mistakes.
• 3-way folder merging allows to trigger the 3-way text merge of files that need merging more conveniently.

Some 3-way merge tools:

• KDiff3
• Beyond Compare 4 Pro (30 days free trial)

Note that WinMerge doesn't support 3-way merge, only 2-way diff.

Launching the merge

3-way merge is composed of 4 windows:

• Source: The mod
• Base: The last vanilla version for which the mod was updated for
• Destination: The vanilla version to updated to
• Result: The mod

For simplicity, it's common to have source and result work on same files, but make sure the old version of the mod is backed-up in case you need to re-start the merge for any reason.

---

Tips

• Tell the mergetool about CK2 syntax, for an even more efficient merge and some syntax coloration:
  • Comment = Text from # to end of line
  • Identifier = Text matching [_a-z]\w*
  • String = Text from " to "
  • ...

• If possible, add new mod entities in separate files, as things added at the end of a vanilla files will always conflict when new elements are added to vanilla.

• If removing elements from a large vanilla file, leave breadcrumbs to help the merge tool. This will prevent the tool from attempting to merge with the next element in the file.

For instance if removing religious CB in 00_cb_types, keeping the following in the mod will help future merges:

# Regular Holy War CB
#religious = {
#	
#	can_use_gui = {
#		
#	}
#
#	can_use = {
#		
#	}
#
#	can_use_title = {
#		
#	}
#	
#	is_valid = {
#		
#	}
#
#	is_valid_title = {
#		
#	}
#
#	on_add = {
#		
#	}
#
#	on_success_title = {
#	
#	}
#
#	on_fail = {
#		
#	}
#
#	on_reverse_demand = {
#		
#	}
#
#	attacker_ai_victory_worth = {
#		
#	}
#	
#	attacker_ai_defeat_worth = {
#		
#	}
#
#	defender_ai_victory_worth = {
#		
#	}
#	
#	defender_ai_defeat_worth = {
#		
#	}
#}

參考資料

合併模組製作指南