claude-pxl README

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

pxl

Pixel art as code. You write a short .px.js file. pxl turns it into PNGs, sprite sheets with JSON, animated GIFs, Tiled maps and Aseprite files, and a live browser viewer replays the painting step by step each time you save. Sprites, animations, scenes in true perspective and 3D forms described in meters all come out as pixel art.

pxl was made for AI agents to draw with: an agent looks at its own art in one call and fixes it. It works by hand too. Three ways to use it:

This is a fork of crsolver/claude-pxl. Fork differences: what it adds, in one page.

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

Animated sunset on a sea cliff: an adventurer watches the sun go down beside a glowing tent and a campfire Animated tournament: two armored knights fight on foot in a sand arena before a cheering grandstand

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/. The long projects are under Showcases.

Contents

Install

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

--depth 1 takes the files as they are now, not every past version of the gallery's GIFs (the whole history is several times the size); git pull still updates it.

Or run it without cloning:

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

Below, pxl means node bin/pxl.js in a clone, or npx github:augusto-scarvalho/claude-pxl. Reading JPEG, WebP or video (only pxl study, pxl shot and pxl compare do) needs ffmpeg on your PATH.

A first file

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

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 writes the same out/ files as build. Art files can also be .ts: types/pxl.d.ts gives editor completion.

Getting started goes on from here: an animation, a scene, what a build writes, which command to use when, and learning from a reference.

Use it with an AI agent

This repository is an agent skill. SKILL.md teaches the agent the workflow: write the file, look with pxl shot (and read a scene as text with pxl describe), fix everything one look showed in one turn, pxl check, pxl build. The agent reads the reference and the guides a section at a time through pxl help, so it pays only for what the task needs.

For Claude Code, clone pxl into your skills folder, then ask Claude to draw something:

git clone --depth 1 https://github.com/augusto-scarvalho/claude-pxl.git ~/.claude/skills/pxl-pixel-art

git pull there updates it. If you already have a clone, make ~/.claude/skills/pxl-pixel-art a link to it instead. To be sure the skill is used, name it: "use the pxl skill to draw ...".

A change to a scene is asked for in plain words ("move the fish stall a bit left", "add a lantern beside the tea stall"). The agent finds the thing with pxl inspect (what the scene holds, by id, and where the file writes each value) and makes the change with pxl edit, which writes it there, refuses it if anything else would move, and says what changed by id: as right as an edit by hand, 16% cheaper and slower in a first measure.

The Codex CLI, Antigravity's agy and other agents install it differently: see Install the skill. Working with an agent also covers which model and effort to pick (in the model study, Opus at xhigh was the sweet spot), writing a brief, a round in stages you approve one by one, asking for an edit, what a session and a frame cost, when to draw in 3D and when by hand, one agent or a pipeline for a big scene, and reviewing the result.

Commands

pxl build <art.px.js>             PNGs, sheets + JSON, GIFs and previews in out/ (--only a,b, --share N, --aseprite)
pxl serve <art.px.js>             the live viewer: rebuilds on save and replays the painting (an HD scene's
                                  frames built as it plays them); /3d turns the exported 3D models round
