TypeSafe Jev와 구조화된 에뮬레이터 텔레메트리로 슈퍼 마리오 브라더스 조작하기

TypeSafe Mario의 기능

TypeSafe Mario는 TypeSafe의 Jev 모델이 오리지널 Super Mario Bros.의 컨트롤러 입력을 선택하도록 하는 실험적 컨트롤러입니다. 모델은 스크린샷을 받는 대신 에뮬레이터 텔레메트리와 RAM에서 추출한 간결한 객체 중심 JSON을 받습니다.

제어 루프는 다음 아키텍처를 따릅니다.

NES 에뮬레이터 -> 텔레메트리/RAM 파서 -> 구조화된 JSON -> Jev Choice -> 컨트롤러 입력

Jev가 유효한 동작을 선택하면 에뮬레이터가 여러 프레임을 진행하고 새로운 상태를 생성합니다. 이 과정은 에피소드 전체에서 반복됩니다. 원시 로컬 타일 그리드는 디버그 로그와 대시보드에서 계속 확인할 수 있지만, 모델 입력에는 중복해서 포함되지 않습니다.

사용 가능한 컨트롤러 동작

초기 동작 공간은 의도적으로 다음 7개의 컨트롤러 매크로로 제한됩니다.

• noop
• right
• right_jump
• right_run
• right_run_jump
• jump
• left

주요 기능

• 구조화된 모델 입력: 파서는 평면화된 설명문이나 스크린샷 대신 TypeSafe가 이해할 수 있는 의미 있는 JSON 객체를 전송합니다.
• 다중 판단: 모든 요청은 컨트롤러 선택, 전방 점프의 유용성, 즉각적인 위험을 평가합니다.
• 측정된 반응 시간: 상태에는 동작 지속 시간과 관찰부터 동작까지의 지연 시간이 포함됩니다.
• 실시간 대시보드: 기본 화면은 게임플레이와 동작 확률, 신뢰도, 지연 시간, 위험도, 보상, 파싱된 상태를 함께 표시합니다.
• 상세 실행 기록: 모든 결정은 나중에 분석하거나 시각화할 수 있도록 JSON Lines 레코드로 저장됩니다.
• 디버그 가시성: 사람이 읽을 수 있는 상태 텍스트와 로컬 타일 그리드를 계속 확인할 수 있습니다.

요구 사항 및 합법적인 설정

프로젝트를 설치하기 전에 환경이 다음 요구 사항을 충족하는지 확인하세요.

• Python 3.13 이상
• TYPESAFE_API_KEY에 저장된 TypeSafe API 키
• Super Mario Bros.를 합법적으로 사용할 수 있는 로컬 환경

저장소에는 Nintendo ROM이나 기타 저작권이 있는 게임 데이터가 포함되어 있지 않습니다. 에뮬레이터와 게임 파일을 합법적으로 입수하고 사용하는 책임은 사용자에게 있습니다.

설치

README에는 가상 환경을 만들고 Mario 및 개발 의존성을 설치하며 API 키를 설정하는 PowerShell 명령이 안내되어 있습니다.

1. Python 3.13 가상 환경을 만듭니다.
2. 필요한 추가 기능과 함께 프로젝트를 editable 모드로 설치합니다.
3. 현재 PowerShell 세션에 TypeSafe API 키를 설정합니다.

py -3.13 -m venv .venv
.venv\Scripts\python -m pip install -e ".[mario,dev]"
$env:TYPESAFE_API_KEY = "your-key"

your-key를 실제 TypeSafe API 키로 바꾸세요. 이 명령은 PowerShell 환경 변수를 설정하므로, 변수를 별도로 영구 저장하지 않았다면 이후 명령을 동일하게 설정된 환경에서 실행해야 합니다.

먼저 모델 입력 확인하기

게임을 실행하기 전에 state-demo를 사용해 프로젝트가 TypeSafe로 전송할 정확한 JSON과 텍스트를 확인하세요.

