Skip to content
Back to search

pxl-pixel-art

SkillWorks with Claude CodeGitHub

Create pixel art (game sprites, characters, items, tiles, tilesets, icons, scenes, sprite sheets) with pxl, a compact JavaScript DSL that renders PNGs and lets the user watch the painting live in a browser. Use when asked to draw, design or iterate on pixel art or game assets.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/crsolver--claude-pxl/badge.svg)](/listings/crsolver--claude-pxl)

HTML

<a href="/listings/crsolver--claude-pxl"><img src="/api/listings/crsolver--claude-pxl/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 105 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: pxl-pixel-art
  3. description: Create pixel art (game sprites, characters, items, tiles, tilesets, icons, scenes, sprite sheets) with pxl, a compact JavaScript DSL that renders PNGs and lets the user watch the painting live in a browser. Use when asked to draw, design or iterate on pixel art or game assets.
  4. ---
  5. # pxl: pixel art as code
  6. You write a small `.px.js` file; pxl renders PNGs and upscaled previews you can look at. The DSL
  7. is built to avoid writing pixels twice: mirroring, auto-outline, palette-swap variants, reusable
  8. parts, primitives, brushes and tilemaps. Needs Node ≥ 22.18. No install step.
  9. `PXL` below means `node <this skill's directory>/bin/pxl.js`.
  10. ## Workflow
  11. 1. Write `art.px.js` (start from the template below; examples in `examples/`).
  12. 2. Build only what you're working on: `PXL build art.px.js --only slime,heart`
  13. 3. **Look at it**: read `out/_preview/<name>.png` (upscaled, checkerboard = transparent, grid every
  14. pixel, darker every 8). For exact pixel fixes use `PXL ascii art.px.js <name>` (keys + x/y rulers);
  15. it's cheaper than an image.
  16. 4. Fix with small edits (a `grid(x, y, ...)` patch, one op) and rebuild. Repeat.
  17. 5. If the user wants to watch: start `PXL serve art.px.js` in the background and give them the URL.
  18. It rebuilds on every save and replays the edited asset's painting steps; it also writes the same
  19. `out/` files, so keep reading previews as usual.
  20. Errors name the file:line:col, the asset/layer/op path, and suggest fixes ("did you mean 'r'?").
  21. One broken asset doesn't stop the others from building.
  22. ## Template
  23. ```js
  24. pal({ k: "#1b1630", g: "#8ccf63", G: "#4c8a44", t: "#2a5560", w: "#fff6e0", r: "#e2585e", R: "#a63a4c" })
  25. ramps("ktGg", "kRr") // dark -> light, drives shade()/light()
  26. // Symmetric: write the left half, mirror it, outline it.
  27. sprite("slime", { mx: true, outline: "k" }, `
  28. ....ggg
  29. ..ggGGg
  30. .ggGwGg
  31. gggkwgg
  32. gggkkgg
  33. tgggggg
  34. .tttttt`)
  35. sprite("slime_red", { base: "slime", swap: { g: "r", G: "R" } }) // variant: 1 line
  36. sprite("_eye", "wk\nkk") // "_" = part, not exported
  37. sprite("chest", { w: 16, h: 12, outline: "k" },
  38. rect(0, 3, 16, 9, "R"), rect(0, 0, 16, 4, "r"), stamp("_eye", 7, 4), shade([0, 9, 16, 3]))
  39. scene("meadow", { w: 160, h: 96, bg: "w" },
  40. layer("ground", { y: 64 }, rect(0, 0, 160, 32, "G"), noise(0, 0, 160, 32, "g", 0.1, 3)),
  41. layer("props", stamp("slime", 40, 54), stamp("slime_red", 70, 54, { flip: "x" })),
  42. layer("shadow", { shade: true }, poly([38, 64, 88, 64, 92, 67, 34, 67], "k"))) // cast shadow
  43. sheet("chars", ["slime*", "chest"], { pad: 1 })
  44. ```
  45. ## Essentials
  46. - **Colors**: one-char keys from `pal`, `"#hex"`, `"."` skip, `"_"` erase. Default palette is pico8
  47. (`0-f`); `use("sweetie16" | "db16" | "endesga32" | "gray8")` for others.
  48. - **Items run in order**: grid strings (drawn at 0,0), ops, `(c) => { c.rect(...) }` functions,
  49. `layer(...)`s. Then mirror → swap → flip → rot → outline (grows 1px each side) → crop.
  50. - **Shapes**: `px rect box line(…, width) hline vline circ ring ellipse poly fill wire text`.
  51. - **Tone**: `dither grad noise`, `shade/light(region, steps, density)`, `recolor`, and
  52. `shade:`/`light:` layers for cast shadows and glows. Regions: `[cx,cy,r]`, `[x,y,w,h]`,
  53. polygon, or a function. `clip(region, ...items)` restricts any items (half shapes, slopes).
  54. - **Reuse**: `stamp tile pattern tilemap scatter`. Names can be groups or globs
  55. (`group("rocks", ["rock_a", "rock_a", "rock_b"])`, `"tree_*"`). Each placement picks randomly but
  56. reproducibly. Use `rflip`, `rswap`, `seed`, and `reseed: true` for per-copy variety.
  57. - **Brushes**: `scatter("_leaf*", x, y, w, h, 30, { on: "g", clip: true, rflip: "xy" })` paints
  58. texture with tiny part sprites, only on the given colors.
  59. - **Animation**: `anim("cat", { outline: "k", fps: 10 }, grid, frame(), frame(grid(23, 0, "_K")))`:
  60. frames are patches over shared items or a `base`; or `frames: 6` + `(c) => ... c.phase ...` for
  61. procedural loops. Stamping an anim animates the scene (`rdelay: true` desyncs copies, `frame: n`
  62. freezes one). Check `_preview/<name>.png` (all frames side by side) or `pxl ascii` per frame.
  63. - **Glow**: `glow("zgQ", { r: 6, strength: 0.5 })` directly in a sprite/scene body gives every pixel
  64. of those keys a halo (flames, potions, moons, neon); `ramp: 2` instead stays in the palette.
  65. Give glowing things their own keys so nothing else lights up, or limit it with `where`.
  66. Full API with every option: [reference.md](reference.md).
  67. Dynamic lighting (lamps, light blocked by solid layers, sky light, Terraria-style): read
  68. [lighting.md](lighting.md) only when a scene needs lights.
  69. ## Habits that save tokens and give better art
  70. - Write half of anything symmetric (`mx`) and let `outline` draw outlines. Never hand-draw either.
  71. - Recolors are `base` + `swap`; repeated details are `_parts` + `stamp`; families are a `group` or a
  72. loop: `for (let i = 1; i <= 3; i++) sprite("tree_" + i, ...)`.
  73. - Large areas: primitives, `grad`, `noise`, `pattern`, `tilemap`. Never big hand grids.
  74. - Organic texture (leaves, grass, stones, rust): 2–3 tiny brush parts + `scatter` with `on`/`clip`.
  75. - **No filler noise.** Don't sprinkle `noise` speckle over walls, floors or plaster to make them
  76. "less flat": it reads as random dots, not material. Every mark on a surface needs a cause you
  77. could name, and it should sit where that cause would put it:
  78. - built structure: siding/plank lines, brick or stone courses with offset joints, tile seams;
  79. - weathering: rain-stain streaks under ledges and sills, splash-back grime fading up from the
  80. ground, rust runs under metal brackets, paint flaking off boards (following the board lines);
  81. - clutter that tells the story: posters, pipes, vents, cracks from a corner.
  82. Flat color is fine; a clean wall beats a dotted one. `noise` is OK only where the material itself
  83. is granular (gravel, sand, asphalt, tar roofs, rough stone), and keep it sparse. On faces drawn
  84. at an angle (3/4 views), make the marks follow the face's slant.
  85. - Lighting: define `ramps`, then `light`/`shade` regions; stack a `density: 0.5` pass for soft edges.
  86. Use `shade: true` layers with a `poly` for cast shadows across many objects.
  87. - Use mnemonic keys (`g`/`G` light/dark green). Keep 2–4 shades per material for a clean pixel-art look.
  88. - Build with `--only` while iterating; a full build also writes every preview.
