README.TXT
for FLICster 1.0.1 (build 18) 
by Moeniir - moeniir@home.com

If you have version 1.0.0 (build 17), this is just a bugfix.  Pop on down to the change log for the scoop.  The rest of this readme is the same as v1.0.0.

If you have a prior version (0.2.2 or earlier), see the change log below, then have a look at 'How to use it'.  ALOT has changed.


WHAT IT IS
----------

FLICster is a FLC file utility for working with unit .FLCs for Civization III from Firaxis/Infogrames.  This version is a major step forward from previous versions.  It's been tested enough that I'm not calling it a beta, but I won't swear it's perfect.  For the love of Ethyl Murman, BACK UP YOUR civilization III\art\units folder and all subfolders before running this thing.  You've been warned.


WHAT IT DOES
------------

This version of FLICster aims to be the Swiss Army Knife of Civ3UnitFlcs.  FLICster allows you to view Civ3UnitFlcs, export them to several formats for modification, and create new Civ3UnitFlcs from the edited exports.  It has many extra little features as well, which are detailed later.  In a nutshell, the orginal FLICster (versions 0.1.1 thru 0.2.2) allowed new Civ3UnitFlcs to be created, version 1.0.0 aims to make the process civilized (no pun inten... well, maybe just a little).


WHY IT EXISTS
-------------

The FLC format is a file format for animation - a series of still frames, displayed in sequence.  CIV III uses FLC files for many purposes, most complex among them for unit animations.  Each unit in CIV III has several different animations - run (movement), attack, death, fidget, etc.  Each animation is stored in a FLC file.  Unfortunately for potential unit creators, CIV III uses a non standard FLC format.  For this reason, existing FLC editing programs, such as Jasc's Animation Shop, cannot edit these files.  Some programs just crash opening the CIV III files, others appear to work, but any files saved from them will crash CIV III.  FLICster was created to address this problem.  

Prior versions just split the Civ3Flc into several standard FLC files, editable with tools like Animation Shop.  Unfortunately, none of the FLC editing tools people tried seem to be well suited to the task.  This is because the FLCs are in 256 color paletted mode, and Civ III relies on the palette positions for many effects.  Tools like Animation Shop like to 'Optimize' palettes by rearanging them and merging entries that represent the same color.  This changes the palette positions, resulting in problems.  This version eliminates the need for any FLC editing tool, by allowing the animation frames to be exported as 256 color PCX files.


INSTALLATION
------------

Run the installer.  If you already have the VB6 runtime on your system, plus a couple of standard Microsoft Custom Controls, you may be able to get the SMALL distribution, which is just the exe and the readme.  If so, you can figure out the rest :)  In any event, check the civ III forums on http://www.civfanatics.com for the latest version.


HOW TO USE IT
-------------

If you've used previous versions of FLICster, don't skip this section - everything has changed.  To get started, open up a Civ3UnitFlc - lets try  CossackRun.flc.  When opened, the tabbed FLC Viewer appears.  The first tab lists basic information about the unit.  

