Emulicious と VS Code で GBC

Emulicious と VS Code で GBC

〜プログラミングとデバッグの準備〜

2026-01-26 作成福島

開発環境

項目内容備考

開発対象ゲームボーイカラーゲームボーイカラーの性能表はこちら

開発言語アセンブラ RGBDS (Rednex GameBoy Development System) LR35902(SM83) の追加命令にも対応している

C コンパイラ GBDK-2020 (GameBoy Development Kit) ROM/RAM バンク切り替えにも対応している

デバッガエミュレータ Emulicious Z80 および Z80 互換 CPU 搭載機エミュレータ

コンソール Visual Studio Code + 拡張機能 Emulicious Debugger ソースコードデバッガ (以下 VS Code と呼称)
https://code.visualstudio.com/download
https://code.visualstudio.com/docs/?dv=win64user

1. エミュレータの用意

1-1. Emulicious の用意

ゲームボーイカラーのエミュレータとして Emulicious を用意する。
Emulicious はゲームボーイカラーだけでなく、CPU Z80 を搭載した他のシステムもサポートする。

GameBoy / GameBoy-Color

MasterSystem

Game Gear

MSX

Emulicious Downloads Section の
Emulicious (with 64-bit Java for Windows) から圧縮ファイル Emulicious-with-Java64.zip をダウンロードする。

Emulicious-with-Java64.zip を解凍し、ディレクトリごと C:\Emulicious-with-Java64\ として設置する。
使用するのは C:\Emulicious-with-Java64\Emulicious.exe となる。

1-2. オープニングの用意。(なくても可)

ゲームボーイの電源を入れると、ロゴが表示されるとともに起動音が鳴動する。
Emulicious にはその機能が無いため、SameBoy から起動バイナリを拝借する。
(SameBoy も優れたエミュレータだが、デバッグ機能が弱いため今回は使用を見送った)

1-2-1. SameBoy を入手する。

SameBoy の Web ページの Download SameBoy x.x.x for Windows から圧縮ファイルをダウンロードする。
今回は sameboy_winsdl_v1.0.2.zip だった。

sameboy_winsdl_v1.0.2.zip から dmg_boot.bin と cbg_boot.bin を取り出し、
C:\Emulicious-with-Java64\ にコピーする。(上記 1-1 で Emulicious を設置したディレクトリ)

1-2-2. emulicious.exe を起動する。

C:\Emulicious-with-Java64\emulicious.exe を起動する。

1-2-3. 起動バイナリを指定する。

Emulicious: メニュー > Options > Emulation > Game Boy

> GB Boot ROMs > Select File... → dmg_boot.bin を指定する。

> GBC Boot ROMs > Select File... → cgb_boot.bin を指定する。

Emulicious.ini にはそれぞれ、
GameBoyBootROM=C\:\\Emulicious-with-Java64\\dmg_boot.bin
GameBoyColorBootROM=C\:\\Emulicious-with-Java64\\cgb_boot.bin
として記録される。

2. アセンブラとコンパイラの設置

2-1. アセンブラを設置する。
2-1-1. RGBDS をダウンロードする。

RGBDS の Web ページから Windows 用の 64bit バイナリへたどり着くのが分かりにくい。
リリース情報から rgbds-win64.zip をダウンロードする。
今回は v1.0.1 だった。(ファイル名にバージョンは含まれない)

2-1-2. RGBDS を設置する。
rgbds-win64.zip を解凍し、C:\rgbds-win64\ として設置する。
PS C:\> tree /f C:\rgbds-win64\
フォルダー パスの一覧
ボリューム シリアル番号は 82C3-3BDE です
C:\RGBDS-WIN64
    libpng16.dll
    rgbasm.exe
    rgbfix.exe
    rgbgfx.exe
    rgblink.exe
    zlib1.dll

サブフォルダーは存在しません
2-2. C コンパイラを設置する。
2-2-1. GBDK-2020 をダウンロードする。

GBDK-2020 のホームページの Current Release から
WINDOWS 64 BIT をクリックして圧縮ファイル gbdk-win64.zip をダウンロードする。
今回は v4.5.0 だった。(ファイル名にバージョンは含まれない)

