KITAQ SERIES

이 설명서를 시작하며

KITAQGB는 Zachtronics와 관련된 NES용 C 컴파일러 NORCAL에서 출발한 포크입니다. 이를 바탕으로 Game Boy와 Game Boy Color의 CPU, 메모리, 영상, 음향, ROM 뱅크 구조에 맞는 C 계열 개발 도구를 만들었습니다. 원작자인 Keith Holman의 저작권 표시를 유지하며, 원 프로젝트에 감사를 표합니다.

NORCAL이라는 이름은 북부 캘리포니아(Northern California)에서 따왔습니다. 지역의 이름을 사용하는 이 발상에서 영감을 받아, 제작자는 자신이 태어나 자란 기타큐슈시를 바탕으로 KITAQGB라는 이름을 지었습니다. KITAQ + GB는 일본 후쿠오카현 기타큐슈시의 애칭인 北九(キタキュー, Kitakyū)와 Game Boy를 합친 이름입니다. KITAQ는 일본어 ‘キタキュー’로 읽습니다. 영어 발음 안내는 kee-tah-KYOO, IPA는 /ˌkiːtɑːˈkjuː/입니다. 끝의 Q는 영어 알파벳 Q의 이름처럼 발음합니다. KITAQGB는 G와 B를 각각 읽어 kee-tah-KYOO jee bee라고 부릅니다.

KITAQGB라는 이름에는 두 가지 뜻이 있습니다. Kernel-Informed Toolchain for AI-Quality Game Boy Development는 대상 하드웨어를 이해하고, 사람이 직접 프로그래밍하는 과정과 생성형 AI를 활용하는 과정을 모두 지원하는 도구 모음을 지향한다는 뜻입니다.

또 다른 뜻은 Kids' Imagination Transformed into Actual Quests in Game Boy Forests입니다. ‘아이들의 상상을 게임보이의 숲에서 진짜 모험으로 바꾸는 도구’라는 의미를 담았습니다. 작은 아이디어나 낙서, AI의 도움으로 만든 시제품을 실제로 즐길 수 있는 모험으로 바꾸는 도구를 만들고 싶다는 창작의 바람을 나타냅니다.

NORCAL은 NES판 HACK*MATCH와 관련하여 개발되었습니다. 배경은 원작자의 NORCAL 소개와 NES판 HACK*MATCH 소개에서 확인할 수 있습니다.

읽는 순서

옛 컴퓨터 설명서처럼, 직접 입력하고 빌드하여 실행해 볼 수 있는 짧은 프로그램부터 시작합니다. 처음부터 모든 용어를 외울 필요는 없습니다. 화면에 결과를 띄운 뒤 그 원리를 하나씩 익혀 보세요.

1. GB 개발은 제1권, FC 개발은 제4권의 첫 프로그램부터 시작합니다.
2. 제2권과 제5권에서 입력, 그래픽, 소리를 추가하는 방법을 살펴봅니다.
3. KOKURA 또는 KUROSAKI로 실행을 관찰하고, SARAKURA로 진단 결과를 정리합니다.
4. 함수 이름을 알고 있다면 해당 권의 검색 기능이나 API 사전을 이용합니다.

언어 문법, 컴파일러 내장 함수, 라이브러리 함수, 명령줄 명령은 서로 다른 참고 항목입니다. 컴파일러 편에는 CPU 명령어 색인도 있습니다. GB와 FC에서 이름이 같더라도 인수나 동작까지 같다고 가정하지 마세요.

전체 구성

예제에 사용하는 글꼴

영문 대문자 26자, 숫자 10자, 소문자 26자와 기호 30자는 저자가 직접 만든 ascii.c를 사용합니다. 92개 글자 모양은 모두 타일 목록에서 확인할 수 있습니다. 공백에는 빈 타일을 사용합니다. 역슬래시와 세로줄은 이 글꼴에 없어 공백으로 표시됩니다. gb_font.c와 fc_font.c는 전체 글자를 표시합니다.

판본과 검증 범위

이 설명서는 2026년 9월 14일의 소스를 기준으로 합니다. 참조 목록에는 소스와 실행 파일의 해시가 기록되어 있습니다. 각 시험의 입력, 조건, 확인 범위는 검증 기록을 참고하세요.

빌드 성공은 ROM이 생성되었다는 뜻입니다. 실행 검사는 지정한 프레임만큼 에뮬레이터가 진행했음을 뜻합니다. 픽셀 비교, 입력 동작, 소리 검사는 별도의 기록으로 구분합니다. 모든 주변기기나 실기와의 호환성을 보장하는 검사는 아니며, 경고도 로그에 남겨 두었습니다.

작업 폴더 준비

예제 명령은 Windows PowerShell을 기준으로 합니다. C 파일은 UTF-8 텍스트로 저장하세요. 현재 폴더는 명령을 실행하는 위치입니다. 공백이 있는 경로는 따옴표로 감싸고, 필요하면 & "경로" 형태로 실행 파일을 호출합니다. 여러 도구를 함께 사용하는 예제에서는 각 도구의 저장소와 게임 프로젝트를 같은 상위 폴더 아래에 두고, 그 상위 폴더에서 명령을 실행합니다.

# リポジトリのルートで実行します。
New-Item -ItemType Directory -Force out | Out-Null
.\kitaqgb\kitaqgb.exe --help
.\kitaqfc\kitaqfc.exe --help

game.c, game.gb, game.nes는 자신의 파일 이름으로 바꾸세요. <ROM>처럼 꺾쇠괄호로 표시된 부분은 대체할 값이며 괄호 자체는 입력하지 않습니다. 명령은 기본적으로 한 줄로 제시합니다. Bash에서 쓰는 역슬래시 줄바꿈은 PowerShell 문법이 아닙니다.

HTML 읽기와 인쇄

내려받은 폴더의 index.html을 열면 오프라인으로 읽을 수 있습니다. 스타일, 검색, 예제, 검증 이미지는 로컬 파일을 사용하므로 외부 CDN이 필요하지 않습니다. HTML 한 장만 복사하지 말고 폴더 구조를 함께 유지하세요. 인쇄 버튼을 누르면 탐색 열을 제외한 인쇄용 레이아웃을 사용합니다.

소스 코드 발췌와 실제 도구 출력은 원문을 유지하므로 파일이나 명령 결과와 그대로 대조할 수 있습니다.