
                _______   _______ _______ _______ _______ 
               | __ __ | |   |   |       |   _   |_     _|
               |   |   | |       |   -   |       |_|   |_ 
               |___-___| |__|_|__|_______|___|___|_______|



-------------------------------------------------------------------------

     Version 1.3; Copyright 2011 Ken Thornton. All rights reserved.
       Brought to you by the sick, twisted minds at |c32Codethulhu|c21();




*************************************************************************

         UPGRADING FROM 1.0 or 1.1 WILL BREAK YOUR WORKSPACE!

    Save any frames you wish to keep and start with a clean install!

*************************************************************************

                      Upgrading from 1.2 is safe,
              but you'll have to reassign your hotkeys :(


      Refer to |c36UPGRADING.TXT|c21 for full details on safely upgrading

*************************************************************************



[ |c36CHANGES FROM 1.2 to 1.3|c21 ]


> No change to workspace format! It's safe to upgrade from 1.2
  > Hotkeys will need reassigning!!

> No need to backup your workspace frames before unzipping/installing


- Fixed bug with file browser slider not scaling properly  (since v1.2)
- Fixed bug with text tool sliders being positioned wrong  (since v1.2)
- Fixed bug with text tool menu not repositioning well     (since v1.2)
- Fixed bug with text tool spacing not being maintained    (since v1.2)
- Fixed bug with program hanging on exit                   (since v1.0)
- Fixed bug in sprite sheet generator (off by 1 pixel x/y) (since v1.0)
- Fixed bug with XOR ink not respecting brush tip alpha    (since v1.0)

- Greatly improved Moai's ability to repair damaged workspaces
- Moai distribution now loads tutorial ONLY if no workspace is present

- BELOW fixed to behave like other CEL activities
- Quickpan displays error message if frame is too small to work
- Extremely slow operations show up on screen progressively
- Glow ink and fill operations have been optimized slightly
- Zoom level is remembered for each frame
- 'Center' action added to FRAME menu. This recenters the window
- 'Center' hotkey added as well
- New schemes added: Toadstool, Mustard, Lilac, Igloo

- Frame can now be repositioned with an edge at center of screen
  This allows easier editing of corners and edges

- Drawing menu automatically fades out when:
  - Getting a CEL
  - Using the move tool





[ |c36CHANGES FROM 1.1 to 1.2|c21 ]

- Optimized spiral tool; less lag when previewing large spirals
- Spirals can be grabbed and repositioned like other shape tools
- GUI sliders have been redesigned to have better contrast and control
- When saving a JPG, quality preview will display automatically
- New themes added; several existing themes updated
- Fixed GUI bug in JPG quality menu

- User's last settings preserved for the following actions:
  - Cel rotation
  - JPG quality setting
  - Rpoly tool
  - Spiral tool

- Several hotkeys fixed
  - Color select, brush tip, favorites, ink and brush tool select fixed
  - User can now enter and exit these menus with their assigned hotkey





[ |c36CHANGES FROM 1.0 to 1.1|c21 ]

- Fixed bug with file browser showing slide bar without being needed
- Fixed GUI issue where node/cel jump menu buttons were off by one pixel
- Fixed bug where seven hotkeys weren't functioning at all
- Supershape tool values are now preserved
- GIF color reduction setting added to options menu
- GIF color reduction improved with NueQuant and custom code
- Extended color favorites support (252 extra colors)
- Updated GUI with stronger slider arrow highlighting
- Zoom preview added, along with several options
- User-defined color schemes + import/export are now available
- Adjusted supershape slider ranges to be more practical (+/- 3000 now)




[ |c36WHAT'S THIS?|c21 ]

Moai is a spiritual continuation/outcropping of Autodesk Animator. There
are quite a few capable pixel editors out there -- I should know, because
I've used almost all of them at some point in time. Artists are fiendishly
adept at latching onto a single piece of technology and fellating it until
the bits fall off. And they're also picky about what they do and do not
want in an art program, which is why there are so many around. You always
run into the typical 'Program X would be perfect if it only did Y and
perhaps Z' statements, and even I did the same thing with both versions of
Animator, which I have used for many, many, many freaking years. It's just
impossible to find one editor that does everything you want.

So, one day I realized that I had the ability to make my own editor that
had all the features and doodads I ever wanted; I just needed the balls to
do it. 2011 rolled around, and I was bored. So here we are.

Admittedly, Moai isn't going to do everything you want, either -- but you
may just find it useful enough to love regardless :)







[ |c36WHERE TO USE|c21 ]