2-2-2. gbdk-win64.zip を解凍し、C:\gbdk\ として設置する。
PS C:\> tree C:\gbdk\ | Select-Object -First 15
フォルダー パスの一覧
ボリューム シリアル番号は 82C3-3BDE です
C:\GBDK
├─bin ← ここに C コンパイラ本体の lcc.exe がある 
├─examples
│  ├─cross-platform
│  │  ├─banks
│  │  │  ├─build
│  │  │  │  ├─duck
│  │  │  │  ├─gb
│  │  │  │  ├─gg
│  │  │  │  ├─nes
│  │  │  │  ├─pocket
│  │  │  │  └─sms
│  │  │  ├─obj
2-3. アセンブラとコンパイラのパスを設定する。

VS Code から rgbasm.exe や lcc.exe を呼び出すため、パスを設定する。
Windows11 が 2025-12-29 に改悪され、「設定」からシステムのプロパティを表示できなくなった。

PoorShell を起動し、プロンプトからシステムのプロパティを表示する。
(Windows11 の改悪により「設定」からたどれなくなってしまった)
PS C:\> sysdm.cpl

システムのプロパティ画面
詳細設定タブを選択する。
⇓
ボタンをクリックする。
⇓
環境変数画面
who のユーザー環境変数(U)
Path を選択してボタンをクリックする。
下記 2 項目を追記する。
→ C:\rgbds-win64\
→ C:\gbdk\bin\
⇓
システムのプロパティまでボタンをクリックしてすべて閉じる。

2-4. サインインをやり直す。

更新した環境変数は、ユーザがサインインするまで有効にならない。
Windows11 を サインアウト → サインアウトする。

3. デバッガの用意

3-1. VS Code をインストールする。

VS Code の Web ページから Windows 10,11 をクリックしインストーラをダウンロード＆インストールする。
今回は VSCodeUserSetup-x64-1.107.1.exe だった。

3-2. VS Code に拡張機能をインストールする。

上記 3-1 でインストールした VS Code を起動し、拡張機能をインストールする。

VS Code: メニュー > 表示 > 拡張機能 (Ctrl+Shift+X)

検索: Emulicious Debugger →

検索: RGBDS →

標準の「C/C++ 拡張」は GBDK の特殊ワードをエラーとするのでインストールしないほうが良い。

3-3. Emulicious のパスを VS Code に設定する。

VS Code: メニュー > ファイル > ユーザー設定 > 設定 (Ctrl+,)

検索: emulicious

Emulicious-debugger: Emulicious Path
Path to Emulicious.exe, Emulicious.bat, Emulicious.jar or Emulicious folder.

入力 → C:\Emulicious-with-Java64\Emulicious.jar

項目を入力したら × をクリックして閉じる。

4. プロジェクトディレクトリの作成と設定

VS Code ではディレクトリを開くことにより、プロジェクトを切り替える。

4-1. ディレクトリを作成する。

ファイルエクスプローラーでディレクトリを作成する。(プロジェクトディレクトリとする)

C:\Users\who\vsc-gba\

… アセンブラの場合

C:\Users\who\vsc-gbc\

… C の場合

4-2. プロジェクトディレクトリとしてディレクトリを開く。
VS Code: メニュー > ファイル > フォルダーを開く (Ctrl+K Ctrl+O)
(上記プロジェクトディレクトリ : C:\Users\who\vsc-gba\ または C:\Users\who\vsc-gbc\)
このフォルダー内のファイルの作成者を信頼しますか？
「信頼します」ボタンをクリックする。
→ このディレクトリの中にあとで .vscode\ が作られる。

5. アセンブラの設定

上記 4 の操作のあとに実行する。

5-1. ひな形からビルド情報を記述する。(アセンブラ)

VS Code: メニュー > ターミナル > タスクの構成...

検索: テンプレートから tasks.json を生成 ← 選択

Others 任意の外部コマンドを実行する例 ← 選択

→ .vscode\tasks.json が生成される。

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            "label": "echo",
            "type": "shell",
            "command": "echo Hello"
        }
    ]
}

⇓ 変更

