PAGAN

PAGAN — Pixel Art Grammar And Notation

PAGAN は、AI とピクセルアートをつなぐトランスレーターです。AI エージェントが流暢に記述できる、パレットキー付きグリッドを YAML で記述する小さなテキスト記法と、同じ記法を読み込んで PNG、スプライトシート、ゲームエンジンですぐに使えるアセットに変換する Python ツールを定義します。

frames:
  idle_0: |
    .....000000.....
    ....05566650....
    ...0556776650...

ステータス： 開発初期段階ですが、パイプライン全体が動作します。パレット、2D スプライトとタイルセット、8 方向からレンダリングする 3D ボクセルモデル、または 3D ゲーム用の実際のメッシュ（glTF）としてエクスポートする機能、プレビュー、lint、インポート、Godot 4 へのビルドに対応しています。CHANGELOG.md とイシューを参照してください。

ドキュメント： インストール、チュートリアル、およびコードから生成されたリファレンス：すべての記法フィールド、pagan.toml の設定、lint ルール。例を含む記法の完全版は、スキルのドキュメントトピック（pagan docs）にあります。

インストール

pip install pagan-gen      # the package is pagan-gen on PyPI; the command and the import are `pagan`
pagan --version

インストール（開発環境）

Python 3.11 以降が必要です。

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pagan --version
pytest

クイックスタート

pagan init my-art            # creates pagan.toml, STYLE.md, palettes/, sprites/, tiles/
cd my-art
pagan new palette dusk       # scaffolds palettes/dusk.pal.yaml; then set default_palette = "dusk" in pagan.toml
pagan palette show           # renders swatches to previews/palettes/*.png

pagan new sprite potion --size 16x16 --description "red health potion"   # 2D: edit the grid
pagan new model ship --size 96x96 --directions 8                          # 3D: shapes + materials
pagan lint                   # format errors + style warnings
pagan preview potion         # upscaled sheet, frames and GIFs in previews/potion/
pagan gallery                # every asset side by side
pagan build                  # sheets + manifest (+ Godot SpriteFrames) into output_dir

すべてのコマンドは、機械可読な出力を行う --json を受け付け、エラー時にはゼロ以外の終了コードを返します。 プロジェクトの例（パレット、ポーション、スライム、草原のタイル、8 方向の 3D 船）は examples/demo/ を、ビルド先の Godot プロジェクトは examples/godot/ を参照してください。Godot 4.7 で開いて Play を押してください。

ゲームでの出力の使用

pagan build は、あらゆるエンジンで使える PNG シートと manifest.json（フレームの矩形、アニメーション、ピボット、タイル座標）を書き出します。export = ["png", "godot"] を指定すると、Godot 4 のリソースも書き出します。

• スプライトと 3D モデル： <name>.tres の SpriteFrames です。Godot のリソースにはピボットを格納できないため、マニフェストのアセットの godot_offset を使ってノードに適用してください。

  $AnimatedSprite2D.sprite_frames = load("res://assets/generated/sprites/ship.tres")
  $AnimatedSprite2D.centered = true
  $AnimatedSprite2D.offset = Vector2(0.0, -12.0)   # manifest: assets.ship.godot_offset
  $AnimatedSprite2D.play("sail_ne")                 # 3D models: one animation per heading
  

• タイルセット： tiles/<name>.tres は、アトラスソース 0 にすべてのタイルを含む TileSet です。マニフェストの tiles には、各タイル名のアトラス座標が記載されています。地形、衝突判定、その他のタイルデータは Godot で設定します。

アイソメトリックタイルゲーム：ダイメトリックカメラ

2:1 のアイソメトリック TileMap（例：Godot の TileMapLayer、64x32 セル）では、正確なピクセルダイメトリックカメラを設定します。

[camera]
projection = "dimetric"   # default "orthographic" (any elevation, `scale` px per voxel)
tile = [64, 32]           # pixels per grid cell: the floor diamond
cell = 16                 # voxels per grid cell side
z_step = 0                # pixels per voxel of height; 0 = tile height / cell (2 here)

