Amazon Q CLI + pygame でゲーム制作【環境構築編／前編】

## はじめに

現在（2025/06/13）、Amazon Q Developer CLIに関するキャンペーンが開催されています。

https://community.aws/content/2xIoduO0xhkhUApQpVUIqBFGmAc/build-games-with-amazon-q-cli-and-score-a-t-shirt

キャンペーンの概要は以下の通りです。

> 1. Amazon Q CLIを使ってゲームを作成する  
> 2. 作成したゲームの内容や開発方法について、ブログ記事や動画で発信し、SNSに投稿する  
> 3. 投稿後、応募フォームから申請してAmazon Qロゴ入りTシャツをもらう  

つまり、Amazon Q CLIを使ってゲームを作り、その制作過程や成果物をブログやSNSでシェアし、所定のフォームから申請することで、Tシャツがもらえるという内容です。

今回は、そのTシャツ欲しさに、このキャンペーンに参加してゲームを作成することにしました！

ブログ記事は2回に分けて投稿する予定で、今回は**環境構築編**となります。

## 前提条件

Amazon Qを利用するには、**AWS Builder ID**が必要です。  
まずは、以下のリンクから登録を行いましょう。

https://community.aws/builderid

なお、私の場合は、以前AWS認定を取得する際に作成していたアカウントをそのまま使いました。

## 構築環境

- OS：Windows 11  
- 開発環境：WSL2（Ubuntu）  
- GUIサポート：WSLg（Windows 11 標準機能）  
- 補足：Windows 10の場合はXサーバーの導入が必要

私はWindows環境で作業しているため、**WSL2（Windows Subsystem for Linux 2）** 上に開発環境を構築していきます。

今回使用する **pygame** は、GUI（ウィンドウ表示）を必要とするライブラリです。そのため、WSL上でpygameを実行するにはGUI描画の仕組みが必要になります。

**Windows 11 以降であれば、WSLg（WSL GUI サポート）が標準で有効**になっているため、特別な設定なしでpygameのウィンドウを表示できます。
一方、**Windows 10の場合はWSLgがサポートされていない**ため、GUI表示には追加で **Xサーバー（例：VcXsrvやXming）** をインストールして連携させる必要があります。
※Windows 10環境にWSLのGUIを構築する手順は今回は記載しません。

## WSL

今回は、**Microsoft Storeからインストールできる WSL（Ubuntu 24.04.1 LTS）** を使用します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4112040/89c836bb-5f7d-432e-9867-68687cdf7119.png)

Ubuntuを初回起動すると、ユーザー名とパスワードの設定を求められます。これらの初期設定が完了すると、次のような環境が構築されます。

```bash
$ cat /etc/os-release
PRETTY_NAME="Ubuntu 24.04.1 LTS"
NAME="Ubuntu"
VERSION_ID="24.04"
VERSION="24.04.1 LTS (Noble Numbat)"
VERSION_CODENAME=noble
ID=ubuntu
ID_LIKE=debian
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
UBUNTU_CODENAME=noble
LOGO=ubuntu-logo
```

今回はこの上に、Amazon Q CLI、pygame、などの開発環境を構築していきます。

## Amazon Q CLI のインストールとセットアップ

ここからは、Amazon Q Developer CLI を実際にインストールしてセットアップする手順について解説します。

### 1. 必要なパッケージのインストール

まずは `unzip` コマンドを使えるようにするため、以下のようにインストールします。

```bash
$ sudo apt install unzip
```
これは .zip 形式のファイルを解凍するためのコマンドで、Amazon Q CLI のインストールに必要です。

### 2. Amazon Q CLI のダウンロード

公式から提供されている最新の Amazon Q CLI を curl を使ってダウンロードします。

```bash
$ curl --proto '=https' --tlsv1.2 -sSf https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/q-x86_64-linux-musl.zip -o q.zip
```

ダウンロードが完了すると、カレントディレクトリに q.zip ファイルが作成されます。

```bash
$ ls
q.zip
```

### 3. ダウンロードファイルの展開

次に、unzip を使ってファイルを解凍します。
解凍後、q/ ディレクトリが作成され、中には実行ファイルやインストールスクリプトなどが含まれています。