ビルド情報を記述する。

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Assemble a_hello",
            "type": "shell",
            "command": "cmd",
            "args": [
                "/C",
                "rgbasm -o a_hello.obj a_hello.asm",
                    // -o Output object
                "&& rgblink -n a_hello.sym -o a_hello.gb a_hello.obj",
                    // -n output symbol file
                    // -o Output object
                "&& rgbfix -v -p 0xFF -C -m 0x1A a_hello.gb"
                    // -v set Validation data
                    // -p set Padding
                    // -C enable GBC
                    // -m set MBC model
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "problemMatcher": []
        }
    ]
}

変更が完了したら、ファイルを閉じる。
VS Code: メニュー > ファイル > エディターを閉じる Ctrl+F4 →

5-2. ひな形からデバッグの構成を記述する。

エミュレータ起動 / 接続の設定 (VS Code の「デバッグの実行」を選択すると呼ばれる)

VS Code: メニュー > 実行 > 構成の追加...

検索: Emulicious Debugger ← 選択

→ .vscode\launch.json が生成される。

{
    // IntelliSense を使用して利用可能な属性を学べます。
    // 既存の属性の説明をホバーして表示します。
    // 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "emulicious-debugger",
            "request": "launch",
            "name": "Launch in Emulicious",
            "program": "${workspaceFolder}/${command:AskForProgramName}",
            "port": 58870,
            "stopOnEntry": true
        }
    ]
}

⇓ 変更

デバッグ情報を記述する。

{
    // IntelliSense を使用して利用可能な属性を学べます。
    // 既存の属性の説明をホバーして表示します。
    // 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "emulicious-debugger",
            "request": "launch",
            "name": "Launch in Emulicious",
            "program": "${workspaceFolder}/a_hello.gb",
            //"preLaunchTask": "Assemble a_hello",  // 実行前に tasks.json の label を呼び出す
            "port": 58870,
            "stopOnEntry": true
        }
    ]
}

(デバッグ前にアセンブルを実行するなら preLaunchTask を有効にする)

変更が完了したら、ファイルを閉じる。
VS Code: メニュー > ファイル > エディターを閉じる Ctrl+F4 →

6. アセンブラのプログラムを作成

VS Code: メニュー > ファイル > 新しいファイル Ctrl+Alt+Win+N

a_hello.asm

プロジェクトディレクトリの直下に作成する。(.vscode\ ではない)

a_hello.asm

; --- カートリッジのエントリ (本体タイトル表示の後に有効化) ---
SECTION "Entry", ROM0[$0100]  ; 自作プログラムは $0100 から記述する
    nop
    jp Start

; --- カートリッジヘッダ (0104h-014Fh) rgbfix がここを埋めてくれる ---
ds $150 - @

; --- メインプログラム ---
Start:

    ; 画面表示の終了待ち (本来は V-Blank 中の処理)
.waitVBlank:
    ld a, [$FF44]   ; LYレジスタ（現在のスキャンライン）を取得
    cp 144
    jr c, .waitVBlank

    xor a           ; LCD OFF
    ld [$FF40], a   ; $00 を書き込み

    ld a, %1110_0100 ; BGP パレットデータ (c0:3=black c1:2 c2:1 c3:0=white)
    ld [$FF47], a   ; $E4 を書き込み

    ld a, %1000_0001 ; LCD ON 背景有効
    ld [$FF40], a   ; $81 を書き込み

    ld sp, $D000    ; SP を初期化 (HRAM にあらず)

MainLoop:
    jr MainLoop

記述したら、ファイルを閉じる。
VS Code: メニュー > ファイル > エディターを閉じる Ctrl+F4 →

7. アセンブルとデバッグ

7-1. ソースをアセンブルする。

VS Code: メニュー > ターミナル > ビルドタスクの実行... Ctrl+Shift+B

→ 上記 5-1 で定義した task.json が実行される。

7-2. デバッグの実行

VS Code: メニュー > 実行 > デバッグの開始 F5

→ 上記 5-2 で定義した launch.json が実行される。

Emulicious が起動し、VS Code の画面には逆アセンブラ画面 a_hello.asm が表示される。
このとき、(上記 launch.json の "stopOnEntry": true により) $0100 の nop で実行が停止する。

ここでデバッグアイコン「 ◁| 反転」をクリックすると、アセンブラのソース画面が表示される。

8. C の設定

上記 4 の操作のあとに実行する。

8-1. ひな形からビルド情報を記述する。(C)

VS Code: メニュー > ターミナル > タスクの構成...

検索: テンプレートから tasks.json を生成 ← 選択

