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]

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]

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]

When launching the game the following steps occur:

Step
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]

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]

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]

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.
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.
  • default.map province limit isn't higher than the last province ID in definition.csv.
  • A province ID in default.map 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.
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.
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.
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]

Since patch 1.23, Europa Universalis IV includes a performance profiler along side 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 launcher, which you can then use to select your mod and launch the game.

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 localization
Scripting AdvisorsAgesBookmarksBuildingsCasus belliColonial regionsCountriesCultureDecisionsDefinesDiplomatic actionsDisastersEstatesEventsFactionsGovernmentGreat projectsHistoryIdea groupsInstitutionsMissionsModifiersNation designerPoliciesReligionRebel typesSubject typesTechnologyTrade companiesTrade goodsUnits
Map MapRandom New WorldTrade nodes
Graphics 3D ModelsInterfaceGraphical AssetsFontsParticlesShadersUnit models
Audio MusicSound
Other Console commandsChecksumJoroDox mod making toolMod structureTroubleshootingThe Validator
Guides Adding a province