KITAQ 개발 시스템
사용 설명서 2026.09

KITAQ SERIES • 참고 판본

KUROSAKI

NES·FDS 실행과 분석

첫 코드 한 줄부터 실행, 관찰, 재시험까지.
소스 스냅샷: 2026년 9월 14일 · 한국어판: 2026년 9월 14일

빌드된 Windows CLI

저장소 루트에 kurosaki.exe가 들어 있습니다. ZIP을 내려받아 실행 파일과 라이선스 문서를 함께 보관하세요. Windows x64용 CLI는 실행 시 Rust, Python, .NET 설치가 필요하지 않습니다. 아래 절차는 소스에서 다시 빌드할 때 사용합니다. 독자적으로 작성한 프로젝트 코드는 DAISUKE OBA가 MIT로 제공합니다. 의존 라이브러리의 조건은 BINARY_NOTICES.md와 licenses/에 유지합니다.

1. KUROSAKI의 역할

KUROSAKI는 KITAQFC의 정보를 읽어 활용하는 NES·패미컴·FDS 관찰용 에뮬레이터입니다. CLI에서 ROM 검사, 실행, 녹음, 진단, 상태 저장, 입력 재생, 역어셈블, 함수 후보 디컴파일을 수행합니다. 매퍼별 구현 범위가 다르므로 ROM과 지원 정보를 먼저 확인하세요.

2. 빌드와 첫 실행

powershell
Push-Location .\kurosaki
.\scripts\build.ps1
.\kurosaki.exe --help
Pop-Location

아래의 짧은 kurosaki 명령은 실행 파일 폴더가 PATH에 등록되어 있다고 가정합니다. 그렇지 않다면 명령 이름을 & "실행 파일의 전체 경로"로 바꾸세요.

powershell
kurosaki inspect-rom .\out\hello.nes --json .\out\rom.json
kurosaki run .\out\hello.nes --frames 120 --png .\out\hello.png --json .\out\run.json

제4권의 hello ROM으로 문자 표시를 확인하세요. inspect-rom은 헤더를 검사하고, run은 CPU와 PPU 실행을 진행합니다. 헤더 검사 성공이 실제 실행 성공을 보장하지는 않습니다.

3. 매퍼와 보드 확인

네임테이블 RAM 매핑

PPU 읽기·쓰기와 렌더링에는 AxROM의 하위/상위 단일 화면 선택, FME7의 수직/수평/하위/상위 선택, CIRAM만 사용하는 MMC5 배치 16가지가 반영됩니다. MMC5 ExRAM과 채우기 렌더링은 지원하지 않습니다. 검증한 동작은 KITAQFC의 보드별 예제를 참고하세요.

모드 값과 실행한 예제

mapper-list는 등록된 매퍼 종류, mapper-info는 특정 매퍼의 설명, audit-board는 보드 제약 검사를 제공합니다. 매퍼 번호는 ROM 헤더와 실제 배선에 관한 가정을 연결합니다. 이름만으로 용량, CHR-RAM, 고정 뱅크 동작이 확인되는 것은 아닙니다.

powershell
kurosaki mapper-list
kurosaki mapper-info 4
kurosaki audit-board .\out\surom.nes --expected-board surom512 --json .\out\board.json

--allow-unimplemented를 사용하면 미지원 요소를 만난 뒤에도 관찰을 계속할 수 있습니다. 이 옵션을 사용한 실행은 해당 요소가 지원된다는 증거가 아닙니다.

4. 컨트롤러 입력

run --pad1, --pad2는 NES 원시 버튼 마스크를 사용합니다. A=1, B=2, SELECT=4, START=8, UP=16, DOWN=32, LEFT=64, RIGHT=128입니다. 동시에 누를 버튼의 값을 더해 지정하세요.

powershell
kurosaki run .\out\game.nes --frames 120 --pad1 1 --png .\out\held_a.png --json .\out\held_a.json

이 예는 A를 120프레임 동안 누릅니다. 타이틀 → 시작 → 확인처럼 순서가 있는 조작에는 리플레이를 사용하세요. CLI의 replay-record 예는 대화형 입력 없이 기준 실행을 기록하며, 사람이 GUI를 조작하는 모습을 녹화하는 것과 다릅니다.

