サイトのトップへ戻る

AndEngineドキュメント 日本語訳




AndEngine チュートリアル - 入門編

このチュートリアルではAndEngineの基礎的な部分について説明します。

AndEngineで開発を始めるために役立つチュートリアルは既にいくつがあります。 しかしそれらは動画のチュートリアルなので、私のように動画で見てもよく分からない人であればこのサイトのチュートリアルがお勧めです。 サイトの内容を気に入っていただけたのであれば、同じくAndEngine について書かれたこの本もお勧めします。

AndEngine とは、 Android用の2D OpenGL ES ゲームエンジンで、ニコラス・グラムリッチ氏によって開発されました。 OpenGL は通常3Dグラフィックに使われますが、特定の設定 (正射図法) をすることによって2Dでも非常に上手く動作します

AndEngine はゲームエンジンです。ゲーム作成システムではありません。 Android用アプリのほとんどはJavaで記述されており、AndEngine もJavaで記述されています。 - AndEngine は、ゲーム作成における一部の処理を手助けするだけのライブラリです。 このチュートリアルを理解するためには、Javaに関する知識、コンピュータへのJavaのインストール方法、基本的なJavaプログラミングについて知っている必要があります。 またAndroidの端末(携帯やタブレット)を持っていることが望ましいです。 チュートリアルの後半では適切なエミュレータのインストールについて説明しますが、それを実機テストの代わりにすることはできません。 私はWindowsを使用しているので、全てWindows向けに説明します。内容は他のOSでも共通するでしょう。

それでは始めましょう。不明瞭な点や分かりにくい点があった場合は記事下からコメントしてください。 メモ: 画像をクリックするとそれを元の大きさで表示できます。



必要なソフトのインストールと準備

最新のJava JDKをインストールします。 単にJDKとだけ書かれているものだけが必要で、NetBeans IDEは必要ありません。選択するAndroidのIDEは、EclipseのGoogleバージョンです。 もう一つの IDE 、Android Studioも登場しましたが、使用するにはまだ早いので今のところは置いておきます。

ADTバンドル版 Android SDK をインストールします。 リンク先のページからダウンロードしてください - 使用許諾契約に同意してあなたの環境に合った正しいバージョン (32-bit か 64-bit)を選んでください。 64-bit システム上で32-bit Javaを動作させている場合は、 32-bitを選んでください。ADTバンドルのみをダウンロードして、インストール済みのEclipseを使用することもできます。 ここではその方法までは説明しません。

ダウンロードしたファイルはadt-bundle-windows-x86-20130729.zipのようなものになります。 それを任意のディレクトリに解凍します。まず最初に"SDK Manager.exe"ファイルを実行します。 起動までに時間がかかることがあり、その間スプラッシュスクリーンは表示されません。そのまま待ってください。 以下のような画面が表示されるでしょう。:

更新可能なパッケージがあるか確認してください。必要なのは最新版のSDKだけなので注意してください。現在の最新版は SDK 18 - Android 4.3です。 どのバージョンのSDKを使用しても、全バージョンのAndroid上へインストールできるアプリケーションを作成することができます。 しかし、SDK 18から実装された、古いAndroid 端末では使用できない機能を使用すると、そのメソッドは実行されずに警告や例外が発生します。 注意してください。しかしそのコードのコンパイルとインストール自体は可能です!

アップデートが終わると画面を閉じます。 もちろん、あなたが必要だと思うパッケージを全てイントールすることができます。 しかしこのチュートリアルでは既定のものだけで十分です。The SDK マネージャーには、Eclipse上からもアクセスすることができます。

それでは eclipse(adt-bundle-windows-x86-20130729/eclipse/eclipse.exeのファイル)を実行します。スプラッシュスクリーンが表示された後、最初にこれが表示されるでしょう:

If you have never worked with Eclipse, note that workspace is both a virtual space on your screen (the layout) and a directory where your projects and some metadata that Eclipse keeps about your projects are stored. 簡単にアクセスできる任意のディレクトリを選んでください。ワークスペースを複数設定することもできます。 "この選択をデフォルトとして使用し、今後この質問を表示しない" のチェックボックスにチェックを入れると、既定でこのワークスペースで作業をするようになり、再度起動してもこのダイアログは表示されません。 この設定はEclipseのメニューからいつでも使用可能です。

