【AndEngine】Entityのリファレンスのようなメモ

AndEngineゲーム用のフレームワークっぽいのを作るにあたってEntityについて少し調べる機会があったので、Entityについてメソッドなどをメモも兼ねて紹介していきたいと思います。

(追記2014/10/11　SyntaxHighlighter導入によりソースコードを載せやすくなったので内容を大幅に修正します）

###よく使うもの

・Visibleを指定/取得する
VisibleはEntityの描画を行うかどうかを判定するフラグです
trueの時は描画され、falseの時は描画されません
初期値はtrueです

public boolean isVisible();
public void setVisible(final boolean pVisible);

＜備考＞
・Visibleがfalseの場合自分とChildの描画処理が一切行われません
・個人的には非表示にするSpriteなどはdetachSelf()するのではなく、これを使って非表示にしてやる方がスマートだと思います

・Tagを指定/取得する
TagとはEntityを識別するために振り分ける番号のことです
初期値はint型の最小値です

public int getTag();
public void setTag(final int pTag);

・ZIndexを指定/取得する
ZIndexはEntityのZ座標を表します
といっても厳密な座標としてではなく、描画時の前後関係を設定するために用いるものです
初期値は０です

public int getZIndex();
public void setZIndex(final int pZIndex);

＜備考＞
・適用させたい場合は親EntityでSortChildren()を呼び出す必要があります
・描画処理はZIndexが小さいものから順に行われるのでZIndexが大きい物ほど前に来ます
・０以下を指定した場合は親Entityの後ろに描画されるようになります

・座標を指定/取得する
Entityの座標を指定します、座標は左上が基準です
取り扱う座標は絶対座標ではなく親Entityからの相対座標です
初期座標は(0,0)です

public float getX();
public float getY();

public void setX(final float pX);
public void setY(final float pY);
public void setPosition(final IEntity pOtherEntity);
public void setPosition(final float pX, final float pY);

＜備考＞
・setPosition(final IEntity pOtherEntity)では引数にしたEntityと同じ座標にすることができます

・相対座標を絶対座標に変換する
上で指定/取得できる座標は親Entityからの相対的な座標ですが、
その相対的な座標を絶対座標として変換することができます

public float[] convertSceneToLocalCoordinates(final float pX, final float pY) ;

＜備考＞
・戻ってきた配列の０番目にｘ座標、１番目にｙ座標が格納されています

・色を指定/取得する
Entityの色を指定します。
表示される色はその表示するものの各ドットの色とこれで指定した色との乗算になります
初期値は白(0,0,0)です

public float getRed();
public float getGreen();
public float getBlue();
public float getAlpha();
public Color getColor();

public void setRed(final float pRed);
public void setGreen(final float pGreen);
public void setBlue(final float pBlue);
public void setAlpha(final float pAlpha);
public void setColor(final Color pColor);
public void setColor(final float pRed, final float pGreen, final float pBlue);
public void setColor(final float pRed, final float pGreen, final float pBlue, final float pAlpha);

＜備考＞
・上記の仕様によりTextの色を変更させたい場合は白いFontを用意する必要があります

###子Entity関連

・自身に子Entityを登録する
Entityを自分の子として登録することができます
普通はこれでEntityを登録すれば画面に表示されるというくらいの認識でいいと思います
子Entityの描画に関しては以前の記事でちょっとだけ解説しています

public void attachChild(final IEntity pEntity);

＜備考＞
・登録した子EntityにはgetChildByIndex()等でアクセスすることができます

・登録されている子Entityの数を知る

public int getChildCount();

・指定したインデックスの子Entityにアクセスする
引数で指定したインデックス（配列番号）にいる子Entityを返します

public IEntity getChildByIndex(final int pIndex);

＜備考＞
・インデックスで指定するため特定の子Entityを呼び出すのには向いておらず、for文と合わせて全ての子Entityにアクセスしたい時などに利用します

・指定したTagの子Entityにアクセスする
上とは違いTagを指定して子Entityを得ます

public IEntity getChildByTag(final int pTag);

＜備考＞
・同じTagを持つ子Entityが複数あった場合でも１つしか返してくれないので、独立したTagを持ったものにのみ使用したほうがいいです

・指定した条件を満たす子Entityにアクセスする
AndEngineには以下の様なIEntityMatcherというインターフェースが用意されています

public interface IEntityMatcher extends IMatcher<IEntity> {
	@Override
	public boolean matches(final IEntity pEntity);
}

このmatchesメソッドの引数として渡した時にtrueが帰ってくる子Entityを得ることができます
後述のUserDataと組み合わせて使うといいかもしれません

public IEntity getChildByMatcher(final IEntityMatcher pEntityMatcher);
public ArrayList<IEntity> query(final IEntityMatcher pEntityMatcher);

＜備考＞
・query(final IEntityMatcher pEntityMatcher);は条件を満たしている子Entityを複数得たい時に利用します

・Entityが持つ子Entityの配列の先頭/末尾の子Entityを得る

public IEntity getFirstChild();
public IEntity getLastChild();

＜備考＞
・SortChlldren()を行っている場合はそれぞれ最背面の子Entityと再前面の子Entity、行っていない場合はattachChild(final IEntity pEntity)で最初に登録した子Entityと最後に登録した子Entityを取得できます

・子EntityをZIndexでソートする
自身の子EntityをZIndexでソートします
通常は描画する直前にソートが行われますが、
引数にtrueを指定した場合はその時点でソートが行われます

public void sortChildren();
public void sortChildren(final boolean pImmediate);

＜備考＞
・ZIndexを適用させたい場合は必ず呼び出す必要があります

・子Entityを指定した条件でソートする
AndEngineにはIEntity用のComparatorであるIEntityComparatorが用意されています
これを用いる事でｘ軸でソート、ｙ軸でソートなんてことも出来ます

public void sortChildren(final IEntityComparator pEntityComparator);

＜備考＞
・Comparatorの解説はこちらを見てください

・自身を親Entityから切り離す
自身を親Entityから切り離します

public boolean detachSelf();

＜備考＞
・親がいなかったり、親はいるが親子関係が成り立っていなかったりするとfalseが帰ってきます

・指定した子Entityを自身から切り離す
指定されたIEntityの参照と同じ参照を持つ子Entityを切り離します

public boolean detachChild(final IEntity pEntity);

・指定したタグを持つ子Entityを自身から切り離す
指定されたタグを持つ子Entityを切り離します

public IEntity detachChild(final int pTag);

＜備考＞
・getChildbyTag(final int pTag)と同様で同じタグを持つ子Entityが複数いる場合は、１番最初に見つかった子Entityしか切り離してくれません

・指定した条件を満たす子Entityを自身から切り離す
getChildByTag(final int pTag)と同様に
条件を指定して、それを満たす子Entityを切り離します

public IEntity detachChild(final IEntityMatcher pEntityMatcher);
public boolean detachChildren(final IEntityMatcher pEntityMatcher);

＜備考＞
・detachChildren(final IEntityMatcher pEntityMatcher);の場合は条件を満たす子Entityを全て切り離します

・自身の子Entityを全て切り離す
自身の子Entityを全て切り離します

public void detachChildren();

・子Entityに対して共通の処理を行う
AndEngineにはIEntityCallableという以下の様なインターフェースが用意してあります

public interface IEntityParameterCallable extends ParameterCallable {
	@Override
	public void call(final IEntity pEntity);
}

このcall(final IEntity pEntity);メソッドをオーバーライドして、引数のIEntityに対して何らかの操作を実装させたものを引数として渡すことで子Entity全体に対して共通の動作をさせることができます
ちなみにEntity内ではdetach時の処理を定義しており、detachChildren()等で活用しています

public void callOnChildren(final IEntityParameterCallable pEntityParameterCallable);
public void callOnChildren(final IEntityParameterCallable pEntityParameterCallable, final IEntityMatcher pEntityMatcher);

＜備考＞
・下のはMatcherのmatch条件を満たすものに対してのみ処理を行うものです

###Modifier関連

・Modifierを登録する
Modifierを登録します
Modifierについての解説は省略させてもらいます

public void registerEntityModifier(final IEntityModifier pEntityModifier);

・Modifierを解除する
引数で指定したModifierを解除します

public boolean unregisterEntityModifier(final IEntityModifier pEntityModifier);

＜備考＞
・指定したModifierと同じものが２つ以上登録されている場合でも１つしか解除されません

・指定した条件を満たすModifierを全て解除する
Matcherのmatch条件を満たすModifierを全て解除します

public boolean unregisterEntityModifiers(final IEntityModifierMatcher pEntityModifierMatcher);

・登録されているModifierの数を得る

public int getEntityModifierCount();

・登録されているModifierを全て解除する

void clearEntityModifiers();

###UpdateHandler関連

・UpdateHandlerを登録する
アップデート時に行われる処理を登録します。

registerUpdateHandler(final IUpdateHandler pUpdateHandler);

・UpdateHandlerを解除する
引数で指定したUpdateHandlerを解除します

boolean unregisterUpdateHandler(final IUpdateHandler pUpdateHandler);

＜備考＞
・指定したUpdateHandlerと同じものが２つ以上登録されている場合でも１つしか解除されません

・指定した条件を満たすUpdateHandlerを全て解除する
Matcherのmatch条件を満たすModifierを全て解除します

boolean unregisterUpdateHandlers(final IUpdateHandlerMatcher pUpdateHandlerMatcher);

・登録されているUpdateHandlerの数を得る

public int getUpdateHandlerCount();

・登録されているUpdateHandlerを全て解除する

public void clearUpdateHandlers();

###その他

・ChildrenVisible関連
Entity自身のVisibleの他に子EntityのVisibleであるChildrenVisibleというものが用意されています
これにより子Entity一つ一つのVisibleを直接いじらなくてもまとめて非表示にすることができます

public boolean isChildrenVisible();
public void setChildrenVisible(final boolean ChildrenVisible);

＜備考＞
・子EntityのVisibleがこの関数によって変更される事はありません

・Update処理を行わないようにする
これでtrueをセットをすると、そのEntityではアップデート処理が行われなくなります

public boolean isIgnoreUpdate();
public void setIgnoreUpdate(boolean pIgnoreUpdate);
public boolean isChildrenIgnoreUpdate(); public void setChildrenIgnoreUpdate(boolean pChildrenIgnoreUpdate);

＜備考＞
・IgnoreUpdateがtrueの時は登録してある子Entity、UpdateHandler、Modifierのアップデート処理も行われません
・ChildrenIgnoreUpdateがtrueの時は子Entityたちのアップデート処理のみが無視されます

・画像を回転させる
回転角を指定して画像を回転させます、
ラジアンではなく度数法で指定する必要があるようです

public void setRotation(final float pRotation);

・回転の中心座標を変更する
画像回転の中心となる座標を指定します
初期値だと左上（0,0）が基準になっています

public void setRotationCenterX(final float pRotationCenterX);
public void setRotationCenterY(final float pRotationCenterY);
public void setRotationCenter(final float pRotationCenterX, final float pRotationCenterY);

＜備考＞
・SpriteやRectangle等標準で用意されているEntityのサブクラスではテクスチャが用意されたタイミングでうまく中心に設定してくれているので通常は意識しなくても大丈夫です

・画像の大きさを変える
画像の大きさを比率で指定できます。初期値は１です

public void setScaleX(final float pScaleX);
public void setScaleY(final float pScaleY);
public void setScale(final float pScale);
public void setScale(final float pScaleX, final float pScaleY);

＜備考＞
・SpriteやRectangleには比率の変更を考慮した上でのWidthやHeightを取得する getWidthScaled(),getHeightScaled()がありますが、
Entityクラス自体にはWidthとHeightの概念は無く、それらのメソッドはサブクラスのRectangularShapeクラスにて定義されています

・画像の拡大の中心座標を指定する
回転の中心と同じように拡大の中心を指定出来ます
画像が拡大されても縮小されても中心座標は変わりません

public void setScaleCenterX(final float pScaleCenterX);
public void setScaleCenterY(final float pScaleCenterY);
public void setScaleCenter(final float pScaleCenterX, final float pScaleCenterY);

・カメラの外にいる場合は描画しないようにする
trueにすればカメラの外にいる場合に描画が行われなくなります
デフォルトではfalseです

public void setCullingEnabled(final boolean pCullingEnabled);

・カメラの外にいるか判定する
カメラの外にいる時trueが帰ってきます、
Entityでは必ずfalseが返ってくるようになってます
これを使用することで描画の負担が下がる場合があります
ただし、座標から描画するべきかどうかの判定は行われるので数が多くなると結局重くなります
明らかに画面に描画されない子Entityがある場合はVisibleをfalseにした方が圧倒的に負荷が下がります。

public boolean isCulled(final Camera pCamera);

・Entityに独自のデータを持たせる
ユーザーが定義したデータを入れることができます
格納したデータを扱いたい時はキャストを用います

public void setUserData(final Object pUserData);

＜全体を通しての注意点＞
・全て実際に動作させて試した訳ではないので間違いがある可能性があります。間違いを発見された場合はコメント欄で指摘してくれると有り難いです
・Child関連の部分でやたらとChildと連呼していますが、うまく言葉で表せれないのでChildという単語を使っています。Child型という型が存在する訳ではないです（実際に扱ってる型はIEntityというインターフェースです）

[15/03/20:修正]
やはりChildと書くと分かりづらいのでChildという表記を全て子Entityに変更しました。 [15/05/29:修正]
修正しきれていなかったChild表記を子Entityに修正。

[3回]

うろのなか（工事中）

[PR]

【AndEngine】Entityのリファレンスのようなメモ