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, анимированные GIF и живой браузерный просмотрщик, который воспроизводит процесс рисования шаг за шагом.
Это библиотека или CLI-инструмент?Это инструмент командной строки, построенный на предметно-ориентированном языке (DSL) на JS/TS для описания пиксельной графики, а в том же репозитории есть готовый навык для агентов (SKILL.md) для ИИ-агентов в программировании.
Как это запустить?Запустите без клонирования командой `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`.
Что на самом деле может нарисовать DSL .px.js?Он поддерживает палитры и цветовые переходы, спрайты с отражением, автоматическим контуром, заменой палитры, а также отзеркаливанием и поворотами; примитивы — прямоугольники, линии, окружности, многоугольники, градиенты, дизеринг, шум, встроенный пиксельный шрифт, кисти-рассыпухи и тайлмапы; многослойные сцены с тенями и источниками света, а также покадровую анимацию, экспортируемую в виде лент, JSON-тегов и GIF.
Что именно показывает живой просмотрщик?Команда `pxl serve art.px.js` открывает браузерный просмотрщик, который пересобирается при каждом сохранении и воспроизводит изменённый ресурс операция за операцией, так что можно наблюдать, как рисуется картинка (или как её рисует ИИ-агент), шаг за шагом.
Для чего нужен SKILL.md?SKILL.md обучает ИИ-агента рабочему процессу pxl: написать, собрать, посмотреть и исправить; reference.md описывает полный API, а lighting.md рассказывает о необязательных возможностях освещения и загружается только при необходимости.
Можно ли писать файлы с графикой на TypeScript?Да, файлы с графикой могут быть .js или .ts, а types/pxl.d.ts обеспечивает автодополнение в редакторе для DSL.
Автор
crsolver
Размер
2.9 MB
Звёзды
690
Обновлён
КоммитOct 15
Возраст
1 мес
Коммиты · 90 дней