Moai is a pixel editor, so it should be deployed alongside general purpose 
image editors such as Gimp or Photoshop. Those are traditionally poorly
suited to detailed pixel work, which is where Moai and related editors
come into play. 

Be smart. Zoom in, corral those fiesty little pixels, and get some good
work done. Find where Moai belongs in your tool chain and let it rock some
pixels.







[ |c36HOW TO USE|c21 ]

Draw.

But seriously, if you want to make Moai sing you need to get used to the
idea of frames and cels pronto. Learn how they work, get used to their
quirks and turn their eccentricities into strong tools to increase your
throughput, or at least how much fun you have.

Frames can be practically any size and shape, so try reserving a frame
or two in a familiar spot to hold WIP sprites, cels, colors, or anything
else you might find useful. With 100 frames available in each workspace,
treat frames like email... why delete what might be useful in a day or
two? You can keep entire projects organized into a single workspace,
using the frames as sprite sheets and breeding grounds for new masks or
textures.

Get data around frames using cels. Remember that when you paste a cel it
obeys the current ink, so you can apply masked cels to frames as effect
patterns. A cel sticks around until it's replaced, so you can reuse it
as many times as you'd like.

Get used to the RESTORE command. Know it; love it. You can restore a frame
to its original state (as it was when you swapped over to it) no matter
how many changes you've made. Combine this with cels, and the undo/redo
queue to make quick experiments and permutations to your work without
risk. 

Swapping to a different frame COMMITS ANY CHANGES YOU HAVE MADE.
Read that again. Memorize it. Then use it to your advantage. Swapping a 
frame out writes it to disk in your workspace, so even a power outage 
won't cost you your work. And just as mentioned above, swapping a frame 
essentially makes a 'checkpoint' you can always get back to with the
restore command, in case you made too many changes to undo and don't like
how things turned out. If you like how things are turning out, swap to
another frame, then back, giving yourself a fresh checkpoint.

When you have a frame just how you like it, save it to disk as a
GIF, PCX, PNG, BMP, or JPG. 






[ |c36INPUT|c21 ]

Moai runs in 32bpp mode, so anything that passes through it gets promoted
if it isn't already in that format. I'm not sure how the program handles
existing alpha channels, as I haven't tested this. Most likely it ganks
any data in that channel, so you're been warned.

If you are working with a medium that needs precise control over a small
number of colors, make sure you are working in RGB color space, and leave
your ink set to OPAQUE. This in the only way to guarantee that each pixel
you drop on the frame is exactly what you want 100% of the time.


GIF, PCX, LBM :
These images will be promoted to 32bpp if they already aren't. Although
the GIF spec allows for high-color images by utilizing multiple palettes,
Moai can't handle this. This is largely a non-issue because 99.99999% of
all GIFs are 256 color. The PCX spec is color agnostic, so there's no
reason to downsample when saving.


PNG, JPG, BMP :
No issues to report.







[ |c36OUTPUT|c21 ]

You can save to all but one of the input formats:

GIF :
Images will be reduced to 256 colors via a routine to generate an
optimized palette. Be aware that passing a GIF through Moai doesn't
preserve your existing palette indices. If you don't know what that
means, then you aren't in a position to have to worry about it! Also,
while Moai will load animated GIFs, I have no idea what happens when you
try to save one. It will probably only have a single frame. Also be aware
that your quality setting has a significant impact on both the quality
of file you get as well as how long it takes to generate it. Running at
'best' quality on a large frame can take several seconds on a typical PC
circa 2009.


PCX, PNG, JPG :
No issues to report. 


BMP :
Compression isn't supported, so BMPs will be rather large. Allegro
doesn't handle this, so I'll have to write a custom loader if I want to
see this happen. Perhaps in the near future?


LBM :
This format isn't supported. You can load an LBM, but not save. Allegro
doesn't provide a save routine for this format, and I haven't had time
to write my own. 






[ |c36PENDING ADDITIONS|c21 ]

Some rudimentary animation preview facilities will likely be built into
the next release, alongside alpha channel editing, and optimizations to
slow ops like fill. I'd also like to address Allegro's handling of BMP
files, as it doesn't give an option to compress the files while saving.
While we're dreaming of stuff, I'd also like to write my own GIF *coder
that would properly preserve palette indices, because that's stuff can
be ultra-important at times. Anyone who'se done any serious 8bpp coding
knows exactly what I mean.

