Assets and Tilesheets ja - Akiaaaa20/Bit8_CLI GitHub Wiki
BIT8_CLI は、登録された PNG Tilesheet を使用してゲームのグラフィック素材を管理します。
各 Tilesheet は 8×8 ピクセルの Tile に分割されます。登録された Tile には安定した Asset ID が割り当てられ、Script、Map、Sprite、Collision の各システムから参照できます。
このガイドでは、BIT8_CLI 0.1.0 の Asset システムについて説明します。
Tilesheet は複数の Tile を含む PNG 画像です。
BIT8_CLI の Tile サイズは固定されています。
8 × 8 ピクセル
例えば、32×16 ピクセルの PNG には以下が含まれます。
- 4 列
- 2 行
- 8 個の Tile
Tile は左から右、上から下の順番で番号が割り当てられます。
32 × 16 PNG
+------+------+------+------+
| A1 | A2 | A3 | A4 |
+------+------+------+------+
| A5 | A6 | A7 | A8 |
+------+------+------+------+
各 Tile は正確に 8×8 ピクセルです。
BIT8_CLI は Asset Registry を使用して登録済み Tilesheet を管理します。
Registry は次のファイルに保存されます。
bit8.assets.toml
Registry は Tilesheet と安定した Group ID を関連付けます。
例えば、ある Tilesheet に Group A が割り当てられている場合、その Tile は次のように参照できます。
A1
A2
A3
A4
Asset Registry は Asset の識別情報に関する唯一の正式な情報源です。
PNG をプロジェクト内に配置するだけで、自動的に登録されるとは限りません。
プロジェクトが提供する Asset 登録機能を使用して、Registry の項目を作成または更新してください。
BIT8_CLI は次の形式の安定した識別子を使用します。
Group + Tile Number
例：
A1
A4
B12
C3
Group は登録済み Tilesheet を識別します。
数字はその Tilesheet 内の Tile を識別します。
この仕組みにより、Script や Map はグローバルな数値順序に依存せずに Tile を参照できます。
例えば：
spr(A4, 16, 16)は指定した座標に Tile A4 を描画します。
複数の Tilesheet を持つプロジェクトを考えてみましょう。
Asset がグローバルなリストの位置だけに依存している場合、Tilesheet の追加や並べ替えによって既存の参照が変わる可能性があります。
Stable Asset ID は、この問題を防ぐために設計されています。
BIT8_CLI は使用終了となった Group ID も記録し、誤って再利用されることを防ぎます。
登録済み Tilesheet は、次の標準的なファイル名形式を使用します。
<name> (<GROUP>).png
例：
terrain (A).png
characters (B).png
items (C).png
Group ID は登録済み Asset の識別情報の一部です。
ただし、最終的な情報源は Asset Registry です。
Registry を更新せずに登録済み PNG の名前を手動変更すると、Asset の参照が失われる可能性があります。
登録済み Tile の描画には spr() を使用します。
func draw()
cls(0)
spr(A4, 16, 16)
endこのコードは画面をクリアし、Tile A4 を描画します。
参照する Tile は、プロジェクトの Asset Registry に存在している必要があります。
BIT8_CLI は旧バージョンとの互換性のため、従来の数値 Sprite 参照も引き続きサポートしています。
新しいプロジェクトでは Stable Asset ID の使用を推奨します。
BIT8_CLI は登録済み PNG Tilesheet の透明ピクセルに対応しています。
透明ピクセルは、Tile の描画時にも透明として扱われます。
PNG の色は Runtime のパレット表現に変換されます。
Asset 処理は、Runtime の描画結果と Editor のプレビューが一致するように設計されています。
予測可能な結果を得るために、色と透明度が明確な Pixel Art 画像の使用を推奨します。
Tile は Collision に使用するため、Solid として設定できます。
Solid Tile の情報は Asset Registry に保存されます。
例えば、Tilesheet の 6 番目の Tile を Solid に設定する場合：
solid = [6]これは登録済み Tilesheet Group 内の 6 番目の Tile を意味します。
Solid Tile は Collision 判定において、8×8 ピクセル全体を占有します。
Node は次のメソッドで Solid Tile との Collision を処理できます。
self:collide(dx, dy)および：
self:move(dx, dy)solid は bit8.assets.toml の対応する Asset 登録項目内に設定する必要があります。無関係なトップレベル設定として配置しないでください。
詳しくは Collision を参照してください。
Map は登録済み Asset ID を参照します。
Map Cell には、例えば次の Tile ID を設定できます。
A1
A2
A3
これにより、1 つの Map で異なる Group の Tile を使用できます。
Map Workspace には、登録済み Tile の選択や Map Cell の描画を行うツールがあります。
詳しくは Map を参照してください。
Sprite Definition も登録済み Tile を使用します。
Sprite は Tile を参照して、次の要素を定義できます。
- 静的プレビュー
- Animation Frame
- 名前付き Animation
Sprite Definition は次のファイルに保存されます。
bit8.sprites.toml
例えば、Player という Sprite は複数の登録済み Tile を Animation Frame として使用できます。
Node Script では次のコードで Animation を制御できます。
self:play("walk")現在の Frame を描画するには：
self:spr()詳しくは Sprite と Animation を参照してください。
Asset を管理する際は、次の点に注意してください。
- サポートされている Asset 登録機能を使用して PNG Tilesheet を登録します。
- 登録済み Group ID を安定させます。
- 既存の Asset ID を手動で再割り当てしないでください。
- 登録済み Asset ファイルを変更する際は Registry も更新します。
- Asset を削除する前に、Map と Sprite の参照を確認します。
- 使用終了となった Group ID を再利用しないようにします。
Stable ID は参照関係を保護するための仕組みですが、Asset の変更後も同じグラフィックが参照されることを自動的に保証するものではありません。
例えば、登録済み PNG 内の Tile の配置を変更すると、既存の Asset ID が別の画像を指す可能性があります。
Tilesheet を使用するプロジェクトには、次のようなファイルが含まれます。
my-bit8-game/
├── main.b8
├── bit8.assets.toml
├── bit8.sprites.toml
└── assets/
├── terrain (A).png
└── characters (B).png
これは構成例です。実際の Asset パスは Asset Registry の登録情報と一致している必要があります。
次のページ：
関連ドキュメント：
Stable Asset ID により、Script、Map、Sprite は登録済み Tile を一貫して参照できます。