claude-pxl README

项目的 README,来自 github.com/crsolver/claude-pxl。合并为一个 markdown 文件:README.md。

pxl

Pixel art as code. Write a compact .px.js file; get PNGs, sprite sheets with JSON, animated GIFs, and a live browser viewer that replays the painting step by step as you save.

Built for AI agents (it ships as a ready-made agent skill) and pleasant for people too. No runtime dependencies, no build step: just Node ≥ 22.18.

Animated witch's cottage at night: bubbling cauldron, fireplace, cat and frog

Comet Repair shop scene Gull & Gill bait shop scene Moon Buns bakery scene Neon noodle bar scene

Animated glowing cave Animated cat Animated frog Animated clock

Every image above is generated from a file in examples/.

Quick start

git clone https://github.com/crsolver/claude-pxl.git
cd claude-pxl
node bin/pxl.js serve examples/shop.px.js     # live viewer at http://127.0.0.1:4321/

Or run it without cloning:

npx github:crsolver/claude-pxl build art.px.js

Write art.px.js:

pal({ k: "#1b1630", g: "#8ccf63", G: "#4c8a44", w: "#fff6e0", r: "#e2585e", R: "#a63a4c" })

// Write the left half; mirror it and outline it automatically.
sprite("slime", { mx: true, outline: "k" }, `
  ....ggg
  ..ggGGg
  .ggGwGg
  gggkwgg
  GGGGGGG`)
sprite("slime_red", { base: "slime", swap: { g: "r", G: "R" } })   // a recolor in one line

sheet("chars", ["slime*"], { pad: 1 })
node bin/pxl.js build art.px.js
out/sprites/slime.png  out/sprites/slime_red.png      the art, at 1x
out/chars.png          out/chars.json                 sprite sheet + TexturePacker-style JSON
out/_preview/*.png                                    upscaled previews with a pixel grid

The live viewer

pxl serve art.px.js opens a viewer that rebuilds on every save and replays the asset you edited op by op, so you (or whoever is watching an agent work) can see the art being painted. It also writes the same out/ files as build.

Commands

pxl build <art.px.js> [--out DIR] [--only a,b] [--scale N] [--no-preview]
pxl serve <art.px.js> [--port 4321] [--out DIR | --no-out] [--no-preview]
pxl ascii <art.px.js> <name>     print an asset as palette keys with x/y rulers
pxl list  <art.px.js>            list assets, groups and sheets with source locations

pxl means node bin/pxl.js in a clone, or npx github:crsolver/claude-pxl. Art files can be .js or .ts (types/pxl.d.ts gives editor completion).

What's in the DSL

Full API: reference.md. Agent workflow and essentials: SKILL.md.

Use it with an AI agent

This repository is an agent skill: SKILL.md teaches the workflow (write → build → look at the preview → patch), reference.md holds the full API, and lighting.md is loaded only when needed.

Claude Code: clone it into your skills folder, then ask Claude to draw something.

# all projects
git clone https://github.com/crsolver/claude-pxl.git ~/.claude/skills/pxl-pixel-art
# or just one project
git clone https://github.com/crsolver/claude-pxl.git .claude/skills/pxl-pixel-art

Other agents (Codex, Cursor, …): point them at SKILL.md and tell them the CLI is node <path to pxl>/bin/pxl.js.

Tip: ask the agent to start pxl serve so you can watch it paint in your browser.

Development

npm install        # dev only: typescript, @types/node
npm run check      # type check + tests
node scripts/gallery.ts   # regenerate docs/gallery
src/core/     engine, no Node APIs: image, palette + ramps, canvas ops, build, trace, project
src/node/     vm sandbox loader, PNG/GIF encoders, outputs, CLI, live server
src/viewer/   browser viewer (served type-stripped; no bundler)
types/        pxl.d.ts globals for editor support in .px.ts files
scripts/      build.js (dist/ for npm installs), gallery.ts
examples/     example art files
test/         node:test suites

In a clone the CLI runs the TypeScript sources directly. When installed as a package it runs dist/, which npm install / npm pack generate via scripts/build.js (Node won't strip types inside node_modules).

License

MIT

claude-pxl (crsolver/claude-pxl)

正在搜索数据库…

这是什么?pxl 让你用代码编写像素画:一个紧凑的 .px.js 文件可以编译成 PNG、带 JSON 的精灵图(sprite sheet)、动画 GIF,以及一个实时浏览器查看器,可以逐步回放绘制过程。
这是一个库还是命令行工具?它是一个命令行工具,围绕用于描述像素画的 JS/TS DSL 构建;同一个仓库还可以直接作为现成的智能体技能(SKILL.md)用于 AI 编程智能体。
我该如何让它运行起来?无需克隆,直接通过 `npx github:crsolver/claude-pxl` 运行;或克隆仓库后运行 `node bin/pxl.js`;编写一个 art.px.js 文件,然后使用 `pxl serve art.px.js` 查看实时查看器。
除了安装 Node,还需要别的东西吗?不需要,pxl 没有运行时依赖,也没有构建步骤,只需 Node 22.18 或更高版本。
作为包安装与克隆使用相比,有什么需要注意的地方吗?在克隆的仓库中,CLI 直接运行 TypeScript 源码;作为包安装后,它运行编译生成的 dist/ 目录,该目录由 npm install 或 npm pack 通过 scripts/build.js 生成,因为 Node 无法在 node_modules 中剥离类型。
哪些编程智能体可以把它当作技能使用?Claude Code 可以通过将其克隆到 skills 文件夹中来加载;其他智能体(如 Codex 或 Cursor)可以指向 SKILL.md,并告诉它 CLI 为 `node bin/pxl.js`。
.px.js DSL 实际能画什么?它支持调色板和色阶、带镜像、自动描边、调色板替换以及翻转和旋转功能的精灵图;基本图形如矩形、直线、圆形、多边形,渐变、抖动、噪点、内置像素字体、散点画笔和瓦片地图,带阴影和光源的分层场景,以及基于帧的动画,可导出为条带图、JSON 标签和 GIF。
实时查看器到底显示什么?运行 `pxl serve art.px.js` 会打开一个浏览器查看器,每次保存都会重新构建,并逐个操作回放被编辑的素材,因此你可以逐步观看像素画(或 AI 智能体)的绘制过程。
SKILL.md 是做什么用的?SKILL.md 教 AI 智能体 pxl 的“编写-构建-预览-修补”工作流程;reference.md 记录完整的 API,lighting.md 介绍可选的光照功能,仅在需要时加载。
我可以用 TypeScript 编写像素画文件吗?可以,像素画文件可以是 .js 或 .ts;types/pxl.d.ts 为 DSL 提供编辑器自动补全。
作者
crsolver
大小
2.9 MB
星标
690
更新
提交Oct 15
时长
1个月
提交 · 90 天