アットウィキロゴ
Playdate 非公式 開発まとめ wiki
アットウィキロゴ
Playdate 非公式 開発まとめ wiki
ページ一覧

playdate.graphics.sprite

playdate.graphics.spriteはスプライト（位置情報・描画情報・コリジョンなど）を扱います。

概要

spriteの全体像
playdate.graphics.sprite は大きく分けると次の3層です。
  1. クラス関数（playdate.graphics.sprite.xxx()）: スプライトシステム全体を操作する関数。例: 全スプライト更新、検索、背景描画、グローバル追加削除など
  2. インスタンス生成（playdate.graphics.sprite.new()）: スプライトを作る入口
  3. インスタンスメソッド（sprite:xxx()）: 個々のスプライトの位置、画像、衝突、表示、更新などを制御する関数

以下は spriteを使うための最小構成は以下のコードです。 
-- 必要なライブラリをimport.
import "CoreLibs/graphics"
import "CoreLibs/sprites"
 
-- 省略名をつける.
local gfx = playdate.graphics
 
-- 画像生成 (or 読み込み).
local image = gfx.image.new(16, 16)
-- 描画情報を登録 (ランタイムで描画する場合).
gfx.pushContext(image)
    gfx.fillRect(0, 0, 16, 16)
gfx.popContext()
 
-- スプライトを生成.
local spr = gfx.sprite.new(image)
spr:moveTo(200, 120) -- 初期位置を設定.
spr:add() -- spriteシステムに登録.
 
-- ゲームの更新.
function playdate.update()
    gfx.sprite.update() -- スプライトの更新.
end
 
  • new() で作る
  • moveTo() などで位置を決める
  • add() で表示リストへ入れる
  • 毎フレーム playdate.graphics.sprite.update() を呼ぶ

importの定義
spriteの機能を使うには以下のimport文が必要です。 
import "CoreLibs/sprites" -- spriteの機能を使うために必要.
 

1. クラス関数 / グローバル操作

addDirtyRect(x, y, width, height)
画面のその矩形領域を「再描画が必要」とマークします。
通常は描画API側が自動で dirty 管理しますが、画像差し替え時の自動再描画を切って細かく制御したい場合に使います。
用途
一部領域だけ再描画したい場合は、setRedrawsOnImageChange(false) と組み合わせて使います。

addEmptyCollisionSprite(r) / addEmptyCollisionSprite(x, y, w, h)
見えない衝突専用スプライトを追加します。
壁、進入禁止エリア、トリガー領域などに便利です。
用途
  • タイルマップの壁を簡易的に collision 化
  • イベント発火エリア
  • 当たり判定だけ必要なオブジェクト

addSprite(sprite)
指定スプライトを表示リストに追加します。sprite:add() のクラス関数版です。
通常はインスタンス側の sprite:add() を使うことが多いです。

addWallSprites(tilemap, emptyIDs, xOffset, yOffset)
タイルマップから壁用の空 collision sprite 群を自動生成します。
tilemap:getCollisionRects() + addEmptyCollisionSprite() の便利版です。
用途

allOverlappingSprites()
現在 overlap している全スプライトの組み合わせを返します。
返るのは「ペアの配列」です。
用途
  • 全体の重なり検査
  • デバッグ
  • 広域判定の可視化

clearClipRectsInRange(startz, endz)
指定 z-index 範囲のスプライトに設定された clip rect をクリアします。
用途
  • 一括クリア
  • レイヤーごとの描画制限解除

getAllSprites()
表示リスト上の全スプライトを返します。
用途
  • デバッグ
  • 一括処理
  • 自前管理せず列挙したいとき

getAlwaysRedraw()
グローバルな always redraw フラグを返します。

new(image_or_tilemap)
新しいスプライトを生成します。
画像またはタイルマップを初期内容として与えられます。 
local spr = new() -- 画像なしで生成.
local spr2 = new(image) -- 画像から生成.
local spr3 = new(tilemap) -- タイルマップから生成.
 
  • 画像なしで作ると、通常は setSize() して draw() を自前実装する形になります
  • 画像ありなら画像サイズがそのまま使われます