Others 任意の外部コマンドを実行する例 ← 選択

→ .vscode\tasks.json が生成される。

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            "label": "echo",
            "type": "shell",
            "command": "echo Hello"
        }
    ]
}

⇓ 変更

ビルド情報を記述する。

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Compile c_hello",
            "type": "shell",
            "command": "cmd",
            "args": [
                "/C",
                "lcc",    // C コンパイラ本体
                "-v",     // コマンドを表示
                "-debug", // ソースコードデバッグを有効 (*.cdb を出力)
                "-Wm-yc",     // ゲームボーイカラーを指定
                "-Wl-m",      // マップファイルを生成
                "-Wl-g .STACK=0xD000",  // SP を D000 で初期化
                "-Wl-yt0x19", // MBC5(0x19) を指定
                "-Wl-yo8",    // バンク数 x 16KB
                "-o", "c_hello.gb", // 出力ファイル名
                "c_hello.c",
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "problemMatcher": []
        }
    ]
}

SP はデフォルトで E000 に初期化される。バンク切り替えで見失わないよう D000 で初期化する。

変更が完了したら、ファイルを閉じる。
VS Code: メニュー > ファイル > エディターを閉じる Ctrl+F4 →

8-2. ひな形からデバッグの構成を記述する。

エミュレータ起動 / 接続の設定 (VS Code の「デバッグの実行」を選択すると呼ばれる)

VS Code: メニュー > 実行 > 構成の追加...

検索: Emulicious Debugger ← 選択

→ .vscode\launch.json が生成される。

{
    // IntelliSense を使用して利用可能な属性を学べます。
    // 既存の属性の説明をホバーして表示します。
    // 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "emulicious-debugger",
            "request": "launch",
            "name": "Launch in Emulicious",
            "program": "${workspaceFolder}/${command:AskForProgramName}",
            "port": 58870,
            "stopOnEntry": true
        }
    ]
}

⇓ 変更

デバッグ情報を記述する。

{
    // IntelliSense を使用して利用可能な属性を学べます。
    // 既存の属性の説明をホバーして表示します。
    // 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "emulicious-debugger",
            "request": "launch",
            "name": "Launch in Emulicious",
            "program": "${workspaceFolder}/c_hello.gb",
            //"preLaunchTask": "Compile c_hello",   // 実行前に tasks.json の label を呼び出す
            "port": 58870,
            "stopOnEntry": true
        }
    ]
}

(デバッグ前にコンパイルを実行するなら preLaunchTask を有効にする)

変更が完了したら、ファイルを閉じる。
VS Code: メニュー > ファイル > エディターを閉じる Ctrl+F4 →

9. C のプログラムを作成

VS Code: メニュー > ファイル > 新しいファイル Ctrl+Alt+Win+N

c_hello.c

プロジェクトディレクトリの直下に作成する。(.vscode\ ではない)

c_hello.c
#include <gb/gb.h>
#include <gb/cgb.h>

void main(void)
{
    SHOW_BKG;   // 背景を ON
    DISPLAY_ON; // LCD を ON

    while(1) {
        // 本来はここで VRAM 描画以外の処理
        wait_vbl_done(); // V-Blank 待ち
        // 本来はここで VRAM 描画の処理
    }
}
記述したら、ファイルを閉じる。
VS Code: メニュー > ファイル > エディターを閉じる Ctrl+F4 →

10. コンパイルとデバッグ

10-1. ソースをコンパイルする。

VS Code: メニュー > ターミナル > ビルドタスクの実行... Ctrl+Shift+B

→ 上記 8-1 で定義した task.json が実行される。

10-2. デバッグの実行

VS Code: メニュー > 実行 > デバッグの開始 F5

→ 上記 8-2 で定義した launch.json が実行される。

Emulicious が起動し、VS Code の画面には C のソース画面が表示される。
このとき、(上記 launch.json の "stopOnEntry": true により) main(void) で実行が停止する。

11. リモートデバッグの実施

11-1. 設定ファイル Emulicious.ini を作成する。
オプションを付けずに Emulicious を起動し、すぐに終了すると設定ファイルが作成される。

