amtep / ck3-tiger

Checks Crusader Kings 3 user mod files for common mistakes and warns about them.

Tiger pounces on bugs. Checks Crusader Kings 3 user mod files for mistakes and warns about them. For example: missing localizations, or using a faith trigger on a character.

Crusader Kings 3 is a grand strategy game made by Paradox Interactive, and user mods are made by the players to enhance or change their game experience. This tool is for the people who make the mods.

ck3-tiger now also comes with vic3-tiger, which does the same thing for Victoria 3, and with imperator-tiger, which does the same thing for Imperator: Rome.

Status

This project is maturing but not yet stable. It will warn about some things that are actually correct.

vic3-tiger is somewhat younger than ck3-tiger and will have less accurate warnings.

Features

ck3-tiger (or vic3-tiger or imperator-tiger) will read the relevant vanilla files and your mod's files, and it will complain about everything in your mod that looks wrong. Where possible, it will tell you why it thinks the thing is wrong and (still in very few cases) what you should do instead.

• Syntax validation: are you using the right key = value pairs? No misspellings?
• Missing items: is every game object that you refer to actually defined somewhere?
• Missing localizations: do you have all the localizations you need for your mod?
• Scope consistency checking: are you using culture effects on cultures and character effects on characters, etc.?
• History (for CK3): Are spouses, employers, and lieges alive on the relevant dates? Is no one their own grandfather?
• Special: rivers.png check

Sample output

How to use

ck3-tiger

Download a release package from GitHub. Unpack it somewhere.

On Windows, if everything works out, you can then just double-click on ck3-tiger-auto and it will try its best.

Otherwise, run the tool from the command prompt:

path/to/ck3-tiger path/to/your/descriptor.mod

or

path/to/ck3-tiger "path/to/Paradox Interactive/Crusader Kings III/mod/YourMod.mod"

(Note that the quote marks around the path are important because of the spaces in it.)

If you want the output in a file, you can redirect it like this:

ck3-tiger path/to/your/descriptor.mod >filename

vic3-tiger

Download a release package from GitHub. Unpack it somewhere.

On Windows, if everything works out, you can then just double-click on vic3-tiger-auto and it will try its best.

Otherwise, run the tool from the command prompt:

path/to/vic3-tiger path/to/your/mod

or

path/to/vic3-tiger "path/to/Paradox Interactive/Victoria 3/mod/YourMod/"

(Note that the quote marks around the path are important because of the spaces in it.)

If you want the output in a file, you can redirect it like this:

vic3-tiger path/to/your/mod >filename

imperator-tiger

Download a release package from GitHub. Unpack it somewhere.

Run the tool from the command prompt:

path/to/imperator-tiger path/to/your/descriptor.mod

or

path/to/imperator-tiger "path/to/Paradox Interactive/ImperatorRome/mod/YourMod.mod"

(Note that the quote marks around the path are important because of the spaces in it.)

If you want the output in a file, you can redirect it like this:

imperator-tiger path/to/your/mod >filename

How to configure

You can place a file ck3-tiger.conf (or vic3-tiger.conf or imperator.conf) in your mod directory. You can use it to select which languages to check localizations for, and to suppress messages about things you don't want to fix.

There is a sample ck3-tiger.conf file, vic3-tiger.conf file, and imperator-tiger.conf file in the release, with an explanation of what goes in it. There is also a guide.

How to build

If you want to build it yourself, you will have to install the Rust programming language. You can either get the source archive from one of the releases (preferably the latest) or clone the git repository.

For ck3-tiger, run cargo build --release -p ck3-tiger in the project's directory, then run the program as cargo run --release -p ck3-tiger.
For vic3-tiger, run cargo build --release -p vic3-tiger in the project's directory, then run the program as cargo run --release -p vic3-tiger.
For imperator-tiger, run cargo build --release -p imperator-tiger in the project's directory, then run the program as cargo run --release -p imperator-tiger.

Visual Studio Code extension

User unLomTrois has made a VS Code extension for ck3-tiger. It enables you to view the reports directly in the Problems tab.

Showing only new reports

You can tell tiger to suppress reports that were shown in a previous run. This can be helpful when you only want to see what changed, for example after updating your mod. First you have to generate a "baseline" to compare future runs to:

ck3-tiger --json path/to/your/mod >baseline.json

You can use any filename in place of baseline.json. Then when you run tiger again, you can tell it to exclude reports from the baseline:

