
* Important stuff

  Do NOT play on a map that you want to save. Don't even leave the
  editor if you can avoid it. When you save the map, it'll be in the
  exact state that it was in when you saved. So if you carefully place
  all your badguys and powerups, then decide to do a test run on the
  level where you go through and kill everything and collect
  everything, then the saved version of your map will have all the
  badguys dead and the powerups gone. Just save your map before
  testing and reload it before going back to work on it.

  If this becomes an issue, I'll make the editor force this on
  you. -Cliff

* Navigation

  Click and drag with the MIDDLE mouse button (the scroll wheel) to
  move around the map. This also works in UI windows, so if you have a
  huge tileset that only partially fits in the tile pane, you can use
  the middle click + drag to move around inside that window.

  Use the scroll wheel to zoom in and out.

* Layers
 
  Things on different layers generally don't interact with each
  other. Except for lights with the "fullbright" flag set.

  Each layer can have a different scroll speed for a parallax
  effect. Here are how the layers are set up:

    - Layer 0: Static background. Doesn't move at all with the
      camera. Put a picture or something nice here. For representing
      "infinitely far" background.

    - Layer 1: Far background. Scrolls at a fraction of the camera
      speed. For things far enough back that they are not important,
      but to create the feeling of depth.

    - Layer 2, 3, 4: Immediate background, Active stuff, and Immediate
      foreground. All of these scroll at the same speed as the
      camera. If a fullbright flagged light is put on one of these
      layers, it will affect the layers above it in this
      set. (Example: Putting a fullbright light on layer 2 will have
      the light draw on layers 2, 3, and 4.)

    - Layer 5: Near foreground. For simulating stuff closer to the
      camera than the active layers. Scrolls faster than the active
      layers.

    - Layer 6: (Deprecated) HUD. Does not scroll (like layer 0), but
      always draws on top of everything.

* Tile mode

  Tile mode is active any time the tile pane tab is selected.

  If a layer doesn't have any tiles, the tile pane will be
  blank. Click on "Browse..." to select a tile texture.

  If the tile divisions don't line up with the tile divisions in the
  image, set the tile size right below that (32 by default). Only
  powers of two (16, 32, 64, etc) work.

  Hold shift in the tile pane to select multiple tiles. When tiles are
  drawn they will be randomly selected from all the selected tiles in
  this way, allowing for a random fill on large areas easily.

  Click in the world to paint tiles.

  Hold control and click to pick a tile in the world and make that the
  currently selected tile to draw.

  Hold shift and control to pick multiple tiles just like in the tile
  pane tab.

* Entities

  Click on an entity in the current layer to select it.

  Click again and drag to move it.

  Press 'd' to duplicate the selected Entity. (Its name and Lua state
  are NOT duplicated.) This only works for entities that can be saved
  (see Lua API documentation for Entities to make an Entity that can
  be saved).

  Press delete to delete the currently selected Entity.

  Hold control and drag from the currently selected Entity to another
  Entity to link the current Entity to the other one. This has
  different meanings for different Entity types.

  For example:

    - In Lily, world map nodes link to each other to indicate that the
      player can travel directly from one to the other.

    - Doors connecting to switches.

    - Lights connectign to switches.

  Click on an Entity in the Entity Palette tab to create a new Entity
  of that type. It will also change the selection to that Entity.

* External Tools

  To make any use out of the programs in the tools directory, you're
  going to have to first move them to the same directory that the
  game's main binary is. On Windows this is the game's root
  directory. On Mac, this is somewhere in that mess of a .app folder.
  
  All of the tools are linked exactly the same way as the main binary
  and make the same assumptions about the location of game data.

** spritepacker

   Run this from the game's main directory to generate
   autogen_spritedef.lua files in the game's Lua directory based on
   all the .tga textures in the textures directory.

   If you don't give it any command line parameters, it'll just
   generate sprite information for every texture in every game
   project. This will also scan all .poop file archives in the
   directory for game sprites.

   Alternatively, you can pass in file names of .tga images and it
   will generate the appropriate autogen_spritedefs.lua file that goes
   along with them to stdout instead of automatically writing the
   script.

*** Extra information used in spritepacker

    spritepacker will scan the images first to try to split it into
    sprite rows separated by entirely transparent (alpha 0) rows that
    can be as little as a single pixel tall.

    Additionally, the game engine will screen out any pixel with a
    pure pink color (0xff00ff??) and set it to zero alpha when it's
    being loaded. The spritepacker tool will use these pink pixels as
    registration marks.

    If pink registration marks are present, additional information
    will be added to the Lua output.

    The pink marks follow these rules: Any column of a sprite that has
    multiple pink pixels in it (like a vertical line of them) will be
    considered the center of the image. Any row of a sprite that has
    multiple pink pixels in it (like a horizontal line) will be
    considered the bottom of the image.

    Note that the horizontal line is for the bottom to easily register
    things that stand on the ground. The actual use of it is
    determined by the Lua script running whatever Entity, so a
    specially set up object in the game could potentially use the
    registration marks in a different way.

*** Notes

    Keep in mind that every sprite in a row will be drawn as tall as
    the tallest sprite in that row. Make sure rows are divided cleanly
    and completely with no overlap because of this.

    Pink registration lines don't actually have to be lines. It will
    figure out that a column or row contains the marker simply if it
    has more than one pink pixel in it. Feel free to draw the lines
    behind a sprite, as long as at least two pixels for the vertical
    and horizontal lines are completely showing through.

    Things that don't end up pure pink will NOT be considered for this
    and will not be filtered out by the game engine. Watch out for
    antialiased edges around sprites blending with the pink stuff!

*** spritepacker output

    Here's the actual Lua scripting side of the spritepacker.

    Files generated with spritepacker are Lua scripts that should be
    included from one of the project's other scripts. They contain
    tables with the following format...

#+BEGIN_SRC lua
  spriteDefs["file.tga"] = {
  -- Row 1 (0)
    {
      {      4,      4,     30,     32,     -1,     -1 }, 
      {     43,      4,     54,     32,     -1,     -1 }, 
      {     75,      4,     87,     32,     -1,     -1 }, 
      {    198,      4,    218,     32,     -1,     -1 }, 
      {    232,      4,    253,     32,     -1,     -1 }
    },
  -- Row 2 (5)
    {
      {      6,     46,     25,     83,     -1,     -1 }, 
  
  -- ... (snip)
#+END_SRC

  Each line contains information ready to be passed into
  Entity:setSpriteFrame() (the first four numbers) and then data ready
  to be passed into Entity:setSpriteBottomCenter().

  If the latter data is -1, -1, then it means that a pink (0xff00ff)
  crosshair was not found on the sprite to indicate the bottom-center
  and Entity:setSpriteBottomCenter() should not be used.

  Sprite information is split into rows, then columns. If one wanted
  to get the data for a sprite that was in the second row and the
  third column, of a texture named "file.tga", this would be
  appropriate:

#+BEGIN_SRC lua
  local spriteData = spriteDefs["file.tga"][2][3];
#+END_SRC

  Remember, Lua uses 1-based indexing, and that applies here.

** _archiver

   Use this to pack up .poop file archives. Commands are shown when
   the binary is executed with no command line parameters.

   Directory paths stored in the archives are relative to the current
   working directory when it is executed!

