Suika3 チュートリアル
=====================

このドキュメントは `Suika3` のチュートリアルです。
チュートリアルの実施に必要な時間は１時間程度です。

---

## Suika3とは？

Suika3 は 2D ゲームを作って動かすためのプログラミング環境です。
ゲームエンジンと言えばわかりやすいかもしれません。
PC で Suika3 を使ってゲームを作れば、スマートフォンでもそのまま動作します。

Suika3 は 2D ゲーム全般を作ることができますが、中でもビジュアルノベルを簡単に作れるようになっています。
ビジュアルノベルを作る場合は、難しいプログラミングは不要で、タグと呼ばれる記述のみでゲームを作れます。

---

## Visual Studio Codeのインストールと起動

Windows で Suika3 を利用する場合は、開発環境として Visual Studio Code を利用することをおすすめします。

- Visual Studio Code をダウンロードしてください
- Visual Studio Code をインストールしてください
- Visual Studio Code を起動してください
- Visual Studio Code 上で NovelML-Helper をインストールしてください

> [!TIPS]
> `Emacs` がお好きな場合は、`novelml-mode.el` と `ray-mode.el` を利用できます。

---

## ファイル構成

- `suika3.exe` や `.vscode` がある Suika3 のフォルダを Visual Studio Code で開きます
- ファイルを開くには左側のペインでファイルをクリックします
- 次のファイルとフォルダがあることを確認します

+----------------+---------------------------------------------------------+
| ファイル名     | 説明                                                    |
+----------------+---------------------------------------------------------+
| main.ray       | ゲームのメインスクリプトファイル。（プログラミング言語）|
| config.ini     | ノベル用の設定ファイル。                                |
| start.novel    | 最初に読み込まれるノベルのタグファイル。（台本）        |
| system/        | ノベルのUIが入ったフォルダ。                            |
| images/        | ゲームの画像データ。                                    |
| sound/         | ゲームの音声データ。                                    |

---

## 実行

- コマンドパレットから `Run Task` を選択して `Suika3: Run` を選択します
- ゲームが実行されます
- `Ctrl+Shift+B` でも実行できます

---

## `main.ray`

`main.ray` はメインのプログラムです。
`Ray` という Suika3 のプログラミング言語で書かれています。

Suika3 は３階建になっており、それぞれの階層で別な言語を利用します。

```
  +----------------------------+
  | ビジュアルノベル (NovelML) |
  +----------------------------+
  | 2D ゲーム (Ray言語)        |
  +----------------------------+
  | エンジン (C言語)           |
  +----------------------------+
```

一番下のエンジン部分はC言語で書かれています。これはゲームにとっての OS だと考えるとわかりやすいです。

その上に Ray があり、これは 2D ゲームを作るための基盤です。

一番上に NovelML があり、2D ゲームの中でもビジュアルノベルが特別にサポートされている形です。

さて、ノベルを作成する場合、`main.ray` の内容は、ほぼデフォルトのままで問題ありません。
このファイルの書き換えが必要になるのは次のケースです。

- 画面サイズを標準の 1280x720 から変更する場合
- プラグインを読み込む場合
- 2D ゲームを作成する場合

ここでは、ウィンドウのタイトルをあなたのゲームの名前に書き換えてみます。
`main.ray` の中の下記のコードをみつけて、`Little Sample` を書き換えます。

```
func setup() {
    return {
        width:  1280,
        height: 720,
        title:  "Little Sample",
        fullscreen: false
    };
}
```

実行すると変更されています。
実行方法は前節で紹介したとおり、コマンドパレットから `Run Task` を選択して `Suika3: Run` を選択します。
もしくは、`Ctrl+Shift+B` でも実行できます。

---

## `start.novel`

このファイルが最初に読み込まれるノベルのタグファイルです。

たとえば、文章表示のタグは次のように記述します。

```
[text text="短い文章はこのように書きます。"]

[text text=
  """
  長い文章はこのように書くこともできます。
  複数行を書くことができます。
  """
]
```

ファイルの先頭に `[text]` タグを書き加えて、ゲームを実行してみてください。

---

## キャラクタの表示

Suika3 では、キャラクタのレイヤーは６つあります。
それぞれ `Left`, `Left-Center`, `Center`, `Right-Center`, `Right`, `Back` という名前のレイヤーです。

たとえば `Left` のレイヤーにキャラクタを表示すると、デフォルトでは左寄せで表示されます。
ただし、オプションを指定すれば表示位置は変更できます。

```
   Left     Left-Center      Center      Right-Center     Right
                              Back
```

他のVNエンジンの場合、キャラクタを表示するときに、キャラクタの名前を付けて管理することが多いですよね。
Suika3 では、スクリプトを簡単にするために、キャラクタの名前ではなく、表示位置で管理しています。
これはキャラクタが左右に行き来するような演出でなければ、十分にわかりやすいです。

たとえば、中央キャラクタを表示するには、下記のように書きます。

```
[ch center="image.png" time="0.3"]
```

中央キャラクタを消すには、下記のように書きます。

```
[ch center="none" time="0.3"]
```

中央キャラクタを表示したあと、右にスライドするには、下記のように書きます。

```
[ch center="image.png" time="0.3"]
[move center-x="r-250" time="1.0"]
```

---

以下、執筆中。

---

## プラグインの使用

Suika3 プラグインを読み込む場合は、`main.ray` の次の位置に `Suika.loadPlugin()` を追記してください。

```
func start() {
    Suika.star();

    Suika.loadPlugin("プラグイン名");
}
```