ck3-tiger --suppress baseline.json path/to/your/mod

It works with vic3-tiger and imperator-tiger too.

Contributions

I welcome contributions and collaborations! Some forms that contributions can take:

• Suggestions and ideas about what things tiger should check
• Telling me which of the output messages are confusing or hard to understand
• Reporting cases where tiger complains about a problem that's not real (false positives)
• Filing an issue on GitHub about a problem you have, or sending me email directly
• Starting up the game to verify something that's marked "TODO: verify" in the code

Contributions in the form of code are also welcome. They should be made as GitHub pull requests, and you should read and understand the project's copyright license before doing so. It may help to file a GitHub issue before starting to code, though, since I may prefer to solve the problem in a different way.

Some ideas for code contributions:

• Adding a new check and its error report
• Adding a validator for a new item type
• Updating a validator to a new game version
• Solving one of the hundreds of TODO comments in the code
• Solving one of the issues marked in the TODO or IDEAS wiki pages
• Speed or memory use improvements; opportunities are all over the place

See the CODING wiki page for an overview of the code and coding style.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the LICENSE file for more details.

ck3-tiger's Issues

[Vic3] Some missing fields

• country_can_have_mass_migration_to = [country scope]: Not used in vanilla but has its localization in vanilla, and the engine still recognize it
• can_be_used_in_sway_offers = [bool] and sway_maneuvers_cost = [int]: In common/diplomatic_actions
• pop_consumption_can_add_infrastructure = [bool]: In common/goods

[Improvement] Some missing field/structure of vic3-tiger

• Special event targets like num_enemy_units can be used like 'value triggers', while requiring input data scope inside parens
• name property allows block to implement dynamic naming (just like those in desc)
• Seems like limited_to_frontier_colonization in law is still not recognized by tiger
• trigger_event can also trigger on_actions, like trigger_event = { on_action = XXX days = 1 }
• Several properties in subject_types: can_be_used_in_sway_offers (boolean), lower_autonomy_subject_type_alternatives (array), same_autonomy_subject_type_alternatives (array), higher_autonomy_subject_type_alternatives (array), ai_value (value block), can_target_with_transfer_wargoal (boolean)
• on_researched in technology

[Feature] Some new (or missing) modifiers in Vic 1.5.13

• limited_to_frontier_colonization in common/laws/00_colonial_affairs.txt, with a boolean argument (not documented but used in original game file)
• show_as_unavailable in all event options, it's actually a trigger block (not documented but can work)
• min_hiring_rate, max_hiring_rate, and ignores_productivity_when_hiring in building_groups (documented in info and used in original game file)
• city_lights_color_index in production_methods of urban center (not documented but used in origianl game file at least since 1.4.0)
• group in jounal entries (documented and used)

[False positive] vic3-tiger should allow `script value block` anywhere requires a value

Currently vic3-tiger will output error(structure): expected value, found block for using in-place script value block instead of a direct value, which is allowed in the game engine

Example:

s:STATE_ALSACE_LORRAINE = {
    add_arable_land = {
        value = region_state:FRA.arable_land
        multiply = 0.5
    }
}

setup_invasion_cb doesn't know about "claimant" field

vanilla stuff

Check whether those buildings with `has_max_level` property have appropriate modifiers to add max level (since without them they become an unusable building)

Check whether the items of `activate_production_methods` inside `create_building` is valid for the given building type

[Bug] console option `--unused` can't recognize vanilla game usage

When using vic3-tiger with --unused switched on and with either --show-vanilla switched on or off, the validator will output thousands of unused items, and most of them are in the vanilla game, also they're actually used.

Vic 3 false-positive warnings

In Vic3 a != doesn't mean the other value has to be a bool or value, it can be any identifying scope.

Example

warning(scopes): `this` produces country but expected value or bool
   --> [MOD] common\scripted_effects\imperia_vienna_congress_effects.txt
755 |                 global_var:imperia_vienna_congress_session_target != this
    |                                                                      ^^^^ 
