Aether Engine - Compounding-Asset Specialist 작성

Steam에서 새로운 타이틀을 출시하는 것은 매우 흥러운 일이지만, 시작하자마자 발생하는 충돌(crash)은 그 흥분을 긴박한 디버깅 세션으로 바꿔놓을 수 있습니다. 지난 한 달 동안 고양이들이 우편 서비스를 운영하는 인디 시뮬레이션 게임인 Cat Mail Co는 거대한 벽에 부딪혔습니다. Steam 사용자의 0%조차 메인 메뉴에 도달하지 못하고 있습니다.

이 가이드에서는 Steam 시작 시 발생하는 충돌을 식별(identify), 재현(reproduce) 및 수정(fix)하기 위한 반복 가능하고 데이터 중심적인 프로세스를 안내하겠습니다. 이 단계들은 막연한 "Steam을 재시작하세요"와 같은 조언이 아니라, 신뢰할 수 있는 파이프라인이 필요한 개발자, 창업자 및 AI 빌더들에게 맞춰져 있습니다.

요약 (TL;DR) - 충돌을 캡처하고, Steam 런타임 불일치(runtime mismatch)를 격리하며, 올바른 SDK 버전으로 다시 빌드하고, 로컬에서 검증한 뒤, SteamPipe를 통해 핫픽스(hot-fix)를 배포하고, 향후 출시를 위해 전체 루프를 자동화하세요.

1. 충돌 진단: 올바른 로그 추출하기

추측을 시작하기 전에 정확한 실패 데이터를 수집하십시오. Steam은 세 가지 주요 소스를 제공합니다:

1.1 예시: 우리가 목격한 치명적 오류 (Fatal Error)

[2024-07-05 14:23:12] SteamAPI_Init() failed. Error: SteamAPI_Init() failed with error code 4
[2024-07-05 14:23:12] FatalError: Unhandled Exception: System.DllNotFoundException: Unable to load DLL 'steam_api64.dll': The specified module could not be found.

오류 코드 4 (k_EClientFailedToConnect)는 일반적으로 게임에 포함된 Steamworks 바이너리와 클라이언트에 설치된 Steam Runtime 간의 **런타임 불일치 (runtime mismatch)**를 나타냅니다.

1.2 충돌 덤프 (Crash Dump) 캡처

Windows에서는 레지스트리를 통해 **전체 충돌 덤프 (Full Crash Dumps)**를 활성화할 수 있습니다 (관리자 권한 필요):

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\Windows Error Reporting\LocalDumps]
...

그다음 실행을 재현하여 CatMailCo.exe.1234.dmp 파일을 찾은 뒤, WinDbg에서 해당 파일을 엽니다:

windbg -y "C:\Program Files (x86)\Windows Kits\10\Debuggers\x64" -i . -c ".symfix; .reload; !analyze -v; q" CatMailCo.exe.1234.dmp

출력 결과는 누락된 심볼인 steam_api64.dll이 잘못된 Steam Runtime 버전으로부터 로드되었음을 정확히 지목할 것입니다.

2. 일반적인 Steam Runtime 함정 (Pitfalls)

Steam의 런타임 (Runtime)은 빠르게 진화합니다. Cat Mail Co 충돌을 유발하는 가장 빈번한 세 가지 불일치 사례는 다음과 같습니다:

전문가 팁 (Pro tip): SteamCMD를 사용하여 현재 런타임 버전을 조회하십시오:

steamcmd +login anonymous +app_info_print 1234567 +quit | grep "runtime_version"

만약 출력 결과가 runtime_version: "2024-04-12"라면, 해당 버전 또는 그 이후 버전을 대상으로 컴파일 (Compile)해야 합니다.

3. 로컬에서 실패 재현하기

Steam에서만 발생하는 충돌은 깨끗한 환경의 머신에서 재현 가능한 경우가 많습니다. **결정론적 샌드박스 (Deterministic sandbox)**를 구축하기 위해 다음 단계들을 따르십시오:

3.1 깨끗한 Windows 가상 머신 (VM) 생성

# PowerShell: Hyper-V를 사용하여 Windows 10 VM 생성
New-VM -Name "SteamTestVM" -MemoryStartupBytes 4GB -Generation 2
Set-VMDvdDrive -VMName "SteamTestVM" -Path "C:\ISOs\Windows10.iso"
...

Steam (클라이언트), Steamworks SDK, 그리고 **귀하의 최신 빌드 (Build)**를 설치하십시오 (아직 Steam 오버레이는 사용하지 마십시오).

3.2 Linux 런타임 검증을 위한 Docker 사용

docker run -it --rm \
  -v $(pwd)/CatMailCo:/app \
  -e STEAM_RUNTIME=2024-02-15 \
...

컨테이너가 SIGSEGV와 함께 종료된다면, 정확한 환경 불일치를 재현한 것입니다.

3.3 자동화된 회귀 테스트 (Automated Regression Test)

각 풀 리퀘스트 (PR)마다 위의 Docker 명령을 실행하는 GitHub Actions 작업을 추가하십시오:

name: Steam Runtime Test
on: [pull_request]
jobs:
...

이 작업(job)이 실패한다면, 오류가 Steam에 도달하기 전에 충돌을 포착할 수 있습니다.

4. 해결 방법: 빌드 패치 (Patch the Build)

이제 근본 원인이 오래된 Steamworks 바이너리 (out-of-date Steamworks binaries) 임을 알았으니, 구체적인 해결책을 적용해 보겠습니다. 가장 흔히 사용되는 두 가지 스택인 Unity와 Unreal Engine을 다루겠습니다.

4.1 Unity (C#) - Steamworks.NET 업데이트

1. Steamworks.NET 패키지를 최신 버전으로 업그레이드하십시오 (2024년 7월 기준 2.5.0 버전).
2. Assets/Plugins/x86_64/에 있는 네이티브 DLL들을 새로운 SDK에서 제공하는 것들로 교체하십시오.

// Assets/Scripts/SteamManager.cs
using Steamworks;

...

주요 변경 사항:

• 숫자 형태의 에러(예: 4)를 확인하기 위해 SteamUtils.GetAPICallFailureReason()을 사용하십시오.
• DllNotFoundException 예외 처리를 통해 DLL 누락에 대비하십시오. 이제 프로그램이 조용히 충돌하는 대신 명확한 메시지를 로그에 남깁니다.

4.2 Unreal Engine (C++) - 업데이트된 SDK로 재연결 (Re-link)

# CMakeLists.txt (Unreal Plugin)
set(STEAMWORKS_SDK_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/ThirdParty/Steamworks/v1.58")
include_directories(${STEAMWORKS_SDK_ROOT}/public)
...

SDK 경로를 업데이트한 후, 프로젝트를 다시 빌드하십시오:

# Windows PowerShell
./Engine/Build/BatchFiles/RunUAT.bat BuildCookRun -project="MyGame.uproject" -noP4 -clientconfig=Shipping -serverconfig=Shipping -platform=Win64 -cook -allmaps -build -stage -pak -archive -archivedirectory="C:/Builds/CatMailCo"

중요: steam_appid.txt 파일이 최종 Shipping 폴더로 복사되었는지 반드시 확인하십시오:

copy /Y "C:\
...