Microsoft MakeCode ArcadeをPythonで　〜ビジュアル型プログラミング言語な苦手なあなたへ〜

## 初めに

MakeCodeはPythonでもプログラミングができるようなのでドキュメントを作ってみました。怒られ案件だったらすぐ消すので教えてください。

なお、**途中で力尽きたので内容は不十分です**。多分1/3しか書いてないです。ごめんなさい。頑張って[公式リファレンス](https://arcade.makecode.com/reference)を読んでください。

## 用語の説明

### スプライト（Sprite）

プレイヤーや敵など、メインとなって動作するもの。画像を貼り付けられたり、判定の基準となったり。基本はこのスプライトを操作することでゲームを展開する。プログラム中では`Sprite`クラスとして実装されている。インスタンスメンバは以下の通り。

* `x, y, z`: スプライトのx座標とy座標とz座標
* `vx, vy`: スプライトの速度（ピクセル/秒）
* `ax, ay`: スプライトの加速度（ピクセル^2/秒）
* `fx, fy`: スプライトの摩擦量（＝負の加速度）
* `sx, sy`: スプライトのスケール値（軸方向に伸縮）
* `scale`: スプライトのスケール値（等倍で伸縮）
* `width, height`: スプライトの横幅と高さ
* `left, right, bottom, top`: スプライトの上下左右の端
* `flags`: フラグ（不可視、自動削除など）
* `lifespan`: 生存時間（ミリ秒）
* `id`: 不明（管理用ID？）
* `layer`: 不明
* `data`: 不明（json型？）

スプライトは長方形の大きさを持っており、座標はその中心を示す。

### 発射体（Projectile）

スプライトや画面端から発射するもの。画面外に出ると自動的に削除される（＝`AUTO_DESTROY`フラグが自動的に有効）。プログラム中では`Sprite`クラスの一つとして管理される。

### 重なり（overlap）

一言で言えば当たり判定のこと。スプライト同士の衝突を判定する。

### 画面の幅/高さ

座標は次の画像の通り。左上が(0, 0)で右下が(160, 120)の位置となっている。定数である「画面の幅」と「画面の高さ」はそれぞれ160と120を表す。

![coordinate_in_makecode.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/481950/4fa0acd4-555a-f639-38ec-05c038dfc88e.png)

### 情報

「スコア」、「ライフ」、「カウントダウン」という3つの変数専門のカテゴリ。多くのゲームで実装される数値のため、事前にモジュール化してある感じ。

### タイプ（kind）

スプライトはタイプという属性を付けられる。`SpriteKind.Player`などのようにアクセスする。デフォルトでは`Player`、`Food`、`Enemy`、`Projectile`の4つが用意されている。タイプごとに関数から一括で処理することが可能である。`SpriteKind`という名前空間内に定数として管理されており、`SpriteKind.create()`によって自作することも可能。

``` python
namespace SpriteKind {
    export const Airplane = SpriteKind.create()
    export const Car = SpriteKind.create()
    export const Ship = SpriteKind.create()
}
```

### 色（color）

MakeCodeでは、色は基本的にカラーパレットに含まれているもののみ利用可能となっている。それぞれの番号と色の対応を示す。

| 番号 | 色 | カラーコード | 番号 | 色 | カラーコード |
|:-:|:-:|:-:|:-:|:-:|:-:|
| 0 | 透明 | - | 8 | 青 | `#003FAD` |
| 1 | 白 | `#FFFFFF` | 9 | 水 | `#87F2FF` |
| 2 | 赤 | `#FF2121` | 10 | 紫 | `#8E2EC4` |
| 3 | ピンク | `#FF93C4` | 11 | 薄紫 | `#A4839F` |
| 4 | オレンジ | `#FF8135` | 12 | 濃紫 | `#5C406C` |
| 5 | 黄 | `#FFF609` | 13 | 薄茶 | `#E5CDC4` |
| 6 | 青緑 | `#249CA3` | 14 | 茶 | `#91463D` |
| 7 | 緑 | `#78DC52` | 15 | 黒 | `#000000` |

15を超えた数値に対しては、15で割った余りに対応する色を表示する。

### 生存時間（lifespan）

スプライトには生存時間が設定可能である。単位はミリ秒。数値を設定すると自動的にカウントダウンを始め、0になるとそのスプライトは消滅する。

### フラグ（flag）
スプライトにはいくつかのフラグが設定可能であり、少し特殊な操作が可能となっている。SpriteFlagという列挙型として管理されており、アクセスには`SpriteFlag.STAY_IN_SCREEN`のようにする。一覧は以下の通り。

| フラグ名 | 説明 |
| :-----: | :--:|
| STAY_IN_SCREEN | 画面内にとどまる　|
| GHOST | おばけ |
| AUTO_DESTROY | 自動的に破壊 |
| DESTROY_ON_WALL | 壁で破壊する |
| BOUNCE_ON_WALL | 壁で跳ね返る |
| SHOW_PHYSICS | 物理効果を表示 |
| INVISIBLE | 不可視 |
| RELATIVE_TO_CAMERA | Relative to camera |
| GHOST_THROUGH_SPRITES | Ghost through sprites |
| GHOST_THROUGH_TILES | Ghost through tiles |
| GHOST_THROUGH_WALLS | Ghost through walls |

以下、各フラグについて説明する。

* 画面内にとどまる（STAY_IN_SCREEN）
    * 速度を持ったスプライトが画面外に出ようとしても強制的に画面内にとどまる。ずっと速度を持ち続けるなら、壁の端にとどまり続ける感じ
* おばけ（GHOST）
    * スプライトの重なりが一切無効化される。次式としても表せる
``` 
Ghost = Ghost through Sprites
      + Ghost through tiles
      + Ghost through walls
```
* 自動的に破壊（AUTO_DESTROY）
    * スプライトが画面外に移動し見えなくなると、そのスプライトは自動的に消滅する
* 壁で破壊する（DESTROY_ON_WALL）
    * スプライトが画面外に移動し見えなくなる、もしくはタイルマップの端にぶつかると、そのスプライトは自動的に消滅する
* 壁で跳ね返る（BOUNCE_ON_WALL）
    * スプライトが画面の端にぶつかる、もしくはタイルマップの端にぶつかると、そのスプライトの速度が正負反転する＝跳ね返される
* 物理効果を表示（SHOW_PHYSICS）
    * スプライトの右下に文字情報として座標、速度、加速度を表示する。デバッグ用途がメイン？
* 不可視（INVISIBLE）
    * スプライトを見えなくする
* Relative to camera（RELATIVE_TO_CAMERA）
    * カメラが動くとき、このフラグがオンのスプライトはカメラ上の位置を常に保ち続けるように移動する。カメラから見た位置が優先で、スプライトの位置がカメラと一緒に動く。当たり判定は無効化される
* Ghost through sprites（GHOST_THROUGH_SPRITES）
    * スプライトの他のスプライトとの重なりのみを無効化する。タイルマップのタイルや、タイルマップの端との重なりは有効のまま
* Ghost through tiles（GHOST_THROUGH_TILES）
    * スプライトとタイルマップのタイルとの重なりのみを無効化する。タイルマップの端との重なりや、スプライトとの重なりは有効のまま
* Ghost through walls（GHOST_THROUGH_WALLS）
    * スプライトとタイルマップの端との重なりを無効化する。タイルマップのタイルとの重なりや、スプライトとの重なりは有効のまま

### タイルマップ（tilemap）

多機能な背景のこと。普通の背景では画像か単色しかない。タイルマップはスプライトとの連携（タイルマップ上の座標を指定し、そこにスプライトを生成させるなど）やレイヤー管理などが可能。マップとして動くような背景を作る場合はこちらを選択する。作成にはエディタが存在しているため、手書き（数値の打ち込み）はしない

## スプライトについて

### ［関数］スプライトの作成（create）

```python
sprites.create(
    img: Image,
    kind: number): Sprite
```

* `img`：スプライトに貼り付ける画像（`Image`クラスのインスタンス）
* `kind`：スプライトに設定するタイプ（`SpriteKind`名前空間内の値）
* 返却値：生成したスプライト（`Sprite`クラスのインスタンス）

スプライトのインスタンス（実体）を生成する。

公式リファレンス：<https://arcade.makecode.com/reference/sprites/create>

### ［関数］発射体をスプライトから発射（create Projectile From Sprite）

``` python
sprites.create_projectile_from_sprite(
        img: Image
        sprite: Sprite
        vx: number
        vy: number): Sprite
```

* `img`：発射体に貼り付ける画像（`Image`クラスのインスタンス）
* `sprite`：発射元となるスプライト（`Sprite`クラスのインスタンス）
* `vx`：発射するときのx軸速度
* `vy`：発射するときのy軸速度
* 返却値：生成した発射体（`Sprite`クラスのインスタンス）

発射体を生成し、同時にスプライトから発射する。

公式リファレンス：<https://arcade.makecode.com/reference/sprites/create-projectile-from-sprite>

### ［関数］発射体を画面端から発射（create Projectile From Side）

``` python
sprites.create_projectile_from_side(
    img: Image,
    vx: number,
    vy: number): Sprite
```

* `img`：発射体に貼り付ける画像（Imageクラスのインスタンス）
* `vx`：発射するときのx軸速度
* `vy`：発射するときのy軸速度
* 返却値：生成した発射体（Spriteクラスのインスタンス）

発射体を生成し、同時に画面端から発射する。このとき、`vx`と`vy`の値から発射元となる位置が決定される。位置はそれぞれの画面の角から7ずつ移動した点。

|vx|vy|発射位置|
|:---:|:---:|:--:|
|正の値|正の値|x=-7, y=-7|
|正の値|負の値|x=-7, y=127|
|負の値|正の値|x=167, y=-7|
|負の値|負の値|x=167, y=127|

公式リファレンス：<https://arcade.makecode.com/reference/sprites/create-projectile-from-side>

### ［関数］スプライトが作られたとき（on Created）

``` python
sprites.on_created(
    kind: number,
    handler: (Sprite) -> None): None
```

* `kind`：生成されるスプライトのタイプ（`SpriteKind`名前空間内の値）
* `handler`：ハンドラとする関数の名前（引数は生成されたスプライト）

スプライトが作られたタイミングで指定されたハンドラを実行する。

> **ハンドラとは**
>
> 指定されたタイミングでシステム側から自動的に実行される特殊な関数のこと。
> ここでは自分でハンドラとなる関数を作成し、上のような関数に作成した関数名を渡す。
> 例えば次のようなプログラムを書くと、スプライトabcが作成されたタイミングで、abcからスプライトballが発射される。
>
> ``` python
> def on_created(sprite):
>     ball = sprites.create_projectile_from_sprite(img("""
>     15 15
>     15 15
>     """), sprite, 50, 50)
>
> sprites.on_created(SpriteKind.player, on_created)
>
> abc = sprites.create(img("""
> 2 2 2
> 2 4 2
> 2 2 2
> """), SpriteKind.player)
> ```

公式リファレンス：<https://arcade.makecode.com/reference/sprites/on-create>

### ［関数］スプライトが破壊されたとき（on Destroyed）

``` python
sprites.on_created(
    kind: number,
    handler: (Sprite) -> None): None
```

* `kind`：破壊されるスプライトのタイプ（`SpriteKind`名前空間内の値）
* `handler`：ハンドラとする関数の名前（引数は破壊されたスプライト）

スプライトが破壊されたタイミングで指定されたハンドラを実行する。

公式リファレンス：<https://arcade.makecode.com/reference/sprites/on-destroyed>

### ［関数］スプライトが重なったとき（on Overlap）

``` python
sprites.on_overlap(
    kind: number,
    otherKind: number,
    handler: (Sprite, Sprite) -> None): None
```

* `kind`：重なるスプライトのタイプ１（`SpriteKind`名前空間内の値）
* `otherkind`：重なるスプライトのタイプ２
* `handler`： ハンドラとする関数の名前（引数は衝突したスプライト２つ）

２つのスプライトが重なったタイミングで指定されたハンドラを実行する。

公式リファレンス：<https://arcade.makecode.com/reference/sprites/on-destroyed>

### ［メソッド］言う（say）

``` python
Sprite.say(
    text: any,
    timeOnScreen: number,
    animated: unknown,
    textColor: number,
    textBoxColor: number): None
```

* `text`：表示させる文字列もしくは値
* `timeOnScreen`：表示継続時間（ミリ秒）［オプション］
* `animated`：不明（boolean型？ テキストスクロール？）［オプション］
* `textColor`：表示させるテキストの色番号 ［オプション］
* `textBoxColor`：表示させるフキダシの背景の色番号［オプション］

スプライトの近くにフキダシ型でテキストを表示させる。

公式リファレンス：<https://arcade.makecode.com/reference/sprites/sprite/say>

### ［メソッド］破壊する（destroy）

``` python
Sprite.destroy(
    effect: effects.ParticleEffect,
    duration: number): None
```

* `effect`：消滅時のエフェクト（`ParticlEffect`クラス内の定数）［オプション］
* `duration`：不明

スプライトを消滅させる。

公式リファレンス：<https://arcade.makecode.com/reference/sprites/sprite/destroy>

### ［メソッド］フラグのセット（set Flag）

``` python
Sprite.set_flag(
    flag: SpriteFlag,
    on: bool): None
```

* `flag`：設定するフラグの種類（SpriteFlag列挙型の値）
* `on`：オンまたはオフ（Bool型）

スプライトにフラグを設定する。

公式リファレンス：<https://arcade.makecode.com/reference/sprites/sprite/set-flag>

### ［メソッド］画像のセット（set Image）

``` python
Sprite.set_image(
    img: Image): None
```

* `img`：スプライトに貼り付ける画像（Imageクラスのインスタンス）

スプライトに画像を設定する。すでに設定されている場合は置き換えられる。

公式リファレンス：<https://arcade.makecode.com/reference/sprites/sprite/set-image>

### ［メソッド］座標のセット（set Position）

``` python
Sprite.set_position(
    x: number,
    y: number): None
```

* `x`：スプライトの新しいx座標
* `y`：スプライトの新しいy座標

スプライトの座標を設定する。

公式リファレンス：<https://arcade.makecode.com/reference/sprites/sprite/set-position>

### ［メソッド］タイプのセット（set Kind）

``` python
Sprite.set_kind(
    value: number): None
```

* `kind`：スプライトに設定するタイプ（`SpriteKind`名前空間内の値）

スプライトのタイプを設定する。

公式リファレンス：<https://arcade.makecode.com/reference/sprites/sprite/set-kind>

### ［メソッド］壁で跳ね返るようにする（set Bounce On Wall）

``` python
Sprite.set_bounce_on_wall(
    on: bool): None
```

* `on`：オンまたはオフ（Bool型）

スプライトが壁で跳ね返るように設定する。つまり、スプライトの`BOUNCE_ON_WALL`フラグをオンにする。

公式リファレンス：<https://arcade.makecode.com/reference/sprites/sprite/set-bounce-on-wall>

### ［メソッド］壁で跳ね返るようにする（set Stay In Screen）

``` python
Sprite.set_stay_in_screen(
    on: bool): None
```

* `on`：オンまたはオフ（Bool型）

スプライトが必ず画面内にとどまる。つまり、スプライトの`STAY_IN_SCREEN`フラグをオンにする。

公式リファレンス：<https://arcade.makecode.com/reference/sprites/sprite/set-stay-in-screen>

### ［メソッド］スケールをセットする（set Scale）

``` python
Sprite.set_scale(
    value: number,
    anchor: ScaleAnchor): None
```

* `value`：伸縮させる量
* `anchor`：伸縮の基準となる点（`ScaleAnchor`列挙型の値）

スプライトを**元のサイズから**`value`倍だけ伸縮させる。このとき座標は移動し、伸縮したあとの画像の中央へ移動する。`ScaleAnchor`は列挙型となっているため、`ScaleAnchor.MIDDLE`のように指定する。基準点の一覧は以下の通り。

| 基準点名 | 説明 | 基準点名 | 説明 | 基準点名 | 説明 |
|:-:|:-:|:-:|:-:|:-:|:-:|
| TOP_LEFT | 左上 | TOP | 中央上 | TOP_RIGHT | 右上 |
| LEFT | 左 | MIDDLE | 中央 | RIGHT | 右 |
| BOTTOM_LEFT | 左下 | BOTTOM | 中央下 | BOTTOM_RIGHT | 右下 |



公式リファレンス：<https://arcade.makecode.com/reference/sprites/sprite/set-scale>

### ［メソッド］スケールを変更する（change Scale）

``` python
Sprite.change_scale(
    value: number,
    anchor: ScaleAnchor): None
```

* `value`：伸縮させる量
* `anchor`：伸縮の基準となる点（`ScaleAnchor`列挙型の値）

スプライトを**現在のサイズから**`value`倍だけ伸縮させる。このとき、座標は移動し伸縮したあとの画像の中央へ移動する。

公式リファレンス：<https://arcade.makecode.com/reference/sprites/sprite/change-scale>

### ［メソッド］エフェクトをかける（start Effect）

``` python
Sprite.start_effect(
    effect: effects.ParticleEffect,
    duration: number): None
```

* `effect`：スプライトが始めるエフェクトの種類（`ParticleEffect`クラス内の定数）
* `duration`：エフェクトの継続時間（ミリ秒）［オプション］

スプライトの周囲にエフェクトを発生させる。`duration`を設定しない場合、無期限にエフェクトを表示し続ける。エフェクトを止めるには`effects.clear_particles()`を使用する。

公式リファレンス：<https://arcade.makecode.com/reference/sprites/sprite/start-effect>

## コントローラーについて

操作はWASDとQE、もしくは矢印キーとZXを利用する。

### ［関数］スプライトをボタンで動かす（move Sprite）

```python
controller.move_sprite(
    sprite: Sprite,
    vx: number,
    vy: number): None
```

* `sprite`：ボタンによって動かすスプライト（Spriteクラスのインスタンス）
* `vx`：スプライトに与えるx軸速度
* `vy`：スプライトに与えるx軸速度

ボタンが押されたとき、スプライトを与えられた速度で動かす。

公式リファレンス：<https://arcade.makecode.com/reference/controller/move-sprite>

### ［関数］左右の移動量を取得（dx）

```python
controller.dx(
    step: number): number
```

* `step`：キーが押されたときに割り当てる横方向の動きの量
* 返却値：押されたキーに対する左右の移動量を示す

キーが押されたときに、スプライトの位置を変えるための横方向の動きの量を取得する。`step`の値が正のとき、左キーが押された場合は負の値、右キーが押された場合は正の値が返される。

公式リファレンス：<https://arcade.makecode.com/reference/controller/dx>

### ［関数］上下の移動量を取得（dy）

```python
controller.dy(
    step: number): number
```

* `step`：キーが押されたときに割り当てる横方向の動きの量
* 返却値：押されたキーに対する上下の移動量を示す

キーが押されたときに、スプライトの位置を変えるための縦方向の動きの量を取得する。`step`の値が正のとき、上キーが押された場合は負の値、下キーが押された場合は正の値が返される。

公式リファレンス：<https://arcade.makecode.com/reference/controller/dy>

### ［メソッド］ボタンが押されたとき（on Event）

```python
controller.Button.on_event(
    event: ControllerButtonEvent,
    handler: () -> None): None
```

* `event`：ボタンが押される動作の種類（`ControllerButtonEvent`列挙型の値）
* `handler：ハンドラとする関数の名前（引数はなし）

ボタンが押されたとき、ハンドラを実行する。

`ControllerButtonEvent`列挙型は、ボタンが押されるうちのどのタイミングであるかを表す。`ControllerButtonEvent.PRESSED`のように指定する。以下の３種類。

* `PRESSED`：ボタンが押された瞬間に実行される
* `RELEASED`：ボタンが離れた瞬間に実行される
* `REPEATED`：ボタンが押されているとき実行され続ける

公式リファレンス：<https://arcade.makecode.com/reference/controller/button/on-event>

### ［メソッド］ボタンが押された（is Pressed）

```python
controller.Button.is_pressed(): bool
```

返却値：ボタンが押されている場合は`true`、押されていない場合は`false`を返す

ボタンが現在押されているかどうかを確認する。

## ゲーム全体管理について

### ゲームループとは

ゲームループは、ゲーム全体を定期的に更新して変化させる役割を持つ。主に下の3つの動作からなる。

1. プレイヤーからの入力処理
2. ゲーム状態の更新
3. 描画

MakeCodeでは、`on_update()`に指定された関数がシステムによって定期的に実行される。感覚は数十ミリ秒程度？　時間間隔を自分で指定してコードを実行するには`on_update_interval()`を使用する。

### ［関数］ゲームを終了しスコアを表示する（over）

```python
game.over(
    win: bool,
    effect: effects.BackgroundEffect): None
```

* `win`：プレイヤーが勝った（True）か負けたか（False）
* `effect`：ゲーム終了時に表示するエフェクト［オプション］

ゲームを終了し、プレイヤーにゲームが終了したことを知らせる。現在のスコアと最高スコアが表示される。キーやボタンを押すとゲームプログラムがリセットされる。

なお、`game.game_over()`も用意されている模様。動作は`game.over()`とほぼ同じだが、エフェクト未選択の場合、エフェクトとして紙吹雪が表示される。

公式リファレンス：<https://arcade.makecode.com/reference/game/over>

### ［関数］ゲームオーバー時のエフェクトを設定する（set Game Over Effect）

```python
game.set_game_over_effect(
    win: bool,
    effect: effects.BackgroundEffect): None
```

* `win`：プレイヤーが勝ったときにエフェクトを開始する場合は`true`、負けたときにエフェクトを開始する場合は`false`
* `effect`：ゲームオーバー時に表示するエフェクト（`BackgroundEffect`クラス内の定数）

ゲームが終了したときに表示するエフェクトを設定する。

公式リファレンス：<https://arcade.makecode.com/reference/game/set-game-over-effect>

### ［関数］ゲームオーバー時のメッセージを設定する（set Game Over Message）

```python
game.set_game_over_message(
    win: bool,
    message: str): None
```

* `win`：プレイヤーが勝ったときにメッセージを表示する場合は`true`、負けたときに表示する場合は`false`
* `message`：ゲーム終了時に表示するメッセージ文字列

ゲームが終了したときに表示するメッセージを設定する。

公式リファレンス：<https://arcade.makecode.com/reference/game/set-game-over-message>

### ［関数］ゲームオーバー時に音を再生する（set Game Over Playable）

```python
game.set_game_over_playable(
    win: bool,
    sound: music.Playable,
    looping: bool): None
```

* `win`：プレイヤーが勝ったときに音を再生する場合は`true`、負けたときに再生する場合は`false`
* `sound`：ゲームオーバー時に再生する音（Playableクラスのインスタンス）
* `looping`：`true`にすると音をループ再生、`false`にすると音を1回のみ再生

ゲームが終了したときに再生する音を設定する

公式リファレンス：<https://arcade.makecode.com/reference/game/set-game-over-playable>

### ［関数］ゲームオーバー時のスコアリングタイプを設定する（set Game Over Scoring Type）

```python
game.set_game_over_scoring_type(
    type: ScoringType)
```

* `type`：複数ゲームの中での最高スコアの記録方法（`ScoringType`クラス内の定数）

複数のゲームプレイの中で、どのスコアを最高スコアとして記録するかを設定する。

`type`は、ボタンが押されるうちのどのタイミングであるかを表す。`game.ScoringType.HIGH_SCORE`のように指定する。以下の３種類。

* `HIGH_SCORE`：最高スコアを記録する
* `LOW_SCORE`：最低スコアを記録する
* `NONE`：スコアを記録しない

公式リファレンス：<https://arcade.makecode.com/reference/game/set-game-over-scoring-type>

### ［関数］ゲームが更新された時実行する（on Update）

```python
game.on_update(
    a: () -> None): None
```

* `a`：ゲームループ毎に実行させる関数の名前（引数はなし）

ゲームの定期的な更新処理を実行する。ゲームエンジンが定期的に呼び出し、スプライトの位置確認やスコアの変更、ライフカウントの調整、ゲーム終了の条件などを処理する。

公式リファレンス：<https://arcade.makecode.com/reference/game/on-update>

### ［関数］指定された時間間隔でゲームが更新された時実行する（on Update Interval）

```python
game.on_update_interval(
    period: number,
    a: () -> None); None
```

* `period`：コードを実行する間隔（ミリ秒）
* `a`：指定時間間隔毎に実行させる関数の名前（引数はなし）

指定した間隔ごとにコードを実行する。`on_update`と異なり、`on_update_interval`ではユーザーが指定した時間間隔でコードが実行される。`on_update`と`on_update_interval`の両方を使用する場合、`on_update_interval`のコードが先に実行される。

公式リファレンス：<https://arcade.makecode.com/reference/game/on-update-interval>

### ［関数］ABボタン入力（ask）

```python
game.ask(
    title: str,
    subtitle: str): bool
```

* `title`：質問のテキスト
* `subtitle`：質問の補足［オプション］
* 返却値：Aボタンが押された場合は`true`、Bボタンが押された場合は`false`

プレイヤーに「はい」または「いいえ」の質問をする。Aボタンで`true`、Bボタンで`false`を返す。

公式リファレンス：<https://arcade.makecode.com/reference/game/ask>

### ［関数］文字列の入力を受け付ける（ask For String）

```python
game.ask_for_string(
    message: any,
    answerLength: number): str
```

* `message`：プレイヤーに入力を促すメッセージ
* `answerLength`：プレイヤーが入力できる最大文字数（最大24文字、デフォルトは12文字）［オプション］
* 返却値：プレイヤーが入力した文字列

プレイヤーに文字列を入力させるためのメッセージを表示する。入力には専用の仮想キーボードが用意されている。入力が完了すると、入力された文字列が返される。

公式リファレンス：<https://arcade.makecode.com/reference/game/ask-for-string>

### ［関数］タイトルを表示する（splash）

```python
game.splash(
    title: str,
    subtitle: str): None
```

* `title`：タイトルのテキスト
* `subtitle`：サブタイトルのテキスト［オプション］

ゲームの開始時やゲーム内の任意のタイミングで、タイトルとサブタイトルを画面に表示する。表示されたスプラッシュテキストは、キーやボタンを押すと消える。

公式リファレンス：<https://arcade.makecode.com/reference/game/splash>

### ［関数］長いテキストを表示する（show Long Text）

```python
game.show_long_text(
    str: any,
    layout: DialogLayout): None
```

* `str`：表示するテキスト
* `layout`：テキストダイアログの画面上の位置（`DialogLayout`列挙型）

長いメッセージを表示するためのダイアログウィンドウを表示する。テキストが長すぎて一度に表示できない場合、Aボタンもしくは上下キーでスクロールできる。

`DialogLayout`列挙型は、ボタンが押されるうちのどのタイミングであるかを表す。`DialogLayout.TOP`のように指定する。以下の6種類。

* `TOP`：画面の上部に表示
* `LEFT`：画面の左側に表示
* `RIGHT`：画面の右側に表示
* `BOTTOM`：画面の下部に表示
* `CENTER`：画面の中央に表示
* `FULL`：画面全体に表示

公式リファレンス：<https://arcade.makecode.com/reference/game/show-long-text>

### ［関数］ダイアログカーソルを設定（set Dialog Cursor）

```python
game.set_dialog_cursor(
    cursor: Image): None
```

* `cursor`：ダイアログカーソルとして表示する画像（`Image`クラスのインスタンス）

ダイアログウィンドウに表示されるカーソル画像を設定する。元のデフォルトカーソルに戻すには、空の画像を使用する。

公式リファレンス：<https://arcade.makecode.com/reference/game/set-dialog-cursor>

### ［関数］ダイアログフレームを設定（set　Dialog Frame）

```python
game.set_dialog_frame(
    frame: Image): None
```

* `frame`：ダイアログウィンドウのフレーム画像

ダイアログウィンドウのフレーム画像を設定する。フレーム画像を作成する際、縁と背景を表すピクセルが必要。最も簡単なフレームは3行3列の画像である。元のデフォルトフレームに戻すには、空の画像を使用する。

公式リファレンス：<https://arcade.makecode.com/reference/game/set-dialog-frame>

### ［関数］ダイアログの文字色を設定（set Dialog Text Color）

```python
game.set_dialog_text_color(
    color: number): None
```

* `color`：表示するテキストの色番号

テキストダイアログで表示されるテキストの色を設定する。

公式リファレンス：<https://arcade.makecode.com/reference/game/set-dialog-text-color>

### ［関数］ゲームをリセット（reset）

```python
game.reset(): None
```

ゲームをリセットする。ゲームプログラムが停止し、再起動される。リセットボタンを押すのと同様である。

公式リファレンス：<https://arcade.makecode.com/reference/game/reset>

### ［関数］開始からの経過時間（runtime）

```python
game.runtime(): number
```

* 返却値：ゲーム開始からの経過時間（ミリ秒）

ゲームが開始されてからの経過時間を返却する。

## シーン（画面管理）について

### ［関数］画面の幅（screen Width）

```python
scene.screen_width(): number
```

* 返却値：スクリーンの幅（ピクセル）

画面の横幅を取得する。

公式リファレンス：<https://arcade.makecode.com/reference/scene/screen-width>

### ［関数］画面の高さ（screen Height）

```python
scene.screen_height(): number
```

* 返却値：スクリーンの高さ（ピクセル）

画面の高さを取得する。

公式リファレンス：なし

### ［関数］背景色を設定（set Background Color）

```python
scene.set_background_color(
    color: number): None
```

画面の背景色を設定する。

公式リファレンス：<https://arcade.makecode.com/reference/scene/set-background-color>

### ［関数］背景色を設定（set Background Color）

```python
scene.set_background_color(
    color: number): None
```

画面の背景色を設定する。

公式リファレンス：<https://arcade.makecode.com/reference/scene/set-background-color>

### ［関数］背景画像を設定（set Background Image）

```python
scene.set_background_image(
    img: Image): None
```

* `img`：設定する背景画像（`Image`クラスのインスタンス）

画面の背景画像を設定する。

公式リファレンス：<https://arcade.makecode.com/reference/scene/set-background-image>

### ［関数］背景色（background Color）

```python
scene.background_color(): number
```

* 返却値：画面の背景色の色番号

画面の背景色を取得する。

公式リファレンス：<https://arcade.makecode.com/reference/scene/set-background-color>

### ［関数］背景色（background Color）

```python
scene.background_color(): number
```

* 返却値：画面の背景色の色番号

画面の背景色を取得する。

公式リファレンス：<https://arcade.makecode.com/reference/scene/background-color>

### ［関数］背景画像（background Image）

```python
scene.background_image(): Image
```

* 返却値：画面の背景画像（Imageクラスのインスタンス）

画面の背景画像を取得する。

公式リファレンス：<https://arcade.makecode.com/reference/scene/background-image>

### ［メソッド］スクリーンエフェクトを開始（start Screen Effect）

```python
effects.ScreenEffect.start_screen_effect(
    duration: number,
    particlesPerSecond: number): None
```

* `duration`：エフェクトを表示する時間（ミリ秒）
* `particlesPerSecond`：1秒あたりに表示されるパーティクルの数

エフェクトを画面に表示する。`duration`が指定されない（または0）場合は表示し続ける。停止には`end_screen_effect()`を使用する。

公式リファレンス：<https://arcade.makecode.com/reference/effects/start-screen-effect>

### ［メソッド］スクリーンエフェクトを開始（stop Screen Effect）

```python
effects.ScreenEffect.stop_screen_effect(): None
```

画面上のエフェクトを停止させる。

公式リファレンス：<https://arcade.makecode.com/reference/effects/end-screen-effect>

### ［関数］カメラがスプライトを追尾する（camera Follow Sprite）

```python
scene.camera_follow_sprite(
    sprite: Sprite): None
```

* `sprite`：カメラが追尾するスプライト（Spriteクラスのインスタンス）

画面を指定したスプライトに追尾させる。ゲームのマップ全体が画面サイズより大きい場合、スプライトが画面外に移動してもカメラがスプライトを中心に捉え、画面が移動する。

### ［関数］カメラの中心位置を設定する（center Camera At）

```python
scene.center_camera_at(
    x: number,
    y: number): None
```

* `x`：カメラの中心位置とするシーンの横方向の座標
* `y`：カメラの中心位置とするシーンの縦方向の座標

ゲームのマップ全体が画面サイズより大きい場合、指定された座標へ画面を移動させる。

### ［関数］カメラを揺らす（camera Shake）

```python
scene.camera_shake(
    amplitude: number,
    duration: number): None
```

* `amplitude`：カメラが動く大きさ
* `duration`：揺れる時間（ミリ秒）

画面を揺らす。