API/playdate.graphics.tilemap - Playdate 非公式開発まとめ wiki

playdate.graphics.tilemap

playdate.graphics.tilemap は、イメージテーブル (playdate.graphics.imagetable) を使ってタイルマップを管理・描画するためのオブジェクトです。

playdate.graphics.tilemap
関連ページ

概要

local gfx <const> = playdate.graphics
local imageTable = gfx.imagetable.new("images/tiles")
local tilemap = gfx.tilemap.new()
tilemap:setImageTable(imageTable)
tilemap:setSize(20, 15)
tilemap:setTileAtPosition(1, 1, 2)
tilemap:draw(0, 0)

重要なのは、タイル座標は 1始まりということです。

-- 左上のタイルを取得.
tilemap:getTileAtPosition(1, 1)

生成

new()

新しいタイルマップオブジェクトを作成します。

カテゴリ	名前	型	説明
戻り値	-	playdate.graphics.tilemap	タイルマップオブジェクト

ただし、作成直後はまだ画像テーブルもサイズも設定されていません。通常はこの後に以下を行います。

-- タイルマップを生成
local tilemap = playdate.graphics.tilemap.new()
 
-- イメージテーブルとサイズを設定.
tilemap:setImageTable(imageTable)
tilemap:setSize(width, height)
 
-- またはタイルデータを設定.
tilemap:setTiles(data, width)

セットアップ

tilemap:setImageTable(table)

タイルマップで使う playdate.graphics.imagetable を設定します。

カテゴリ	名前	型	省略	説明
引数	table	playdate.graphics.imagetable	x	イメージテーブル

基本的な使い方。

-- イメージテーブルの読み込み.
local tiles = playdate.graphics.imagetable.new("images/tiles")
-- イメージテーブルの設定.
tilemap:setImageTable(tiles)
-- imagetable の各画像が、タイルIDとして参照されます.
tilemap:setTileAtPosition(1, 1, 1) -- imagetable の1番目の画像
tilemap:setTileAtPosition(2, 1, 2) -- imagetable の2番目の画像

注意点として、"0" は空タイル扱いです。
描画されないタイル、または通行可能タイルとして使われることが多いです。

tilemap:setSize(width, height)

タイルマップのサイズを、タイル数で設定します。

カテゴリ	名前	型	省略	説明
引数	width	number	x	タイルマップのX軸の数
引数	height	number	x	タイルマップのY軸の数

例えば、tilemap:setSize(20, 15) という設定は「20ピクセル × 15ピクセル」ではなく「20列 × 15行」となります。

tilemap:getSize()

タイルマップのサイズを、タイル数で取得します。

カテゴリ	名前	型	説明
戻り値	width	number	タイルマップのX軸の数
戻り値	height	number	タイルマップのY軸の数

tilemap:getTileSize()

1タイルあたりのピクセルサイズを取得します。

カテゴリ	名前	型	省略	説明
戻り値	tileWidth	number	x	1タイルあたりのピクセル幅
戻り値	tileHeight	number	x	1タイルあたりのピクセル高さ

tilemap:getPixelSize()

タイルマップ全体のピクセルサイズを取得します。

カテゴリ	名前	型	説明
戻り値	pixelWidth	number	タイル全体のピクセル幅
戻り値	pixelHeight	number	タイル全体のピクセル高さ

タイル操作

tilemap:setTileAtPosition(x, y, index)

指定したタイル座標にタイルIDを設定します。

カテゴリ	名前	型	省略	説明
引数	x	number	x	タイルX座標。1始まり
	y	number	x	タイルY座標。1始まり
	index	number	x	imagetable の画像番号。1始まり

tilemap:getTileAtPosition(x, y)

カテゴリ	名前	型	省略	説明
引数	x	number	x	タイルX座標。1始まり
引数	y	number	x	タイルY座標。1始まり
戻り値	index	number	x	imagetable の画像番号。1始まり。範囲外の場合は "nil"

tilemap:setTiles(data, width)

一次元配列でタイルマップ全体を設定します。

カテゴリ	名前	型	省略	説明
引数	data	list	x	タイルIDの一次元配列
引数	width	number	x	マップの横幅、タイル数

-- 幅 "4" で設定.
tilemap:setTiles({
    1, 1, 1, 1,
    1, 0, 0, 1,
    1, 0, 2, 1,
    1, 1, 1, 1,
}, 4)

tilemap:getTiles()

現在のタイルマップデータを取得します。

カテゴリ	名前	型	説明
戻り値	data	list	タイルIDの一次元配列
戻り値	width	number	マップの横幅、タイル数

描画

tilemap:draw(x, y, sourceRect)

タイルマップを画面座標 x, y に描画します。

