Getting Started ja
🌐 English · 日本語
コードを書き、保存し、実行して文字を表示するところから始めます。最後に、コンパイルの仕組みを確認し、エラーを一つ直します。
ファイル編集とターミナルの操作に慣れている方は、準備から進めます。すでに mana を使える場合は、最初のプログラムを実行してください。
続きは Mana チュートリアルです。
Mana は、ゲーム内のキャラクターやイベントの進行を、テキストで記述するプログラミング言語です。「案内役が話す → 門を開ける → 次の案内をする」といった、複数の役割を持つ処理を組み合わせるために使います。
最初に文字を表示し、その後で、案内役と門を連携させる小さなイベントを作ります。学習用のイベントはターミナルへ文字を表示します。ゲーム画面やキャラクター画像を用意する必要はありません。
Guide: Welcome!
Gate: Open.
Event: Finished.
実際のゲームでは、文字を表示している部分を、ゲーム本体の会話・アニメーションなどの処理につなぎます。描画、物理、サウンドなどの機能はゲーム側で用意し、Mana でそれらを動かす順番や条件を記述できます。
この例なら、案内役と門をそれぞれ Actor（アクター） にします。Actor は、自分の処理と状態を持つ実行主体です。キャラクターのほか、門やイベント全体の進行役にも使えます。
Actor が行う処理が Action（アクション）、Action の実行を依頼する仕組みが Request（リクエスト） です。
| 言葉 | このイベントでの例 |
|---|---|
| Actor | 案内役の Guide、門の Gate
|
| Action | 会話する talk、開く open
|
| Request | 進行役が、案内役に会話を依頼する |
名前を今すべて覚える必要はありません。コードを書きながら確かめます。
Mana のプログラムは、テキストエディタで書いてファイルに保存します。人が書いたプログラムを ソースコード、それを保存したファイルを ソースファイル と呼びます。
Mana はコンパイル段階を持つ言語です。コンパイルとは、ソースコードを調べ、実行用のデータへ変換することです。そのデータを Mana VM という実行環境が動かします。
flowchart LR
A["ソースコードを書く"] --> B["コンパイルする"]
B --> C["Mana VM で実行する"]
C --> D["結果を確認する"]
入門では、一つのコマンドでコンパイルと実行を続けて行います。コンパイラや VM を自分でプログラミングする必要はありません。
- プログラミングが初めてなら、次の テキストでプログラムを書く へ進んでください。
- ファイルの編集やターミナルの操作に慣れているなら、Mana を使う準備 から始められます。
- C++ アプリケーションへ組み込みたい場合は、組み込みガイド を参照してください。
ここでは、コードを書く場所と、コードを実行する場所を区別できるようにします。まだ Mana のツールを用意していなくても読めます。
テキストエディタは文字を入力してファイルへ保存するアプリです。Mana のコードは、文字の色や段落の装飾を保存する文書形式ではなく、プレーンテキストとして保存します。
ターミナルは、コマンドを入力してツールを動かす画面です。Windows では PowerShell、Linux ではシェルを使います。
この教材では、コード欄の直前に用途を書きます。
ソースコードの例 — エディタに入力する内容：
actor Hello
{
action main()
{
print("Hello, Mana!\n");
}
}
実行コマンドの例 — ターミナルに入力する内容：
mana hello.mn
コマンドをソースファイルへ書き込む必要はありません。mana がツール名、hello.mn が処理するファイル名です。ツールの具体的な指定方法は次の準備ページで設定します。
hello.mn の .mn は 拡張子です。ファイルの用途を示す名前の末尾で、Mana のソースファイルでは通常これを使います。
保存時は次の点を確認します。
- ファイル名は
hello.mnにする。hello.mn.txtになっていないか確認する。 - 文字コードは UTF-8 にする。この教材の例は UTF-8 で保存して使う。
- 保存したフォルダーを覚えておく。フォルダーは ディレクトリとも呼ぶ。
- 編集後は保存する。コマンドが読み込むのは、ディスクへ保存した内容。
Windows で拡張子が見えない場合は、エクスプローラーでファイル名拡張子の表示を有効にしてください。
print("Hello, Mana!\n"); は、文字を表示する処理です。
| 書き方 | 役割 |
|---|---|
"Hello, Mana!\n" |
表示する文字列。文字列は半角の " で囲む |
\n |
文字列の中で改行を表す |
; |
この文の終わり |
{ と }
|
定義や処理の範囲を囲む |
括弧やセミコロンなどの記号は半角で入力します。Hello と hello のような大文字・小文字も区別します。
行頭の空白は インデントと呼びます。どの範囲に属する処理かを読みやすくするため、教材では内側へ入るたびに空白を4個増やしています。インデントしても、必要な括弧や ; を省略できるわけではありません。
// から行末までは コメントです。人が読む説明を書けます。
Action の中に書く例：
// 案内の文字を表示する
print("Welcome!\n");
プログラムは、一度で完成させなくても構いません。小さく変更して、結果を確かめます。エラーは入力した内容を見直す手がかりです。エラーの読み方も後で練習します。
次は Mana を使う準備 で、実行に使うツールを用意します。
このページの目標は、ターミナルで mana --version を実行し、バージョン情報を表示することです。
ここではリポジトリからツールをビルドします。ビルドとは、Mana の処理系を実装した C++ ソースなどから、使える実行ファイルを作る作業です。Mana スクリプトを書くたびに行う作業ではありません。
Git が使える場合は、ターミナルで次を実行します。Git はソースコードを取得・管理するツールです。
git clone https://github.com/shun126/Mana.git
cd Mana
cd は作業するフォルダーを移動するコマンドです。ここで入った、CMakeLists.txt のあるフォルダーを、この教材では Mana フォルダーと呼びます。
Git を使わない場合は、リポジトリのソースを ZIP として取得して展開し、そのフォルダーでターミナルを開いてください。
必要なものは、Visual Studio 2022 以降の C++ デスクトップ開発環境（MSVC v143 以降と Windows SDK）、CMake 3.20 以降、Python 3、Bison 3.8 以降、Flex 2.6.4 以降です。Bison と Flex は、Mana の文法を処理する C++ コードの生成に使います。
- Visual Studio Installer で C++ によるデスクトップ開発を用意します。
- Windows で動く Bison と Flex の実行ファイルを用意します。
- Mana フォルダーの PowerShell で、必須の環境変数に Bison と Flex の実行ファイルの絶対パスを設定し、次のコマンドを実行します。パスは実際の配置に合わせてください。
$env:BISON_EXECUTABLE = "C:\path\to\bison.exe"
$env:FLEX_EXECUTABLE = "C:\path\to\flex.exe"
cmake -S . -B build -A x64
cmake --build build --config Release --parallel
ctest --test-dir build -C Release --output-on-failureBison と Flex が PATH にある場合も、両方の環境変数が必要です。Visual Studio で CMakeLists.txt を開く場合は、Windows のユーザー環境変数として設定して Visual Studio を再起動するか、ローカルの CMakeSettings.json の environments に設定してください。32 ビット版を作る場合は -A Win32 を使用し、別のビルドフォルダーを指定してください。CMake は見つかった最新の Visual Studio を使います。特定のバージョンを使う場合は、-G "Visual Studio 17 2022" のようにジェネレーター名を -G で指定してください。
ビルド成功後、Mana フォルダーの PowerShell で確認します。
.\build\Release\mana.exe --versionバージョン情報が表示されたら、同じ PowerShell に次を入力します。
Set-Alias mana (Resolve-Path .\build\Release\mana.exe).Path
mana --versionこれで、この PowerShell を開いている間は mana という短い名前で実行できます。PATH の変更は不要です。新しく PowerShell を開いたら、Mana フォルダーで再び Set-Alias を実行してください。
C++17 を扱えるコンパイラ、CMake 3.20 以降、Make、Python 3、Bison 3.8 以降、Flex 2.6.4 以降を用意します。必要なパッケージの導入方法は使用する Linux 環境に従ってください。
端末で次を実行し、各ツールが利用できることを確認します。
cmake --version
bison --version
flex --versionMana フォルダーでビルドします。
export BISON_EXECUTABLE="$(command -v bison)"
export FLEX_EXECUTABLE="$(command -v flex)"
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
ctest --test-dir build --output-on-failure
./build/mana --versionバージョン情報が表示されたら、Bash で次を実行します。
mana_executable="$(pwd)/build/mana"
mana() { "$mana_executable" "$@"; }
mana --version以降は同じ端末で mana と入力できます。この関数は実行ファイルの場所を覚え、引数を渡して呼び出します。現在のシェルだけで有効なので、新しい端末を開いたら、Mana フォルダーで再び設定してください。
以降の教材は、Mana フォルダーを作業場所にし、ここで設定した同じターミナルを使う前提です。mana --version が動けば準備は完了です。
うまくいかない場合は、次の順番で調べます。
| 状況 | 確認すること |
|---|---|
| Bison / Flex を見つけられずビルドに失敗する |
BISON_EXECUTABLE と FLEX_EXECUTABLE が実行ファイルを指しているか |
| 実行ファイルが見つからない | ビルドが成功したか。Windows は Release / x64 でビルドしたか |
フルパスなら動くが mana では動かない |
このターミナルで短縮名を設定したか |
| ソースファイルが見つからない | ターミナルの作業場所と、指定したファイルの保存場所が一致するか |
次は はじめての Mana プログラム です。
文字を表示し、その文字を自分で変更します。準備ページで設定したターミナルを使ってください。
エディタに次のファイル全体を入力し、Mana フォルダーへ hello.mn として保存します。UTF-8 のプレーンテキストで保存してください。
actor Hello
{
action main()
{
print("Hello, Mana!\n");
}
}
Mana フォルダーのターミナルへ、次を入力します。
mana hello.mn
期待する出力：
Hello, Mana!
表示できれば成功です。うまくいかない場合は、hello.mn.txt になっていないか、ファイルを保存したか、ターミナルの作業場所が Mana フォルダーかを確認します。
入力例と比較したいときは、同梱の完成コードも使えます。
mana examples/tutorial/01-hello.mn
actor Hello は、Hello という名前の Actor を定義します。Hello は自分で付けた名前です。
その中の action main() は、Actor が行う処理を定義します。main は起動時に実行される特別な Action 名です。今は、この中へ最初に動かす処理を書くと覚えてください。
print("Hello, Mana!\n"); は文字を出力する文です。ここまでの例では、画面への出力はターミナルに表示されます。
{ と } の対応をたどると、print が main の中にあり、main が Hello の中にあることが分かります。
print の行を、次の2行に置き換えてください。
print("Welcome!\n");
print("The gate is closed.\n");
保存し、もう一度 mana hello.mn を実行します。
Welcome!
The gate is closed.
この Action の中では、上から順に文が実行されます。2行の順番を入れ替えると、出力も入れ替わります。
次は コンパイルと実行・エラーの直し方 で、実行までの仕組みと、間違えたときの調べ方を学びます。
mana hello.mn は、ソースをコンパイルし、その結果を Mana VM で実行します。このページでは、二つの工程を分けて確認し、エラーを一つ直してみます。
コンパイラは、文法や名前、型などを調べ、実行用のデータである Program Image（プログラムイメージ） を生成します。Program Image は Mana VM が読むデータであり、CPU が直接実行する実行ファイルではありません。
flowchart TD
A["ソースを編集して保存"] --> B["コンパイル"]
B --> C{"成功した？"}
C -->|いいえ| D["診断を読んで修正"]
D --> A
C -->|はい| E["Program Image"]
E --> F["Mana VM で実行"]
F --> G{"期待した結果？"}
G -->|いいえ| A
G -->|はい| H["次の変更へ"]
コンパイルに成功しても、意図した動作になるとは限りません。例えば、表示する順番を間違えたプログラムも、文法が正しければ実行できます。
hello.mn を次の内容に置き換えます。この例は意図的にコンパイルエラーになるコードです。
actor Hello
{
action main()
{
print("Hello, Mana!\n")
}
}
保存して実行します。
mana hello.mn
print の行の末尾に ; がないため、コンパイルに失敗します。現行処理系で確認した診断は次のとおりです。ファイル名の前には保存場所のパスが付く場合があります。
hello.mn(6): error: syntax error
hello.mn(8): error: syntax error
最初の行は「hello.mn の6行目で、文法上の問題を見つけた」という意味です。診断の表記はバージョンによって異なりますが、次の情報を探してください。
| 診断に含まれる情報 | 調べること |
|---|---|
| ファイル名 | どのファイルを直すか |
| 行番号 | 問題が見つかった場所 |
| メッセージ | 文法の問題か、名前の問題かなど |
コンパイラが間違いに気づくのは、書き忘れた場所の次の行になることもあります。今回なら、閉じ括弧の行を指した場合も、その直前の print を確認します。
末尾へ ; を戻し、保存して再実行してください。最初のエラーを直すと、続いて表示されたエラーも消える場合があります。一度に全部を直そうとせず、最初の診断から調べましょう。
| 症状 | まず行うこと |
|---|---|
mana が見つからない |
準備ページの短縮名設定を確認する |
hello.mn が見つからない |
保存場所、作業場所、拡張子を確認する |
| コンパイルに失敗する | 診断のファイルと行、その直前を確認する |
| 実行中にエラーになる | 実行時のメッセージを読む。コンパイル成功だけでは防げない問題もある |
| エラーはないが結果が違う | 保存したか確認し、処理の途中へ print を入れて通った場所を調べる |
| 実行が終わらない | ターミナルで Ctrl+C を押して止め、繰り返しの終了条件などを調べる |
質問するときは、実行したコマンド、コード、診断全文、期待した結果を一緒に示すと状況を伝えやすくなります。
普段の学習では mana hello.mn で十分です。コンパイルと実行を別々に行いたいときは、次を使います。
コンパイルして保存するコマンド：
mana hello.mn -o hello.mx
-o は出力先を指定するオプションです。この場合は hello.mx を作り、自動実行はしません。
保存した結果を実行するコマンド：
mana --execute hello.mx
ソースを変更しても、以前作った hello.mx は変わりません。変更を反映するには再度コンパイルします。全オプションは CLI リファレンスで調べられます。
次は Actor と Action で、処理を役割ごとに分けます。