查看“排除故障”的源代码

'''排除故障'''即发现游戏崩溃、bug或其他问题原因的过程。

== 综述 ==
总的来说，游戏报错分致命和非致命两种性质。 

游戏缺少一部分关键数据时会无法运行且闪退(Crash To Desktop, CTD)，是为致命错误。发生致命错误时游戏会将日志写入{{path|logs/exceptions.log}}。致命错误的产生常见于游戏加载游戏或执行特定操作的时候。

游戏遇到部分数据无效或不合语法时会产生非致命错误。这些错误通常记录在{{path|logs/error.log}}'''。''' 

== 游戏测试 ==
要找到mod的bug，测试很重要，而测试通常都是用控制台完成的。以下是一些对开发者较有用的控制台命令：
{| class="wikitable sortable" width="100%"
! width="20%" | 命令
! width="80%" | 作用
|-
|reloadfx all
|重新加载大部分游戏所用的游戏特效，如战争迷雾、HDR和国家边界透明度等。
|-
|reload texture
|重新加载大部分游戏所用的纹理，如领导人画像、科技图标等。
|-
|reload localization
|重新加载大部分游戏所用的本地化文本，如事件标题和描述。
|-
|reload defines
|从{{path|common/defines/}}重新加载定义文件。
|-
|reload focus 
|从{{path|common/national_focuses/}}重新加载国策。
|-
|reloadoob
|将指定tag所属所有单位重置到配置文件指定的开局状态。
|-
|reloadtechnologies
|重新加载科技树。如科技树有问题会导致游戏崩溃。
|-
|reloadinterface 
|重新加载所有用户界面配置文件(.gui文件)
|-
|reload decision
|重新加载决议及其相关用户界面({{path|common/decisions}}和相关.gui文件)
|-
|tdebug
|启用debug提示，显示state ID、province ID等重要数据。
|-
|event
|在玩家所选国家立即触发指定事件。
|-
|nocb
|取消外交行动限制。
|-
|observe
|允许玩家转为旁观游戏。游戏在玩家无输入的状态下继续。
|-
|aiview
|光标悬浮在科技等特定按钮上时显示AI点击其的权重。
|-
|tag
|允许玩家扮演另外一个国家继续游戏。
|-
|update_loc 
|重新加载指定本地化条目。
|-
|updateequipments
|重新加载{{path|common/units/equipment/}}下的装备相关文件。
|-
|updatesubunits
|重新加载{{path|common/units/}}下的单位相关文件。
|-
|research_on_icon_click
|点击某科技时立即完成其研发。
|-
|Focus.NoChecks
|关闭国策前提条件检查。
|-
|Focus.AutoComplete
|立即完成某国策。
|-
|set_country_flag
|为当前国家设立一个国家flag。
|-
|add_ideas
|为指定国家添加一个国家精神。
|}

== 游戏日志 ==
本游戏在其工作目录下记录了很多日志文件。(Windows: <code>\\Documents\Paradox Interactive\Hearts of Iron IV\logs\</code>, Linux: <code>.local/share/Paradox Interactive/Hearts of Iron IV/logs</code>)每次游戏启动时旧日志都会被替换成新的。

要启用所有日志记录，请在Steam的游戏设置内增加 <code>-debug</code>[[启动选项]]。
{| class="wikitable sortable" width="100%"
! width="20%" | 文件
! width="60%" | 记录内容
! width="20%" | 有用程度
|-
|ai.log
|游戏中AI做出的选择。
|中
|-
|ai_trace.log
|游戏中AI的单位操作记录。
|低
|-
|error.log
|非致命错误。大多数可以忽略，如源自{{path|common}}的内容问题则应修复。
|高
|-
|exceptions.log
|发生致命错误时的堆栈信息。 
|低
|-
|executedcommands.log
|玩家和AI的操作。
|低
|-
|game.log
|游戏内国家的操作。如果游戏总是因特定操作崩溃则十分有用。
|高
|-
|graphics.log
|位置、河流、树木等引起的图像错误。
|低
|-
|memory.log
|Prints the memory used during setup. Useful for crashes during the loading process, to see when the game crashed.
|高
|-
|message.log
|Prints the session info for the current session.
|Low
|-
|postedcommands.log
|
|Low
|-
|random.log
|Prints times for game state changes.
|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
|-
|system.log
|Prints the system information HOI4 is loaded on.
|Low
|-
|system_debug.log
|Prints interface errors.
|Medium
|-
|text.log
|Prints asserts on localization keys.
|Medium
|-
|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.
|Medium
|}