カテゴリ	名前	型	省略	説明
引数	x	number	x	描画先のX座標 (px)
	y	number	x	描画先のY座標 (px)
	sourceRect	playdate.geometry.rect	o	描画する範囲 (省略で全体を描画)

sourceRect を指定すると、タイルマップの一部だけを描画できます。

-- カメラ位置 cameraX, cameraY の範囲だけ描画
local view = playdate.geometry.rect.new(cameraX, cameraY, 400, 240)
tilemap:draw(-cameraX, -cameraY, view)

tilemap:drawIgnoringOffset(x, y, sourceRect)

現在設定されている drawOffset を無視して描画します。

カテゴリ	名前	型	省略	説明
引数	x	number	x	描画先のX座標 (px)
	y	number	x	描画先のY座標 (px)
	sourceRect	playdate.geometry.rect	o	描画する範囲 (省略で全体を描画)

通常の draw() は、playdate.graphics.setDrawOffset() の影響を受けますが、それを無視できます。

-- あらかじめオフセットを指定して描画.
playdate.graphics.setDrawOffset(-cameraX, -cameraY)
tilemap:draw(0, 0)
-- オフセットを無視して描画.
tilemap:drawIgnoringOffset(0, 0)

カメラ用の drawOffset を使っているが、特定のタイルマップだけ画面固定で描きたい
UI用のタイルマップをワールド座標に影響されず描きたい
デバッグ表示としてそのまま描きたい

コリジョン

tilemap:getCollisionRects(emptyIDs)

通行不可タイルを、矩形の配列として取得します。

カテゴリ	名前	型	省略	説明
引数	emptyIDs	list	x	通行可能として扱うタイルIDの配列
戻り値	-	list	x	playdate.geometry.rect の配列

重要なのは、emptyIDs は「壁ID」ではなく、通行可能IDです。

例えば、以下のようなタイルマップIDがあります。

0 = 空
1 = 床
2 = 壁
3 = 水

ここから「床:1」だけ通行可能にしたいなら、

local rects = tilemap:getCollisionRects({ 1 })

とします。
この場合、2 や 3 は衝突対象になります。"0" はデフォルトで空扱いなので、通常 emptyIDs に含めなくてよいです。

getCollisionRects() の使い方

取得した矩形を、空の衝突スプライトとして登録します。

local rects = tilemap:getCollisionRects({ 1 })
for _, rect in ipairs(rects) do
    playdate.graphics.sprite.addEmptyCollisionSprite(
        rect.x,
        rect.y,
        rect.width,
        rect.height
    )
end

ただし、通常はsprite.addWallSprites()を使う方が楽です。

playdate.graphics.sprite.addWallSprites(tilemap, { 1 })

これは内部的に、tilemap:getCollisionRects() で矩形を作り、それを衝突用スプライトとして登録するショートカットです。

関連：playdate.graphics.sprite.addWallSprites(tilemap, emptyIDs, xOffset, yOffset)

これは tilemap 直下の関数ではありませんが、タイルマップ運用では非常に重要です。

local wallSprites = playdate.graphics.sprite.addWallSprites(
    tilemap,
    { 1 },
    0,
    0
)

tilemap の中で、emptyIDs 以外のタイルを壁として扱い、衝突用の invisible sprite を自動生成します。

xOffset, yOffset は、生成される壁スプライトの位置オフセットです。

マップを画面上でずらして配置している場合に使います。

関連：sprite:setTilemap(tilemap)

これも tilemap 直下ではありませんが、実用上重要です。

-- タイルマップをスプライトとして扱う.
local sprite = playdate.graphics.sprite.new()
sprite:setTilemap(tilemap)
sprite:add()

sprite.update() 管理に乗せられる
スプライトのZ順に混ぜられる
他のスプライトと描画順を統一できる
draw() を毎回手動で呼ばなくてよい

資料

座標変換の基本

ピクセル座標 → タイル座標

local function pixelToTile(px, py, tileW, tileH)
    local tx = math.floor(px / tileW) + 1
    local ty = math.floor(py / tileH) + 1
    return tx, ty
end

Playdate のタイル座標は1始まりなので、最後に +1 します。

タイル座標 → ピクセル座標

local function tileToPixel(tx, ty, tileW, tileH)
    local px = (tx - 1) * tileW
    local py = (ty - 1) * tileH
    return px, py
end

最小サンプル

import "CoreLibs/graphics"
local gfx <const> = playdate.graphics
local tiles = gfx.imagetable.new("images/tiles")
local map = gfx.tilemap.new()
map:setImageTable(tiles)
map:setTiles({
    1, 1, 1, 1, 1,
    1, 0, 0, 0, 1,
    1, 0, 2, 0, 1,
    1, 0, 0, 0, 1,
    1, 1, 1, 1, 1,
}, 5)
function playdate.update()
    gfx.clear()
    map:draw(0, 0)
end

Playdate 非公式開発まとめ wiki