ゲーム内デバッグツール

ゲームには、問題のデバッグや修正、新しい要素のテストに役立つ組み込みツールがいくつかあります。

主なものを以下に示します。

デバッグメッセージ

debugmsg、または「黒い画面に赤い文字」とも呼ばれます。データファイルのエラーや内部状態の不整合をゲームが検出したときに表示されます。

深刻度は無害で細かな警告から、復旧不能なクラッシュまでさまざまです。各メッセージのコピーは通常、エラーが発生した場所を示すバックトレースが先頭に付いた状態でデバッグログに保存されます。

space でメッセージを閉じ、i でメッセージとゲーム再起動までの後続メッセージをすべて閉じられます。

ゲーム実行ファイルを --dont-debugmsg コマンドラインオプション付きで実行すると、（自己責任で）すべてのデバッグメッセージを抑制できます。

コードからは次のようにデバッグメッセージを呼び出せます。

#include "debug.h" // 詳細はこのヘッダーを参照
 . . .
// 第1引数は書式文字列。詳細は `string_formatter.h` を参照
 debugmsg( "Failed to open file, code %d", 123 );

デバッグログ

デバッグログには、一般情報、警告、重大なエラーなど、ゲームが出力するさまざまな状態メッセージが含まれます。多くのバグを最初に診断するときに確認する場所です。

ユーザーの config フォルダにある debug.log という 1 つのファイルに保存されます。

ゲーム内オプション（Options → Debug タブ → Logging サブメニュー）でデバッグログの詳細度を手動で変更できます。

コードからログに出力する例:

#include "debug.h" // 詳細はこのヘッダーを参照
 . . .
// 第1引数は重大度、第2引数はカテゴリ
// 行末に改行を追加しないでください。自動的に追加されます。
DebugLogFL( DL::Info, DC::Map ) << "My " << "logged" << " info!";

クラッシュログ

クラッシュログにはゲームがクラッシュした後のバックトレースが含まれます。クラッシュしたコードと場所の情報がほぼそのまま残るため、クラッシュの解決に非常に役立ちます。

ユーザーの config フォルダにある crash.log という 1 つのファイルに保存されます。

クラッシュが十分に特殊な場合や、実行ファイルがバックトレース対応なしでコンパイルされている場合は、クラッシュログが生成されないことがあります。

コードにクラッシュトレース用の特別な処理を追加する必要はありませんが、ビルドでバックトレースを有効にする必要があります。一部のビルドでは、バックトレースを読みやすくする任意の libbacktace も利用できます。Linux でバックトレース生成に最大 30 秒ほどかかる場合は、g++ の代わりに clang++ でコンパイルしてみてください。

デバッグモード

デバッグメニューと混同しないでください。デバッグモードはログに大量のノイズの多いメッセージを出力し、一部の UI ウィンドウで追加機能を有効にします。

たとえばアイテムを調べたときにアイテム ID、タグ、チャージが表示され、車両の詳細メニューに旋回軸、重心、カーソル位置（車両座標）が表示されます。

デバッグメッセージの大半は車両、効果、サウンド、NPC の処理に関するものです。

デバッグモード切り替えを使用するには、「default」モード（操作キャラクターが中央にいる地形表示）で Toggle Debug Mode アクションをキーに割り当てます。キー割り当て一覧は ? で開けます。

コードからは cached_options.h にある debug_mode 変数でデバッグモードを確認できます。

デバッグメニュー

「チートメニュー」とも呼ばれ、デバッグモードとは異なります。テストに最も便利な機能です。

既定では非表示です。任意のキー（通常はバッククォートキー \）に``Debug Menuアクションを割り当て、キーを押すかEscメニューからDebug Menu` を選択します。

機能の多くは明確なラベル付きでカテゴリに分かれています。自由に試してください。

「Debug Mutations」という少し隠れた機能もあります。昔のゲームのチートコードに似ており、キャラクターにいくつかのゲームメカニクスへの耐性を与えます。すぐに開くには p（Player）→ u（Mutate）→ /（Filter）を押し、検索欄に Debug と入力します。

追加の JSON チェック

主にコンテンツ制作者向けに、追加の JSON データチェックを有効にできます。次のようなチェックが含まれます（これらに限りません）。

JSON の誤字やゲームから削除された非推奨フィールドなど、未使用フィールド。
非推奨機能の警告と移行方法。
奇妙な動作につながる可能性のチェック。

古い Mod や更新頻度の低い Mod では何百もの警告が出ることがあるため、既定では無効です。ゲーム内オプション（Options → Debug タブ → Report unused JSON fields）で有効にできます。

BN に変更を提案する場合、テスト実行ファイル tests/cata_test[.exe] とリポジトリの自動 PR チェックでは、このオプションが有効な状態で実行されることに注意してください。

TODO: 一覧のすべてのチェックを示す名前に変更し、既定で有効にすることも検討する。

タイルセットの再読み込みとレポート

タイルセット制作者向けの機能です。ディスクからアクティブなタイルセットを再読み込みし、画面を再描画して、完全性レポートをデバッグログに書き込みます。

使用するには Reload Tileset アクションを任意のキーに割り当てて押します。