```bash
$ unzip q.zip
$ ls
q  q.zip
```

### 4. インストールスクリプトの実行

解凍された中にある install.sh を実行可能にし、インストールを開始します。

```bash
$ chmod +x q/install.sh
$ ./q/install.sh
```

実行中に、以下のようなプロンプトが表示されます。

- 「Do you want q to modify your shell config?」 → Yes を選択
- 「Select login method」 → Use for Free with Builder ID を選択

すると、以下のようなコードとURLが表示されます。

```bash
Confirm the following code in the browser  
Code: XXXX-XXXX ## ここはランダム  
Open this URL: https://view.awsapps.com/start/#/device?user_code=XXXX-XXXX
```

このURLをブラウザで開き、表示されたコードを入力して AWS Builder ID でログインします。ログインが完了すると、CLI 側に
```
Logged in successfully
```
と表示されます。

### 5. WSL の再起動と動作確認

インストールとログインが完了したら、一度 WSL を再起動して設定を反映させましょう。

```bash
$ exit
# → WSL ターミナルを閉じて再度開く
```

その後、Amazon Q CLI が正しくセットアップされたか確認します。
下記のような表示が出れば、インストールは成功です。

```bash
$ q doctor

✔ Everything looks good!
  Amazon Q still not working? Run q issue to let us know!
```

### 6. ログインの再実行（必要な場合）

もしログイン状態が切れた場合や、別の AWS Builder ID でログインしたい場合は、以下のコマンドで再ログインできます。

```bash
$ q login
```

## Q を使用する

インストールとログインが完了すると、Amazon Q Developer CLI を使ってチャット形式でやりとりができるようになります。以下のコマンドで、チャットモードを起動できます。

```bash
$ q chat
To learn more about MCP safety, see https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-security.html


    ⢠⣶⣶⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣤⣶⣿⣿⣿⣶⣦⡀⠀
 ⠀⠀⠀⣾⡿⢻⣿⡆⠀⠀⠀⢀⣄⡄⢀⣠⣤⣤⡀⢀⣠⣤⣤⡀⠀⠀⢀⣠⣤⣤⣤⣄⠀⠀⢀⣤⣤⣤⣤⣤⣤⡀⠀⠀⣀⣤⣤⣤⣀⠀⠀⠀⢠⣤⡀⣀⣤⣤⣄⡀⠀⠀⠀⠀⠀⠀⢠⣿⣿⠋⠀⠀⠀⠙⣿⣿⡆
 ⠀⠀⣼⣿⠇⠀⣿⣿⡄⠀⠀⢸⣿⣿⠛⠉⠻⣿⣿⠛⠉⠛⣿⣿⠀⠀⠘⠛⠉⠉⠻⣿⣧⠀⠈⠛⠛⠛⣻⣿⡿⠀⢀⣾⣿⠛⠉⠻⣿⣷⡀⠀⢸⣿⡟⠛⠉⢻⣿⣷⠀⠀⠀⠀⠀⠀⣼⣿⡏⠀⠀⠀⠀⠀⢸⣿⣿
 ⠀⢰⣿⣿⣤⣤⣼⣿⣷⠀⠀⢸⣿⣿⠀⠀⠀⣿⣿⠀⠀⠀⣿⣿⠀⠀⢀⣴⣶⣶⣶⣿⣿⠀⠀⠀⣠⣾⡿⠋⠀⠀⢸⣿⣿⠀⠀⠀⣿⣿⡇⠀⢸⣿⡇⠀⠀⢸⣿⣿⠀⠀⠀⠀⠀⠀⢹⣿⣇⠀⠀⠀⠀⠀⢸⣿⡿
 ⢀⣿⣿⠋⠉⠉⠉⢻⣿⣇⠀⢸⣿⣿⠀⠀⠀⣿⣿⠀⠀⠀⣿⣿⠀⠀⣿⣿⡀⠀⣠⣿⣿⠀⢀⣴⣿⣋⣀⣀⣀⡀⠘⣿⣿⣄⣀⣠⣿⣿⠃⠀⢸⣿⡇⠀⠀⢸⣿⣿⠀⠀⠀⠀⠀⠀⠈⢿⣿⣦⣀⣀⣀⣴⣿⡿⠃
 ⠚⠛⠋⠀⠀⠀⠀⠘⠛⠛⠀⠘⠛⠛⠀⠀⠀⠛⠛⠀⠀⠀⠛⠛⠀⠀⠙⠻⠿⠟⠋⠛⠛⠀⠘⠛⠛⠛⠛⠛⠛⠃⠀⠈⠛⠿⠿⠿⠛⠁⠀⠀⠘⠛⠃⠀⠀⠘⠛⠛⠀⠀⠀⠀⠀⠀⠀⠀⠙⠛⠿⢿⣿⣿⣋⠀⠀
 ⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠛⠿⢿⡧

╭─────────────────────────────── Did you know? ────────────────────────────────╮
│                                                                              │
│      Set a default model by running q settings chat.defaultModel MODEL.      │
│                          Run /model to learn more.                           │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

/help all commands  •  ctrl + j new lines  •  ctrl + s fuzzy search
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🤖 You are chatting with claude-3.7-sonnet

>
```