Of course, an LBM encoder would also be a nice addition, just to
round things out. I'd also look into getting the thumbnails, image
preview, and quick pan windows perspective-corrected. As it stands now
they simply stretch the contents to fill their area, which can make
some images look awfully wonky.

Feature creep is not and won't be a problem with Moai since it is almost
exactly what it needs to be. Aside from the aforementioned adders, I
wouldn't look for much else. 






[ |c36SOME NOTES ON OPTIONS|c21 ]

Power saving mode exchanges vsync usage to give CPU time back to the
operating system. By default this is high, which is good if you're
running on a laptop or silimarly battery-tethered machine. If you're
running on a desktop and you don't mind your fans running all the
time, you can turn this off for a smoother experience. If you find
the mouse lags, or drawing operations are laggy, try turning this down.

Yes, you can turn the crosshairs off. Setting the strength to zero
accomplishes this. You can also make the cursor maintain a constant
size instead of zoom with the camera. By default this makes the mouse
match pixels on screen at a 1:1 ratio.

GIF output defaults to FAST, but low quality output. If you want more
accurate color reduction and don't mind waiting, bump the GIF COLOR
REDUCTION setting to GOOD or BEST.

Running the config.exe program allows you to select a new preferred
video mode for the program. If the mode isn't available, Moai will
try to fall back to the next lower mode. If nothing else is available,
it'll shit itself and die :)






[ |c36MISC. NOTES - KNOWN ISSUES|c21 ]

- Sometimes Moai will hang on exit when running on multi-core systems.
  The cause of this is not quite known yet. While running Moai, go to
  the task manager and set the affinity for moai.exe to CPU 0. This
  seems to fix that problem. Since Moai is not designed to take
  advantage of multiple cores, this is no loss for the user.


- Run config.exe to set your preferred video mode.
  Moai will try to step down if it can't hit your mode.

- By default, Arrow keys and WASD pan around the frame.
  By default, delete steps back a frame, and page down steps forward
  a frame. All keys can be remapped in the user menu.

- Hold the middle mouse button to quick pan. This is very handy!

- Hold backslash '\' to jump frames. Handy if you have a lot of frames
  in your workspace.

- Mouse wheel controls zoom level. You can also use +/- on numpad.

- A lot of GUI elements can be right-clicked to change them.

- Right clicking off the drawing menu will toggle it -- gives you a 
  clean view of the frame.

- Many menus and ops can be closed out by right clicking OFF them.
  That's an original Animator thing, so you'll figure it out fast.

- When browsing for files or fonts, you can set a directory as the HOME
  with that button. It'll always try to go there first if you've set
  your home for that file type.

- CTRL-C / CTRL-V work to access the Windows clipboard.
  Use cels to cut and paste while in Moai.

- The thumbnails, quick pan, and image preview windows aren't
  perspective corrected. Images will stretch to fill those areas.

- The fill operation is *amazingly* slow, and needs rewriting. If you
  combine filling large areas with glow ink you may as well go read
  a nice novel while the program does its thing.

- Setting glow ink to a large radius is a recipe for hang time. Go
  take a nice shower while it works.

- You can change your GUI colors from the scheme menu. The default
  color scheme is saved in the SCHEMES directory.






[ |c36CREDITS / THANKS|c21 ]


Moai was constructed in my spare time across ~6 months, upon a custom
framework consisting of the following technologies/libs:

- GCC
- Allegro 4
- LibJPEG
- AlPNG
- sGif
- FreeType
- Enet
- NeuQuant


Moai was written using Code::Blocks, and VerySleepy for profiling.

Licenses for individual fonts can be found in the LICENSES directory.

Many hoopy froods were involved in beta testing. Many thanks to
everyone at the GDR for keeping me on-task when all I wanted to do
was play Xenoblade :)







[ |c36HEY, LISTEN!|c21 ]

Visit the GDR, where crazy old game developers hang out and opine about
the good old days. Also, we still make games in our spare time! That's
gamedevelopersrefuge.org for the non-google inclined.

Also, if you need to bitch at me about Moai, email me at 
|c32callofcodethulhu at gmail dot com|c21. I don't check it regularly, so
if you don't hear anything for a while I'm not ignoring you. I'm just
being typically lazy. Don't ask about Linux or Mac ports, or I may
actually ignore you. No, really. I've tested Moai with Ubuntu and Wine
and it ran well. That's good enough for the moment.

If you have a bug to report, useful suggestion, or genuine concern,
I'm all ears.


Sirocco says 'The orange ones are candy.'



- |c32codethulhu|c21(); 2012 -                           - callofcodethulhu.com -