게임 내 디버깅 도구

게임에는 문제를 디버깅하고 수정 사항이나 새 요소를 테스트하는 데 도움이 되는 여러 내장 도구가 있습니다.

주요 도구는 다음과 같습니다.

디버그 메시지

debugmsg, 또는 "검은 화면 위의 빨간 글자"라고도 합니다. 데이터 파일 오류나 내부 상태의 불일치를 게임이 발견하면 표시됩니다.

이미지

심각도는 무해하고 세부적인 경고부터 복구할 수 없는 충돌까지 다양합니다. 각 메시지의 사본은 보통 오류가 발생한 위치를 설명하는 백트레이스가 앞에 붙은 상태로 디버그 로그에 저장됩니다.

space를 눌러 메시지를 닫거나, i를 눌러 메시지와 게임을 재시작할 때까지 이어지는 모든 메시지를 닫을 수 있습니다.

게임 실행 파일을 --dont-debugmsg 명령줄 옵션과 함께 실행하면(위험을 감수하고) 모든 디버그 메시지를 억제할 수 있습니다.

코드에서는 다음과 같이 디버그 메시지를 호출합니다.

#include "debug.h" // 자세한 내용은 이 헤더 참조
 . . .
// 첫 번째 인수는 형식 문자열입니다. 자세한 내용은 `string_formatter.h` 참조
 debugmsg( "Failed to open file, code %d", 123 );

디버그 로그

디버그 로그에는 일반 정보, 경고, 심각한 오류 등 게임이 생성한 여러 상태 메시지가 들어 있습니다. 대부분의 버그를 처음 진단할 때 확인하는 곳입니다.

사용자의 config 폴더에 있는 debug.log라는 단일 파일에 저장됩니다.

게임 옵션(Options → Debug 탭 → Logging 하위 메뉴)에서 로그 상세도를 직접 조절할 수 있습니다.

이미지

코드에서 로그에 출력하는 예시는 다음과 같습니다.

#include "debug.h" // 자세한 내용은 이 헤더 참조
 . . .
// 첫 번째 인수는 심각도, 두 번째 인수는 카테고리입니다.
// 끝에 줄바꿈을 붙이지 마세요. 자동으로 추가됩니다.
DebugLogFL( DL::Info, DC::Map ) << "My " << "logged" << " info!";

충돌 로그

충돌 로그에는 게임 충돌 후의 백트레이스가 들어 있습니다. 어떤 코드가 어디에서 충돌했는지에 대한 정보를 사실상 그대로 담고 있으므로 충돌 해결에 매우 유용합니다.

사용자의 config 폴더에 있는 crash.log라는 단일 파일에 저장됩니다.

충돌이 매우 특이하거나 실행 파일이 백트레이스 지원 없이 빌드된 경우에는 충돌 로그가 생성되지 않을 수 있습니다.

코드에 충돌 추적용 특별한 로직을 추가할 필요는 없지만 빌드에서 백트레이스를 활성화해야 합니다. 일부 빌드는 백트레이스를 더 읽기 쉽게 해 주는 선택적 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 데이터 검사를 활성화할 수 있습니다. 검사에는 다음 항목이 포함되며 이에 한정되지 않습니다.

  1. JSON 오타나 게임에서 제거된 사용 중단 필드로 인해 생긴 미사용 필드.
  2. 사용 중단 경고와 마이그레이션 안내.
  3. 이상한 동작이 발생할 가능성에 대한 검사.

오래되었거나 관리가 드문 모드는 수백 개의 경고를 낼 수 있으므로 기본적으로 비활성화되어 있습니다. 게임 옵션(Options → Debug 탭 → Report unused JSON fields)에서 활성화할 수 있습니다.

BN에 변경 사항을 제안하려면 테스트 실행 파일 tests/cata_test[.exe]와 저장소의 자동 PR 검사가 이 옵션을 활성화한 상태로 실행된다는 점을 기억하세요.

TODO: 나열된 모든 검사를 나타내도록 옵션 이름을 바꾸고 기본 활성화도 검토합니다.

이미지

타일셋 다시 불러오기 및 보고서

타일셋 제작자에게 유용한 기능입니다. 디스크에서 활성 타일셋을 다시 불러오고 화면을 다시 그린 다음 완전성 보고서를 디버그 로그에 기록합니다.

사용하려면 아무 키에 Reload Tileset 동작을 지정하고 누르세요.

이미지