サイトのトップへ戻る

AndEngineドキュメント 日本語訳

チュートリアル - Android のログ機能とAndEngineのログ機能

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

あなたがソフトウェア開発者として働いている場合は、たぶん毎日ログ機能を使っているでしょう。 しかしゲーム開発初心者の場合は、ログ機能のコンセプトは全てまったく新しいものかもしれません。 では、正確にはログ機能とは何でしょうか?

プログラムからメッセージを出力したい時、通常は二つの選択肢があります。画面に出力するか何らかのログに出力するかです。ログとは、単純にメッセージの一覧です。 後でコンソールやファイルやそれ以外のどこかに出力されます。

ゲームでは、通常はフルスクリーンで画像を出力して作業しており、画面上に何かを出力するのはあまり実用的ではありません。 Javaの古き良きSystem.out.println()メソッドを使うことができますが、ログ機能を使うともっと便利になります。

Android にはLogCatと呼ばれるログ機能が実装されています。Eclipseを使用している場合は、adbを通してLogCat の出力を参照することができます。 ウィンドウ -> ビューの表示 -> と辿って LogCat を探してください(虹色の尻尾のようなものが付いているものです)。 携帯がつながっている場合は、すぐにいくつかのメッセージが表示されるでしょう。

ログメッセージには以下の属性があります:

  • ログレベル - これはメッセージの重要度です。verbose, debug, info, warning, error , assert (WTF - とてもひどい失敗としても知られる)のレベルがあります。
  • 時刻 - メッセージが追加された時のタイムスタンプ
  • PID - メッセージを出力したアプリのプロセス ID
  • TID - スレッド ID
  • アプリケーション - パッケージ名で識別されます
  • タグ - 独自に設定できる識別子
  • テキスト - 独自に設定できるメッセージ

表示したいメッセージのレベル選択し、またフィルターを使って特定の文字列(単に文字列を入力)やタグ(tag:nameの形式で入力)を含むメッセージのみを表示することもできます。 他のオプションも使用できるので、詳細はEclipse上で確認してください。



コード内でログ機能を使用する方法

標準のAndroid ログ機能を使用するか、AndEngineを使用している場合はそのログラッパーを使用することができます。いくつか例を記載します:


Log.v("kulis", "This is a very detailed message");
Debug.v("This is a very detailed message");
// notice missing tag above, "AndEngine" will be used

Log.i("kulis", "Info level message");
Debug.i("kulis", "Info level message");

try {
  doSomethingDangerous();
} catch (Exception e) {
  // never swallow exceptions, at least print them to log!
  Log.e("kulis", "Oops!", e);
  Debug.e("Oops!", e);
}

Debug.setDebugLevel(DebugLevel.ERROR);
Log.i("kulis", "This message still will be printed");
Debug.i("kulis", "This will not be printed, current level is ERROR");
  
Log.wtf("kulis", "This should never happen");

Android のLogクラスを使う場合は、タグとメッセージと、任意で例外オブジェクト(exception)を指定しなければならないのが分かるでしょう。 AndEngine のDebug クラスではタグなしでメソッドを実行できます。タグを指定しなかった場合、 "AndEngine" タグが自動的に使われます。 また、setDebugLevel というメソッドもあります。- これはログレベルの上限を設定してAndEngine のログ出力を制限します。 AndEngine はwtf()メソッドを実装していません。 It should be used for things that should never happen - so in case they happen, you will know ;)



ベストプラクティス

例外が発生した場合は常にログを記録するようにしてください。 catch ブロック内で何もしないなんて有り得ません。 例外が発生するのを期待している場合は、少なくとも例外が発生したことを示すデバッグメッセージを出力してください - the code above might change later and you will be surprised if you don't print anything. また、特定の例外処理を使用し (単なる Exceptionをキャッチするのではなく、例えばNullPointerExceptionのような特定の Exception をキャッチするようにしてください)、異なるタイプごとに異なるメッセージを使用するようにしてください。

  • Verbose - 低いレベルのデバッグで使用します。キャラクターが画面外に落ちてしまった原因をデバッグする場合になどに、キャラクターの位置といった情報を出力します。
  • Debug - どこか間違えてしまった箇所を特定するのに便利なメッセージです。例えば、メソッドの始まりと終わりでデバッグレベルのメッセージを出力します。
  • Info - These messages can be useful in production as well. infoレベルの重要なイベント、例えばEngine 作成などをログに記録します。
  • Warning - 非常によろしくありませんがバグでもありません。例えば ハイスコアを登録するために Facebook へ接続できない - 良くはありませんが、できなくてもアプリは使えます。
  • Error - 後で分析して修正する必要がある例外やエラーをログに記録します。
  • Assert - これは WTF レベルです。単に発生するはずのない事象をログに記録します。例えば、switch 文で決して想定していないcaseが実行される。

複数の文字を組み合わせてメッセージを作成する場合は注意してください。 For each statement where you concatenate:


Log.d("kulis", "Position: " + x + ", " + y);

Java will create a StringBuilder object, use three method calls and then throw the StringBuilder away. これはパフォーマンスに深刻な影響を与えることがあります! ゲームループ内でこの処理が行われるのを想像してみてください。これが毎秒60回も呼び出されるのです...

以下の三つの選択肢からいずれかの方法を選んでください:


if (BuildConfig.DEBUG) {
  Log.d("kulis", "Position: " + x + ", " + y);
}

if (MainActivity.DEBUG) {
  Debug("Position: " + x + ", " + y);
}

if (Debug.getDebugLevel().isSameOrLessThan(DebugLevel.DEBUG)) {
  Debug("Position: " + x + ", " + y);
}

The first option, BuildConfig.DEBUG,  is Android's built-in property that should be set to false during export with production certificate. しかしこれはあまり上手く動作しないのでお勧めしません。

二つ目の選択肢は独自に設定するboolean プロパティです - highly recommended, because you will probably want to use it elsewhere too.

そして最後の三つ目の選択肢は、デバッグレベル(前述のログレベルを参照)の場合にテストするために、AndEngineに内蔵されているメカニズムです。 一見とても複雑に見えますが、それでもとても便利です

上記のうちいずれかの方法を使用した場合 (特定の場合における最初の選択肢は除く ;))、条件式がfalseの場合は文字連結は実行されません。

またAndEngine のデバッグクラスを使用している場合は、何も出力されない自体を避けるためにデバッグレベルをNONEに設定してください。



まとめ

あなたのアプリケーションからメッセージを渡す場合は常にデバッグ機能を使用し、文字連結はあまり多くは使わないように注意してください。 文字連結が必要な場合はif文で囲んでください。既にAndEngineを使用している場合は Debug クラスを活用してください。

お気づきかもしれませんが、Eclipse 内でのLogCat ビューのアイコンは虹色の尾を引いて飛んでいるドロイドです。 これはイースター・エッグと呼ばれるお遊び的な隠し要素です。 Another easter egg in Ice Cream Sandwich is the actual nyandroid swarm. Go to Settings -> About and start tapping on Version (that should say 4.0.x). After a while a droid dressed in ice cream sandwich appears. Tap and hold on it. Enjoy...




エンジェル戦記