2Dアニメーションの管理

はじめに

Karakuri Framework は、コマベースで実現される2Dのキャラクタ・アニメーションを簡単にサポートするための機構を用意しています。この文書では、その概念と使い方について説明します。

主な概念

キャラクタの特徴

キャラクタの特徴は、利用するテクスチャ、テクスチャ内の1コマのサイズ、1個以上の状態から構成されます。

状態

状態は、テクスチャ内の各コマを組み合わせて表現される、一連のアニメーションを表します。

たとえば、シューティングゲームのプレーヤ機体の、上方向の移動アニメーション、下方向の移動移動アニメーション、通常時のアニメーションなどに応じて、それぞれのアニメーションは「状態」として表現されます。

ある状態に含まれるアニメーションは、すべてのコマが表示されたあと、先頭から繰り返す場合もありますし、そこで表示がストップする場合もあります。また、アニメーションが終了した時点で、他の状態に自動的に遷移する場合もあります。

キャラクタ

キャラクタの特徴を元に、個々のキャラクタ・アニメーションを実体化したものです。キャラクタは、現在の位置、現在のZオーダ、現在の色をもち、それらの情報を元に自動的に描画されます。個々のキャラクタの情報は、ゲーム実行時に手動で変更することができます。

キャラクタの特徴記述ファイルの仕様

KRAnime2D::addCharacterSpecs() メソッドを使い、以下の仕様で記述されたキャラクタの特徴を読み込むことができます。このファイルは、テキストエンコーディングが UTF-8、改行が LF のテキストファイルとして用意してください。

まず以下に、記述例を示します。

@version 1.0

# キャラクタ 0
chara: 0 (tex=player.png, atlas=(40, 32), group=1)
    state: 0 (interval=4)
        image: 0, 0
        image: 1, 0
        image: 2, 0 (repeat-back=2)

    state: 1 (interval=4)
        image: 3, 0
        image: 4, 0
        image: 5, 0
        image: 6, 0 (interval=8)
        image: 7, 0

    state: 2 (interval=4, next=0)
        image: 0, 1
        image: 1, 1
        image: 2, 1
        image: 3, 1
        image: 4, 1

# キャラクタ 1
chara: 1, bullet.png, (10, 10)

メタ記述子

ファイルの先頭には、「@」から始まるメタ記述子を書いてください。

メタ記述子には、現在のところ、キャラクタの特徴記述のバージョンを示す「@version 1.0」だけが利用できます。

「#」から始まる行は、コメント記述として無視されます。

chara 命令

フォーマット：【chara: 特徴ID (tex=テクスチャのファイル名, atlas=(1コマあたりのX方向のサイズ, 1コマあたりのY方向のサイズ) )】

使用するテクスチャのファイル名と1コマあたりのサイズを指定して、新しいキャラクタの特徴を定義します。特徴IDには、0 より大きな数字を割り振ってください。複数のキャラクタに同じ特徴IDを割り振ることはできません。

またオプションで、group を指定してテクスチャ読み込みのグループIDを設定できます。デフォルトでは 0 が設定されます。

state 命令

フォーマット：【state: 状態ID (オプション1, オプション2, ...)】

直前に実行された chara 命令で作成されたキャラクタに対して、新しい状態を追加します。状態IDは、0 から開始し、上から順に連続した数字を割り振ってください。

オプションは、「key = value」の形式で記述します。指定できる key は、以下のとおりです。

interval: ひとつのコマから次のコマに移動する間隔を、1 以上のフレーム単位の整数で指定します。デフォルト値は 1 です。
next: この状態のアニメーションが完了したあと、自動的に遷移する状態の状態IDを指定します。デフォルト値は -1 で、自動的に遷移する状態がないことを示しています。

image 命令

フォーマット：【image: アトラスのX座標, アトラスのY座標】

直前に実行された state 命令で作成された状態に対して、新しいコマを追加します。アニメーション時には、最初に追加されたコマから順に表示されていきます。

オプションで、repeat-back を指定することで、そのコマの次に何コマ戻ってアニメーションを繰り返すかを指定することができます。

オプションで、interval を指定することで、コマごとの表示間隔を指定できます。

主な使い方

1. キャラクタ特徴記述ファイルの用意

上記のフォーマットに従って作成した特徴記述ファイルを用意し、これを Xcode プロジェクトに追加します。拡張子などの決まりはとくにありませんが、プロジェクト・テンプレートで用意している「chara2d.spec」という名前に従うことを推奨します。

2. キャラクタ特徴記述ファイルの読み込み

ゲームの開始前のワールドの becameActive() メソッドで、以下のようにしてキャラクタ特徴記述ファイルを読み込みます。記述内容に問題がある場合には、ここで実行時例外がスローされます。

void TitleWorld::becameActive()
{
    gKRAnime2DMan->addCharacterSpecs("chara2d.spec");
    ...
}

3. 必要なテクスチャの読み込み

キャラクタの特徴記述ファイルを読み込んだだけでは、描画に必要なテクスチャは読み込まれません。becameActive() メソッドの中で、テクスチャの読み込みを開始します。

void TitleWorld::becameActive()
{
    ...
    loadResourceGroup(1);
}

なお、ここで読み込みに時間がかかる場合には、KRWorld::getLoadingScreenWorldName() を使った読み込み画面の利用を考えてください。読み込み画面は、あるワールドの becameActive() の処理が完了するまでの間、軽量の描画を行うためのワールドとして実装します。

4. キャラクタの作成・状態変更・削除

ゲーム内では、以下のようにして、適宜キャラクタを作成し、キャラクタの現在位置やZオーダなどを変更していきます。

void PlayWorld::updateModel()
{
    ...
    // mChara は KRCharacter2D クラスのポインタ変数
    if (...) {
        // キャラクタの作成
        mChara = gKRAnime2DMan->createChara2D(0, // キャラクタの特徴ID
                                                 KRVector2D(100, 100), // 初期位置
                                                 0, // 開始時の状態ID
                                                 5); // Zオーダー
    }
    ...
    if (...) {
        // キャラクタの状態変更
        mChara->pos.x += 3;     // 位置の変更
        mChara->setZOrder(3);   // Zオーダの変更
        mChara->changeState(2); // 状態の変更
    }
    ...
    if (...) {
        // キャラクタの削除
        gKRAnime2DMan->removeChara2D(mChara);
        mChara = NULL;
    }
    ...
}

5. アニメーションのステップ実行と描画

アニメーションの描画は、自動的には行われません。

アニメーションの描画は、以下のようにして手動で行う必要があります。

void PlayWorld::drawView(KRGraphics *g)
{
    ...

    gKRAnime2DMan->draw();
}