performOnAllSprites(f)
全スプライトに対して関数 f(sprite) を実行します。
用途
  • 全停止
  • 全非表示
  • タグによる一括変更

querySpriteInfoAlongLine(lineSegment) / querySpriteInfoAlongLine(x1, y1, x2, y2)
線分と交差するスプライトを、sprite だけでなく entry/exit 情報付きで返します。
返る情報の中心
  • sprite
  • entryPoint
  • exitPoint
用途
  • レーザー
  • 視線判定
  • 弾道チェック
  • レイキャスト風の用途

querySpritesAlongLine(lineSegment) / querySpritesAlongLine(x1, y1, x2, y2)
指定の線分と交差するスプライト群を返します。
querySpriteInfoAlongLine()の簡易版です。

querySpritesAtPoint(p) / querySpritesAtPoint(x, y)
指定の点を collide rect に含むスプライトを返します。
用途
  • カーソル位置判定
  • タップ/選択代替
  • クリック的な hit test

querySpritesInRect(rect) / querySpritesInRect(x, y, width, height)
指定の矩形と collide rect が重なるスプライトを返します。
用途
  • 範囲選択
  • カメラ内オブジェクト収集
  • AoE 判定

redrawBackground()
背景描画コールバックの再描画を強制します。
setBackgroundDrawingCallback() と組み合わせて使います。

removeAll()
全スプライトを表示リストから削除します。
用途
  • シーン切り替え
  • リセット
  • タイトル→ゲーム本編遷移

removeSprite(sprite)
指定スプライトを表示リストから削除します。
sprite:remove() のクラス関数版です。

removeSprites(spriteArray)
配列で渡した複数スプライトを一括削除します。

setAlwaysRedraw(flag)
すべてのスプライトを毎フレーム再描画する設定。
dirty rect 管理を使わず、常に全部描くモードです。
用途
  • dirty 管理が複雑すぎる場合
  • 画面全体が毎フレーム激しく変わる場合
ただし普通は重くなりやすいです。

setBackgroundDrawingCallback(drawCallback)
背景描画用のコールバックを設定します。
内部的には最背面の背景スプライトを作って描かせる仕組みです。
用途
  • タイル背景
  • パララックス未満の固定背景
  • ゲーム世界の下地

setClipRectsInRange(rect, startz, endz) / setClipRectsInRange(x, y, width, height, startz, endz)
指定 z 範囲のスプライトに clip rect を設定します。
用途
  • レイヤー単位の表示制限
  • UI領域だけ描画
  • ビューポート風の制限

spriteCount()
表示リスト内のスプライト数を返します。

spriteWithText(text, maxWidth, maxHeight, backgroundColor, leadingAdjustment, truncationString, alignment, font)
テキストから文字画像つきスプライトを作る便利関数です。
戻り値は sprite, textWasTruncated。
用途
  • ラベル
  • ダメージ表示
  • 会話吹き出しの簡易実装

update()
全スプライトの update と描画処理を進める中心関数です。
通常 playdate.update() の中で毎フレーム呼びます。 
function playdate.update()
    -- すべてのスプライトを更新.
    playdate.graphics.sprite.update()
end
 
混同しやすいですが、sprite:update() とは別物です。

2. インスタンスメソッド / 表示リスト操作

sprite:add()
このスプライトを表示リストへ追加します。
描画・更新対象に入ります。

sprite:remove()
表示リストから削除します。
画面に出ず、sprite:update() も呼ばれなくなります。

3. インスタンスメソッド / 描画・画像

sprite:draw(x, y, width, height)
画像を持たないスプライトで、自前描画したいときに override するメソッドです。
dirty rect 範囲だけ描かれます。
重要
setImage() ではなく draw() を使う方式の場合、何か描くには事前に setSize() か setBounds() で領域を確定させることが必要です。
また、座標はスプライト内部座標で処理されます。

local spr = gfx.sprite.new()
spr:setSize(32, 32)
function spr:draw(x, y, width, height)
    gfx.fillCircleAtPoint(16, 16, 8)
end
 

sprite:getImage()
現在セットされている画像を返します。