pxl shot <art.px.js> <name>       one asset as a picture to look at: frames side by side (in rows when too
                                  wide), a region enlarged, values only (--grey), guide layers over it (--ref),
                                  the last commit above and the pixels that changed (--vs HEAD --diff); more
                                  names a row each, or playing side by side in one GIF (--gif, --every N for a
                                  long scene's preview); a reference GIF, WebP or video too
pxl ascii <art.px.js> <name>      an asset as palette keys with x/y rulers
pxl describe <art.px.js> <name>   a whole scene as text: what is where, what covers it, how it moves
pxl check <art.px.js>             warnings on every scene and frame; LOOK lines on hand-drawn lines; a
                                  scene's rules, expect and expect3d (--fix: a failing one fixed by one number)
pxl inspect <art.px.js> <scene>   what an edit can name in a scene, by id (--find words); --id x: its values,
                                  where the file writes each, the operations it takes
pxl edit <art.px.js> <scene> <edit>
                                  a move, recolor, flip, swap, relation or new stamp written where the value
                                  lives, refused if anything else moves, then what changed by id and the
                                  check; --dry shows it first
pxl steps <art.px.js> <name>      how it was painted; --at x,y names the line that painted that pixel
pxl list <art.px.js>              a map of the file: each definition's lines and comment
pxl lib [entry | subject]         the library: its subjects; their entries (a subject, --genre, --cell, --all), an entry's card;
                                  draft draws a 3D entry in a genre (--genre) or at a cell it lacks
pxl compare <art.px.js> <name> <ref.png | other>   silhouette rows against a reference or another asset
pxl blind <art.px.js> <name...>   facing labels checked by a reader who doesn't know them
pxl study <picture or clip>       learn from finished art or a reference, and what to use in pxl for each part
pxl help [name]                   the reference on an op or option, or a guide's section

pxl alone prints every command with all its options. Which command, when says which to reach for.

What's in the DSL

Documentation

For Read
a first sprite, an animation and a scene by hand; which command when docs/getting-started.md
running an agent: install, model and effort, briefs, a round in stages, edits by name, costs, 3D or by hand, review; tests and tools for contributors docs/agents.md
which model and effort to draw with: one scene, seventeen runs docs/model-study.md
whether the 3D layer helps agents: four comparisons, each run once an arm docs/evaluation-3d.md
whether inspect and edit make a small edit cheaper than editing the file: six edits, two arms docs/evaluation-edit.md
every op and option reference.md, or pxl help <name>
the agent's workflow, and where to read each thing SKILL.md
which example teaches what, a line each examples/README.md
the library: props, nature, characters, buildings to include, a card each, a sheet per subject lib/README.md, or pxl lib
scenes, perspective, HD-2D dioramas, parallax, shadows scenes.md
grass, trees, bushes, rocks, walls and paths as games draw them environment.md
characters, animation with parts, rigs characters.md
lamps, walls that block light, normal maps lighting.md
turning a sprite by any angle, 8 or 16 directions rotation.md
what this fork adds to the original docs/fork-differences.md
what is still open BACKLOG.md

Showcases

Long projects made with pxl by agents, most over rounds of a curator's notes, the strongest first. Each is in examples/ to read and copy. Smaller files to start from (the starter basics.px.js, tilesets) are in the list of examples; characters, props, grass, trees and rocks to include are in the library.

HD-2D dioramas: a graveyard, a harbor, a clearing

Animated HD-2D diorama in pixel art: a graveyard on a grassy hill in a pine wood, morning mist, seen from high up through a long lens; a rounded hill held up by a mossy stone wall, stone steps up its front, a flagstone path between headstones, a wooden picket fence following the hill's edge, a dead tree, boulders at the corners, pines and the dead tree swaying in the wind as dead leaves blow across; a young traveler in a green cloak comes in through the wood, climbs the steps, kneels by an old grave and lays a red rose at its foot, crosses to a grey-haired mourner and asks in a parchment dialogue box if she is all right; she turns to him and answers, and he walks back down and away; the near and far edges soft with depth of field

Animated HD-2D diorama in pixel art: a harbor on a bright afternoon, seen from high up through a long lens; a galleon moored along a wooden pier, its pale planked hull with a red band of gold ornaments, white balusters, red and white lanterns at the stern, three masts with rope ladders and sails sewn of canvas panels glowing in the sun from behind, bobbing gently; the pier on two levels with a diagonal ramp, a wooden crane with a swinging crate, crates, barrels and sacks, rowboats moored in front, gulls crossing, blue water full of sun glints blurring into bokeh, a striped awning soft in the foreground; dockhands and sailors at work, each with their own hair and clothes; a young traveler in a green cloak walks up beside a grey-haired captain in a long navy coat and asks in a parchment dialogue box if this is the ship to Port Winds; the captain turns to him and answers, and the traveler walks up the gangplank aboard

Animated HD-2D diorama in pixel art: a clearing in a pine wood at dusk, seen from high up through a long lens, long shadows across the grass; pines, a dead tree, bushes and tufts of grass swaying in one wind, out of step; a young traveler in a green cloak on a flagstone path draws his hand back as fire gathers at it, an aura of fire flickering round him, and throws a fireball that lights the ground as it flies; it passes behind a ruined stone wall, which hides it, and hits a straw scarecrow, which catches fire at the chest, the flames spreading over it and lighting the grass and the wall, a column of smoke rising, until it burns away to embers and ash; then the scarecrow comes back and the loop closes

The look of Octopath Traveler's dioramas, in examples/hd2d/: the ground built in meters with mesh() (textured boxes laid a texel to a pixel, a hill with an uneven outline), people, stones and trees standing in it as sprites, shadows from one sun, post()'s depth of field. The traveler (traveler.px.js) is a 34 px figure in 3D (rig3d()), his head modeled, baked once per view and its face painted over by hand: he walks his eight directions along a route(), kneels to lay a rose and talks in bubble() boxes. In graveyard_3d, beside the graveyard, its dead tree, a ground mist and the swinging gate are drawn in 3D inside the diorama's light (what they take after its mesh()), 0.7 s a frame. The harbor's camera was matched by measuring a screenshot of Octopath Traveler II; its crew (crew.px.js) is dressed on the traveler's skeleton. The clearing (clearing.px.js) has every shader at once: a wood swaying in one wind, a fireball cast from the traveler's hand by the spell kit, hidden by the wall on its way, a scarecrow burning away, smoke, sparks, bloom and a .cube grade.

A Japanese shrine in autumn

Animated top-down pixel art of a Japanese shrine courtyard in autumn under a low golden sun, long shadows: a vermilion torii with a black lintel at the entrance, a temple path of long granite slabs laid across it, fanning round its bend, curbs and a strip of pebbles along it, raked white gravel in lines and rings round the stone lanterns; a hall with a green copper roof, a thick shimenawa rope with white paper streamers, an offering box and a bell rope, two kitsune statues with red bibs facing each other; red and orange momiji maples, a golden ginkgo with a rope round its trunk over a carpet of yellow leaves, a cloud-pruned black pine, all swaying in gusts; a shrine maiden in a white kosode and red hakama sweeps fallen leaves along the path with a bamboo broom, walks back and bows to the hall while leaves fall again and the lanterns catch at dusk

examples/shrine/: a top-down courtyard whose props are drawn once in 3D and turned by turnaround (the torii, the hall, the lanterns, the foxes), under one sun that lights the 3D, the light rule and the shadows. The miko is a rig3d figure with a head modeled, baked per view and retouched by hand. The path is laid along a polyline by lane(); the trees come from a kit of species (nature/trees.px.js) built on one grower, each in its seasons; the Japanese ground and buildings are a kit too (nature/japan.px.js). It began as a fresh agent's dogfood made with only the skill, and was then reworked in stages.

A top-down village from the library

Animated top-down pixel art of a village's edge in the style of a 16-bit action RPG, bright and saturated: a cottage with a big red tile roof, a porch hood over its door and a stone chimney pot, a teal spruce, a round green oak and a red autumn maple, a bank of brown earth along the top, a dirt path with a lit middle, a fence, a hedge, a bed of flowers, a stump, boulders, a pier into blue water; a pot, a chest, a sign, a crate, a barrel and a lamp post; a brown-haired hero in a blue tunic walks in from the bottom, along the path past an old man who turns to watch him, up past a villager woman and the lamp post, cuts a pot with his sword so that it bursts in dust and shards, and walks out to the left; a slime hops, a dark-haired fighter idles, three hearts at the top left; the pot comes back in a puff of dust before the loop closes

examples/village.px.js: the library's demo for the action top-down genre at a 16 px grid (lib/profiles/topdown16.px.js), every piece taken from lib/. The kit was drawn by hand after measuring The Minish Cap's and A Link to the Past's maps for numbers only: the ground in regions on corner tiles, round crowns, a house that is mostly roof, a dark line round the characters only, one light and one shadow. The hero is the genre's base body, and the villagers and Reva are made from him by hero.character(); he walks a route({ px: true }) and cuts the pot.

The same village at 32 px

Animated top-down pixel art of a village by the water at a 32 px grid, bright and detailed: a cottage with a tall red tile roof, a gabled porch over an arched plank door and a stone chimney with a square flue, a teal spruce, a full green oak and a red autumn maple swaying in gusts, a patch of tall grass waving, grass in lighter and darker regions with tufts, a dirt road by corner tiles down to a shore with foam and water darkening with depth; a barrel, a crate, a lamp post, a sign, a chest, boulders, bushes and flowers; a slim brown-haired hero in a blue shirt tucked into dark trousers walks up the road from the bottom, past a blonde villager in a red dress and a bald old man in a brown robe who turns to watch him, cuts a pot with his sword so that it cracks and bursts in dust and shards, and walks out to the left behind the lamp; a green slime hops; three hearts at the top left; the pot comes back in two puffs of dust before the loop closes

examples/village32.px.js: the same genre at a 32 px grid (lib/profiles/topdown32.px.js), every piece from lib/. The hero is the genre's slim body at 48 px, painted over a body posed in 3D; the props are drafted in 3D, brought to the grid with their edges treated (shrink: { by, cover, ink }, pxl check --edges) and finished by hand, their forms measured on game models for numbers only. The trees and the tall grass sway in gusts that cross the scene by effect("sway").

Racing seen from above

Animated top-down pixel art of a short racing circuit seen from above at a steep angle: a grey asphalt loop with red and white kerbs on the four bends and a white line along the straights, a chequered start line under a gantry on the left straight with two grid slots, tyre stacks and tyre walls at the corners, cones and striped barriers, a lamp post, oaks, spruces, bushes and a rock on the grass in and around the loop, each casting its shadow; a red car and a teal car lap the circuit clockwise, turning through each bend rotation by rotation with their shadows under them: the red car leads out of the start, the teal one dives inside it into the first bend and passes on the top straight, and the red one dives inside the third bend and passes back on the bottom straight; thin dark skid marks are laid in the bends and wear away

examples/race_topdown.px.js: the library's demo for racing seen from above (lib/profiles/racing_topdown.px.js), every piece from lib/. The cars are drafted in 3D and drawn in 32 rotations at the genre's 58 degrees, each frame taking the rotation of the way it moves (car.facing); the track is laid by corner sets, its props and trees drawn by their 3D builders, each lined in its own dark tones. Two cars lap it in 4 s, slower into the bends, passing and passed back, with skid marks in the bends; the scene's expect holds them on the track, off the props and off each other.

Racing from behind

Animated pixel art in the style of a handheld kart racer, seen from just behind and above the player's kart: a red-orange open kart with a brown-haired driver in a blue tunic sits low in the middle of the screen on a flat grey asphalt track laid in perspective, white edge lines and red and white kerbs on the bends, sand runoff outside the fast ones; the camera turns with the kart through a right-hander, a tight hairpin, a left kink and a long sweep, the floor turning under it while a backdrop of clouds, blue-green hills and a line of round trees slides sideways at their own speeds; at the start a chequered gantry passes overhead with flags, lamps, a grandstand with its crowd and a billboard beside the track, and tyre walls, chevron signs, guardrails, full oaks, palms and spruces stand along it at their sizes; two teal karts race alongside, seen from behind and shrinking with distance: the player passes one off a boost strip on the start straight and the other inside the kink, and both come back past round the last sweep

examples/race_behind.px.js: the library's demo for racing from behind, Mario Kart's kind (lib/profiles/racing_behind.px.js), every piece from lib/. The track is a map drawn from above by corner sets and laid on the ground by plane(), seen through a camera behind your kart that turns with it (perspective({ yaw })), the backdrop's layers sliding at their own speeds. The kart and its driver are drafted in 3D and painted in 48 headings; your kart steers a step at a time, and each rival takes the drawing of its heading against the line of sight at the size its distance gives (kart.rival(), the smallest by hand). One lap in 8.4 s, two passes and two passes back; what stands along the track is drawn at a ladder of sizes for its distance.

A platformer from the library

Animated side-scrolling pixel art of a 16-bit platformer level, the camera following the hero from day to night: a brown-haired hero in a blue tunic runs up a grassy slope, climbs a ladder with his back to us, crosses wooden planks, drops onto a crate, jumps a spike pit through an arc of coins, dashes and jumps over a pool past a beetle, and speeds up into a sprint to a cliff; the sky turns to dusk as he drops into a village of timbered houses, hops onto a barrel, a stack of barrels and a hay cart, passes a well and an inn's sign, the town's roofs and a church spire scrolling by behind; night falls with the moon and stars as he reaches a castle, bats flitting round the towers and gargoyles on the walls, sprints through the gate into the courtyard, climbs its steps to the keep, where the door opens, he turns his back and goes into the dark, the door closes and the camera rises to the moon

examples/nightfall/: the library's demo for the platformer genre at a 16 px grid (lib/profiles/platformer16.px.js), every piece taken from lib/. A level 4.3 screens long seen through a camera that follows the hero: obstacles by day, a village at dusk, a castle at night, ending at the keep's door. His way is a route({ px: "side" }) of runs, a run that speeds up into a sprint with its soles planted, dashes, jumps by the genre's gravity onto the props' tops (their sockets()) and a ladder climb. The light changes along the level by a palette swap per layer mixed by the camera's x, and the backdrop's planes are places that scroll in, never copies.

A fighting game's stages from the library

Animated pixel art of a 2D fighting game's round about to start, on three Shinto shrine stages in turn, the camera panning from each stage's left end to its right end and back so its planes slide at their own speeds: at dusk in autumn, a paved approach under a vermilion torii with the sun setting between its posts, red, orange and gold maples and stone lanterns with flickering flames in a moss bed behind a stone curb, violet mountain ranges, a maple leaf falling; at noon in spring, a hall with a green copper roof between two stone foxes, cherries in bloom in stone planters dropping petals, white gravel, cedar hills and a blue range, clouds drifting; at night in snow, a torii and lanterns sunk in the snow, black pines in tree wells, a moonlit snowy massif with mist at its foot, snow falling; on each, a slim woman fighter in a white top and blue trousers and a huge bald smith in a leather apron in their fighting stances, a shadow under each, a shrine maiden in white and red watching from the back, the life bars, names and timer of a lacquer or a paper HUD on top

examples/fighting/: the library's three shrine stages for the fighting genre (lib/stages/shrine.px.js, on lib/profiles/fighting.px.js's 320×224 screen), drawn as an engine draws a stage from its layout: each layer a sprite as wide as its parallax shows it, the floor going by row (parallax: { top, bottom, rows }: 0.75 at its back, 1 at the fighters' line), what stands on it at its row's speed, the far ranges by terrain(), the kit's torii, hall, lanterns, foxes and trees drawn in 3D through the fighting camera and planted on their drawn foot (turnaround(..., { pivot: "foot" })). The stage's loops play (flames, a falling leaf, clouds, petals, snow, mist), Reva and Haldor idle where a round starts, the miko watches in the stage's palette slot, and the HUD is the library's.

Animated pixel art of a 2D fighting game's round on a Shinto shrine's approach at dusk, under a vermilion torii, maples and stone lanterns: a slim woman fighter in a red top and blue trousers against a huge bald smith in a leather apron. Both wait in their guards as the gold lettering ROUND 1 opens in the middle of the screen and fades, and FIGHT! flashes in; they walk in; her jab and her low kick are blocked high and low with cold sparks; his hammer blow folds her and she slides back; she walks back in and her front kick hits his belly; she throws a golden wave of energy that hits him; he jumps over a second wave and kicks her head; he grabs her, turns her over and slams her on her back in a cloud of dust as the screen shakes, and she gets up; she jumps in with a kick to his head and, landing, steps back and punches his body; she jumps over him and lands behind, both turn to face each other; her roundhouse kick hits his head as he crouches; she crosses him again, both turn crouching, and she steps back and sweeps him; he catches her in the air as she jumps in and plunges her to the floor; at the end he jumps at her and her rising spinning kick meets him in the air, the game slows down, a gold K.O. flashes up over his fall, and he lies still while she steps in and, as her round marker lights, throws one fist up over her head, holding the pose to the end, both in view. The camera follows them, each has a shadow, a shrine maiden at the back throws her arms up on each fall, and the life bars fall, the timer counts down and a round marker lights

examples/fighting/round.px.js: the round itself, played by an engine in the file from the fighters' frame data, as lib/profiles/fighting.px.js says an engine reads it: timeline() gives each frame's ticks, drawn box, hit and hurt boxes and data, and a choreography runs once at 60 ticks a second, each move asked waiting until its fighter is free. Steps and turns, the bodies pushed apart, hits once a move with their hitstop, shake, pushback and reaction, blocks high and low, a throw and an anti-air grab binding her between his arms, the wave, sparks, dust and the screen's shake; the camera following the two by the games' tension (after the KO, both as drawn), the bars and their lag, the timer, the announcer's calls (the HUD's ROUND 1 and FIGHT! before control, K.O. on the knockout, timed by the HUD's layout), the KO slowed, the winner's pose (win) as her marker lights. Its rules are checked every tick (no bodies overlapping, both on the screen, no move ending with a back to the other, life falling only on a hit, no hit on the floor landing deeper than the reach table's 20 px), and the scene draws a picture every 2 ticks from what it kept.

3D as code: fields, voxels, volumes, splats, decals

Animated pixel-art scene seen from high up through a long lens: on a grassy ground, an oak in full leaf sways in the wind, its crown made of leaf clusters lit on top; a red mushroom house with cream spots, a hand-drawn wooden door, a round window and a small sign, smoke rising from its chimney and drifting in the wind; a mossy boulder in front of it; a pale ground mist lying behind; a little snow spirit in a red scarf turns its head from side to side, its hand-drawn face changing from the front to three quarters, and blinks

Everything here is described in meters, in code, and drawn as pixel art by pxl itself, on the CPU (examples/sdf/): the forms are distance fields drawn by surface(), the mist and the smoke densities ray-marched by volume(), the leaves and moss details scattered on the forms, the door, the sign and the spirit's face hand-drawn decals pinned on them. The scene is data (world3d): "a denser canopy, twistier branches, wind from the left" is an edit that leaves the house and the rock byte for byte as they were, and its rules are checked by pxl check. The same fields go out as voxel models, meshes and splats (.vox, .obj, .glb, .ply), or as a game's sprites turned to each heading by turnaround (turnaround.px.js).

A spell kit: elements, tiers, variants, views

Animated sheet in pixel art of ten spells at their strongest tier, each in a small dusk scene where a young traveler in a green cloak gathers energy at his hand and casts at a standing stone: above, ice: spikes bursting from the ground, an iceberg of flat faceted ice rising out of the ground, cracking and shattering into shards, a block of glacier falling with a slow turn onto the stone and breaking, a blizzard of shards driven slantwise, a ring of frost running out along the ground with crystals springing up; below, earth: rock spikes, a tall stone spire thrusting up and crumbling, a mossy boulder falling, cracking the ground and breaking up, a quake whose fissures run out while rocks thrust up along them, a slide of rocks coming down one after another

A whole cast in one call, spell("ice", 3, { from: "hero.hand", to, variant: "iceberg" }) (spells.px.js, spell_variants.px.js): nine elements at three tiers, variants with a form (an iceberg, a falling boulder, a quake, a meteor), seen from the side, from above, in iso or through a camera, in a diorama's depth.

A cyberpunk street at dusk, made two ways

Animated pixel-art cyberpunk street at dusk in dusty yellow haze, made by one agent: a sun-bleached megacity of brutalist blocks and glass towers behind an elevated freeway with its own traffic, a taco stand, a liquor store, a parking lot with fan palms, a clinic under a cyberware billboard, a red hotel with a fire escape and neon signs, power lines and a wooden pole, cars along four lanes and people walking the sidewalk

The same brief made by a pipeline of agents: a denser cyberpunk street at dusk, teal shade and sodium lamps, apartment blocks and shops with neon signs (FIX, TACO, OPEN, WASH, DOC), a billboard, a teal hologram bust, an elevated freeway, palms and power lines, cars and a bus in the street and a crowd walking the near sidewalk

One brief, a 320×180 street, made twice from the skill alone (examples/cyberpunk/). On top, one agent: 85 turns in 31 minutes. Below, a pipeline (a planner, eight forks drawing parts at once, a last fork assembling): denser but less coherent, for about five times the tokens and twice the time.

Knights built skeleton first, at a tournament

Animated tournament in pixel art: two trumpeters sound a fanfare, the marshal, an old herald with a white beard, drops his white baton, and two armored knights, blue and red, fight on foot in a sand arena: two exchanges mirror to mirror with sparks where the blades meet, a slash from above taken on the shield each way, a last clash that throws both back in a cloud of dust, a salute, and the walk back to their marks; behind them a palisade, a grandstand under a striped canopy with a cheering crowd and heraldic banners, two trumpeters, striped pavilions with pennants and a castle on a hill

A 72 px knight built as characters.md §11 describes (examples/rig/): a rig() of slots with stand-ins, parts drawn from plates lit on their own, ordered by the way he faces and turned with turn; each pose of the 96-frame bout set by IK, the sparks, dust and fanfare on one clock.

True perspective

Animated pixel-art road across the Brazilian sertão at sunset in one-point perspective: cracked asphalt with dashes and edge lines running to the horizon, mandacaru and xique-xique cacti, leafless catingueira shrubs, juazeiro trees, boulders and dry grass, a crooked barbed-wire fence, power poles and a windmill, a chapada on the horizon and the sun going down into a pass with vultures circling; a backlit walker in a leather hat with a pack and bedroll walks away down the road, getting smaller step by step until they dissolve into the light, their long shadow walking with them

Animated pixel-art park at two in the afternoon in two-point perspective: two paths crossing in the middle, hedges, benches and lamp posts running to two vanishing points, pastel apartment blocks beyond with their windows doing the same; a playground with swings, a slide, a climbing frame and a seesaw, a yellow ipê in bloom, an ice-cream cart under a striped umbrella; two children playing tag come out from behind a hedge, turn at the crossing and run off behind the cart, a woman in a straw hat walks her caramel dog away up the other path until a hedge hides them, a girl swings, pigeons peck by a chalk hopscotch

Animated pixel-art end of the Cretaceous in three-point perspective, seen from low down looking up: a huge volcano erupting, a fountain of lava from its crater and rivers of lava down its gullies, its ash column bent over by the wind; a soot-dark sky with the four o'clock sun breaking through, the glow of the big meteor's strike behind the mountain and smaller meteors still falling; burning araucarias whose trunks lean in toward a vanishing point above the picture; a tyrannosaur and a herd of gallimimus running left in front of a burning fire front, pterosaurs fleeing overhead, embers and ash blowing on the wind

Scenes laid out in meters through a camera (examples/perspective/): the road in one point, the walker shrinking into sprites drawn by hand for the small sizes; the park in two, solid shapes cast by one sun; the extinction in three, a volcano by terrain() and everything burning by flame().

Parallax and a cockpit

Animated pixel-art steam train crossing the hills of Minas Gerais on a misty morning, seen from beside the line: a black maria-fumaça after the Oeste de Minas engines, with a tall stack, two domes and a bell, red wheels and polished rods, a gray-haired driver at the cab window and a fireman feeding the firebox, a tender of firewood with a big white 41, and a varnished wooden coach with people leaning on the window sills, a child waving, a conductor on the platform; its smoke streams back over the coach. Behind it the land runs past at six speeds: a blue stone ridge on the horizon barely moving, hills with araucárias and mist in the valleys, pasture in patches of drier and greener grass with cattle trails along the slopes, woods in the folds, coffee rows, cows and a white farmhouse, then telegraph poles, a bamboo clump, banana plants and an ipê-roxo in bloom along the embankment, and the grass in front a blur of blades and flowers.

Animated street race at sunset on a coastal highway, seen from the driver's seat of a nineties sports coupe: the road bending to its vanishing point, the sea and the setting sun on the left, mountain ranges paling with distance, Atlantic forest, palms and lamp posts on the right; three rival cars overtaken one after another, drawn in perspective as they draw level; the 3D-modelled dash, gauges and mirrors, gloved hands on a turning wheel, the right hand dropping to change gear before a burst of speed

The train: the land runs past in planes that wrap (scroll), each a whole number of px a frame, so none judders and the loop closes. The race: the road bending through the camera, rivals drawn by hand at seven sizes, the cockpit modelled in meters and drawn by mesh(), each mirror another camera. A level longer than the picture: a scene's camera follows the hero as a platformer's does, each layer moving by its parallax (camera).

Journey's end, a Halloween party, a tropical forest

Animated sunset on a sea cliff: an adventurer seen from behind, cloak streaming in the wind, watches the sun go down over the sea while the camp goes up behind them: a ridge tent glowing where the low sun comes through the canvas, its loose corner flapping, a campfire, a pack, a sleeping bag laid out at the door, a cairn with a pennant; clouds drift, a skein of birds crosses toward the sun Animated Halloween party at night in a cemetery: a full moon behind a dead tree, a crypt with its door glowing and a werewolf howling on its roof, string lights and a mirror ball, a Frankenstein DJ at a coffin booth between coffin speakers, a witch stirring a cauldron, and a skeleton, a vampire, a mummy, a zombie and a ghost dancing among graves and jack-o'-lanterns Animated tropical forest seen from above at an angle: a waterfall churning its pool, a river under a plank bridge, a dirt trail, palms and big trees, a jaguar on a branch, a monkey swinging, a macaw, butterflies and a girl breathing on the trail

A backlit sunset on a sea cliff (examples/sunset/): what faces us in shadow, edges toward the sun glowing, a tent lit through, a sky looping slower than the rest. A night party lit only by lighting() (examples/halloween/): eight monsters on one cycle, throwing their silhouettes away from the lamps. The first long project, a 320×240 jungle (examples/tropical/): its trees, palms and big leaves are reduced from "[LPC] Jungle" by bluecarrot16, Lanea Zimmerman (Sharm), Sevarihk, Hyptosis and others, and from Sevarihk's "Animated Palm Tree Sprite", both CC-BY 4.0: credit their authors when you reuse them (refs/CREDITS.md). The rest is drawn in code, MIT.

Development

npm install                                          # dev only: typescript, @types/node
node --test test/docs.test.ts                        # one test file, while you iterate
PXL_EXAMPLES=hd2d node --test test/examples.test.ts  # the examples' check on one folder
npm run test:quick                                   # every test but the two slowest (9-16 s; ~45 s after a change to pxl's sources)
npm run check                                        # type check + every test (13-20 s; ~2 min after an engine change), before a commit
src/core/     engine, no Node APIs: image, palette + ramps, canvas ops, build, trace, project, study
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/      the maintainers' scripts, below
examples/     example art files
test/         node:test suites
Script What it does
scripts/build.js writes dist/ for npm installs
scripts/gallery.ts regenerates docs/gallery/ from the examples (--out DIR to look first, --every N for a quick look; --lib: the library's sheets)
scripts/calibrate.ts scores pxl study against the examples' own source
scripts/perf.ts pxl check's time, processor time and peak memory on every example; --vs <rev>: ms a frame, that revision's pxl against yours
scripts/hashes.ts a hash of every asset of the files given (none: every example); --vs <rev>: what differs from that revision's pxl, --frames frame by frame, for an engine change that shouldn't move a pixel
scripts/vs.ts what hashes.ts, perf.ts and served.ts share: a revision's src/ and examples/ unpacked once into the temp folder
scripts/served.ts what the live viewer sends and holds for one asset (--vs <rev>: that revision's server first)
scripts/pulse.ts how many of an animation's normals turn from frame to frame on the parts that only moved
scripts/meter.ts preloaded into the tests, each test file's time, processor time and peak memory
scripts/cpuprofile.ts a CPU profile of any pxl command, summed by function
scripts/tokens.ts where a Claude Code session's tokens went, read from its transcript
scripts/model-study.sh one run of the model study: a brief to a new Claude Code, Codex or agy session
scripts/eval3d.ts what an edit of a 3D scene changed, part by part, and what it shouldn't have (evaluation-3d.md)
scripts/evaledit.ts what an edit of a scene changed, by id, and the pixels outside what the request names (evaluation-edit.md)
scripts/mhtml.ts saved web pages (.mhtml) opened as text and images, to read tutorials

How to use them, and how to update the examples' snapshot after a change you meant, is in Working with an agent.

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 (augusto-scarvalho/claude-pxl)

正在搜索数据库…

这是什么?pxl 让你用代码编写像素画:一个紧凑的 .px.js 文件可以编译为 PNG、JSON 格式的精灵图集、动态 GIF,以及一个可在浏览器中实时查看、逐步回放绘制过程的查看器。
这是一个库,还是带有自有 DSL 的命令行工具?它是一个命令行工具(`pxl`),围绕一种用于像素画的 JS/TS 领域专用语言构建;美术文件就是普通的 .js 或 .ts 文件,编辑器可提供完整的类型补全。
除了 Node 之外,运行它还需要别的东西吗?只需要 Node >= 22.18。没有运行时依赖,也不需要构建步骤。
这是原创项目,还是从别的项目复刻来的?它是 crsolver/claude-pxl 的复刻版本;README 中链接了一个专门的 docs/fork-differences.md 页面,列出了该复刻版新增的全部内容,并附有 BACKLOG.md,记录仍待处理的事项。
我该如何在 Claude Code 或其他编程智能体中使用它?在 Claude Code 中,把仓库克隆到你的 skills 文件夹,然后让 Claude 画点东西即可;对于 Codex、Cursor 等其他智能体,把它们指向 SKILL.md,并告诉它们命令行工具是 `node /bin/pxl.js`。
这个 DSL 开箱即能画出哪些东西?调色板与色相偏移的渐变色阶、带自动描边和调色板替换变体的精灵、像素级精确的基础图元(线条、渐变、抖动、像素字体)、带分层光照的完整场景、带一到三个灭点的真实透视相机、视差滚动,以及带反向运动学的角色骨骼绑定。
它能导出哪些格式?带 JSON 标签的精灵图集、动态 GIF、Tiled 瓦片地图(.tmj),以及可供后续手动编辑的 Aseprite 文件。
仓库里的展示示例有哪些?若干个由 AI 智能体在人工策展人把关下、完全使用 pxl 历经多轮长时间完成的项目:一幅 320x240 的动态热带丛林、一幅带光照的万圣节墓园场景、一幅逆光的日落海崖场景、一场以骨架优先、带骨骼绑定的骑士比武,以及一条真实透视的赛博朋克街道——后者分别由单个智能体和多智能体流水线完成。
对于大型场景,使用多智能体流水线真的有帮助吗?赛博朋克展示项目对比了单个智能体与“规划器加八个分叉子智能体”的流水线:流水线生成的场景更密集,但连贯性较差,消耗的 token 约为五倍,耗时约为两倍,因此它作为大型场景的一个可选方案提供,而非默认方案。
大小
375.2 MB
星标
249
更新
提交Nov 18
时长
1个月
提交 · 90 天