KITAQ SERIES • REFERENCE EDITION
KITAQ SERIES
プログラミング・ユーザーズマニュアル
ローカルソース採取：2026年9月14日
ネイティブコンパイラの検証
Windows・Linux・macOS ARM・macOS Intelでネイティブビルドと実行検証が成功しています。KITAQGBは各環境48件のテストと395件の補助ツール検証、KITAQFCは55件と401件が成功しました。Rust 1.85でも確認済みです。PUBLIC_DISTRIBUTION.jsonに配置済みバイナリのハッシュと検証の出典を記録しています。公開GitHub Actionsでもこのソースを独立してビルド・検証します。
保存済みの比較データでROMのバイト列、診断と補助ツールの形式を検証しています。以前のC#版によるエミュレータ検証は、そのソース指紋に対応する過去の記録として残しています。これだけでRust版の全API、実機動作、FDSのBIOS経由のゲーム起動を保証するものではありません。元のPNG変換スクリプトは入手できないため仕様から再実装し、元スクリプトとのバイト一致は確認できません。
はじめに
KITAQGBは、ZachtronicsのNES向けCコンパイラ NORCALのフォーク として始まった、ゲームボーイ／ゲームボーイカラー向けのC系コンパイラです。NORCALを出発点に、GBのCPU、メモリ、映像、音、ROMバンクなどに合わせた機能が加えられています。原作者・原プロジェクトへの敬意を込めて、ここに系譜を明記します。
NORCALの名前は北カリフォルニア（Northern California）に由来します。地域の名前を使うこの命名に着想を得て、作者は自身が生まれ育った北九州市をもとにKITAQGBと名付けました。KITAQ + GB、つまり日本の福岡県北九州市の愛称である北九（キタキュー、Kitakyū）とGame Boyを組み合わせた意味です。KITAQは「キタキュー」と読みます。英語話者向けの発音の目安は kee-tah-KYOO、発音記号は /ˌkiːtɑːˈkjuː/ です。最後のQは英語のアルファベットQと同じ音です。KITAQGBはGとBを一文字ずつ読み、「キタキュー・ジー・ビー」と呼びます。
KITAQGBという名前には、二つの意味があります。Kernel-Informed Toolchain for AI-Quality Game Boy Developmentは、対象マシンを理解し、人間のプログラマーと生成AIの双方を支えるツールチェーンという目標を表しています。
もう一つの意味は、Kids' Imagination Transformed into Actual Quests in Game Boy Forestsです。「子どもの想像を、Game Boyの森で本物の冒険へ変える道具」という意味を込めています。小さなアイデアや落書き、AI支援による試作を、実際に遊べる冒険へ変えていくための道具にしたい、という創作面での願いを表しています。
NORCALはNES版HACK*MATCHに関係してKeith Holman氏が開発したCコンパイラです。NORCAL: A C Compiler for the NES と HACK*MATCH for the NES に原作者による紹介があります。フォークの説明と名称の由来は作者提供のREADMEに基づきます。
このマニュアルの使い方
昔のコンピュータに付属した取扱説明書のように、最初は短いプログラムを入力し、実行結果を見てから仕組みを学びます。わからない語をすべて覚えてから始める必要はありません。
- GBなら第1巻、FCなら第4巻の「最初のプログラム」から始めます。
- 入力・画像・音を加えるときは、第2巻または第5巻の対応する機能へ進みます。
- 画面や音の確認はKOKURA／KUROSAKI、異常の整理はSARAKURAを使います。
- 関数名がわかるときは、検索欄または各巻の命令・API辞典を使います。
「命令」は文法、コンパイラ組み込み関数、ライブラリ関数、コマンドライン操作を分けて説明します。CPUの命令表もコンパイラ巻の付録にあります。GBとFCで同じ名前に見えても、引数や動作が同じとは限りません。
7冊の役割
| 巻 | 入力 | 出力・役割 |
|---|---|---|
| KITAQGB | Cソース・素材 | GB/CGB用ROM、マップ、ビルド情報 |
| KITAQGBライブラリ | ゲームからの関数呼び出し | 描画・音・入力・物理などの処理 |
| KOKURA | GB/CGB用ROM | 実行画面、音、状態、観測ログ |
| KITAQFC | Cソース・CHR素材 | NES/FDS向け出力とビルド情報 |
| KITAQFCライブラリ | ゲームからの関数呼び出し | NES向けの描画・音・機器処理 |
| KUROSAKI | NES/FDSイメージ | 実行・記録・解析 |
| SARAKURA | ビルド情報と診断イベント | 診断HTML、修正・再テストの計画 |
指定フォントの使い方
英大文字26字・数字10字・英小文字26字・記号30字は、作者自作のascii.cを使用しています。全92文字の字形はタイル一覧のとおりです。空白には空のタイルを使います。バックスラッシュと縦棒はこのフォントに含まれず、空白表示になります。gb_font.cとfc_font.cで全字形を表示できます。
本書の版と検証の読み方
本書は2026年9月14日のソースに基づいています。参照一覧にはソースと実行ファイルのSHA-256を記録しています。各試験の入力、条件、確認範囲は検証記録を参照してください。
「ビルド確認」は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> は書式上の引数名であり、山括弧ごと入力しません。長いコマンドは本書では原則1行にしています。Bashの行継続文字 \ をPowerShellへ貼り付けないでください。
この版で修正したコンパイラの問題
サンプルを実行する過程で、KITAQGBの同名ローカル分岐ラベルの混同と、KITAQFCの関数呼び出し時の途中値・戻り値の扱いに問題が見つかりました。本版の検証では修正済みコンパイラを使い、GBのオブジェクトプール例も通常の教材に含めています。 を参照してください。古いEXEで同じ症状が出る場合は、本版のソースからコンパイラを再ビルドします。
API辞典の呼び出し断片は完全なROMとは区別しています。全API・実機・全周辺機器を試験したという意味ではありません。各教材の確認結果は 検証記録 に示します。
HTMLを持ち歩く・公開する
このフォルダーの index.html を開けば、外部CDNやインターネットなしで読めます。スタイル、検索用JavaScript、サンプル、検証画像も相対リンクで同梱しています。HTMLファイルだけを抜き出さず、フォルダー単位で扱ってください。印刷ボタンでは目次欄を省いた紙面になります。
GitHubへアップロードする範囲はこの latest フォルダーです。閲覧用HTMLの生成にサーバー処理は不要です。GitHubでHTMLファイルを開く画面は通常ソース表示になるため、Webマニュアルとして公開する場合はGitHub Pagesなどの静的ホスティングを設定します。公開作業そのものは本書作成時には実行していません。具体的な配置手順は同梱 README.md を参照してください。