sprite:setImage(image, flip, scale, yscale)
スプライト画像を設定します。
必要に応じて flip, scale も渡せます。
注意点

sprite:getImageFlip()
現在の flip 状態を返します。

sprite:setImageFlip(flip, flipCollideRect)
画像の反転を設定します。
  • 左右反転や上下反転
  • flipCollideRect = true なら collide rect も反転
注意
setImage() を呼ぶと flip が初期化されるため、setImage() → setImageFlip() の順で処理を行うのが基本です。

sprite:setImageDrawMode(mode)
画像描画モードを設定します。
playdate.graphics.setImageDrawMode() 系と同じ考え方です。
用途
  • fill, copy, xor などの描画モード変更

sprite:getRotation()
現在の回転角を返します。

sprite:setRotation(angle, scale, yScale)
画像スプライトを回転させます。
オプションで scale も指定可能です。
注意
  • ハードでは重くなりやすい
  • 頻繁に回すなら事前生成画像の方が安全なことが多い

sprite:getScale()
現在のスケールを返します。

sprite:setScale(scale, yScale)
画像スプライトのスケールを変更します。

sprite:isOpaque()
opaque フラグを返します。

sprite:setOpaque(flag)
このスプライトが下を完全に覆うと知らせます。
描画最適化に有効です。
  • マスクや透過のない画像なら自動で opaque になりやすい
  • 背景が完全に見えないと確実に言えるとき向き

sprite:setRedrawsOnImageChange(flag)
setImage() 時の自動再描画を有効/無効にします。
用途
  • 小さな範囲だけ dirty にしたい
  • redraw 制御を自前で最適化したい

sprite:setStencilImage(stencil, tile)
ステンシル画像を設定します。
描画前にフレームバッファへステンシルを適用します。
用途
  • 特殊マスク表現
  • 抜き表示
  • 模様つき描画

sprite:setStencilPattern(level, ditherType) / sprite:setStencilPattern(pattern) / sprite:setStencilPattern(row1, ..., row8)
ステンシルをディザパターンまたは8行パターンで設定します。
用途
  • 半透明っぽい見た目
  • パターン付き塗り
  • 白黒ハードらしい表現

sprite:clearStencil()
ステンシルを解除します。

4. インスタンスメソッド / 位置・サイズ・境界

sprite:getPosition()
現在位置 (x, y) を返します。

sprite:moveTo(x, y)
中心位置ベースで移動します。
setCenter() の設定を反映します。

sprite:moveBy(x, y)
現在位置から相対移動 (差分移動) します。

sprite:getBounds()
境界を (x, y, width, height) で返します。

sprite:getBoundsRect()
境界を rect で返します。

sprite:setBounds(rect) / sprite:setBounds(x, y, width, height)
境界矩形を直接設定します。
ここでの x, y は必ず左上基準です。
moveTo() との違い

sprite:getCenter()
中心アンカーを (x, y) の 0.0〜1.0 で返します。

sprite:getCenterPoint()
中心アンカーを point で返します。

sprite:setCenter(x, y)
中心アンカーを設定します。デフォルトは (0.5, 0.5)です。
例
  • (0, 0) にすると moveTo(x, y) が左上基準になる
  • (0.5, 1.0) にすると足元基準っぽくなる

sprite:getSize()
サイズ (width, height) を返します。

sprite:setSize(width, height)
スプライトサイズを設定します。
setImage() などで画像を読み込んだスプライトには無効です。
主に画像なし spriteが draw() で自前するためのスプライトと言えます。

5. インスタンスメソッド / 可視性・レイヤー・タグ

sprite:isVisible()
可視状態か返します。
sprite:setVisible(flag)
表示/非表示を切り替えます。
非表示スプライトは draw() されません。
sprite:getZIndex()
z-index を返します。
sprite:setZIndex(z)
z-index を設定します。
値が大きいほど前面です。
用途
  • 前後関係
  • タイル背景の前後
  • UIを最前面に置く

sprite:getTag()
タグ値を返します。

