「Cocos Code IDEとLua言語でゲームを作る」逆引き辞典for Lua

スプライト

Cocos Code IDEとLua言語を使ったサンプルコードと例文集です。

スプライトを使用すると、画像ファイルを画面に表示することができます。

サンプルコード

プロジェクトの新規作成で作成されるGameScene.luaのGameScene.create()を下記のサンプルコードと書き換えます。 画像をcharacter.pngのファイル名で作成し、resディレクトリに追加します。 実行すると画面にスプライトが表示されます。

function GameScene.create()
    local scene = GameScene.new()

    local sprite = cc.Sprite:create("character.png") -- 画像ファイルからスプライトを作成
    sprite:setPosition(200, 200)
    scene:addChild(sprite) -- シーンにスプライトを加える

    return scene
end

character.png

スプライトの例文

スプライトを作成する

Spriteクラスを使い、スプライトを作成します。

画像ファイル名を指定してスプライトを作成します。作成したスプライトはシーンやレイヤーの子として加えることで画面に表示されます。引数のrectでスプライトとして表示する矩形を指定することができます。

local sprite = cc.Sprite:create("image.png")

Spriteクラス：createメソッド

create() （空のスプライトを作成します。メソッドに続いてsetTextureメソッドを呼び出してください。）
create(filename)
create(filename, rect)
スプライトを作成します。

• (string) filename:画像ファイルへのパス
• (rect_table) rect:描画する矩形

シーンやレイヤーに配置する

スプライトはシーンやレイヤーに配置するまで表示されません。シーンへの配置はaddChildメソッドを使います。

scene:addChild(sprite) -- シーンにスプライトを加える

Nodeクラス：addChildメソッド

addChild(child)
addChild(child, localZOrder)
addChild(child, localZOrder, name)
addChild(child, localZOrder, tag)

子ノードとして追加します。Zオーダーのデフォルト値は0になります。

• (cc.Node) child:子ノード
• (int) localZOrder:ローカルZオーダー
• (string) name:ノードにつける名前
• (int) tag:ノードにつけるタグ番号

表示位置を設定する

スプライトの表示位置を変えるにはsetPositionメソッドを使います。

sprite:setPosition(100.0, 100.0) -- スプライトを(100.0,100.0)に表示します。

Nodeクラス：setPosition(x,y) メソッド

親の座標系での(x,y)にノード位置を設定します。

• (float) x:X座標
• (float) y:Y座標

画面中央に表示する

スプライトを画面中央に表示するには、cc.Director:getInstance():getVisibleSize()で画面サイズを取得し、スプライトを中央に表示するように座標を指定します。

local visibleSize = cc.Director:getInstance():getVisibleSize() -- 画面サイズを取得
sprite:setPosition(visibleSize.width/2.0, visibleSize.height/2.0)

表示位置を取得する

スプライトを表示位置を取得するには、getPositionX()、getPositionY()、getPosition()を使います。getPosition()はx,yの２つの値が返ります。

local x = sprite:getPositionX()
local y = sprite:getPositionY()
-- または、
local pos = cc.p(sprite:getPosition()) -- pos.xとpos.yでX座標、Y座標がわかります。
-- または、
local x, y = sprite:getPosition()

サイズを取得する

スプライトのサイズを取得するには、getContentSize()を使います。 下記の例では、size.widthで幅、size.heightで高さがわかります。

local size = sprite:getContentSize()

拡大・縮小する

スプライトを拡大・縮小にはsetScale(倍率), setScaleX(倍率), setScaleY(倍率)を使います。

-- 2倍に拡大
sprite:setScale(2.0)
-- X方向に半分に縮小
sprite:setScaleX(0.5)

Spriteクラス：setScaleメソッド

setScale(scale)
setScale(scaleX, scaleY)
setScaleX(scaleX)
setScaleY(scaleY)

ノードの倍率を設定します。