起動が終わってようこそ画面を閉じると、Eclipse の既定レイアウトで開発画面が表示されます。 Everybody prefers something else but you will see my layout later on the screenshots. 画面のレイアウトは全てドラッグアンドドロップで変更することができます。 また、ワークスペースごとに異なった画面レイアウトをすることもできます。これについては後ほどデバッグに関するチュートリアルで説明します。



AndEngine のソースをダウンロードして解凍する

AndEngine はオープンソースで、 Apache licese v2のライセンスを適用しています。 商用ゲームに使用し、そのゲームに任意のライセンスを適用することができます。 エンジンを修正することも可能ですが、修正したことが誰にでも分かるようにしなければなりません。

公式の AndEngine ソースがある場所は GitHubです。このチュートリアルでは、基本的な AndEngine ライブラリのみが必要になります。

使用可能な拡張を使ったサンプルプロジェクトがあり、それらのAndEngine サンプルをコンパイルして実行するには全ての拡張クラスが必要ですが、今のところはそんな面倒なことはしないでおきましょう。拡張クラスとサンプルについては次のチュートリアルで説明します。

AndEngineには複数のブランチがあるので注意してください。 GLES1 ブランチでは OpeGL ES 1.0 を扱っており、最も古いです。これを使うのはお勧めしません。 GLES2 は比較的新しく、 GLES2-AnchorCenterが最も新しいものです。これまでAndEngine を使ったことがないのであれば、GLES2-AnchorCenterを使ってください。 AnchorCenter と GLES2 の最大の違いは、(0,0)座標が画面の左下隅にあるということです。 これはOpenGLと同じ仕様であり、そのためにAnchorCenter の使用を推奨します。

GitHub は(SVN や CVSのような)ソースコードのバージョン管理リポジトリですが、それらよりもさらに簡単になっています。Donwload Zip ボタンをクリックしてください。 バージョン管理システムはソフトウェア開発で広く使用されており、 sooner or later you might want to go back and use it. For your own benefit. ソースをダウンロードする別の方法を知りたいのであれば、GitHubについて説明したチュートリアルを確認してください。

AndEngine-GLES2-AnchorCenter.zip ファイルをワークスペースとして設定したディレクトリに解凍します。 "v" ディレクトリの名前を "AndEngine"に変更します。それから Eclipse画面上で、ファイル -> インポート と進んでExisting Projects into Workspaceを選んでください。 Browse をクリックしてあなたのワークスペースのディレクトリを設定します。以下のような表示になるでしょう。完了をクリックしてプロジェクトをインポートします。




SDK 18バンドルのadbをインストールした場合はコンソールに以下のメッセージが表示されるでしょう: 

[2013-08-25 15:36:11 - AndEngine-GLES2-AnchorCenter] Unable to resolve target 'android-17'
[2013-08-25 15:36:11 - AndEngine-GLES2-AnchorCenter] Project compiler settings changed. Clean your project.

実際、この表示はしばしば目にします。それではこれを修正しましょう: AndEngine プロジェクトを右クリックし、プロパティ→ Androidと選びます。 そこでオプションを一つだけ選んでください。そうしたらOKをクリックします。 おそらく、エラーを消すにはプロジェクトで プロジェクト -> クリーンを実行する必要があるでしょう(単にEclipseの仕様です)。 このプロジェクトはSDK 17を選んで保存されているため、この作業が必要なのです。SDK 17はインストールされていないので、インストールされているものを選ぶ必要があるのです。



Hello Worldプログラム

Hello Worldプログラムを作成するチュートリアルを学んだことはありますか? ファイル -> 新規 -> Android アプリケーションプロジェクトの順に進んでください。

Application name は、端末上でアプリのアイコンの下に表示されます。実際にアプリケーションやゲームを作成するのであれば、ちゃんと意味を持った名前をつけてください。 Project name は、単にeclipse 上でのプロジェクトの名前です - これはapkファイルの名前として使われます。 あなたのアプリケーション名に由来する一つの単語を使用することを推奨します。 あなたのゲームがAwesome Football Managerという名前としましょう。 Applicaiton Nameにこれを入力できますが、表示できる文字数制限のために端末上ではおそらくアイコンの下に"Awesome Foo..."と表示されるでしょう。