sprite:setTag(tag)
0〜255 のタグを設定します。
衝突時の識別に便利です。 
player:setTag(1) -- プレイヤーにタグ番号 "1" を設定.
enemy:setTag(2) -- 的にタグ番号 "2" を設定.
 

6. インスタンスメソッド / update 系

sprite:update()
個別スプライトの毎フレーム更新メソッドです。
すべてのスプライトを更新するには playdate.graphics.sprite.update()を使います
override して使います。(overrideもとの update() は空なので、super.update() は不要です) 
function spr:update()
    self:moveBy(1, 0)
end
 
呼ばれる条件
  • add() を呼び出してスプライトシステムに登録済みであること
  • updatesEnabled() が true

sprite:setUpdatesEnabled(flag)
このスプライトの update() 呼び出しの有効/無効を切り替えます。

sprite:updatesEnabled()
update() が有効かどうかを返します。

sprite:markDirty()
現在 bounds 全体を再描画対象にします。
用途
  • draw() 自前描画で見た目が変わった
  • アニメ状態が変わった
  • 自動で dirty にならない変化が起きた

7. インスタンスメソッド / clip

sprite:setClipRect(rect) / sprite:setClipRect(x, y, width, height)
このスプライトの描画範囲を制限します。
用途
  • メーターの切り抜き
  • ウィンドウ内表示
  • スクロール領域表現

sprite:clearClipRect()
個別 clip rect を解除します。

8. インスタンスメソッド / 衝突の基本

Playdate の sprite collision は、setCollideRect() を設定して初めて参加するのが重要です。
moveTo() や moveBy() では衝突解決はされず、moveWithCollisions() を使う必要があります。

sprite:setCollideRect(rect) / sprite:setCollideRect(x, y, width, height)
衝突用矩形を設定します。
座標はスプライト内部の左上基準です。center は関係ありません。
コード例： 
-- スプライトサイズそのままでコリジョンサイズにする.
spr:setCollideRect(0, 0, spr:getSize())
 

sprite:getCollideBounds()
collide rect を (x, y, width, height) で返します。

sprite:getCollideRect()
collide rect を rect で返します。

sprite:clearCollideRect()
衝突矩形を解除します。

sprite:setCollisionsEnabled(flag)
衝突を一時的に有効/無効にします。

sprite:collisionsEnabled()
衝突有効フラグを返します。

sprite:moveWithCollisions(goalPoint) / sprite:moveWithCollisions(goalX, goalY)
衝突を考慮して移動します。
戻り値は:
  • actualX
  • actualY
  • collisions
  • length
重要
  • これを使わないと built-in collision 解決は動かない
  • collisions[i] から相手や法線などを調べられる
  • collision info は moveWithCollisions() / checkCollisions() まで有効
用途
  • プレイヤー移動
  • 壁滑り
  • コイン取得
  • バウンドや停止

sprite:checkCollisions(point) / sprite:checkCollisions(x, y)
moveWithCollisions() と同じ衝突結果を返しますが、実際には移動しません。(移動前に衝突チェックを行う)
用途
  • 先読み、この移動先に行けるか確認
  • AI の経路確認

sprite:overlappingSprites()
現在重なっているスプライト群を返します。
グループ/マスクも考慮されます。

sprite:alphaCollision(anotherSprite)
画像の非透明ピクセル同士で本当に重なっているかを返します。
bounding box ではなく、ピクセル単位の overlap です。
用途
  • 見た目通りの厳密判定
  • bounding 判定後の絞り込み

sprite:collisionResponse(other)
衝突時の応答タイプを決めるコールバックです。
必要に応じて override します。
代表的な返却候補
  • kCollisionTypeSlide
  • kCollisionTypeFreeze
  • kCollisionTypeOverlap
  • kCollisionTypeBounce
使い分け
  • 壁 → slide / freeze
  • コイン → overlap
  • 跳ね返る球 → bounce
注意
この中でスプライトのコリジョンや描画情報を変更したりせず、できるだけ速く処理を返すべきです。

9. インスタンスメソッド / collision group / mask

Playdate では「どのスプライト同士が衝突するか」をgroup と collidesWithGroups で制御できます。