== Crash data log ==
When the game crashes, it provides information on system settings and what caused it to crash in the [[Modding|user directory's]] {{path|crashes/}} folder. Although most of the time this is not beneficial as to what caused it to crash, the error log could contain clues. However, one important logging mechanism can be additionally turned on:

Adding the <code>-crash_data_log</code> launch command via ''Launch Options'' in Steam will also cause the <code>meta.yml</code> file in that folder (''Directly within'', not in the {{path|custom=1|/logs/}} subfolder) to contain the last read line of code before crashing, as well as turning on the debug mode. This slows down the game by a significant amount, so it shouldn't be used outside of crash debugging. '''If the last read line of the file given is the last line in the file, it's rather likely the game crashed on the ''next'' read file instead, which is quite difficult to locate.''' In some cases, the game can grant a script instead of a file, such as a savefile or client_ping.<br/>
This can appear like <code>LastRead: map/supply_nodes.txt (727)</code> (Where the number represents the line of the file that was last read before the crash occurred) or <code>LastRead: client_ping (1)</code>.

Note that while -crash_data_log enables debug mode, not all benefits of the launch option get applied by default and require using both launch options. For example, edits to files indexed during the main menu loading will not get automatically loaded, requiring a console command usage to get reloaded instead. However, -crash_data_log's debug does include the game loading into the main menu with map errors, the nudge being available for selection, and the debug information when hovering over a province or a country.

== Common crash causes ==

'''A variety of crash types are caused by recklessly unloading folders with [[Modding#Mod structure|replace_path]]''', leading to the game detecting there not being any database entries of a certain type. It's best practice to port over generic files to the mod if overwriting a folder in entirety for this reason, as well as to avoid unintuitive errors.

In case of a different crash, note that if a file is completely empty, the game may skip reading it in entirety. As such, the same crash may display a different file if the one in this list is empty. <br/>
It's best to completely clean the error log before trying to find a crash, as some errors may appear innocuous while still crashing the game.

If the last read file proves useless, it's possible to temporarily remove files from the mod and slowly re-add them to find the exact cause; upon finding the cause folder, it should be adjusted accordingly. A sort of [[wp:Binary search algorithm|binary search]] can be used by adding/removing the files large chunks at the time. replace_paths can be removed aside from essential ones: {{path|custom=1|history/states/}} and {{path|custom=1|map/strategicregions}}. Note that [[Modding#Mod structure|'''both''' *.mod files need to be edited for replace_paths to apply.]]

'''This list is non-exhaustive''': There are more potential crashes, and any given file or script can have more causes that are not outlined in the list. This has been broken up into sections on when they happen for easier navigation. The file provided is the file marked as last read by the [[crash data log]].
=== Main menu loading ===
* {{path|custom=1|common/countries/cosmetic.txt}} – Caused by a complete overwriting of {{path|custom=1|common/national_focus/}} or {{path|custom=1|common/continuous_focus/}}.
* {{path|custom=1|map/rocketsites.txt}} – Caused by a complete overwriting of {{path|custom=1|history/states/}} or {{path|custom=1|common/unit_leader/}}. As there are no "generic files" for states, one should be created manually instead.
* {{path|custom=1|common/national_focus/*.txt}} – This crash, granted that it's the last line of the last file in the folder, can be caused by a focus tree using a <code>shared_focus = my_focus</code> argument, specifying a shared focus that does not exist.
* {{path|custom=1|gfx/models/supply/railroad.shader}} – Caused by an error within the [[Map modding|the .bmp files creating the map]]. This can be a wide variety of causes. Some causes include provinces.bmp having dimensions as numbers that are undivisible by 256, having a size of over 40 MiB, the dimensions changing between different bitmaps (aside from trees.bmp, where the size changes the density of static models), or an incorrect DIB header formatting (such as setting encoding to be used or using BITMAPV5HEADER instead of BITMAPINFOHEADER) in any bitmap.
* {{path|custom=1|history/general/*.txt}} / {{path|custom=1|history/countries/*.txt}} / {{path|custom=1|map/rocketsites.txt}} (In order in which they'd appear with replace_paths to the previous ones) — One of the states within the mod has a <code>victory_points = { ... }</code> definition that attempts to assign victory points to a province that does not exist within the game.
* {{path|custom=1|savegame.hoi4}} (takes on the name of a savefile, not necessarily one that exists right now) or {{path|custom=1|map/cities.txt}} – Caused by there being a large quantity of countries defined while there are few (such as 15) or no dynamic countries. The exact amount of countries that the game can handle is not a consistent number, usually falling in the range of 40–80. Typically caused by a reckless overwriting of {{path|custom=1|common/country_tags}} or the file that stores the dynamic countries being outdated. 

=== During country selection ===
This also includes the loading after a country has been selected, but it's not yet possible to play.
* <code>set_controller</code> – This crash typically happens when trying to select a country in a bookmark if the country doesn't have a valid capital defined within its {{path|history/countries/TAG*.txt}} file. The game uses the capital in order to determine what portion of the map to zoom onto, and not getting one is unexpected.
* {{path|custom=1|history/units/filename.txt}} – One of the naval orders of battle in the mod has a carrier defined with airwings directly inside, as was done in 1.11 and earlier. [[Patch 1.12#Important Modding Notes|Adjust the orders of battle in the mod as needed]]. Note that the file shown as the last read one is not necessarily the one that crashes the game.
* {{path|custom=1|history/units/filename.txt}} / {{path|custom=1|map/railways.txt}} – Caused by a country having a division template, yet not finding any possible {{path|common/ai_templates}} entry to use to expand on the template. The exact file/script in question depends on ''when'' the country obtains the division template: an order of battle (which'll be last read) or another history file (leading to railways).
* {{path|custom=1|map/supply_nodes.txt}} or {{path|custom=1|map/railways.txt}} – This crash is most commonly caused by the specified building types being placed on invalid provinces, such as those that are not located in states. This crash occurs both when trying to open the supply menu in nudge or when trying to start a single player game. This can be corrected by emptying the files in question and [[Map_modding#Supply_nodes_and_railways|optionally creating a proper definition of the files, either manually or via nudge]].
* {{path|custom=1|tutorial/tutorial.txt}} – This crash is caused by the tutorial file being erroneous. This can be represented as a link to an invalid state ID within the file (such as if every base game state was erased) or as the file lacking a <code>tutorial = { ... }</code> definition of any kind entirely. Replacing the entire file's contents with <code>tutorial = { }</code> works to solve the crash.
: This is also the last file that gets read after the country selection process finishes. If a crash occurs directly afterwards and the game fails to write the file properly, it will land on this one.

=== Middle of the game ===
* <code>client_ping</code> or <code>hourly_tick</code> – This crash is caused by the in-game AI, which can be seen by turning off the AI [[Console commands|using the console]]. There are several causes for this occurring, including but not limited to:
** A country has a division template, yet couldn't find any {{path|common/ai_templates}} entry to use to expand on the template. Typically caused by a reckless overwriting of the folder with replace_path or an error in setting up the <code>blocked_for = { ... }</code>/<code>available_for = { ... }</code> blocks.
** Any state not having an owner defined in the history file. In general, such states always run unstably, with a lot of actions crashing them, such as right-clicking or attempting to transfer one to a country. One of such actions is attempting an air mission over that state. As the AI is able to use airplanes, they will try to attempt to at least evaluate the value of doing a mission over the state, which results in a crash to desktop.
** [[Map modding#Buildings|An incomplete {{path|custom=1|map/buildings.txt}}]]. The buildings file is used for determining into which sea province the naval bases and floating harbours will go out into, alongside positioning building models. This information is necessary when attempting to use any naval base or floating harbour, as the game would have no idea via which province the province connects to the sea otherwise. The game also checks this information when attempting to ''build'' a naval base, and if the game attempts to evaluate an invalid naval base definition, the game gets stuck in an infinite loop of attempting to obtain the naval base information, resulting in a CPU/GPU overload and a game crash.
:: This also results in an error.log entry of <code>Province 12345 is setup as coastal but has no port building in the nudger. This will likely crash the game.</code> after launching the game.

== Additional details ==
A version tracking website, such as [[https://about.gitlab.com/ Gitlab]] or [[https://github.com/ Github]], can be used to keep track of updates to the code. As such, it can be beneficial to use them and regularly push mod's updates to them in order to limit the selection of possibly problematic files when trying to debug an issue.

When the game has a major update, it can be important to read the patch notes to fix the newly-appearing errors. For example, the [[1.12#Important Modding Notes|1.12's patch notes provide an "Important modding notes" section]], which also serves as a check-list of necessary things to fix in the mod in order to avoid a crash. It is also important to avoid overwriting most base game files when possible in order to ease compatibility, though this is not always possible. One folder where it's incredibly important to do is [[Defines#Overrides|defines, where an override file is essentially mandatory]] in order to avoid even minor game updates from introducing crashes.

In case the game crashes on startup, but there's no obvious reason why in the error log and it's unknown what was last changed since the last time, the mod could have folders strategically removed. As an example, it is almost always possible to remove the entire {{path|common/}} folder from the mod without the game crashing, provided debug mode is turned on and there are no replace_paths to the folder. 
 
{{Modding navbox}}
[[Category:Modding]]
[[en:troubleshooting]]