5. 스냅샷과 리플레이

powershell
kurosaki snapshot-save .\out\game.nes --frames 120 --out .\out\title.kss.json
kurosaki snapshot-load .\out\title.kss.json
kurosaki replay-record .\out\game.nes --frames 120 --out .\out\baseline.replay.json
kurosaki replay-run .\out\game.nes .\out\baseline.replay.json --json .\out\replay.json

재개 가능한 상태는 버전 2 스냅샷을 사용합니다. 상태와 ROM의 SHA-256을 맞춰 보관하세요. snapshot-resume은 저장 지점에서 실행을 이어 갑니다. snapshot-rebase는 명시한 호환성 계약에 따라 다른 ROM으로 상태를 옮깁니다. 코드나 RAM 배치를 바꾼 뒤 예전 상태를 무조건 재사용하면 안 됩니다. 보통은 시작부터 같은 조작을 다시 수행하는 편이 적절합니다.

스냅샷 JSON의 오디오 타이밍 소수 값은 f64 정밀도를 유지해 저장하고 읽습니다. 이 숫자를 반올림하거나 다시 쓰지 마세요. 저장된 타이밍 값이 바뀌면 ROM과 입력이 같아도 재개 후 상태의 완전한 일치를 비교할 수 없습니다.

6. 트레이스, 진단, 프로파일

powershell
kurosaki trace .\out\game.nes --frames 2 --cpu --ppu --apu --mapper --nmi --dma --out .\out\trace.jsonl
kurosaki diagnose .\out\game.nes --frames 120 --out .\out\diagnostics.json --md .\out\diagnostics.md
kurosaki profile .\out\game.nes --frames 120 --out .\out\profile.json

트레이스는 시간에 따른 사건, 진단은 규칙에 해당하는 관찰, 프로파일은 실행이 집중된 위치를 보여 줍니다. 긴 전체 기록보다 이상 현상 전후 몇 프레임을 살펴보는 편이 이해하기 쉽습니다.

--kitaqfc-debug에는 해당 빌드와 일치하는 디버그 JSON을 전달하세요. 소스 줄 정보가 없는 관찰을 완전한 소스 수준 트레이스로 해석하면 안 됩니다.

7. 화면과 소리 저장

powershell
kurosaki audio-export .\out\sound.nes --frames 180 --wav .\out\sound.wav --json .\out\audio.json
kurosaki run .\out\game.nes --frames 120 --png .\out\frame.png --snapshot .\out\frame.kss.json --json .\out\frame.json

레지스터 변화, PCM 생성, 올바르게 들리는 소리는 서로 다른 검사입니다. 기본 음원과 확장 음원을 시험할 때는 매퍼도 기록하세요. PNG 한 장만으로 움직임이나 입력 동작을 확인할 수 없으므로 전후 상태와 입력도 함께 남기세요.

8. 역어셈블과 디컴파일

powershell
kurosaki disasm .\out\game.nes --bytes 256 --text .\out\reset.txt
kurosaki decompile .\out\game.nes --format markdown --out .\out\decompile.md

disasm은 명령열을, decompile은 함수 경계 후보, CFG, 참조, 의사 코드를 출력합니다. 전환 가능한 뱅크에서는 CPU 주소만으로 ROM의 실제 위치를 특정할 수 없습니다. 필요하면 --snapshot으로 매퍼 상태를 제공하고, 실행 트레이스나 주석을 근거로 대조하세요. 원본 소스의 완전한 복원은 아닙니다.

Reset, Nmi, Irq는 캡처한 매퍼 상태에서 읽은 각 벡터로 식별합니다. 그 밖의 스냅샷 현재 PC는 자동 이름 sub_B...를 가진 current_pc 후보이며, 리셋 발생이나 확정된 함수 경계의 증거가 아닙니다.

9. SARAKURA 연동

powershell
kurosaki run .\out\game.nes --frames 300 --emit-diagnostics .\out\kurosaki_events.jsonl --json .\out\run.json
sarakura fc analyze --metadata .\out\build.json --events .\out\kurosaki_events.jsonl --out .\out\fc_report --fail-on error

