Mod troubleshooting

From Europa Universalis 4 Wiki
Jump to navigation Jump to search

Troubleshooting is the identification of the cause of crashes, bugs or other problems.

Overview[edit | edit source]

In general there are two kinds of errors: fatal and non-fatal.

Fatal errors occur when the game cannot load a vital piece of data and cannot operate without it present. This causes a crash to desktop (CTD). When fatal errors occur, an exception will be printed to the exceptions.log. Typically these errors occur during the loading process or when a specific action is taken in game.

Non-fatal error occur when the game encountered invalid data or broken syntax. These errors are almost always printed to the error.log.

Testing[edit | edit source]

Performing testing is vital to debugging a mod. Typically this is done via the in-game console with commands such as event, observe and run.

The run command is very useful for testing effects without having to reload the game. It also makes it very easy to setup test scenarios without introducing wayward code within the mod itself.

The observe is useful when you want to test the stability of your mod during gameplay. By becoming an observer, you can let the game run without your input, making it easier to detect issues that occur irregularly.

Loading[edit | edit source]

When launching the game the following steps occur:

Loading Databases
Initializing Maplogic
Loading Databases...
Loading History Files...
Loading Sounds...
Loading Events...
Loading GUI Definitions...
Loads Flags...
Creating Checksum...
Loading Graphics...
Creating Province #
Loading Map (Creating Shaders)...
Loading Map (Creating Terrain)...
Loading Map (Creating Borders)...
Loading Map (Creating Straits)...
Loading Map (Creating Textures)...
Loading Map (Creating Trees)...
Loading Map (Creating Rivers)...
Loading Map (Creating objects)...
Initializing Game...

Log files[edit | edit source]

The game stores various log files in your EU4 user folder: (\\Documents\Paradox Interactive\Europa Universalis IV\logs\). These are overwritten every time the game is started.

To enable full error logging, add the -debug launch command via Set Launch Options in Steam.

File Description Usefulness
ai.log Prints the country selection of the player and then the Starting AI line. Low
error.log Prints the various non-fatal errors. Many errors can be ignored, although almost all errors relating to files in the common folder should be fixed. High
error_old.log The error.log from the previous game launch. Low
error_old_old.log The error.log from the second previous game launch. Low
exceptions.log Prints the stacktrace when the game crashes to desktop. Currently only prints the hexadecimal address, making this file fairly useless. Low
executedcommands.log Prints the internal commands uses by the player and AI. Low
game.log Prints the actions taken by countries in game. Useful when the crash is due to a specific action. High
graphics.log Prints the graphical errors relating to positions. Low
local_temp.log Low
memory.log Prints the memory used during setup. Useful for crashes during the loading process, to see when the game crashed. High
message.log Prints the session info for the current session. Low
profiling.log Prints the profiling output if using the profiling .exe file. High
random.log Low
random02.log Low
receivedcommands.log Prints the internal commands received by the player in multiplayer. Low
sentcommands.log Prints the internal commands sent by the player in multiplayer. Low
setup.log Prints the completion of setup loading for each part of the process. Very useful for discovering which file may be causing a crash. High
setup_error.log Prints errors in the /Europa Universalis IV/common/countries files. Typically errors are of low importance. Low
system.log Prints the system information EU4 is loaded on. Low
system_interface.log Prints interface errors. Low
text.log Prints asserts on localization keys. Low
time.log Prints the time it takes for the various loading steps to complete, and the tick interval. Very useful for crashes during the loading process, to see when the game crashed. High

Debugging[edit | edit source]

Generally, when debugging you want to narrow down the possible causes for a crash. This is why it is best to run your mod after every change, so any issues become immediately apparent, and you can find the cause easily since it'll be the last file you edited.

If this is not possible, then you want to isolate the potential causes. This is done by moving the suspected files and folders out of your mod folder and into a temporary folder, and then launching the mod without them. This requires a good amount of knowledge of how each file works together, so you can safely isolate files and folders without introducing broken dependencies.

Typically you can easily isolate the events, decisions, missions and interface folders without too much worry. Then in the common folder, remove files or folders one-by-one, re-launching the game each time to determine which is causing the issue. If none, then it is likely the issue is in the history or map folder. Repeat this process throughout them.

Crashes[edit | edit source]

Most fatal errors that cause crashes to desktop can be very difficult to debug without extensive knowledge of modding. The following list is of known crashes to help modders debug:

Crash Fix
During "Loading Databases" If you are using the defines.lua, check you have included all the entries that vanilla includes.