• (float) scale:倍率
• (float) scaleX:X方向の倍率
• (float) scaleY:Y方向の倍率

回転する

スプライトを回転するにはsetRotation(角度)を使います。角度は時計回りの角度を指定します。

-- 時計回りに45度回転
sprite:setRotation(45)

Spriteクラス：setRotation(rotation) メソッド

ノードの回転角度を設定します。初期値は0です。正の数は時計回り、負の数は反時計回りとなります。

• (float) rotation:回転角度

反転表示する

スプライトを反転表示するにはsetFlippedX(true)、setFlippedY(true)を使います。

-- X方向に反転
sprite:setFlippedX(true)

表示・非表示にする

スプライトを表示するにはsetVisible(true)、非表示にするにはsetVisible(false)を使います。

sprite:setVisible(true)

重なり順を変更する

スプライトの重なり順を変更するにはsetGlobalZOrderメソッド、setLocalZOrderメソッドを使います。Zオーダーが大きいほど手前に描画されます。 setGlobalZOrderはノードの親子関係に関係なく重なり順を決めます。setLocalZOrderは兄弟ノード同士の重なり順を決めます。

sprite:setGlobalZOrder(10)

Z座標を変更する

スプライトのZ座標を指定するには、setPositionZメソッドを使います。 Z座標が大きいほど手前に大きく、小さいほど奥に小さく描画されます。

sprite:setPositionZ(1)

Spriteクラス：setPositionZ(positionZ)メソッド

Z座標を設定します。setGlobalZOrder()も設定されます。

• (float) positionZ:OpenGLのZ頂点座標

透明度を変更する

スプライトの透明度を指定するには、setOpacityメソッドを使います。 0〜255の範囲内で値を指定します。0で完全に透明、255で不透明になります。

-- 半透明
sprite:setOpacity(255/2)
-- 透明
sprite:setOpacity(0)

Nodeクラス：setOpacity(opacity)メソッド

ノードの透明度を設定します。

• (unsigned char) opacity:透明度

スプライトに色を付ける

スプライトに色をつけるにはsetColorメソッドを使います。色はcc.c3b(赤,緑,青)を使って指定します。

sprite:setColor(cc.c3b(0, 0, 255))

Nodeクラス：setColor(color)メソッド

ノードの色を設定します。

• (color3b_table) color:色

アンカーポイントを変更する

スプライトのアンカーポイントを変更するにはsetAnchorPoint(x,y)を使います。x,yは0.0〜1.0の値で指定します。

-- 中央（デフォルト）
sprite:setAnchorPoint(0.5, 0.5)
-- 左下
sprite:setAnchorPoint(0.0, 0.0)
-- 左上
sprite:setAnchorPoint(0.0, 1.0)

Nodeクラス：setAnchorPoint(x,y)メソッド

setAnchorPoint(anchorPoint)
ノードのアンカーポイントを設定します。

アンカーポイントはすべての変形や位置決め操作が行われる中心点です。これは親に貼り付ける場所を示すノード内のピンのような物です。アンカーポイントはパーセントのように正規化されています。(0,0)は左下の角を意味し、(1,1)は右上の角を示します。しかし、(1,1)以上の値や(0,0)以下の値を使うこともできます。アンカーポイントのデフォルト値は(0.5,0.5)で、ノードの中央を起点とします。

• (float) x:アンカーポイントのX座標
• (float) y:アンカーポイントのY座標
• (vec2_table) anchorPoint:アンカーポイントの座標値

2つのスプライト同士が交差しているかどうかを調べる

2つのスプライト同士が交差しているかどうかを調べるにはcc.rectIntersectsRect関数を使います。２つの矩形が交差している時にtrueが返ります。 スプライトの矩形はgetBoundingBox()メソッドで取得することができます。

-- 2つのスプライトsprite1,sprite2を作成しておきます。
local result = cc.rectIntersectsRect(sprite1:getBoundingBox(), sprite2:getBoundingBox())
-- 交差するとresultにtrueが返ります。