KUROSAKI의 --emit-diagnostics에도 KOKURA와 마찬가지로 JSONL 파일 경로를 전달합니다. CPU 트레이스와 진단 이벤트 파일을 구분해 보관하세요.

10. FDS와 세이브 RAM

fds-inspect는 디스크 구조를 검사하고 export-assets는 리소스를 내보냅니다. FDS는 시작, BIOS, 디스크 접근 조건이 NES 카트리지와 다르므로 별도로 시험하세요. 배터리 저장용 .sav와 .kss.json 스냅샷은 목적이 다릅니다. 구현이 지원하는 저장 구성을 사용해야 합니다.

powershell
kurosaki battery-export .\out\game.nes .\out\title.kss.json --out .\out\save.sav
kurosaki battery-run .\out\game.nes --sav .\out\save.sav --frames 120 --save-out .\out\next.sav --png .\out\battery.png

battery-export는 서로 일치하는 ROM과 스냅샷에서 원시 세이브 RAM을 추출합니다. battery-run은 그 RAM을 읽고 전원 투입 상태에서 시작합니다. 중단된 CPU·PPU 실행 상태를 복구하는 기능은 아닙니다. 출력은 --save-out으로 지정하세요. 이 기능은 세이브 RAM을 갖춘 지원 ROM에 필요하며, 모든 학습용 ROM에 적용되는 것은 아닙니다.

명령 문법 참조

아래 도움말은 이 소스 판본에서 수집한 것입니다. 선택 인수, 기본값, 허용값을 확인하고 예시 파일 이름은 자신의 파일로 바꾸세요. 실제 도구 응답은 원문을 유지합니다.

kurosaki
help
KITAQFC-aware clean-room NES observation emulator CLI

Usage: kurosaki.exe <COMMAND>

Commands:
  battery-export   Export raw battery RAM from a matching snapshot (not a snapshot file)
  battery-run      Cold boot with an explicit battery file; no implicit save-file writes
  inspect-rom      
  audit-board      
  run              
  trace            
  audio-export     
  profile          
  diagnose         
  replay-record    
  replay-run       
  snapshot-save    
  snapshot-load    
  snapshot-rebase  Rebind a reviewed v2 snapshot to an explicitly allowlisted compatible ROM
  snapshot-resume  
  diff             
  decompile        Recover bounded function CFGs and readable pseudocode from a mapper context
  disasm           
  mapper-test      
  fds-inspect      
  export-assets    
  report           
  mapper-list      
  mapper-info      
  help             Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version
kurosaki battery-export — 저장 상태에서 배터리 RAM 원시 데이터 추출
powershell
kurosaki battery-export out/game.nes out/state.kss.json --out out/save.sav
help
Export raw battery RAM from a matching snapshot (not a snapshot file)

Usage: kurosaki.exe battery-export --out <OUT> <ROM> <SNAPSHOT>

Arguments:
  <ROM>       
  <SNAPSHOT>  

Options:
      --out <OUT>  
  -h, --help       Print help
kurosaki battery-run — 저장된 RAM으로 전원 투입 상태에서 시작
powershell
kurosaki battery-run out/game.nes --sav out/save.sav --frames 120 --png out/loaded.png --save-out out/next.sav
help
Cold boot with an explicit battery file; no implicit save-file writes

Usage: kurosaki.exe battery-run [OPTIONS] --sav <SAV> <ROM>

Arguments:
  <ROM>  

Options:
      --sav <SAV>            
      --frames <FRAMES>      [default: 600]
      --replay <REPLAY>      
      --json <JSON>          
      --snapshot <SNAPSHOT>  
      --png <PNG>            
      --save-out <SAVE_OUT>  
  -h, --help                 Print help