Package name はJavaコードで使用されます。あなたが独自ドメインを所持している場合は、それを(後ろに)入力してください。 独自ドメインを所持していない場合は、imagine that you do and what it would look like. package はGoogle Play storeやその他ストアにおけるユニークIDとなるので注意してください。使用するpackage nameが既に使用されていないか確認してください! 私のドメインは kul.isなので、私のpackage は is.kulから始まります。

Minimum target SDK は、単にあなたがサポートする予定の最小Androidバージョンです。 AndEngine は SDK 8でも上手く動作しますが、大きなテクスチャを使用すると問題が発生するかもしれません。これについては後半のチュートリアルで説明します。

Target SDK とCompile with には、使用可能な最も高いバージョンの SDK (18) を選び、常にそうするようにしてください。 古いバージョンで発生したバグを再現する必要でもない限り、最高バージョン以外を選ぶ意味はありません。

Theme には noneを選びます。activity の背景は表示されないので、気にする必要はありません 。 もしかしたら画像の周りにいくつかゴミが表示されるかもしれません。 今のところ、Theme はこのチュートリアルの範疇外です。

Nextをクリックします。"カスタムランチャーアイコンを作成する"の選択を外してください。見た目を良くするためだけに無駄な時間を使うつもりはありません。 再度Next をクリックすると、Activity 作成ウィザードが表示されます。 "Blank activity" が選択状態になっているはずです。なっていなかった場合は "Blank activity"を選択し、次へをクリックします。

次の画面ではactivityのカスタマイズができます。今のところ重要なのはactivity nameだけです。これはactivityのクラス名と同じです。 全ての項目を既定のままにして、 完了を押します。

これで空のAndroid アプリケーション(AndEgine アプリケーションではない)が作成されました。 Android 端末を接続して試してみてください。Android 端末上でUSB デバッグが有効になっていることを確認してください。 有効になっていない場合は、設定をタップし、{}開発者向けオプションへスクロールして有効にしてください。 Eclipse のジョブのパネルにある緑色の実行ボタンをクリックして 実行 -> Android アプリケーション を選んでください。

 

するとポップアップが表示されます。そこにはあなたの Android 端末の一覧が表示されています。ここでは、"unknown-q88"として識別されている私の中華タブレットが表示されています。 エミュレータではなく、実機を使うことを強く推奨します。ですが、エミュレータについても後で説明はします。 複数の端末でテストをする場合、そのテストをする段階になるまでは "今後の起動で同じデバイスを使用する"にチェックを入れておくことを推奨します。

あなたのアプリが端末上で起動するでしょう。起動しないのであれば、その原因究明をしなければなりません。 - この段階でのトラブルは AndEngine とは無関係です。

別のポップアップが表示されて、LogCatを使用しているアプリからのメッセージを自動で監視するか聞いてくるでしょう。 その場合は「はい」を選んでください。 LogCat とデバッグ機能については別のチュートリアルで説明します。しかし今のところは、「はい」を選んでEclipse上に組み込まれているLogCatの画面を確認してください。 そこにはあなたのアプリやその他全てのアプリから出力された有用なメッセージが表示されています。これらは後で使います。

全て正しく作業したのであれば、Hello World メッセージが表示されます。



AndEngine を Hello Worldプロジェクトに追加する

プロジェクトを右クリックし、プロパティを選びます。Androidを選びます。「追加」をクリックして、その中にある使用可能なオプションのみを選びます。 追加すると以下のように表示されます。 OKをクリックします。

設定すべき項目やダウンロードすべきものがたくさんありましたが、これで全部完了です。ではコードを見てみましょう! MainActivity.javaを開いてください。 ヒント: Ctrl+Shift+R を使ってワークスペース内の任意のリソースをすばやく開くことができます。Ctrl+Shift+Rを同時押しした後、表示されたポップアップに Main...と入力してください。多くの選択肢が表示されてその中にMainActivity があるのが分かるでしょう

MainActivity.javaは以下のようになっています: 


package is.kul.tutorial.helloworld;

import android.os.Bundle;
import android.app.Activity;
import android.view.Menu;