cc.rectIntersectsRect(rect1, rect2)関数

矩形同士が交差しているかどうかを調べます。交差している場合trueが、そうでない場合falseが返ります。

• (rect_table) rect1:
• (rect_table) rect2:

座標点がスプライト内にあるかを調べる

座標点が矩形内にあるかどうかを調べるには、cc.rectContainsPoint関数を使います。

local position = cc.p(100, 100)
local result = cc.rectContainsPoint(sprite:getBoundingBox(), position)
-- 座標点がスプライトの矩形ないにあるとresultにtrueが返ります。

cc.rectContainsPoint(rect, point)関数

座標点が矩形内にあるかどうかを調べます。矩形内の場合trueが、そうでない場合falseが返ります。

• (rect_table) rect:
• (point_table) point:

スプライトをシーンやレイヤーから削除する

スプライトを親シーンや親レイヤー上から削除するには、removeFromParent()メソッドを使います。

sprite:removeFromParent()

スプライトに名前をつける

スプライトに名前をつけるにはsetNameメソッドを使います。

-- 名前をつける
sprite:setName("name1")

Nodeクラス：setName(name)メソッド

ノードを容易に識別できるように名前を設定します。

• (strong) name:ノード名の文字列

名前からスプライトを探す

名前からスプライトを探すには、親レイヤーなどに対してgetChildByName(名前)を使います。

-- 名前をつけたスプライトを取得する
local sprite = layer:getChildByName("name1") -- layerはスプライトを追加したレイヤー

Nodeクラス：getChildByName(name)メソッド

子ノードを名前で探して取得します。

• (strong) name:ノード名の文字列

スプライトにタグ番号を付ける

スプライトにタグ番号を付けるにはsetTag(タグ番号)を使います。

-- タグをつける
sprite:setTag(10)

Nodeクラス：setTag(tag)メソッド

ノードを容易に識別できるようにタグを設定します。

• (int) tag:タグ番号

タグ番号からスプライトを探す

タグ番号からスプライトを探すには、親レイヤーなどに対してgetChildByTag(タグ番号)を使います。

-- タグを指定してスプライトを取得する
local sprite = layer:getChildByTag(10) -- layerはスプライトを追加したレイヤー

Nodeクラス：getChildByTag(tag)メソッド

子ノードをタグ番号で探して取得します。

• (int) tag:タグ番号

スプライトに独自のデータを設定する

スプライトのインスタンスに変数を持たせて、そこにデータを格納できます。Luaではコードの途中からでも変数を追加できてしまうので、どこで変数を作成したかわからなくならないように配慮しましょう。コンストラクタで初期値を設定するなどして、変数の使用を明示するとよいでしょう。 また、既存の変数を上書きしないようにも注意してください。

sprite.myData = "abc"

テクスチャからスプライトを作成

テクスチャからスプライトを作成するにはcreateWithTextureメソッドを使います。

local texture = cc.Director:getInstance():getTextureCache():addImage("texture.png")
local sprite = cc.Sprite:createWithTexture(texture, cc.rect(0, 0, 64, 64))

Spriteクラス：createWithTextureメソッド

createWithTexture(texture)
createWithTexture(texture, rect, rotated = false)
テクスチャからスプライトを作成します。

• (cc.Texture2D) texture:テクスチャ
• (rect_table) rect:この矩形内のテクスチャがスプライトとして使われる
• (bool) rotated:テクスチャが回転しているかどうか

スプライトフレームからスプライトを作成

スプライトフレームからスプライトを作成createWithSpriteFrame(spriteFrame)を使います。

local spriteFrame = cc.SpriteFrame:create("image.png", cc.rect(0, 0, 64, 64))
local sprite = cc.Sprite:createWithSpriteFrame(spriteFrame) 

