排除故障

排除故障即發現遊戲崩潰、bug或其他問題原因的過程。

綜述

總的來說，遊戲報錯分致命和非致命兩種性質。

遊戲缺少一部分關鍵數據時會無法運行且閃退(Crash To Desktop, CTD)，是為致命錯誤。發生致命錯誤時遊戲會將日誌寫入/Hearts of Iron IV/logs/exceptions.log。致命錯誤的產生常見於遊戲加載遊戲或執行特定操作的時候。

遊戲遇到部分數據無效或不合語法時會產生非致命錯誤。這些錯誤通常記錄在/Hearts of Iron IV/logs/error.log。

遊戲測試

要找到mod的bug，測試很重要，而測試通常都是用控制台完成的。以下是一些對開發者較有用的控制台命令：

命令	作用
reloadfx all	重新加載大部分遊戲所用的遊戲特效，如戰爭迷霧、HDR和國家邊界透明度等。
reload texture	重新加載大部分遊戲所用的紋理，如領導人畫像、科技圖標等。
reload localization	重新加載大部分遊戲所用的本地化文本，如事件標題和描述。
reload defines	從/Hearts of Iron IV/common/defines/重新加載定義文件。
reload focus	從/Hearts of Iron IV/common/national_focuses/重新加載國策。
reloadoob	將指定tag所屬所有單位重置到配置文件指定的開局狀態。
reloadtechnologies	重新加載科技樹。如科技樹有問題會導致遊戲崩潰。
reloadinterface	重新加載所有用戶界面配置文件(.gui文件)
reload decision	重新加載決議及其相關用戶界面(/Hearts of Iron IV/common/decisions和相關.gui文件)
tdebug	啟用debug提示，顯示state ID、province ID等重要數據。
event	在玩家所選國家立即觸發指定事件。
nocb	取消外交行動限制。
observe	允許玩家轉為旁觀遊戲。遊戲在玩家無輸入的狀態下繼續。
aiview	光標懸浮在科技等特定按鈕上時顯示AI點擊其的權重。
tag	允許玩家扮演另外一個國家繼續遊戲。
update_loc	重新加載指定本地化條目。
updateequipments	重新加載/Hearts of Iron IV/common/units/equipment/下的裝備相關文件。
updatesubunits	重新加載/Hearts of Iron IV/common/units/下的單位相關文件。
research_on_icon_click	點擊某科技時立即完成其研發。
Focus.NoChecks	關閉國策前提條件檢查。
Focus.AutoComplete	立即完成某國策。
set_country_flag	為當前國家設立一個國家flag。
add_ideas	為指定國家添加一個國家精神。

遊戲日誌

本遊戲在其工作目錄下記錄了很多日誌文件。(Windows: \\Documents\Paradox Interactive\Hearts of Iron IV\logs\, Linux: .local/share/Paradox Interactive/Hearts of Iron IV/logs)每次遊戲啟動時舊日誌都會被替換成新的。

要啟用所有日誌記錄，請在Steam的遊戲設置內增加 -debug啟動選項。

文件	記錄內容	有用程度
ai.log	遊戲中AI做出的選擇。	中
ai_trace.log	遊戲中AI的單位操作記錄。	低
error.log	非致命錯誤。大多數可以忽略，如源自/Hearts of Iron IV/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 user directory's /Hearts of Iron IV/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 -crash_data_log launch command via Launch Options in Steam will also cause the meta.yml file in that folder (Directly within, not in the /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.
This can appear like LastRead: map/supply_nodes.txt (727) (Where the number represents the line of the file that was last read before the crash occurred) or LastRead: client_ping (1).

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 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.
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 binary search can be used by adding/removing the files large chunks at the time. replace_paths can be removed aside from essential ones: history/states/ and map/strategicregions. Note that 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

• common/countries/cosmetic.txt – Caused by a complete overwriting of common/national_focus/ or common/continuous_focus/.
• map/rocketsites.txt – Caused by a complete overwriting of history/states/ or common/unit_leader/. As there are no "generic files" for states, one should be created manually instead.
• 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 shared_focus = my_focus argument, specifying a shared focus that does not exist.
• gfx/models/supply/railroad.shader – Caused by an error within the 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.
• history/general/*.txt / history/countries/*.txt / 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 victory_points = { ... } definition that attempts to assign victory points to a province that does not exist within the game.
• savegame.hoi4 (takes on the name of a savefile, not necessarily one that exists right now) or 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 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.

• set_controller – 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 /Hearts of Iron IV/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.
• 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. 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.
• history/units/filename.txt / map/railways.txt – Caused by a country having a division template, yet not finding any possible /Hearts of Iron IV/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).
• map/supply_nodes.txt or 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 optionally creating a proper definition of the files, either manually or via nudge.
• 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 tutorial = { ... } definition of any kind entirely. Replacing the entire file's contents with tutorial = { } 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

• client_ping or hourly_tick – This crash is caused by the in-game AI, which can be seen by turning off the AI 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 /Hearts of Iron IV/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 blocked_for = { ... }/available_for = { ... } 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.
  • An incomplete 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 Province 12345 is setup as coastal but has no port building in the nudger. This will likely crash the game. after launching the game.

Additional details

A version tracking website, such as [Gitlab] or [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'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, 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 /Hearts of Iron IV/common/ folder from the mod without the game crashing, provided debug mode is turned on and there are no replace_paths to the folder.

模組製作 

文檔	效果 • 條件 • 定義 • 修正 • 修正列表 • 作用域 • 本地化 • 行動 • Data structures (Flags, Event targets, Country tag aliases, Variables, Arrays)