Check that there are no references to non-existing files.

  • A tag in country_tags must not reference a file that does not exist.
  • Make sure that all defined colonial regions have at least one province assigned.
  • Scripted Effect / Meta Script with wrongly coded (leads to stack overflow exception) -> conditional input not used correctly, [] used for something thats not an conditional input e.g. localisation, non closed $input$ like $input
During "Initializing Maplogic" Check that the gamelogic map images have been saved in the correct formats. Make sure the map files used follows the guidelines listed in Map modding.
  • province limit isn't higher than the last province ID in definition.csv.
  • A province ID in no longer exists in the definition.csv.
  • A province ID in adjacencies.txt no longer exists in the definition.csv.
  • A province ID in area.txt no longer exists in the definition.csv.
  • A province ID in climate.txt no longer exists in the definition.csv.
  • A province ID in continent.txt no longer exists in the definition.csv.
  • A province ID in terrain.txt no longer exists in the definition.csv.
  • A province ID in trade_winds.txt no longer exists in the definition.csv.
  • A province ID in area.txt no longer exists in the definition.csv.
  • terrain.bmp has a missing or corrupted color table.
  • rivers.bmp has a missing or corrupted color table.
  • trees.bmp has a missing or corrupted color table.
  • Map dimensions are not a product of 128.
  • The provinces.bmp exceeds 52 megabytes.
  • The provinces.bmp contains provinces that are too large.
During "Loading History Files..." Check that the history files do not reference any missing country tags or provinces IDs.
During "Loads Flags..." Check that the history files do not reference any missing country tags (specifically the diplomacy folder).
During "Loading Graphics..." Check that the graphical map images have been saved in the correct formats. Make sure the map files used follows the guidelines listed in Map modding.
During "Loading Map (Creating Straits)..." Check that the adjacencies.txt file lists valid straits.
During "Loading Map (Creating Tree)..." * Check that the trees.bmp file is not corrupted in any manner.
  • Check that the terrain.bmp file is not corrupted in any manner.
Clicking Play in the lobby The issue can lie within the common files:
  • Missing entries in required files such as static_modifiers
  • Missing entries for modifiers used in effects or triggers.

History files:

  • A country capital defined in history/countries references a province id that has no pixels in map/provinces.bmp.
Clicking a Province * Make sure the province belongs to a continent in continent.txt.
  • Make sure the province belongs to an area in area.txt.
Crash when zooming into a specific place Can be caused by a certain country in the area's graphical_culture = <misspelled>.

It may also happen if you did not assign a port to a coastal province and the AI is forced to send out their ships, e.g. after being sieged down.

Nation Designer Government Tab when using more than 3 Government Ranks The nationadesignerview.gui file needs to be edited to have additional icon_gov_desc_* and gov_desc_* for each new level of government rank.
Crash on Hover in an Interface Typically caused by a clause missing from the relevant files, i.e. the army professionalism static modifiers when hovering over the Hire General button. It may also be caused by errors in on_actions.txt.
Trying to Move a Capital Often caused by missing or misnumbered provinces in continent.txt.
Hovering over a country in the Great Powers list Also often caused by missing or misnumbered provinces in continent.txt.

This process will almost always allow you to discover the cause of a crash, although it is tedious.

Profiling[edit | edit source]

Since patch 1.23, Europa Universalis IV includes a performance profiler alongside the normal game. This tool is useful for modders that want to measure and diagnose poor performance within their mods.

To use the profiler, you need to launch the game launcher by click eu4_profiling.exe within the game installation folder. This will launch the game with whatever mods you had selected previously in the launcher. In other words, if you wish to test the performance of the game with mods enabled, be sure to enable these mods before launching eu4_profiling.exe.

Once in game, allow the game to run until you have reached a suitable duration, and then open the console and type dump_script_profiling to write to the profiling.log in the logs folder.

The profiling.log should be viewed in a mono-spaced font for best readability.

Documentation EffectsTriggersModifiersScopesVariablesLocalisationCustomizable localizationRun files
Scripting Scripted functionAdvisorsAgesBookmarksBuildingsCasus belliColonial regionsCountriesCultureDecisionsDefinesDiplomatic actionsDisastersEmpire of ChinaEstatesEventsFactionsGovernmentGreat projectsHistoryHoly Roman EmpireIdea groupsInstitutionsMercenariesMissionsModifiersNation designerOn ActionsParliamentPeace treatiesPoliciesRebel typesReligionSubject typesTechnologyTrade companiesTrade goodsUnits
Map MapNation designerRandom New WorldTrade nodes
Graphics 3D ModelsInterfaceGraphical AssetsFontsParticlesShadersUnit models
Audio MusicSound
Other Console commandsChecksumJoroDox mod making toolMod structureTroubleshootingThe ValidatorRun files
Guides Adding a provinceSave-game editing