cell x cell の床は、手描きの 64x32 のひし形（行は 2、6、…、62、62、…、6、2）としてレンダリングされ、隙間や重なりなくグリッド間隔にタイルが配置されます。壁や家具も同じスケールになり、1 ボクセルの移動は常にピクセル単位で整数になります（x/y 方向にそれぞれ横 2、縦 1 ピクセル、上方向は z_step）。モデルでは heading: 45 と directions: 4（フレームは ne、nw、sw、se）を使います。それ以外の向きではピクセル単位の整数に収まらないため、エラーになります。メッシュには影響しません。

3D ゲーム：メッシュ

自由に動かせる3Dカメラを使うには、export に "mesh" を追加します。すべての3Dモデルで、models/<name>.glb（バイナリ glTF。パーツごとに1つのノード、アニメーション、パーツのメタデータを含む）とパレットランプテクスチャも生成されます。また、"godot" を指定すると、PAGANのパレットに固定されたランプシェーダーを適用した models/<name>.tscn も生成されます。プロジェクトのテクセル密度は pagan config set mesh.voxel_size 0.0625 で設定します（1ボクセルあたりのメートル数）。モデルは+Z方向を向き、+Yが上です。モデルの origin はメッシュの原点です。モデル内の rig: では、パーツのピボット、親、メタデータ（ヒットゾーン、取り外し可能なパーツ）を設定できます。

var soldier: Node3D = load("res://assets/generated/models/soldier.tscn").instantiate()  # manifest: mesh.godot_scene
add_child(soldier)
soldier.look_at(target, Vector3.UP, true)                  # true: the model's front (+Z) faces the target
soldier.get_node("AnimationPlayer").play("walk")           # looping animations loop
var helmet: Node3D = soldier.get_node("body/torso/head/helmet")   # manifest: mesh.parts.helmet.node
if helmet.get_meta("extras").get("detachable", false):    # rig meta -> node metadata "extras"
    helmet.reparent(get_tree().current_scene)              # knock it off: keeps its place in the world

DirectionalLight3D（シャドウを有効）でシーンを照らし、Linearトーンマッパーを使用します。ランプシェーダーにより、ライティングされた各ピクセルの色がパレットカラーに保たれます（Forward+およびCompatibilityレンダラーに対応。Mobileでは暗い色が数段階ずれる場合があります）。地面や壁などの大きな反復サーフェスには、タイルセットテクスチャを使用します。export_textures は、繰り返し使用できるPNGと、トライプラナー方式のGodotマテリアルを書き出します。pagan preview <model> --orbit（下からも含む、すべての角度）、--closeup <part>、--engine を使ってモデルを確認できます。examples/godot/scenes/mesh_test.tscn では、動く太陽の下でターンテーブルに載せたデモ用メッシュを確認できます。

ClaudeでPAGANを使用する

PAGANにはClaudeスキルが付属しており、ゲームのアートフォルダーの設定、適切な質問、描画やモデリング、プレビューの確認、時間をかけた見た目の調整まで、ワークフロー全体をエージェントに教えます。

pagan skill install          # copies it to <repo>/.claude/skills/pagan/

あとは、「海洋探索ゲームを作っています。プレイヤーの船を、マスト3本、8方向で作ってください」と頼むだけです。

あらゆるエージェントからPAGANを使用する（MCP）

pagan mcp はPAGANをMCPサーバーとして実行します。そのため、あらゆるMCPクライアント（Claude Desktop、Claude Code、Cursor、独自のエージェント）から、1つのプロジェクトのアートを作成、リント、プレビュー、ビルドできます。ツールはCLIの --json と同じJSONを返し、プレビューはモデルが確認できる画像として返されます。

claude mcp add pagan -- uvx pagan-gen mcp --project /path/to/art     # no install needed (uv); or `pagan mcp` after pip install

ほかのクライアントでも、設定に同じコマンドを指定します。

{ "mcpServers": { "pagan": { "command": "uvx", "args": ["pagan-gen", "mcp", "--project", "/path/to/art"] } } }

PAGANはMCP Registryに io.github.lukasgolino/pagan として登録されています。

ビルドツールでヘッドレスGodotによる出力の検証を許可するには、--allow-godot を追加します。その後、「16x16の回復薬を作ってください」「ゾンビに攻撃アニメーションを追加してください」「ゲーム全体を少し暗くしてください」と頼めます。

ライセンス

Apache 2.0 — LICENSEを参照してください。