The next tab, 'View Animation', is where the fun begins.  When you select the tab, you see the animation... animated.  The compass allows you to view each direction.  The Civ Color drop down lets you change the unit's color to any civ's color (by number only right now... I haven't got a cross reference of numbers to civilizations).  The Alpha Blend check box is my vote for coolest new feature <grin>.  It emulates the alpha blending done in the game by putting the unit on a grey background.  Give it a try!  Please note, tho, that this is just an approximation - the values used in the game aren't known.  Finally, the frame delay slider allows you to adjust the animation speed.

Tab 3, Extended Information, is boring, and you probably wont ever need it.  It contains two reports - the Sanity Check and the Chunk report.  The Sanity Check is run as soon as a FLC file is opened.  It's just a  series of tests that ensure the file is valid.  In future releases, the number of tests in the Sanity Check is likely to increase.  The chunk report is just a breakdown of the flc file, by chunk and subchunk.  Useful mainly for debugging.

The next tab, Palette View, allows you to see the palette in use.  The Civ Color dropdown from the viewer is duplicated here, letting you see how various civ palettes affect the overall palette.

The final tab, Export, is the real heart of the matter.  From this tab you can export the FLC to one of three PCX formats, or even to multiple standard FLCs, a la FLICster 0.2.2 (although this function is deprecated, and should be avoided).  Exporting also allows many other options.  The frame size can be increased (but not decreased), up to the maximum 240x240.  The frame count, or number of frames per direction, can also be changed, from a minumum of 1 (not much animation happening) to a maximum of 64 (this upper limit is arbitrary, and could be increased in the future.  I was worried about file sizes.  The longest animations I've seen in the game are about 20 frames).  Additional frames are blank.  Truncated frames are removed from the END of each animation.  The palette can be changed to any Civ's colors on export, and the speed can also be adjusted (this number represents the delay, in ms, between frames).  Finally, the Base file name (such as CossackRun) and the export directory can be changed.

To try it out, export our cossack, but change his palette to Civ Color 6 (blue).  Leave the other settings at default for now.  After the export is complete, you will be asked if you want to open the new FXM file.  This is how your view a PCX export (or create a new UnitFLC from it) - by opening the FXM file.  Answer yes.  The FXM viewer should look hauntingly familiar - its based on the FLC viewer we just met.  If you flip to the Animation tab, you will see our cossack is now in blue.  Now, for some fun.  Click the 'Popup mode' button.  The app is now converted to the FLICster PCX Watcher until you close the watcher.  The PCX Watcher is an always-on-top utility for seeing your PCX changes in action.  Note that you can collapse the options panel to save space.  Leave the pop-up popped-up and tuck it in an unused corner of your screen.  Now, use explorer to navigate to c:\program files\infogrames interactive\civilization iii\art\units\cossack\FLICster (adjust if you used a non-standard install directory for Civ3).  Find the file CossackRun.PCX, and open with the gfx program of your choice.

The PCX file you've opened is a 7 by 8 grid showing all the frames exported from CossackRun.flc.  Each direction has its own row.  If you are using Paint Shop Pro, or any program that will read a JASC PAL file, try this.  From the menu, choose Color|Load Palette... browse to ...\cossack\FLICster, and load the file "CossackRun_Alpha.pal".  BE SURE TO CHOOSE "MAINTAIN INDEXES" before clicking ok.  You've been warned.  The result should be that the file now appears to be on a grey background, with proper shading.  This is a nice way to check shading details, but I don't recommend editing or saving with this palette.  Also, if you need to change the colors of your palette, there are additional concerns when viewing the *_alpha.pal file - see the palette editing addendum at the end of this secton for more info.

To change back, either use undo, or Load Palette again, this time opening "CossackRun.PAL".  You should once again have the hideous green shadow on magenta background that we all adore.

Now, lets try an edit.  Zoom in on the top-left frame.  For the purposes of this walkthrough, just make a put something in the empty area in the top left corner of the frame.  Try selecting a 1 pixel brush, and create a little 5x5 'X' or something.  This is just a simple demo!.  Now, save the file.  If you look at the popup... nothing changed.  This version does not automatically monitor for file changes.  Just double click the animation to see your changes.  If you don't see anything, make sure your popup is still viewing SW.  You should see your X wink in every 7th frame.  Now click the X at the top right to close the watcher, and return to the main FLICster window.  

Switch to the export tab on the FXM viewer.  Notice the default export type for a FXM is Civ3UnitFLC.  If you click to change, you'll see that you can also re-export to any of the PCX variations.  This means that if you start editing an animation, and decide you need more frames, or bigger frames, don't try to enlarge the PCX by hand.  Just open it with FLICster and re-export it, making the changes with FLICster.  For this demo, leave the export type as Civ3 Unit Flc.  You will also notice that the option to change frame size and frame count are not available when creating a FLC - only when exporting to FXM (PCX).  It's just simpler that way.  If you click Export now, a new CossackRun.FLC will be created in the Cossack\FLICster directory.  To see the unit in game, just rename your old CossackRun.flc, and copy the new one into the main Cossack directory.  THERE!  You just created a custom Civ3 Unit!

Read the section below titled "THE FUTURE" to learn about upcoming enhancements planned for FLICster.

**Additional info about editing PCX files and Palettes:  Chances are, you will need to edit your palette at some point.  If you start from scratch (File|New...) you are almost certain to, since you only get the 64 civ-specific colors to start with.  Even editing an existing FLC, sometimes you just need a new color.  This section covers some VERY IMPORTANT caveats about changing your palette.

The 256 colors that make up a Civ3UnitFlc's palette are not all equal.  If you open a FLC in FLICster and go to Palette View, you will see the palette arranged in 16 rows of 16 colors each - the same way that the PaintShopPro palette editor shows the palette.  The first 64 colors, or 4 rows, are civ-specific colors, and can change for each civ.  Change the Civ Color in the drop down to see this.  You should NEVER change the colors in the first 4 rows.  Doing so shouldn't break anything, but the effort is futile, since Civ3 will replace the first 4 rows in your unit's palette with a set of Civ-Specific colors anyway.

The last 32 colors (last two rows) are also special - these are the Alpha Blending palette entries.  Note that I called them palette entries, not colors.  This is because the colors appearing in these positions are just place holders.  Each palette position in this range specifies a certain level of Alpha Belending.  The last position, which is normally magenta, is used to indicate full transparency.  The other 15 colors in the last row form a transparency ramp, down to fully opaque black.  These varying levels of transparency are used to create shadow effects.  The 16 positions in the next-to-last line seem to form a ramp from transparent to fully opaque white, and are used to form smoke and haze effects.  These palette entries are used in animations like BattleshipAttackA.flc to create the smoke from the big guns.  Please note that the gray values I use when simulating alpha blending are my best guesses - I haven't been able to get any info about how the game ramps everything.  Again, you should not edit these colors unless you know what you are doing. 

The rest of the palette is yours to edit.  Just be sure you NEVER perform an operation like Increase colors or Decrease colors - this will totaly screw up your palette.  When creating your animation, remember that if you use any colors in the first 4 rows, they will be subject to change with each civ, and if you use any colors in the last two rows, you will get shadow or haze in game. 


CHANGE HISTORY
-------------

CURRENT: v1.0.1 (build 18)

This one is just a quick bugfix release:
 * Fixed a bug that caused some units created from PCX exports to crash civ3.  The Anim_time in the FlicAnimHeader was being written as a 0.
 
 * Added code when opening a FLC to check for the condition listed above.  If a FLC is opened with an invalid FlicAnimHeader value, FLICster will offer to fix it on the spot.  You can accept, decline, or cancel opening the unit.
 
 * Added .PAL file creation when exporting to Multi-Flc format (FLICster 0.2.2 compat).  This was supposed to be in the original release, and was overlooked.  Note that only the actual palette is exported; the "alpha" palette available for PCX mode isn't created, since it doesn't work when using Animation shop to export a frame to PaintShop Pro. I'm looking into a way to address this in a future release.
 

v1.0.0 (build 17)

Where to begin? Here goes...
 * New FLC Viewer.  Allows viewing of Civ3UnitFlcs.  Each direction can be viewed.  Units can be viewed with default colors or with any civ-specific colors.  Also allows viewing with 'simulated alpha blending', to show how shadow effects actually look.
 
 * New Export formats: StoryBoard PCX, Filmstrip PCX, and Cel PCX.  Storyboard creates a single PCX containing all frames of all directional animation laid out in a grid.  Each direction is tiled left-to-right in its own row.  Filmstrip is similar, except that each direction's row of frames is saved to a different PCX file.  Cel creates a separate PCX for each frame in each direction of the animation.  Exporting to these formats also creates a FXM (FLICster eXport Manifest) file, containing information required to create a new Civ3UnitFlic from the PCX File(s).  Storyboard and Filmstrip formats can include an optional border (recommended!).
 
 * New FXM Viewer.  The FXM viewer allows the animations stored in a PCX Storyboard, or PCX Filmstrips/Cels, to be viewed just like a completed FLC.  Viewer features are the same as the FLC viewer.  Additionally, the FXM viewer has a 'Popup' mode, which hides the full application, and displays an always-on-top version of the viewer, for checking your progress while editing the PCX file(s).
 
 * Change more stuff - when exporting to PCX, you can change the frame size, frame count, filename, color palette, and animation speed.
 
 * Start from scratch - Just select File|New... to create a blank StoryBoard (or other PCX format).
 
 * Support for single-direction Civ3UnitFlcs, such as CruiseMissileDeath.flc
 
 * Additional PAL file created with 'Alpha' coloring.  See 'HOW TO USE IT' for important details.
 
 * FLICster 0.2.2 style 'split' and 'merge' functionality is still supported, although it is deprecated.  To split a file into standard FLC files, open the Civ3UnitFlc and set the export type to 'Multiple Standard FLCs'.  Still creates an INI file.  To merge the standard FLCs into a Civ3UnitFlc, Choose File|Open... and select the INI file.  You may need to set the file type to "*.*"
 
 * Help|About... function.
 
 * Rewrote the hell out of this readme file.  Sheesh.  Dropped 'the gory details', at least for now.  I may update all that info and post it somewhere in the future.
 

v0.2.2 (build 5) beta

 * New versioning scheme.  The build numbers will always go up, even with major version changes.  The build numbers may also skip, because not all builds get released.
 
 * Fixed a merge bug causing incorrect chunk counts in frame headers after direction 0
 
 * Fixed a merge bug caused by assuming color_256 chunks always follow a byte_run.  Sometimes they precede it.
 
 * Now sets the Creator field of the standard FLC header to 0xF2F2F1F1 when merging.  Civ may crash if another number is present.
 
 
v0.2.1 (build 2) beta  (originally called v0.1.2)
 
 * added palette export to .PAL file
 
 
v0.2.0 (build 1) beta  (originally called v0.1.1)

 * first released version


LICENCING
---------

FLICster is Free for non-commercial use.  Use it, abuse it, share it with your friends.  Just dont:
 - distribute just part of it.  If you share it share the whole thing (including this README!)
 - Get indignant if it breaks.  It's worth every penny you paid for it.  But tell me if you have problems, I will try to help/fix.
 - forget to backup your art\units folder.  Really.
 - Decompile.  I'll may release source code once I clean it up (but no promises).  If you just cant wait, e-mail me.

You may not sell any portion of the product, or any files created by the product.  This includes releasing said files as part of a free patch or upgrade for users of a program you did sell them.  If you are interested in using FLICster in such a capacity, please contact me using the email address at the top of the file.
 
Want to publish FLICster on your website?  That's fine, just please keep it all together, with this readme.  As a courtesy, send me an email with your website's URL.  I like to visit.


THE FUTURE
---------

Well, I've put alot of time into this release.  Alot.  Certainly alot more than the orginal version.  Thing is, I've really enjoyed it.  I've learned alot of new things.  The following is the section of my punchlist labeled 'For future enhancement'.  If you have enhancements you'd like to see, email me or post it to the FLICster thread on http://forums.civfanatics.com.  I won't promise any of these will be done, but I'd bet at least some will.

* Allow viewing of multiple animations in sequence, such as default->attack->death
* better alpha blending 
* auto-notify of pcx file changes for popup viewer
* add palette helper - take all colors from 254 down which match, and change to a ramp
* Add more sanity checking (pcx & flc sizes, geometries, etc)
* INI file support for the INI files used by Civ
* Distribution support: civilopeadia, icon, sounds, inifile, BIC, distro package
* true alpha blending with maps for backgrounds
* shell to pcx editor option
* progress bars on exports
* register FXM file type, optionally reigster FLC
* turntable mode in viewer


APPOLOGIES & CREDITS
--------------------
Big thanks to SWB of Civfanatics' "CIV3 Creation and Customization" forum (http://forums.civfanatics.com) for getting the ball rolling on this.  Thanks also to Dan Megha of firaxis for reading the threads and getting Mike Breitkreutz, a Firaxis developer, involved.  Big Thanks to Mike Breitkreutz for sending SWB a rundown of the custom parts of the format.  ANother round of thanks to SWB for posting that info, and a link to an excellent FLC format reference at http://www.compuphase.com/flic.htm.  These are the resources I used to build this thing.

Thanks to those who've provided feedback &  test files, and tested internal builds-  Eric Tan, Zippo, Smazza, Heardie, Blue Orange.  Special thanks (again) to SWB for setting me straight on unit-specific palettes, and to Blue Orange for finding the Magic Number bug.

Special thanks and a big plug to Matthew Curland, author of "Advanced Visual Basic 6: Power Techniques for Everyday Programs".  If you think of yourself as an advanced VB developer, you must read this book - but read it slow.  Some of the material is very advanced.  The stuff he does is amazing.  FLICster uses many of his techniques.  