kurosaki inspect-rom — ROM 헤더 검사
powershell
kurosaki inspect-rom out/game.nes --json out/rom.json
help
Usage: kurosaki.exe inspect-rom [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --json <JSON>  
      --md <MD>      
  -h, --help         Print help
kurosaki audit-board — 보드 요구 사항 검사
powershell
kurosaki audit-board out/game.nes --expected-board surom512 --json out/board.json
help
Usage: kurosaki.exe audit-board [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --expected-board <EXPECTED_BOARD>  [default: surom512]
      --metadata <METADATA>              
      --json <JSON>                      
  -h, --help                             Print help
kurosaki run — 지정 프레임 수만큼 실행
powershell
kurosaki run out/game.nes --frames 120 --png out/game.png --json out/run.json
help
Usage: kurosaki.exe run [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>                                  [default: 1]
      --max-instructions <MAX_INSTRUCTIONS>              
      --headless                                         
      --state-hash <STATE_HASH>                          
      --json <JSON>                                      
      --md <MD>                                          
      --png <PNG>                                        
      --snapshot <SNAPSHOT>                              
      --observe-json <OBSERVE_JSON>                      
      --trace-jsonl <TRACE_JSONL>                        
      --emit-diagnostics <EMIT_DIAGNOSTICS>              
      --repro-bundle <REPRO_BUNDLE>                      
      --break-on-diagnostic <BREAK_ON_DIAGNOSTIC>        
      --png-on-diagnostic <PNG_ON_DIAGNOSTIC>            
      --snapshot-on-diagnostic <SNAPSHOT_ON_DIAGNOSTIC>  
      --kitaqfc-debug <KITAQFC_DEBUG>                    
      --allow-unimplemented                              
      --pad1 <PAD1>                                      [default: 0]
      --pad2 <PAD2>                                      [default: 0]
  -h, --help                                             Print help
kurosaki trace — 시간순 이벤트 트레이스 기록
powershell
kurosaki trace out/game.nes --frames 2 --cpu --ppu --out out/trace.jsonl
help
Usage: kurosaki.exe trace [OPTIONS] --out <OUT> <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>                [default: 1]
      --out <OUT>                      
      --cpu                            
      --mem-read                       
      --mem-write                      
      --ppu                            
      --apu                            
      --mapper                         
      --nmi                            
      --dma                            
      --full                           
      --kitaqfc-debug <KITAQFC_DEBUG>  
      --allow-unimplemented            
      --pad1 <PAD1>                    [default: 0]
      --pad2 <PAD2>                    [default: 0]
  -h, --help                           Print help
kurosaki audio-export — PCM 음향을 WAV로 저장
powershell
kurosaki audio-export out/game.nes --frames 120 --wav out/audio.wav
help
Usage: kurosaki.exe audio-export [OPTIONS] --wav <WAV> <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>      [default: 60]
      --wav <WAV>            
      --json <JSON>          
      --allow-unimplemented  
      --trace-audio          
      --pad1 <PAD1>          [default: 0]
      --pad2 <PAD2>          [default: 0]
  -h, --help                 Print help
kurosaki profile — 실행 집중 지점 찾기
powershell
kurosaki profile out/game.nes --frames 120 --out out/profile.json
help
Usage: kurosaki.exe profile [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>                [default: 60]
      --out <OUT>                      
      --md <MD>                        
      --kitaqfc-debug <KITAQFC_DEBUG>  
      --allow-unimplemented            
  -h, --help                           Print help
kurosaki diagnose — 정적·실행 시 진단 생성
powershell
kurosaki diagnose out/game.nes --frames 120 --out out/diagnostics.json
help
Usage: kurosaki.exe diagnose [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>
          [default: 0]
      --out <OUT>
          
      --md <MD>
          
      --emit-diagnostics <EMIT_DIAGNOSTICS>
          
      --check <CHECK>
          [possible values: ppu, nmi, mapper, apu, abi, input, fds, asset]
      --kitaqfc-debug <KITAQFC_DEBUG>
          
      --allow-unimplemented
          
      --pad1 <PAD1>
          [default: 0]
      --pad2 <PAD2>
          [default: 0]
  -h, --help
          Print help
kurosaki replay-record — 기준 리플레이 기록
powershell
kurosaki replay-record out/game.nes --frames 120 --out out/replay.json
help
Usage: kurosaki.exe replay-record [OPTIONS] --out <OUT> <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>      [default: 60]
      --out <OUT>            
      --allow-unimplemented  
  -h, --help                 Print help
kurosaki replay-run — 기록된 입력 순서 실행
powershell
kurosaki replay-run out/game.nes out/replay.json --json out/replay-result.json
help
Usage: kurosaki.exe replay-run [OPTIONS] <ROM> <REPLAY>

Arguments:
  <ROM>     
  <REPLAY>  

Options:
      --load-snapshot <LOAD_SNAPSHOT>
          Restore this version-2 snapshot before applying the replay timeline. With this option, --frames and trace bounds are absolute emulator frames
      --frames <FRAMES>
          
      --verify
          
      --json <JSON>
          
      --png <PNG>
          
      --snapshot <SNAPSHOT>
          
      --observe-json <OBSERVE_JSON>
          
      --wav <WAV>
          
      --trace-jsonl <TRACE_JSONL>
          
      --trace-start-frame <TRACE_START_FRAME>
          
      --trace-end-frame-exclusive <TRACE_END_FRAME_EXCLUSIVE>
          
      --cpu
          
      --mem-read
          
      --mem-write
          
      --ppu
          
      --apu
          
      --mapper
          
      --nmi
          
      --dma
          
      --full
          
      --allow-unimplemented
          
  -h, --help
          Print help
kurosaki snapshot-save — 기기 상태 저장
powershell
kurosaki snapshot-save out/game.nes --frames 120 --out out/state.kss.json
help
Usage: kurosaki.exe snapshot-save [OPTIONS] --out <OUT> <ROM>

Arguments:
  <ROM>  

Options:
      --frames <FRAMES>      [default: 1]
      --out <OUT>            
      --allow-unimplemented  
      --pad1 <PAD1>          [default: 0]
      --pad2 <PAD2>          [default: 0]
  -h, --help                 Print help
kurosaki snapshot-load — 상태 파일 검사
powershell
kurosaki snapshot-load out/state.kss.json --json out/state-summary.json
help
Usage: kurosaki.exe snapshot-load [OPTIONS] <SNAPSHOT>

Arguments:
  <SNAPSHOT>  

Options:
      --json <JSON>  
  -h, --help         Print help
kurosaki snapshot-rebase — 호환성 계약이 허용하는 ROM으로 상태 이전
powershell
kurosaki snapshot-rebase out/before.nes out/after.nes out/state.kss.json --contract out/compatibility.json --out out/rebased.kss.json
help
Rebind a reviewed v2 snapshot to an explicitly allowlisted compatible ROM

Usage: kurosaki.exe snapshot-rebase [OPTIONS] --contract <CONTRACT> --out <OUT> <SOURCE_ROM> <TARGET_ROM> <SNAPSHOT>

Arguments:
  <SOURCE_ROM>  
  <TARGET_ROM>  
  <SNAPSHOT>    

Options:
      --contract <CONTRACT>               
      --prg-ram-patch <ADDRESS=FILE>      
      --cpu-ram-patch <ADDRESS=HEXBYTES>  
      --out <OUT>                         
      --json <JSON>                       
  -h, --help                              Print help
kurosaki snapshot-resume — 저장 상태에서 실행 재개
powershell
kurosaki snapshot-resume out/game.nes out/state.kss.json --frames 60 --json out/resumed.json
help
Usage: kurosaki.exe snapshot-resume [OPTIONS] <ROM> <SNAPSHOT>

Arguments:
  <ROM>       
  <SNAPSHOT>  

Options:
      --reset-at-start               Reset the CPU after restoring the snapshot while retaining mapper RAM
      --frames <FRAMES>              [default: 1]
      --out <OUT>                    
      --json <JSON>                  
      --png <PNG>                    
      --observe-json <OBSERVE_JSON>  
      --trace-jsonl <TRACE_JSONL>    
      --cpu                          
      --mem-read                     
      --mem-write                    
      --ppu                          
      --apu                          
      --mapper                       
      --nmi                          
      --dma                          
      --full                         
      --allow-unimplemented          
      --pad1 <PAD1>                  [default: 0]
      --pad2 <PAD2>                  [default: 0]
  -h, --help                         Print help
kurosaki diff — 저장한 결과 비교
powershell
kurosaki diff --before out/before.kss.json --after out/after.kss.json --json out/diff.json
help
Usage: kurosaki.exe diff [OPTIONS] --before <BEFORE> --after <AFTER>

Options:
      --before <BEFORE>  
      --after <AFTER>    
      --json <JSON>      
      --md <MD>          
  -h, --help             Print help
kurosaki decompile — 함수·제어 흐름 그래프·의사 코드 추정
powershell
kurosaki decompile out/game.nes --format markdown --out out/decompile.md
help
Recover bounded function CFGs and readable pseudocode from a mapper context

Usage: kurosaki.exe decompile [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --out <OUT>
          Write the rendered report here; stdout is used when omitted
      --format <FORMAT>
          [default: json] [possible values: json, markdown, text]
      --function <FUNCTIONS>
          Function name or Bnnn:$AAAA physical PRG-bank selector. Repeatable
      --all
          Also start a bounded candidate analysis at $8000 in every physical 8 KiB PRG bank
      --annotations <ANNOTATIONS>
          JSON annotation sidecar. ROM.decompile.json is loaded automatically when present
      --snapshot <SNAPSHOT>
          Restore a version-2 snapshot before capturing the PRG-bank windows
      --trace-jsonl <TRACE_JSONL>
          KUROSAKI trace JSONL to overlay exact physical-bank/PC hit counts
      --max-instructions <MAX_INSTRUCTIONS>
          Per-function static-analysis cap, preventing data from causing unbounded output [default: 2048]
  -h, --help
          Print help
kurosaki disasm — CPU 명령 표시
powershell
kurosaki disasm out/game.nes --bytes 256 --text out/disasm.txt
help
Usage: kurosaki.exe disasm [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --bytes <BYTES>              [default: 256]
      --start <START>              CPU address in decimal or with a 0x/$ hexadecimal prefix
      --snapshot <SNAPSHOT>        Restore a version 2 snapshot before reading mapped CPU bytes
      --prg-bank-8k <PRG_BANK_8K>  Read one exact physical 8 KiB PRG-ROM bank, independent of mapper state
      --json <JSON>                
      --text <TEXT>                
  -h, --help                       Print help
kurosaki mapper-test — 매퍼 동작 관찰
powershell
kurosaki mapper-test out/game.nes --json out/mapper-test.json
help
Usage: kurosaki.exe mapper-test [OPTIONS] <ROM>

Arguments:
  <ROM>  

Options:
      --json <JSON>  
  -h, --help         Print help
kurosaki fds-inspect — 디스크 구조 검사
powershell
kurosaki fds-inspect out/game.fds
help
Usage: kurosaki.exe fds-inspect [OPTIONS] <DISK>

Arguments:
  <DISK>  

Options:
      --json <JSON>  
  -h, --help         Print help
kurosaki export-assets — ROM 리소스 내보내기
powershell
kurosaki export-assets out/game.nes --out out/assets
help
Usage: kurosaki.exe export-assets --out <OUT> <ROM>

Arguments:
  <ROM>  

Options:
      --out <OUT>  
  -h, --help       Print help
kurosaki report — 저장된 관찰로 보고서 작성
powershell
kurosaki report out/run.json --md out/report.md
help
Usage: kurosaki.exe report --md <MD> <INPUT>

Arguments:
  <INPUT>  

Options:
      --md <MD>  
  -h, --help     Print help
kurosaki mapper-list — 등록된 매퍼 목록
powershell
kurosaki mapper-list
help
Usage: kurosaki.exe mapper-list [OPTIONS]

Options:
      --all          
      --json <JSON>  
      --md <MD>      
  -h, --help         Print help
kurosaki mapper-info — 매퍼 설명
powershell
kurosaki mapper-info 4
help
Usage: kurosaki.exe mapper-info [OPTIONS] <MAPPER>

Arguments:
  <MAPPER>  

Options:
      --json <JSON>  
  -h, --help         Print help