sprite:setGroups(groups)
所属グループを設定します。
整数1〜32、または配列。 
enemy:setGroups(2)
bullet:setGroups({3, 4})
 

sprite:setGroupMask(mask)
所属グループを bitmask で設定します。

sprite:getGroupMask()
group mask を取得します。

sprite:resetGroupMask()
group mask を 0x00000000 に戻します。

sprite:setCollidesWithGroups(groups)
どのグループと衝突するかを整数または配列で設定します。

sprite:setCollidesWithGroupsMask(mask)
どのグループと衝突するかを bitmask で設定します。

sprite:getCollidesWithGroupsMask()
collides-with mask を取得します。

sprite:resetCollidesWithGroupsMask()
collides-with mask を 0x00000000 に戻します。

10. インスタンスメソッド / animator

sprite:setAnimator(animator, moveWithCollisions, removeOnCollision)
playdate.graphics.animator をこのスプライトに割り当て、
アニメータ進行に合わせて自動移動させます。
条件
  • 点から点への animator を使う想定
  • moveWithCollisions = true なら衝突付き移動
  • removeOnCollision = true なら衝突で animator を外す
用途
  • 自動移動
  • イージング移動
  • イベント演出

sprite:removeAnimator()
設定された animator を外します。

11. インスタンスメソッド / タイルマップ・オフセット

sprite:setTilemap(tilemap)
スプライト内容を tilemap にします。
タイルマップをスプライトとして扱いたいときに使います。
用途
  • 深度つき地形
  • 一部背景を sprite 系へ統合

sprite:setIgnoresDrawOffset(flag)
グローバル drawOffset を無視して画面座標固定で描くようにします。
用途
  • HUD
  • 固定UI
  • カメラ移動の影響を受けない表示
注意
  • 描画だけで、collision はワールド座標のまま
  • collision 用スプライトには向かない

12. 補助系

sprite:copy()
スプライトを複製します。

資料

spriteの重要な関数
spriteで頻繁に使用する優先度が高いのはこのあたりです。
  • new()
  • sprite:add()
  • sprite:remove()
  • sprite:moveTo()
  • sprite:moveBy()
  • sprite:setImage()
  • sprite:setSize()
  • sprite:setCenter()
  • sprite:setZIndex()
  • sprite:setVisible()
  • sprite:setCollideRect()
  • sprite:moveWithCollisions()
  • sprite:update()
  • sprite:markDirty()
  • update()
このセットで、たいていのゲームオブジェクトは組めます。

その他の注意点

よくある実装パターン

画像スプライトの生成
local spr = gfx.sprite.new(img)
spr:moveTo(100, 100)
spr:add()
 

自前描画スプライト
local spr = gfx.sprite.new()
spr:setSize(32, 32)
function spr:draw(x, y, w, h)
    gfx.fillRect(0, 0, 32, 32)
end
spr:add()
 

衝突付きプレイヤー
player:setCollideRect(0, 0, player:getSize())
function player:update()
    local gx, gy = self.x, self.y
    if playdate.buttonIsPressed(playdate.kButtonLeft) then
        gx -= 2
    end
    self:moveWithCollisions(gx, gy)
end
 

HUD を画面固定
hud:setIgnoresDrawOffset(true)
hud:setZIndex(1000)
 
スプライトをクラスで継承する方法
import "CoreLibs/object"
import "CoreLibs/graphics"
import "CoreLibs/sprites"
 
local gfx = playdate.graphics
 
-- スプライトを継承
class('Enemy').extends(gfx.sprite)
 
function Enemy:init(x, y)
    -- 親クラス(sprite)のinitを呼ぶ
    Enemy.super.init(self)
 
    -- スプライトの初期設定
    local image = gfx.image.new(32, 32, gfx.kColorBlack)
    self:setImage(image)
    self:moveTo(x, y)
    self:add() -- 画面の描画リストに追加
end
 
-- 毎フレーム呼ばれる更新処理をオーバーライド
function Enemy:update()
    self:moveBy(1, 0) -- 右へ移動
end
 

関連ページ

「playdate.graphics.sprite」をウィキ内検索
最終更新：2026年05月01日 08:57