700 |     every_country = {
    |     ^^^^^^^^^^^^^ <-- scope was deduced from `every_country` here

The "special_selection" seems to just inherit the scope of it's outer scope. It now has country, country definition and power block as a use. They should all be able to be identified by the outer scope it is in.

Example:

warning(scopes): `power_bloc_leader` is for power bloc but scope seems to be country or country definition
   --> [MOD] common\coat_of_arms\template_lists\coa_templates.txt
417 |                 ROOT.power_bloc_leader = c:GBR
    |                      ^^^^^^^^^^^^^^^^^ 
414 |         special_selection = {
    |         ^^^^^^^^^^^^^^^^^ <-- scope was supplied by the game engine

false positive for operator >=

Scripted trigger courtier_guest_management_1001_exceptional_marriage_candidate_trigger in courtier_guest_management_events.txt throwing this error

[MOD] file events/courtier_guest_management_events/courtier_guest_management_events.txt
line 393 TIER >= scope:host.highest_held_title_tier
line 393 ^
ERROR (validation): expected TIER = or ?=, found >=

			marriage_between_characters_unlocks_alliance_of_min_tier_trigger = {
				MY_CHARACTER = scope:host
				THEIR_CHARACTER = scope:marriage_candidate
				TIER >= scope:host.highest_held_title_tier
			}

[Bug] DLC errors are not controlled by `--show-vanilla`

Currently errors from DLCs are always displayed, however I think these should be (almost) treated the same as those from the original game, thus also controlled by --show-vanilla

two values inside opinions

opinion and reversed_opinion can have two values if placed inside a trigger scope

[Vic] Check more items for Victoria 3

According to my modding experience, there're several additional items shall be auto-checked by vic3-tiger:

• #125
• #124

thread '<unnamed>' panicked at 'index out of bounds: the len is 13 but the index is 211', src\ck3\data\interaction_cats.rs:71:42

Hello!

So I decided to try to become a modder for ck3 and for the milestone in it I set the updating an old mod. However, I failed at setupping ck3-tiger correctly for days now 😔. I come to concussion that there may be a bug within tiger code because it would be very embarrassing if that was iust my fault and I'm apologizing already to for it🙏. So this is how i tried to launch it(I tried many ways, this error appears the most).

PS E:\Narzedzia do modow\ck3\tiger> .\ck3-tiger.exe --ck3 "c:/Games/Steam/steamapps/common/Crusader Kings III" "c:/Games/Steam/steamapps/workshop/content/1158310/2218620123/descriptor.mod"
This validator was made for Crusader Kings version 1.12.3 (Scythe).
If you are using a newer version of Crusader Kings, it may be inaccurate.
!! Currently it's inaccurate anyway because it's in beta state.
Using CK3 directory: c:/Games/Steam/steamapps/common/Crusader Kings III
Using mod directory: c:/Games/Steam/steamapps/workshop/content/1158310/2218620123

thread '<unnamed>' panicked at 'index out of bounds: the len is 13 but the index is 211', src\ck3\data\interaction_cats.rs:71:42
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
PS E:\Narzedzia do modow\ck3\tiger>

As I couldn't find the mentioned file src\ck3\data\interaction_cats.rs in my ck3 directory so I tried by verifying integrity of files, no success. I don't know what to do I really want to make mods for this game and this tool seems essential to me. I would be very grateful for help.
Thanks for the reading and have a nice day!

Update Game Constants for Vic3

ck3-tiger/vic3-tiger/src/lib.rs

Line 6 in 114cd89

version: "1.6.2 (BLACKCURRANT)",

This should be updated to 1.7.1 (or 1.7.3 if #120 is merged)

false positive for landed title from barony?

Scripted trigger pilgrimage_0500_valid_holy_site_trigger in pilgrimage_events.txt throwing this error

[MOD] file events/activities/pilgrimage_activity/pilgrimage_events.txt
line 285 this = capital_province.barony
line 285 ^
WARNING (scopes): barony produces landed title but expected character

The line numbers may be slightly off as it is a edited event but the trigger is untouched vanilla

scripted_trigger pilgrimage_0500_valid_holy_site_trigger = {
	#... we really shouldn't talk about the holy site we might be _in_ right now / invalid capital_province holy site
	NOR = { 
		this = root.location.barony
		AND = {
			exists = capital_province
			this = capital_province.barony
		}
	}
}

rightclicksound GUI field is unknown

GUI field rightclicksound creates a false positive of being unknown.

While this field is not used in anywhere in vanilla CK3 GUI files, it is a valid parameter. As can be seen on Advanced Cheat Menu mod. (Shameless plug.)

Several false-positives for Vic3 1.7.*

• The localization key of a modifier type is simply the type itself, with no modifier_ prefix any more
• scope:law in can_impose scope under law definitions produces law_type instead of law (However, scope:law in ai_enact_weight_modifier indeed produces law, that is strange, but I've confirmed it under Debug Mode)
  • Reproduce steps: Start as Great Britain in Debug Mode, add Colonization technology for Kaurna, try to impose Colonial Exploitation for it and you can see the correct tooltip, then change scope:law to scope:law.type in the law definition & restart (or hot reload), you'll get thousands of error log complaining about wrong scope type

Specify the version of the game in the releases

Can you please write version of the game to releases description? Like, I want to download a release for 1.8 version, what release should I download?

TechnologyEra is never used

The DBkind for TechnologyEra is never used, so it evaluates the eras.txt wrongly. I tried adjusting the currently wrong path ( Item::TechnologyEra => "common/technology//eras/", to: Item::TechnologyEra => "common/technology/technologies/eras/")

But that wasn't enough.

Suggested feature #include

I have a personal mod that is split over a couple of mods, also a few personal compatches.

I'm finding that running ck3-tiger over some of my mods, especially the compatches are throwing errors because ck3-tiger does not know about triggers, effects, modifiers, etc that are defined in other mods.

I personally think it would make the tool more useful if mods could be specified in an include = { } section in the conf file, so ck3-tiger could load them to resolve a lot of the associated errors.

ofc I would not want to see ck3-tiger actually process the include mods for errors/warning, just to use them as a source for resolution.

Random crash error

As shown in the image, it seems that vic3-tiger crashes randomly, because I didn't change anything between the two runs.
The same crash error has occured twice, though I should say it's still relatively rare.

Tiger seems to have trouble with long files

2 shots of the same file after 2 scans. It may be vscode extension fault, if so I apologize🙏

Update the main message for error(filename)

The current main message for error(filename) is a constant 'file in unexpected directory', which has no effective information
Perhaps we could add the quoted filename and/or directory to the main message so that it can be filtered using text
For example, when I update my mod for a new version, I usually move some of my files/folders into a special .obsolete folder, and I'd like tiger to only ignore files in this folder, however, due to the insufficient main message of error(filename), I can only ignore the whole filename key

Possible false positives for missing field

I get these errors but this is vanilla syntax and it's used quite a lot throughout vanilla, with no error log complaints, so not sure if this is legal syntax or not.

line 19847 		any_relation = { this = root }
line 19847 		               ^
ERROR (field-missing): required field `type` missing

[False positive] vic3-tiger misunderstand `modifier` and `modifer_type`

In Victoria 3, the folder common/modifier contains detailed modifiers which can be added directly to an entity (country, character, etc.)
While the folder common/modifier_type contains modifier types that may be used in modifiers or something else, it can also be accessed via modifier:xxx.

Currently, vic3-tiger outputs error(missing-item): modifier XXX not defined in common/modifiers/ when the mod accesses user-defined modifier types, however, actually it should read from common/modifier_types to find user-defined modifier types

[Vic3] scripted_button must have `name` and `desc` field

Currently tiger will accept scripted_button with no name and desc field. Such scripted_button will not trigger error logs, but will cause the game to crash after opening the journal entry containing it. So perhaps tiger should warn for this.

False positive about warning(logic)

Currently tiger will emit "warning(logic): setting value here will overwrite the previous calculations" if you use value = xxx in a script value's body (not the first line). This works for most situations, but it will cause false positive with save_temporary_value_as
Example:

da_value_max_3 = {
	if = {
		limit = { scope:_1 > scope:_2 }
		if = {
			limit = { scope:_1 > scope:_3 }
			value = scope:_1
		}
		else = {
			value = scope:_3
		}
	}
	else_if = {
		limit = { scope:_2 > scope:_3 }
		value = scope:_2
	}
	else = { value = scope:_3 }
}
da_test_value = {
	value = 100
	save_temporary_value_as = _1
	value = 200
	save_temporary_value_as = _2
	value = -100
	save_temporary_value_as = _3
	value = da_value_max_3
}

In this example, the paired value = xxx and save_temporary_value_as = yyy actually acts like passing parameters and then call a function, so perhaps we can suppress the warning if it follows a save_temporary_value_as ? Or simply treat save_temporary_value_as as the start of a new script value?

Using a scoped trait in add_trait_xp effect causes a missing item error

Using a scoped trait in add_trait_xp effect causes a missing item error.

For example

add_trait_xp = {
  trait = scope:trait
  track = hunter
  value = 10
}

This is a valid code. But gives an error(missing-item): trait scope:trait not defined in common/traits/ error.