public class MainActivity extends Activity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
  }

  @Override
  public boolean onCreateOptionsMenu(Menu menu) {
    // Inflate the menu; this adds items to the action bar if it is present.
    getMenuInflater().inflate(R.menu.main, menu);
    return true;
  }

}

免責事項: Androidのコードスタイルに合わせて、ハンガリアン表記法で記載しています。 この表記法の良し悪しについては、インテーネット上で大きな議論にもなっています。 Without starting any flames,ニコラス氏はエンジンでこの表記方法を使用しています。 このチュートリアルでは私もそれに倣おうと思います。 You will see it more often than not, get used to it. It will make your life easier. 詳細はこのページを参照してください。

以下の画像をダウンロードして、名前を"helloworld.png"にしてワークスペースのTutorial_1_HelloWorld/assetsフォルダ内に配置してください:

そしてMainActivity 内のコードを以下のように書き換えます: 


package is.kul.tutorial.helloworld;

import java.io.IOException;

import org.andengine.engine.camera.Camera;
import org.andengine.engine.options.EngineOptions;
import org.andengine.engine.options.ScreenOrientation;
import org.andengine.engine.options.resolutionpolicy.RatioResolutionPolicy;
import org.andengine.entity.scene.Scene;
import org.andengine.entity.sprite.Sprite;
import org.andengine.entity.util.FPSLogger;
import org.andengine.opengl.texture.ITexture;
import org.andengine.opengl.texture.bitmap.AssetBitmapTexture;
import org.andengine.opengl.texture.region.ITextureRegion;
import org.andengine.opengl.texture.region.TextureRegionFactory;
import org.andengine.ui.activity.SimpleBaseGameActivity;
import org.andengine.util.adt.color.Color;


public class MainActivity extends SimpleBaseGameActivity {

  private static final int CAMERA_WIDTH = 800;
  private static final int CAMERA_HEIGHT = 480;

  private ITexture mHelloWorldTexture;
  private ITextureRegion mHelloWorldTextureRegion;


  @Override
  public EngineOptions onCreateEngineOptions() {
    final Camera camera = new Camera(0, 0, CAMERA_WIDTH, CAMERA_HEIGHT);

    return new EngineOptions(true, ScreenOrientation.LANDSCAPE_SENSOR, 
        new RatioResolutionPolicy(CAMERA_WIDTH, CAMERA_HEIGHT), camera);
  }

  @Override
  public void onCreateResources() throws IOException {
    this.mHelloWorldTexture = new AssetBitmapTexture(this.getTextureManager(), 
        this.getAssets(), "helloworld.png");
    this.mHelloWorldTextureRegion = TextureRegionFactory.extractFromTexture(
        this.mHelloWorldTexture);
    this.mHelloWorldTexture.load();
  }

  @Override
  public Scene onCreateScene() {
    this.mEngine.registerUpdateHandler(new FPSLogger());

    final Scene scene = new Scene();
    scene.getBackground().setColor(Color.YELLOW);

    final float centerX = CAMERA_WIDTH / 2;
    final float centerY = CAMERA_HEIGHT / 2;

    final Sprite sprite = new Sprite(centerX, centerY, 
        this.mHelloWorldTextureRegion, this.getVertexBufferObjectManager());
    scene.attachChild(sprite);

    return scene;
  }

}

これは AndEngineExamples プロジェクト内にあるSpriteExample.javaに記載されたサンプルとほとんど同じものです。 ですが、今の段階でそのサンプルプロジェクトをインポートしようとすると、失敗するでしょう。 サンプルについては次のパートで扱います。

このアプリケーションを実行すると、以下のように表示されます:

今のところは上記のコードに限定し、各部分がどういった動きをしているのかを少し説明ます。 


public class MainActivity extends SimpleBaseGameActivity {

SimpleBaseGameActivity は BaseGameActivityを拡張したものです。 AndEngine における全てのActivity は、その拡張元としてBaseGameActivity を持つ必要があります。 SimpleBaseGameActivity はいくつかの機能(イベント後に呼び出されるコールバック)を実装しており、必要に応じてそれらをカスタマイズします。 実際のゲームでは、 おそらくBaseGameActivity のみを継承してコールバックを独自に実装することでしょう。 