.venv\Scripts\typesafe-mario state-demo

이 명령은 게임을 실행하지 않으며 API도 호출하지 않습니다. 모델 입력 스키마를 이해하고 에뮬레이터 관찰 결과가 어떻게 표현되는지 확인하는 가장 안전한 방법입니다.

구조화된 상태 이해하기

표준 객체는 관찰 결과를 용도별로 그룹화합니다.

• player: 위치, 속도, 지면 접촉 상태, 점프 단계, 파워업.
• trajectory: 체공 시간, 이륙 후 이동 거리, 그리고 Mario가 틈을 건너는 동작에 들어갔는지 여부.
• hazard: 최대 3명의 적, 예상 위치, 예상 접촉 시점, 이륙 마감 시점.
• terrain: 장애물과 틈의 형태, 관찰 신뢰도, 마지막 지면 접촉 시 미리 본 정보.
• reaction_timing: 컨트롤러 동작 지속 시간과 측정된 관찰부터 동작까지의 지연 시간.
• recent_control: 이전 동작, 지속 시간, 얻은 진행도, 관찰된 결과.
• episode: 목숨, 시간, 진행도, 정체 횟수, 사망 상태, 레벨 완료 여부.

구조화된 JSON이 모델 상태의 표준 형식입니다. 더 자세한 텍스트 렌더링은 디버깅과 사용자 인터페이스에만 사용됩니다. 디버그 스냅샷에는 Mario의 좌표와 이동 정보, 에피소드 진행도, 주변 적, 문자로 표현된 로컬 타일 그리드가 포함될 수 있습니다.

월드 1-1 실행

월드 1-1 환경을 시작하고 Jev가 에뮬레이터 스텝 8회마다 동작을 선택하도록 하세요.

.venv\Scripts\typesafe-mario play --env SuperMarioBros-1-1-v0 --frames-per-decision 8

--env 옵션은 환경을 선택하고, --frames-per-decision 8은 모델이 결정을 내리는 사이에 진행할 에뮬레이터 스텝 수를 정합니다. 기본 화면을 사용하면 프로젝트가 실시간 게임과 모델 텔레메트리를 함께 표시하는 기록 가능한 창 하나를 엽니다.

대시보드 사용

대시보드에는 Jev의 동작을 추적하는 데 필요한 정보가 표시됩니다.

• 선택된 컨트롤러 동작
• 전체 Choice 확률 분포
• 모델 신뢰도
• Jev 요청 지연 시간
• 전방 점프 확률
• 즉각적인 위험 점수
• 보상
• 파싱된 게임 상태

새 에피소드를 시작하려면 R을 누르거나 Restart를 클릭하세요. Mario가 죽거나 레벨을 완료한 후에도 대시보드는 열려 있습니다. 종료하려면 Esc 또는 Q를 누르세요.

디스플레이 모드 선택

기본 결합 대시보드는 플레이를 관찰하거나 녹화할 때 유용합니다. 추가로 두 가지 모드가 특정 용도에 맞게 제공됩니다.

에뮬레이터만 표시

.venv\Scripts\typesafe-mario play --env SuperMarioBros-1-1-v0 --frames-per-decision 8 --display game

game 디스플레이 모드는 에뮬레이터 창만 표시합니다.

디스플레이 없이 실행

.venv\Scripts\typesafe-mario play --env SuperMarioBros-1-1-v0 --frames-per-decision 8 --display none

none 디스플레이 모드는 헤드리스로 실행되며 벤치마크 방식의 실행에 적합합니다.

TypeSafe의 세 가지 판단 이해하기

각 요청은 동일한 구조화된 상태를 바탕으로 서로 독립적인 세 가지 판단을 평가합니다.

• Choice: 다음에 사용할 수 있는 컨트롤러 매크로를 선택합니다.
• Noul: 현재 시점에 전방 점프가 유용한지 추정합니다.
• Score: 라이브 시각화에 사용할 즉각적인 위험도를 측정합니다.

