pxart compose

compose -o OUT[:frame] [--size WxH] [--under] [--rekey [KEYS]] [--used-keys-only] [--variant-map NAME=V1,V2] [--replace] [--dry-run] LAYER@x,y ... compose --map MAP [--tile N] -o OUT[:frame] [the options above] [LAYER@x,y ...]

usage: pxart compose [-h] -o O [--map MAP] [--tile TILE] [--size SIZE] [--under] [--rekey [KEYS]]
                     [--used-keys-only] [--variant-map NAME=V1,V2] [--replace] [-v] [--dry-run]
                     [layers ...]

  compose -o OUT[:frame] [--size WxH] [--under] [--rekey [KEYS]] [--used-keys-only]
          [--variant-map NAME=V1,V2] [--replace] [--dry-run] LAYER@x,y ...
  compose --map MAP [--tile N] -o OUT[:frame] [the options above] [LAYER@x,y ...]
      Stack frames from any files (layers at x,y, or a --map's cells) into one frame of OUT,
      bringing their keys and variants into OUT's palette. Add --rekey when two sources (or a source
      and OUT) use the same key letter for different colors: E_KEY_CONFLICT says so.

positional arguments:
  layers

options:
  -h, --help                show this help message and exit
  -o O
  --map MAP                 tilemap file, as scene --map: its cells become the layers (the canvas is its size)
  --tile TILE               tile size for --map: WxH, or N for NxN (default 16x16)
  --size SIZE
  --under                   draw the layers behind OUT's frame
  --rekey [KEYS]            give keys that clash with OUT's colors free keys in OUT only; the source files stay as they are. KEYS: only these ('o,r'), or KEY=OUTKEY to use OUT's key ('k=j,n=q')
  --used-keys-only          a new OUT gets only the keys the frame uses (default: the sources' whole palettes, for shade ramps)
  --variant-map NAME=V1,V2  a new OUT's variant NAME takes each layer's first of NAME, V1, V2 (repeatable)
  --replace                 a plain OUT that exists is started fresh, as if new
  -v, --verbose             every note in full (more than 3 of them are otherwise put in short, a line per kind)
  --dry-run                 print what the edit says and a diff of the file it would change; write nothing

      Stack single frames (later layers on top; '.' never overwrites) into one frame.
      Rules ('pxart help compose-rules' prints only these):
        - A new OUT gets the layers' whole palettes, drawn with or not (for shade ramps). When
          every layer imports the same @palette file, OUT imports it too; else its keys become
          key lines.
        - An existing OUT keeps its own palette, @palette and variants; each layer's keys join
          it.
        - Variants merge by name: OUT's night colors each layer's pixels as that layer's own
          file's night does, and a layer whose file has no night stays at its base colors in
          it. --variant-map dusk=night reads another name as OUT's dusk.
        - A key a layer has in another color than OUT's is E_KEY_CONFLICT; --rekey gives it a
          free key in OUT. The layers' files are read, never written.
        - OUT:frame adds that frame to OUT, or replaces it; a plain OUT is one unnamed grid.
      Examples: 'compose -o room.px tiles.px:cobble@0,0 hero.px:idle/0@4,2', 'compose -o
      party.px:keeper/walk keeper.px:walk/0@0,0 --rekey' (keeper.px's k is another color in
      party.px: it gets a free key there). --dry-run prints what compose says (notes,
      conflicts, --rekey's moves) and OUT's diff (a new OUT: every line); nothing is written.

      A new OUT (rule 1; a shared import re-pointed from OUT's directory): local keys follow
      the import, the keys the layers use first: a key layers have in different colors gets
      the color of the layer that uses it, else the earlier layer's, and one line per source
      file names its colors left out and why: a key none of the file's layers here
      draw with is no conflict, and OUT has the color of the layer named (which draws with it,
      or is the earlier layer). That line is a WARNING when the file needs a key it lost (its
      other frames draw with it, named, or a variant lists it unchanged or keeps it while
      recoloring most keys: a lamp kept lit); --rekey then keeps such keys under free keys in
      OUT.

      --used-keys-only gives a new OUT only the keys its frame uses (and their variant colors;
      a @palette they all import is still imported, since it adds no key lines), so check has
      no 'unused keys' to note. Not the default: the unused keys are often a material's
      ramp: a cloak drawn in its base key c still needs X x C w for 'shade --ramp XxcCw' to
      re-shade it. An existing OUT only ever gets the used keys. So they're no
      surprise, a new OUT's note names the keys its frame doesn't draw with, by file ('...
      from its layers' whole palettes (for shade ramps and recolors): wick.px's E'), and
      check's 'unused keys' note offers the palette --remove that drops them.

      An existing OUT (rule 2): a layer's key is added unless OUT has it in that color, in
      the colors the layer's file gives it in OUT's variants of the same name (a variant the
      file hasn't got leaves the key at its base color there, and a file with variants, none
      of them OUT's, gets a note saying so and naming the --variant-map that would read one
      as OUT's). A plain OUT that exists (no :frame) keeps its palette too, keys from an
      earlier run included, and a note says so: 'note: glade.px exists: keeping its palette
      (61 keys, @variant dusk); --replace starts it fresh' (as does an E_KEY_CONFLICT).
      --replace starts it as if new: the layers' palettes, nothing of the old file (not with
      OUT:frame, whose other frames it would drop, or with --under).

      Key conflicts: a key a layer uses in another color than OUT's (or an earlier layer's) is
      E_KEY_CONFLICT, one line per source file (all its layers: 'layers 1-4, 7 (field.px)')
      naming every key and both colors, and free keys for them ('s>a' 't>b'). The free keys
      are chosen once for the whole compose, so no two lines' suggestions collide: a key OUT
      already has in that color first, then the key an earlier file of this compose was given
      for a color that looks the same in every variant (two packs' one outline share one key,
      and the note says so), then letters and digits, then % + - / : ^ _, and only when those
      run out the keys a shell reads (! $ ` ' * ? [ ] { } ~ & ; | < > ( )) or pxart does (,
      and =). A key any layer's file has isn't free, used here or not. Two ways to use them:
        --rekey: compose gives those keys the free ones in OUT as it goes, and a note says
          which: 'note: --rekey gives field.px's keys free ones in scene.px: 's>a' 't>b'
          (field.px is unchanged)'.
        a copy: 'pxart recolor field.px 's>a' 't>b' -o rekeyed/field.px' (rekeyed/ beside
          OUT), then compose from rekeyed/field.px; the line prints it ready to run.

      --rekey KEYS touches only the keys it lists. --rekey o,r gives o and r free keys and
      leaves the others as they are (a key of another color is still E_KEY_CONFLICT, a variant
      clash still a WARNING). KEY=OUTKEY puts KEY on OUT's key OUTKEY instead of a free one:
      --rekey k=j,n=q uses OUT's j and q, which must be in k's and n's base colors (else
      E_KEY_CONFLICT), and must not be keys of the layer's file; where OUT's variants color
      them otherwise, a WARNING per key names each color that changes. Both mix: k=j,n,s gives
      n and s free keys, and r=r keeps r as it is on purpose. An entry FILE.px:KEY[=OUTKEY] is
      for that source file alone: --rekey o,girl.px:T=V puts girl.px's T on V, gives every
      file's o a free key, and leaves the other files' T alone (a file's own entry wins over
      one for every file; FILE.px is a path, or the name of one source file). When --rekey
      gives a key a free one though an existing OUT has its base color under another key (in
      other variant colors, so it wasn't reused), a note names that key and the --rekey list
      that uses it anyway: 'note: party.px has the base colors of k n as j q, in other variant
      colors; --rekey k=j,n=q uses those anyway'. After crop's --rekey, four digits are the
      rectangle; write --rekey=1,2,3,4 to name four digit keys there.

      The report: compose reports per source file, in layer order, one line per reason: what
      --rekey moved and why (another color there; OUT's base color but other variant colors; a
      key its layers here don't draw with that the file needs; a key --rekey KEY=OUTKEY
      named), the colors a new OUT left out, which of the file's frames draw with a key it
      lost, and one WARNING per key OUT's variants color otherwise ('WARNING: layer 2
      (keeper.px:idle) draws 'r' #c4473a in party.px's variant colors, not keeper.px's: dusk
      #a33a4c (keeper.px: #83344e); compose --rekey r gives it a key of its own'). An
      E_KEY_CONFLICT line offers the same moves --rekey makes, with the same reasons.

      Variants (rule 3) come along for the keys OUT has, in the colors of the layer whose
      key OUT has. Layers from files with different variants (a market's dusk, a keeper's
      night, a candle's dark): each of OUT's variants covers only the layers whose file has
      it, and a note per variant says which layers stay at their base colors in it.
      --variant-map dusk=night,dark (repeatable) builds OUT's dusk from each layer's first
      of dusk, night, dark, so every layer dims together; a new OUT's palette is then
      inlined (its variants are built, not imported). The map adds to the same-name lookup,
      never replaces it: it says only where OUT's dusk comes from, and OUT's other variants,
      night among them, still read each file's variant of the same name (a keeper's night is
      then OUT's dusk and OUT's night too), and may feed several maps. A new OUT merges a variant into the map's only
      when every file that has it gave it to the map (the keeper's night, read as dusk):
      then it gets no variant of its own. One that a file keeps as its own (its file has a
      dusk too) stays one of OUT's variants. With an existing OUT, whose variants stay its
      own, the map says which of each layer's variants to read as OUT's dusk (dusk must be
      one of OUT's). A key a layer draws in OUT's base color but that its file's variants
      color otherwise (one red awning, recolored by one pack's dusk and another's night), in
      a new OUT or an existing one, gets a WARNING: OUT's variants color those pixels OUT's
      way. --rekey gives such a key a free key of its own, as it does a key of another
      color, reusing a key of OUT only when it looks the same in every variant. crop writes
      a new OUT the same way, and crop, paste and frames --copy-to bring keys in the same
      way.

      Comments: the comments above the layers' key and @variant lines come along, as for
      palette --extract-to; a comment naming a key --rekey renamed says so: '# lamp colors
      (l, g) stay lit (renamed l>I g>J)'. The keys right below a key's comment in its file
      (the keys it is about: '# light-emitting keys' above f a i) stay below it. From
      several files, each saying which file's it is ('from keeper.px's @variant night, dusk
      here'), and one that names a variant --variant-map merged into another says so ('from
      player.px, whose dark is dusk here'). A @variant's comment names only the files whose
      variant lines gave OUT's own @variant keys, and when OUT imports the rest, says so
      ('from visitors.px's @variant night; the rest from pal.px's night'). An OUT whose
      palette is inlined also gets the palette files' header comments at the top of its
      palette, each with the files it came from.
      A new OUT's header says how it was made: '# composed by: pxart compose --map room.map -o
      room.px', its paths from OUT's folder (composing OUT whole again updates it). A variant
      WARNING about OUT then also offers composing it again, with --replace, once the sources
      have that variant.

      Frames and canvas: layers can be frames of one parts file: parts.px:hat@3,0
      parts.px:body@0,8. OUT:frame keeps OUT's other frames (OUT may be a palette-only file),
      and the 'wrote' line says when it replaced one. A new frame goes after the last frame of
      its animation (like dup), or at the end for a new animation. Canvas size: --size,
      else --map's, else the frame being replaced, else the other frames of its animation,
      else the first layer. Pixels outside the canvas are cropped; a note counts them.
      --under keeps OUT's frame and draws the layers behind it: they fill only its empty
      pixels (a floor or a shadow under a finished sprite). The frame must exist.

      From a map: --map MAP reads scene's tilemap (legend, rows, '---' layers, +b, a '#'
      legend line; see scene) and makes each cell a layer, drawn where scene draws it, then
      the LAYER@x,y given over them; --tile is scene's (N means NxN). Palette, --rekey and
      --variant-map work as for any layers. A legend entry with its own %VARIANT comes in
      that variant's colors, as a file of its own (tiles.px%dark; --rekey tells it from
      tiles.px), and a PNG in keys of its own: OUT's variants leave both as they are, as
      scene --variant does. So 'compose --map market.map -o market.px' renders as 'scene
      --map market.map --bg transparent --scale 1 -o market.png' does, pixel for pixel, in
      every variant too, except where a translucent pixel lands on another: a .px pixel is
      one key, so it replaces what scene blends.

See also, in pxart help all: EDITING (-o OUT gets the whole file, only changed lines are
  rewritten, 'no change'); FORMAT: selecting frames (FILE:SEL, an unnamed grid's name, zsh's
  "${F}:sel").

pxart help all has the whole reference, pxart help TOPIC one part of it.

This is the output of pxart help compose. The other editing commands and their shared notes are in pxart help EDITING.