Format

FORMAT (.px)
    # comments start with '#'
    pxart 1                  optional version line (first non-comment line)
    @palette base.px         optional: import palette keys from another .px file
    k #3f2631                palette: one key char, then #rrggbb, #rrggbbaa, or 'transparent'
    g #43e1b3                ('.' is always transparent; you may omit it)

    ....kkkk....             grid rows: all the same width, only palette keys.
    ...kggggk...             The sprite's size is the grid's size: nothing to count.

  A comment right above a line is that line's; a header is above 'pxart 1' or a blank line.
  Several frames per file: name each grid with @frame; the id is a path, and frames
  sharing a parent path form an animation (walk/down/0, walk/down/1 -> "walk/down"):
    @anim walk/down direction=forward repeat=0 ms=125
    @frame walk/down/0
    ....kkkk....
    @frame walk/down/1 ms=250          per-frame duration overrides the anim's
    ...
  An animation plays its frames in file order (not by the number in the id).
  pivot=x,y (optional) on '@frame ID' or '@anim GROUP' is the frame's anchor pixel, counted
  from its top-left (the feet: pivot=8,23 on a 16x24 frame). A frame's own wins over its
  anim's; no pivot is the default. anim and onion line frames up by pivot instead of bottom-
  centre (a frame without one then uses its bottom-centre pixel, w // 2, h - 1); export
  writes pivots (Aseprite slices, --frames pivots.json). A pivot may lie outside the frame (a
  hand, the ground under a jump); check notes it, in case of a typo. flip, rotate and
  transpose move a frame's pivot with its pixels: a whole group's @anim pivot moves on its
  @anim line, and a frame flipped alone gets its own.
  direction: forward | reverse | pingpong | pingpong_reverse (Aseprite's words).
  repeat: 0 or absent = loop forever; N = play N times. ms: default frame duration.
  'anim-set hero.px:walk/down ms=125' writes these, pivot=8,23 too (FILE:GROUP/ID: a frame's).
  Frame groups that aren't animations (UI icons, a parts file): '@still ui/life' keeps them
  out of animation exports and checks; '@still *' marks every frame in the file, top-level
  ids with no '/' included (a parts file; frames then lists them as 'still'). A frame copied
  as a still (a top-level id, or a @still group) drops its ms and keeps its pivot, with a note.
  Palette variants (recolors): keys listed after '@variant night' override the base
  palette. Variants in a @palette file are inherited; local keys (and local variant keys)
  override imported ones, and check notes the override, and a local key that repeats an
  imported one's color (with the palette --remove that drops its line when nothing changes).
  A variant a file gets only from its @palette leaves the file's own keys at base colors;
  commands that render it print a WARNING naming them and the fix, and check notes it.
  Slots, a key's alternatives for runtime recolors ('f #e0ac69 | #f5cfa0'): help slots.

  Anywhere a command takes FILE, FILE:SEL picks frames: SEL is a frame id or a parent
  path (FILE:walk/down = every walk/down/* frame), or a list of them, FILE:idle,walk/0.
  No SEL (or *) means every frame. A file with one unnamed grid (no @frame) calls it by
  the file's name, as frames lists it: ant.px's grid is ant.px:ant. Writing a named frame into such a file (compose, crop, new, put -o
  ant.px:ID, or from-png into it) first makes the grid '@frame ant', with a note; with ID
  ant that is the frame written. Add %VARIANT to render with a variant: FILE:idle/0%night.
  +----------------------------------------------------------------------------------------+
  | zsh users: write "${F}:walk", not "$F:walk" (zsh reads ':w' as a modifier), or quote   |
  | the whole argument. A missing hero.pxalk/0 or hero.pxidle is reported as that mistake. |
  +----------------------------------------------------------------------------------------+
  An output under a file (-o hero.px/walk/0) is E_FILE; an image output with no image
  extension (-o /dev/null, -o x.px) is E_BAD_ARG.
  Paths: a path typed on the command line is read from the current directory, as the shell's
  are: FILE, -o OUT, layers and items, and every path option (--palette, --import, --match,
  --copy-to, --into, --map, --labels, --in, --extract-to, --export, --preview, --frames,
  --aseprite, --tiled, --indexed). A path written inside a file is read from that file's
  directory: a .px's '@palette pal.px', a .map's legend entries, a --labels CSV's file
  names. A file pxart writes elsewhere gets its @palette lines re-pointed (see EDITING). An
  output's missing directory is made, and said: 'created out/'. An E_FILE for a relative
  path says so, and a path option's names it: 'palette: --match (../wick/pal.px%dark):
  ../wick/pal.px (from the current directory): E_FILE: No such file or directory'.