이 판단들은 서로 다른 역할을 합니다. Choice 결과가 Mario를 제어하고, 점프 추정치와 위험도는 추가적인 해석 및 시각화 정보를 제공합니다.

정확한 타이밍 계산은 코드에 남아 있습니다. 예를 들어 파서는 응답 경과 시간, 적의 움직임, 행동 주기, 점프에 필요한 여유 시간을 결합해 타입이 지정된 jump_must_start_this_decision 사실을 생성합니다. Jev는 이 사실을 해석하면서 컨트롤러 선택권을 계속 담당하며, 하네스는 스크립트로 작성된 복구 행동을 대신 적용하지 않습니다.

기록된 판단 검사

각 판단은 타임스탬프가 포함된 JSON Lines 파일에 기록됩니다.

artifacts/run-<timestamp>.jsonl

기록에는 다음 항목이 포함됩니다.

• Jev 지연 시간
• 행동 확률
• 신뢰도
• 정규 모델 상태
• 원시 디버그 상태
• 게임 결과

이 기록을 사용하면 실행 후 플레이를 검사하는 데 필요한 데이터를 확보할 수 있습니다. 라이브 오버레이나 렌더링된 소셜 클립의 입력으로도 사용할 수 있습니다.

고급 사용 팁

게임플레이 전에 관찰 결과 검증

에뮬레이터를 시작하거나 API 호출을 사용하지 않고 모델에 전달되는 표현을 검토하려면 라이브 세션 전에 state-demo를 실행하세요. 정규 구조화 상태와 사람이 읽는 디버그 텍스트가 어떻게 구분되는지 특히 주의해서 확인하세요.

행동 주기와 함께 타이밍 정보 해석

컨트롤러는 여러 프레임 간격으로 작동하므로 반응 타이밍은 외부 가정이 아니라 상태의 일부입니다. 판단을 검토할 때 선택한 행동을 응답 지연, 행동 지속 시간, 예상 적 접촉 시점, 파서가 보고한 이륙 기한과 비교하세요.

작업에 맞는 디스플레이 사용

• 모델 추론 신호와 게임플레이를 함께 검사할 때는 기본 대시보드를 사용하세요.
• 에뮬레이터 출력만 필요할 때는 --display game을 사용하세요.
• 헤드리스 벤치마크 실행에는 --display none을 사용하세요.

전체 확률 분포 분석

선택된 행동만 분석하지 마세요. 대시보드와 JSONL 아티팩트에는 전체 Choice 확률 분포와 신뢰도가 포함되어 있어, Jev가 한 행동을 강하게 선호했는지 또는 비슷한 가중치를 가진 여러 대안 중에서 선택했는지 확인할 수 있습니다.

개발 검사 실행

저장소에는 기여자를 위한 포맷팅, 린팅, 테스트 명령이 포함되어 있습니다. 구성된 가상 환경에서 다음 명령을 실행하세요.

.venv\Scripts\ruff format --check src tests
.venv\Scripts\ruff check src tests
.venv\Scripts\python -m pytest -q

첫 번째 명령은 포맷을 확인하고, 두 번째 명령은 Ruff의 린트 검사를 실행하며, 세 번째 명령은 간결한 출력으로 테스트 모음을 실행합니다.

결론

TypeSafe Mario는 스크린샷 기반 게임 제어를 대신할 구조화된 방식을 보여 줍니다. 에뮬레이터 텔레메트리와 RAM을 정규 객체 중심 JSON으로 변환하고, Jev가 간결한 허용 행동 집합에서 선택하도록 하며, 라이브 검사나 이후 분석을 위해 모든 판단을 기록합니다. state-demo부터 시작해 대시보드에서 World 1-1을 실행하고, 생성된 JSONL 아티팩트를 사용해 상태, 타이밍, 신뢰도, 결과가 서로 어떻게 관련되는지 이해하세요.