  @Override
  public EngineOptions onCreateEngineOptions() {
    final Camera camera = new Camera(0, 0, CAMERA_WIDTH, CAMERA_HEIGHT);

    return new EngineOptions(true, ScreenOrientation.LANDSCAPE_SENSOR, 
        new RatioResolutionPolicy(CAMERA_WIDTH, CAMERA_HEIGHT), camera);
  }
上記のメソッドは、そのように動作するかをengineに指示します。 engineに対してcamera を引数として渡すため、ここで camera を作成します。 今のところはcamera にはScene全体を映したいでしょうから、camera には解像度と同じサイズを設定します。

EngineOptionsには注意してください。

  • 一つ目のパラメータは、フルスクリーンで実行するかどうかです。
  • ScreenOrientation は、端末を回転させた時にどのように動作するかをアプリに指示します。 ここでは四つのオプションが指定できます。横向きと縦向き両方について、fixed(画面固定) とsensor(センサー) を指定できます。 センサーとは、端末をひっくり返した時にengine がスクリーンを回転させることを意味します。
  • resolution policy is one of the trickiest thing ever. Let's just say that the two bars you might see around your screen are caused by that. The rule of thumb is that you specify resolution (and resolution policy) that best suits your game and the engine will take care of all scaling. 
    • camera に幅800x高さ480を設定するも携帯の解像度が 1280x720だったとしましょう。 - RatioResolutionPolicyを使えば何も問題ありません。 engine がscene を800x480から1200 x 720へ拡大し、画面の左端と右端に40pxのバーが表示されます。 そして800x480の画面サイズの時と同じ設定でSceneにエンティティを設置することができます。
    • 処理自体は何も難しくありませんが、最適な解像度を見つけ出すのは難しいかもしれません。
  • 最後に camera を設定します


  @Override
  public void onCreateResources() throws IOException {
    this.mHelloWorldTexture = new AssetBitmapTexture(this.getTextureManager(), 
        this.getAssets(), "helloworld.png");
    this.mHelloWorldTextureRegion = TextureRegionFactory.extractFromTexture(
        this.mHelloWorldTexture);
    this.mHelloWorldTexture.load();
  }
上記で全てのリソースを作成します。今回は画像のみを作成しています。ここでは三つの基本的な用語を理解する必要があります:
  • Texture - これは端末のメモリ上にあり、画像を表すビットマップです
  • Texture Region - これはtextureの一部分です。
  • Sprite - これは仮想エンティティで、Texture Regionに関連付けられてそのTexture Regionを画面に表示します。
Texture オブジェクトを作成し、Texture Regionを定義し、Texture をファイルからメモリへ読み込みます。 
  @Override
  public Scene onCreateScene() {
    this.mEngine.registerUpdateHandler(new FPSLogger());

    final Scene scene = new Scene();
    scene.getBackground().setColor(Color.YELLOW);

    final float centerX = CAMERA_WIDTH / 2;
    final float centerY = CAMERA_HEIGHT / 2;

    final Sprite sprite = new Sprite(centerX, centerY, 
        this.mHelloWorldTextureRegion, this.getVertexBufferObjectManager());
    scene.attachChild(sprite);

    return scene;
  }

最後はSceneを作成するメソッドです。フレームレートを表示するために、特別なハンドラを登録すると良いでしょう。 FPS のメッセージがLogCat似表示されます。

ここでは単に黄色い背景を作成して、その中央にSpriteを設置しています。 Spriteについては作成方法について参照しておいてください。 位置と表示するTexture Regionとvertex buffer object manager (vbom)を設定しなければなりません。 vbom はこのチュートリアルでは説明しません。vbom について今のところ言えるのは、常にこのように設定してください、です...



まとめ

This is it. 携帯上でHelloWorld のサンプルが実行できていることでしょう。サンプルでもっと色々なことを試してみてください。 そのうち他の全てのプロジェクトについても、Eclipse上でを開いて問題を修正するチュートリアルも追加する予定です。 もちろん、あなたが自分の力でやってみることもできます。 単純にニコラス氏のGitHubから全ての拡張クラスをダウンロードし、それらをEclipseに追加し、プロジェクトの設定を修正するだけですから。

次: AndEngine の拡張クラスと AndEngineのサンプル