この状態で、プロンプトに質問やコマンドを入力すると、Amazon Q が応答してくれます。

## PyGameをインストールする

Amazon Q を使った開発を進めるために、今回は Python のゲームライブラリである **PyGame** をインストールしていきます。

### 1. Python のバージョン確認

まずは Python が正しくインストールされているかを確認します。
WSLにはデフォルトでPythonがインストールされています。

```bash
$ python3 --version
Python 3.12.3
```

本来はpyenv等でPythonのバージョン管理を行うことが推奨されますが、今回は割愛します。

### 2. pip のインストール

以下のコマンドで pip をインストールします。

```bash
$ sudo apt update
$ sudo apt install python3-pip
```

インストール後に pip3 list を実行して、正しくインストールされているか確認します。

### 3. PyGame のインストール

公式で案内されているインストールコマンドを実行してみると、エラーとなってしまいます。
これは、Ubuntu 24.04 では、システムの整合性を保つために pip での直接インストールが制限されているためです。

```bash
$ python3 -m pip install -U pygame --user
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.

    See /usr/share/doc/python3.12/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.
```

このエラーは、Python が "外部管理環境" (PEP 668) として保護されているためです。
そのため、仮想環境（venv）をインストールし、パッケージ管理を行うように設定を行います。

#### 仮想環境の作成と有効化

まずは venv を使えるようにするためのパッケージをインストールします。

```bash
$ sudo apt install python3.12-venv
$ python3 -m venv q-game
$ source q-game/bin/activate
```

仮想環境に入ると、プロンプトが (q-game) のように変化します。

### 4. PyGame をインストール

仮想環境内で PyGame をインストールします。

```bash
(q-game) $ pip install pygame
(q-game) $ pip list
Package Version
------- -------
pip     24.0
pygame  2.6.1
```

### 5. PyGame の動作確認

PyGame には動作確認用のサンプルが用意されています。以下のコマンドで、エイリアンシューティングの簡単なデモゲームを実行できます。

```bash
(q-game) $ python3 -m pygame.examples.aliens
```

問題なくゲーム画面が起動すれば、PyGame のインストールと GUI 描画環境の動作は正常です！

![pygame.examples.aliens.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4112040/04fb1d6d-6254-465c-8840-08c08123e11e.png)

---

これで開発の準備が整いました！
次回は、Amazon Q Developer に PyGame を使ってゲームを作ってもらいます！
お楽しみに！

→ [後編：実装＆プレイ編](https://qiita.com/tyumugiko/items/5e00ad1ae9643b3b486d)

## 参考

https://community.aws/content/2xIoduO0xhkhUApQpVUIqBFGmAc/build-games-with-amazon-q-cli-and-score-a-t-shirt

https://community.aws/content/2v5PptEEYT2y0lRmZbFQtECA66M/the-essential-guide-to-installing-amazon-q-developer-cli-on-windows

https://www.pygame.org/wiki/GettingStarted