Spriteクラス：createWithSpriteFrame(spriteFrame)メソッド

スプライトフレームからスプライトを作成します。

• (cc.SpriteFrame) spriteFrame:テクスチャと矩形位置・サイズを含むスプライトフレーム

スプライトでパラパラアニメーションをする

スプライトを使ってパラパラアニメーションをするには、主に次の手順で行います。

• アニメーション用の画像からテクスチャを作成
• アニメーションのコマ数だけテクスチャを切り出してスプライトフレームを作成
• アニメーションを行うアクションを作成してスプライトに設定

下記のサンプルコードでは256x256サイズの２枚の絵からパラパラアニメーションを行っています。texture.pngは256x256サイズの絵を横に２枚並べて512x256のサイズの画像としています。

サンプルコード

local layer = cc.Layer:create() -- レイヤーを作成

-- テクスチャの作成
local texture = cc.Director:getInstance():getTextureCache():addImage("texture.png")

-- スプライトフレームの作成
local frame0 = cc.SpriteFrame:createWithTexture(texture, cc.rect(0, 0, 256, 256))
local frame1 = cc.SpriteFrame:createWithTexture(texture, cc.rect(256, 0, 256, 256))

-- スプライトの作成
local sprite = cc.Sprite:createWithSpriteFrame(frame0)

-- アニメーションの作成
local animation = cc.Animation:createWithSpriteFrames({frame0,frame1}, 0.8) -- 0.8はアニメーションを切り替える秒数
local animate = cc.Animate:create(animation)
sprite:runAction(cc.RepeatForever:create(animate))

-- スプライトの位置を設定
sprite:setPosition(visibleSize.width / 2, visibleSize.height / 2)

-- レイヤーに加える
layer:addChild(sprite)
-- この後layerをシーンに配置します。

スプライトのマスク処理

スプライトのマスク処理を行うにはClippingNodeを使います。 まず、クリッピングノードを作成し、レイヤーへ追加します。この時setAlphaThreshold(0)を設定しておきます。 次にマスク用の画像をスプライトとして作成し、クリッピングノードのステンシルに設定します。 マスク用の画像は透明な部分が繰り抜かれます。 これでクリッピングノードの準備は終了です。

最後に必要な分だけスプライトをクリッピングノードへ追加していきます。

下記のサンプルコードはマスク用画像mask.pngを背景を透明色、表示したい部分を塗りつぶした画像を使用しています。

サンプルをテストするための画像はQiitaに投稿した画像を使用してください。

サンプルコード

local layer = cc.Layer:create() -- レイヤーを作成

-- 画面サイズを取得    
local visibleSize = cc.Director:getInstance():getVisibleSize()

-- クリッピングノードの作成とレイヤへ追加
local clippingNode = cc.ClippingNode:create()
clippingNode:setAlphaThreshold(0)
layer:addChild(clippingNode)

-- マスク画像の作成とクリッピングノードのステンシルに設定
local mask = cc.Sprite:create("mask.png")
mask:setPosition(visibleSize.width/2, visibleSize.height/2)
clippingNode:setStencil(mask)

-- スプライトをクリッピングノードに追加
local sprite = cc.Sprite:create("image.png")
sprite:setPosition(visibleSize.width/2, visibleSize.height/2)
clippingNode:addChild(sprite)

-- この後layerをシーンに配置します。

マスク用の画像について

マスク用の画像は背景を透明色、表示したい部分を何色でも良いので塗りつぶして作成します。

マスクする部分を逆にしたい時

マスクして隠す部分と表示する部分を逆にしたいときはclippingNode:setInverted(true)を使います。

うまく表示されない時

うまく表示されない時は、clippingNode:setAlphaThresholdの設定がされているか、clippingNode:setStencilでマスク画像が指定されているか、クリッピングノードや画像の位置、アンカーポイントがおかしいため表示範囲外にはみ出ていないか、などをチェックしてみてください。