README.md · README · 144 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # pxl
  2. **Pixel art as code.** Write a compact `.px.js` file; get PNGs, sprite sheets with JSON, animated
  3. GIFs, and a live browser viewer that replays the painting step by step as you save.
  4. Built for AI agents (it ships as a ready-made [agent skill](#use-it-with-an-ai-agent)) and pleasant
  5. for people too. No runtime dependencies, no build step: just Node ≥ 22.18.
  6. <p>
  7. <img src="docs/gallery/no_magic_night.gif" width="100%" alt="Animated witch's cottage at night: bubbling cauldron, fireplace, cat and frog">
  8. </p>
  9. <p>
  10. <img src="docs/gallery/comet_repair.png" width="49%" alt="Comet Repair shop scene">
  11. <img src="docs/gallery/gull_and_gill.png" width="49%" alt="Gull &amp; Gill bait shop scene">
  12. <img src="docs/gallery/moon_buns_3d.png" width="49%" alt="Moon Buns bakery scene">
  13. <img src="docs/gallery/neon_noodle_3d.png" width="49%" alt="Neon noodle bar scene">
  14. </p>
  15. <p>
  16. <img src="docs/gallery/cave.gif" width="49%" alt="Animated glowing cave">
  17. <img src="docs/gallery/cat.gif" height="96" alt="Animated cat">
  18. <img src="docs/gallery/frog.gif" height="96" alt="Animated frog">
  19. <img src="docs/gallery/clock.gif" height="128" alt="Animated clock">
  20. </p>
  21. Every image above is generated from a file in [`examples/`](examples).
  22. ## Quick start
  23. ```sh
  24. git clone https://github.com/crsolver/claude-pxl.git
  25. cd claude-pxl
  26. node bin/pxl.js serve examples/shop.px.js # live viewer at http://127.0.0.1:4321/
  27. ```
  28. Or run it without cloning:
  29. ```sh
  30. npx github:crsolver/claude-pxl build art.px.js
  31. ```
  32. Write `art.px.js`:
  33. ```js
  34. pal({ k: "#1b1630", g: "#8ccf63", G: "#4c8a44", w: "#fff6e0", r: "#e2585e", R: "#a63a4c" })
  35. // Write the left half; mirror it and outline it automatically.
  36. sprite("slime", { mx: true, outline: "k" }, `
  37. ....ggg
  38. ..ggGGg
  39. .ggGwGg
  40. gggkwgg
  41. GGGGGGG`)
  42. sprite("slime_red", { base: "slime", swap: { g: "r", G: "R" } }) // a recolor in one line
  43. sheet("chars", ["slime*"], { pad: 1 })
  44. ```
  45. ```sh
  46. node bin/pxl.js build art.px.js
  47. ```
  48. ```
  49. out/sprites/slime.png out/sprites/slime_red.png the art, at 1x
  50. out/chars.png out/chars.json sprite sheet + TexturePacker-style JSON
  51. out/_preview/*.png upscaled previews with a pixel grid
  52. ```
  53. ## The live viewer
  54. `pxl serve art.px.js` opens a viewer that rebuilds on every save and replays the asset you edited
  55. op by op, so you (or whoever is watching an agent work) can see the art being painted. It also
  56. writes the same `out/` files as `build`.
  57. ## Commands
  58. ```
  59. pxl build <art.px.js> [--out DIR] [--only a,b] [--scale N] [--no-preview]
  60. pxl serve <art.px.js> [--port 4321] [--out DIR | --no-out] [--no-preview]
  61. pxl ascii <art.px.js> <name> print an asset as palette keys with x/y rulers
  62. pxl list <art.px.js> list assets, groups and sheets with source locations
  63. ```
  64. `pxl` means `node bin/pxl.js` in a clone, or `npx github:crsolver/claude-pxl`. Art files can be `.js` or
  65. `.ts` (`types/pxl.d.ts` gives editor completion).
  66. ## What's in the DSL
  67. - **Palettes and ramps**: one-character color keys, built-in palettes (pico8, sweetie16, endesga32…),
  68. dark→light ramps that drive `shade()` / `light()`.
  69. - **Sprites**: text grids, mirroring, auto-outline, palette-swap variants, flips/rotations, reusable
  70. `_parts`, `stamp`.
  71. - **Primitives and brushes**: rects, lines, circles, polygons, gradients, dithering, noise, a built-in
  72. pixel font, `scatter` brushes, tilemaps, random groups with reproducible seeds.
  73. - **Scenes**: layers, cast-shadow and light layers, per-layer PNG export.
  74. - **Animation**: frames as patches over a base sprite → strips + JSON tags + GIF.
  75. - **Lighting** (optional): lamps, glow, normal-based relief (see [`lighting.md`](lighting.md)).
  76. - **Errors** point at `file:line:col` and the asset/layer/op path, with "did you mean…" hints.
  77. Full API: [`reference.md`](reference.md). Agent workflow and essentials: [`SKILL.md`](SKILL.md).
  78. ## Use it with an AI agent
  79. This repository is an agent skill: `SKILL.md` teaches the workflow (write → build → look at the
  80. preview → patch), `reference.md` holds the full API, and `lighting.md` is loaded only when needed.
  81. **Claude Code**: clone it into your skills folder, then ask Claude to draw something.
  82. ```sh
  83. # all projects
  84. git clone https://github.com/crsolver/claude-pxl.git ~/.claude/skills/pxl-pixel-art
  85. # or just one project
  86. git clone https://github.com/crsolver/claude-pxl.git .claude/skills/pxl-pixel-art
  87. ```
  88. **Other agents** (Codex, Cursor, …): point them at `SKILL.md` and tell them the CLI is
  89. `node <path to pxl>/bin/pxl.js`.
  90. Tip: ask the agent to start `pxl serve` so you can watch it paint in your browser.
  91. ## Development
  92. ```sh
  93. npm install # dev only: typescript, @types/node
  94. npm run check # type check + tests
  95. node scripts/gallery.ts # regenerate docs/gallery
  96. ```
  97. ```
  98. src/core/ engine, no Node APIs: image, palette + ramps, canvas ops, build, trace, project
  99. src/node/ vm sandbox loader, PNG/GIF encoders, outputs, CLI, live server
  100. src/viewer/ browser viewer (served type-stripped; no bundler)
  101. types/ pxl.d.ts globals for editor support in .px.ts files
  102. scripts/ build.js (dist/ for npm installs), gallery.ts
  103. examples/ example art files
  104. test/ node:test suites
  105. ```
  106. In a clone the CLI runs the TypeScript sources directly. When installed as a package it runs
  107. `dist/`, which `npm install` / `npm pack` generate via `scripts/build.js` (Node won't strip types
  108. inside `node_modules`).
  109. ## License
  110. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.