• Emulicious を起動する。
C:\> java -jar C:\Emulicious-with-Java64\Emulicious.jar
⇓
• Emulicious を終了する。
Emulicious: メニュー > Exit
⇓
設定ファイル Emulicious.ini (初期値)
#Emulicious settings file
#Sat Jan 01 01:01:01 JST 2026
AudioSync=false
CodeFontSize=13
FontSize=13
Update=2
WindowEmuliciousHeight=300
WindowEmuliciousWidth=300
WindowEmuliciousX=0
WindowEmuliciousY=0
Emulicious の GUI から項目を変更すると、このファイルが更新される。
11-2. Emulicious の設定ファイルをリモートデバッグ用に変更する。
Emulicious.ini
#Emulicious settings file
#Sat Jan 01 01:01:01 JST 2026
AudioSync=false
CodeFontSize=13
FontSize=13
RemoteDebuggingEnabled=true
Update=2
WindowEmuliciousHeight=300
WindowEmuliciousWidth=300
WindowEmuliciousX=0
WindowEmuliciousY=0
WindowDebuggerOpen=true
WindowDebuggerWidth=800
WindowDebuggerHeight=512
RemoteDebuggingEnabled=true
リモートデバッグを有効にする。

WindowDebuggerOpen=true
WindowDebuggerWidth=800
WindowDebuggerHeight=512
デバッグウィンドウを開く。
なぜか、デバッグウィンドウが無いと
VS Code のソース表示がズレるので、
これを抑止する。
11-3. デバッグ情報を変更する。
c_hello の .vscode\launch.json を変更する例。
{
    // IntelliSense を使用して利用可能な属性を学べます。
    // 既存の属性の説明をホバーして表示します。
    // 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "emulicious-debugger",
            "request": "attach",
            "name": "Launch in Emulicious",
            //"program": "${workspaceFolder}/c_hello.gb",  // リモートデバッグでは指定不可
            //"preLaunchTask": "Compile c_hello",   // 実行前に tasks.json の label を呼び出す
            "host": "localhost",
            "port": 58870,
            //"stopOnEntry": true      // リモートデバッグでは指定不可
        }
    ]
}
リモートデバッグだけど、大仰になるのを避けるため localhost に接続している。

変更が完了したら、ファイルを閉じる。
VS Code: メニュー > ファイル > エディターを閉じる Ctrl+F4 →
11-4. Emulicious を起動する。

c_hello.gb が存在するディレクトリへ移動する。
C:\> cd \Users\who\vsc-gbc\

ポート 58870 で待ち受けて起動する。(Emulicious のデバッグウィンドウが表示されていると _main: で停止する)
C:\Users\who\vsc-gbc\> java -jar C:\Emulicious-with-Java64\Emulicious.jar -remoteDebuggerPort=58870 c_hello.gb

11-5. VS Code から Emulicious へ接続する。

VS Code: メニュー > 実行 > デバッグの開始 F5

c_hello.gb を生成したときのソース一式とシンボル情報ファイル (.cdb, .map) がカレントディレクトリに存在していること。

項目		内容	備考
開発対象		ゲームボーイカラー	ゲームボーイカラーの性能表はこちら
開発言語	アセンブラ	RGBDS (Rednex GameBoy Development System)	LR35902(SM83) の追加命令にも対応している
開発言語	C コンパイラ	GBDK-2020 (GameBoy Development Kit)	ROM/RAM バンク切り替えにも対応している
デバッガ	エミュレータ	Emulicious	Z80 および Z80 互換 CPU 搭載機エミュレータ
デバッガ	コンソール	Visual Studio Code + 拡張機能 Emulicious Debugger	ソースコードデバッガ (以下 VS Code と呼称) https://code.visualstudio.com/download https://code.visualstudio.com/docs/?dv=win64user

Emulicious: メニュー > Options > Emulation > Game Boy
	>	GB Boot ROMs	>	Select File... →	dmg_boot.bin	を指定する。
	>	GBC Boot ROMs	>	Select File... →	cgb_boot.bin	を指定する。

検索:	emulicious
	Emulicious-debugger: Emulicious Path Path to Emulicious.exe, Emulicious.bat, Emulicious.jar or Emulicious folder.
入力 →	C:\Emulicious-with-Java64\Emulicious.jar

検索:	テンプレートから tasks.json を生成	← 選択
	Others 任意の外部コマンドを実行する例	← 選択