PAGAN

PAGAN — 像素艺术语法与符号

PAGAN 是 AI 与像素艺术之间的转换器。它定义了一种简洁的文本符号，用 YAML 编写以调色板为键的网格，AI Agent 可以流畅地编写这种符号；同时还提供一个 Python 工具，可读取相同的符号并将其转换为 PNG、精灵图集和可直接用于游戏引擎的资源。

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

状态： 尚处于早期开发阶段，但完整流程已可用：调色板、2D 精灵和图块集、以 8 个朝向渲染的 3D 体素模型，或导出为可在 3D 游戏中使用的真实网格（glTF），以及预览、lint、导入和构建到 Godot 4。请参阅 CHANGELOG.md 和 issues。

文档：安装指南、教程，以及根据代码生成的参考文档： 所有符号字段、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 参数以输出机器可读的结果，遇到错误时会以非零状态码退出。 请参阅 examples/demo/ 中的示例项目（包含调色板、药水、史莱姆、草地地块和一艘具有 8 个朝向的 3D 飞船），以及 examples/godot/ 中构建生成的 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 是一个 TileSet，其中所有图块都位于图集源 0 中；清单中的 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）；图块会按网格间距放置，不会出现间隙或重叠；墙壁和家具也会采用相同的缩放比例；沿 x/y 移动 1 个体素始终对应整数像素（横向 2 像素、纵向 1 像素，沿 z 轴向上移动 z_step 像素）。模型使用 heading: 45 和 directions: 4（帧为 ne、nw、sw、se）；其他朝向无法落在整数像素上，会被视为错误。网格不受影响。

3D 游戏：网格

对于自由 3D 摄像机，在 export 中添加 "mesh"：每个 3D 模型还会生成 models/<name>.glb（二进制 glTF： 每个部件对应一个节点，包含动画和部件元数据）以及调色板渐变纹理；添加 "godot" 后，还会生成应用了 PAGAN 调色板锁定渐变着色器的 models/<name>.tscn。使用 pagan config set mesh.voxel_size 0.0625 设置项目的纹素密度（每个体素的米数）。模型朝向 +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 技能，用于教会 Agent 完整的工作流：设置游戏的美术文件夹、 提出恰当的问题、绘制和建模、查看预览，以及随着时间推移调整整体风格。

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

然后只需提出需求：“我正在制作一款海洋探索游戏；制作玩家的船、三根桅杆和 8 个朝向。”

在任意 Agent 中使用 PAGAN（MCP）

pagan mcp 会将 PAGAN 作为 MCP 服务运行，因此任何 MCP 客户端（Claude Desktop、Claude Code、Cursor 或你自己的 Agent）都能为一个项目制作、检查、预览和构建美术资源。工具 会返回与 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 注册表，名称为 io.github.lukasgolino/pagan。

添加 --allow-godot，即可让构建工具在无头 Godot 中验证输出。然后提出需求：“制作一个 16x16 的生命药水”、“给僵尸添加攻击动画”、“让整个游戏稍微暗一点”。

许可证

Apache 2.0 — 参见 LICENSE。