========================================================================
         Pygmalion Animator, Version Alpha 0.2 Release Notes
	          Chris "Gwynhala" Burke  13 February, 2001
========================================================================

Pygmalion is a 3D animation program for video gamers. I'm still working
on it, and this is a very eraly version of the program, so it probably
has a lot of bugs, non-working menu items, etc. Use at your own risk.

The main thing Pygmalion is designed to do, is allow animations from one
video game player model to be applied to a new mesh, to create new player
models for that or another video game. Pygmalion also has limited ability
to create new animations, but it's no substitute for the high-end modeling
packages used by video game companies and professional artists.

You can also view animations with Pygmalion. This is handy if you're making
a mod for a game, and want to know the name of an animation so you can
script it into your game.

This version of Pygmalion adds the ability to export meshes from Rune as
in WaveFront .OBJ format, and also limited creation of .SCM files needed
to import models and textures into Rune. There is no animation export, or
animation / skeleton creation capability, in this version of Pygmalion.

All of this will be fixed over time, and many new features are coming. For
the latest news on Pygmalion for Rune, check:
    http://www.runenews.com/rigfolk

Pygmalion is based on my very popular GwynFlex animation tool for Heretic II,
which you can learn more about at:
    http://www.hereticii.com/models.shtml
Look in the tools section for downloads and tutorials.


Installation
------------

Just unzip the archive to any convenient folder.


How To Export Models To Rune
----------------------------
- Get the tutorial at:
  http://www.runenews.com/files.asp?dir=/rigfolk&file=modeltutorial1.zip


How To Use Skins
----------------

- Once your model is imported, use Model->View Materials to see the names of
  all of the materials it uses.
- Use File->Open Textures, or Textures->Load, to load up all of the materials
  you need.
- Use Textures->Rename to change the names of your textures to match the names
  of the materials your model uses.
- Check Model->Solid and Model->Textured
- If the screen is too dark to see your model with textures, try checking
  View->House Lights and / or View->Blue Screen
- The texture will stay across animation changes.


How To View Rune Animations
---------------------------

- Run Pygmalion

- Select File->Open Mesh
- Navigate to your Rune\Meshes folder
- Change the files-of-type to "Rune Files (.UMS)"
- Click on one of the .UMS files (e.g. creatures.ums), click Open
- If a model selection menu appears, select which model you want
  and click OK
- If a mesh selection menu appears, select which mesh you want
  and click OK (sorry, the names aren't very descriptive; UMS format
  doesn't store mesh names).
- When the frame selection menu appears - DON'T SELECT ANYTHING!
  Just click OK. You'll get a real ugly looking bunch of 3D images
  on your screen, but don't worry - those are just the body parts of
  the model.

- Select File->Open Animation
- Navigate to your Rune\Meshes folder
- Change the files-of-type to "Rune Files (.UMS)"
- Click on one of the .UMS files (e.g. creatures.ums), click Open
  NOTE: You should use the same file you loaded the mesh from.
- If a model selection menu appears, select the same model you loaded
  before click OK
- An animation sequence menu appears. Select the name of the animation
  you want to view, and click OK. The screen will still look ugly.

- Select Animation->Loop
- Select Animation->Play->Forward, or click the corresponding toolbar
  icon, to start the animation playing continuously.
- Adjust the camera so that you have a good view of the model. For
  example, if the model is sideways, and too large, press the down
  arrow to move the camera farther away and keypad 6 to rotate the
  camera 90 degrees.

- To select another animation, you can use File->Open Animation, or
  you can use Animation->QuickPick... to load another animation more
  quickly from the same .UMS file.


How To Move The Model and Camera
--------------------------------

- Use the Edit->Control Device dialog to pick the kind of controler
  you want. A "flying" controler changes the view as if you were
  flying an aiplane around the scene (frame of reference is current
  direction). A "position" controler moves and turns its target
  relative to an absolute coordinate system. 
- You can use the keyboard, a joystick, or the mouse for control
- You can control either the camera or the model (object)

- The SHIFT and CTRL keys modify the behavior of the mouse and
  keyboard controllers. Holding SHIFT causes a different kind of
  motion (for example, rotation instead of position control).

- By default Pygmalion uses a flying camera control. This control
  is similar to how a video game works, except you can't change
  the key bindings. Here are the key bindings for the default
  flying camera controller (works best with keyboard):

  Keyboard  Mouse         Function
  --------  ----------    ------------------------------------------
  up        away from me  move camera forward
  down      toward me     move camera backward
  KeyPad/   ---           move camera left
  KeyPad*   ---           move camera right
  right     right         turn camera to look right
  left      left          turn camera to look left
  PageDn    Sh-left       turn camera upward
  Delete    Sh-right      turn camera downward
  PageUp    Ctrl-away     move camera upward
  Insert    Ctrl-toward   move camera downward
  KeyPad+   Sh-toward     turn camera clockwise
  KeyPad-   Sh-away       turn camera counterclockwise
  Shift     ---           slower movement (better "control")
  Ctrl      ---           regain control of runaway camera
  Keypad9   ---           turn camera clockwise 45 degrees
  Keypad6   ---           turn camera clockwise 90 degrees
  Keypad2   ---           turn camera cw/ccw 180 degrees
  Keypad4   ---           turn camera counterclockwise 90 degrees
  Keypad7   ---           turn camera counterclockwise 45 degrees

- You can also select a position object control. This control is
  similar to how you would drag items around on a computer screen,
  but it works in 3D. Here are the key bindings for the position
  object controller:

  Keyboard  Mouse         Function
  --------  ----------    ------------------------------------------
  up        away from me  move object up
  down      toward me     move object down
  right     right         move object to right
  left      left          move object to left
  KeyPad-   Sh-away       move object away
  KeyPad+   Sh-toward     move object closer
  PageUp    Sh-left       rotate object counterclockwise
  PageDn    Sh-right      rotate object clockwise
  Insert    Ctl-away      rotate front of object upward
  Delete    Ctl-toward    rotate front of object downward
  Home      Ctl-left      rotate front of object to left
  End       Ctl-right     rotate front of object to right

- When using an object control with the mouse, remember to left-click
  on the object!

- In addition to the controlers, you can use the Camera menu to
  quickly move the camera to various positions.


Note for Mod Makers
-------------------
- If you use Pygmalion to learn the name of an animation for your mod,
  please remember that Pygmalion adds an "_" to the end of the sequence
  name so that it can name the animation frames. For example, the sequence
  "AttackA" would show up in Pygmalion as "AttackA_", with frame names
  like "AttackA_001", "AttackA_002", etc. The Rune engine won't understand
  the trailing "_", so you should use the name without that final character.


Known Bugs
----------

- Current limits: 8192 verteces, 8192 triangles per mesh. 64 vertex (bone)
  groups, 64 triangle (skin) groups per mesh. 32 textures per mesh.
- Funky vertex normals on generated objects - objects become VERY bright when
  rotated into certain positions.
- Several menu items and listed file formats are just stubs - trying to use
  them does nothing.
- Occasional crashes when loading new body parts while an animation is running.
  To work around, stop the animation before loading new parts.
- Texture export can only export 24-bit textures, and only to .TGA format.


Revision History
----------------


Version Alpha 0.2
-----------------
- Fixed texture export function.
- Added ability to rename a material (Model->Rename Material)
- Modified animation STOP function to restore body parts mesh instead of
  continuing to display most recent animation frame.
- Loading a texture with the same name (e.g. file path) as a previously
  loaded texture, will overwrite the previous texture instead of adding
  another texture with the same name. This is useful when checking out
  iterative changes to skins you're developing, since you can just keep
  reloading the skin after each modification.
- Added code to generate artificial triangle group if a mesh has none.
- Added File->Export->Trivial Mesh for limited .SCM and .OBJ file export.
  The dialog box will list many export file types, but only .SCM and .OBJ
  are supported. The exported .SCM model has one sequence named "BaseFrame",
  one joint, and one animation frame placing the joint at (0,0,0).
- Added prompt for mesh name when loading unnamed models.


Version Alpha 0.1d
------------------
- Quick release to fix incorrect handling of .MD2 file textures.
- Added code to generate artificial skin names for triangle groups having no
  material assigned during import.
- Added "How To Use Skins" tutorial.


Version Alpha 0.1c
------------------
- Lots of internal reorganization.
- Re-wrote .OBJ, .3DS, .UMS, .SCM, .FM, and .MD2 loaders to use new data
  structures and utility routines.
- Fixed bug in tree browser that led to off-by-one frame error when loading
  from files where not every sequence follows the <sequence><framenumber>
  naming convention.
- Changed File->Open to File->Open Body Parts to clarify that this menu
  just loads in body parts (which might not be arranged in any recognizable
  order until an animation is loaded)
- Added ability to play vertex-animated sequences from .OBJ, .FM, .MD2,
  and .3DS files.
- Added material and multiple-object support to .OBJ loader
- Fixed off-by-1 error that prevented display of last sequence of a model
- Added move camera up (Page Up) and down (Insert) to flying controler
- Increased speed of forward and back movement in flying controler
- Eliminated some memory leaks during mesh allocation / deallocation
- Added perky music to Help->About selection
- Added Texture, Texture Library and Model Materials menu functions with
  support for .BMP, .PCX, .TGA, .SCM, .UTX, and .UMS formats.
- Added lame texture viewing capability (background image is set to texture)
- Added option for solid or wireframe model view
- Added move left (KP/) and move right (KP*) functions to flying controler
- Modified single-step to always move to previous or next frame, rather
  than advancing frame based on fractional frames per tick.
- Fixed dropped / duplicated frames bug when changing direction of
  animation playback
- Load / save all controller settings in registry
- Added ability to view models with texture
- Added View->House Lights and View->Blue Screen options for lighting
  and background.
- Added File->Open Textures to load all of the textures associated with
  a .UTX, .UMS or .SCM model
- Added Model->Textured to display animations with model textures applied


Version Alpha 0.1b
------------------
- Added animation playback for Rune
- Recognize multiple frame snapshots in .3DS files
- Heirarchical frame name / sequence name browser
- Fixed toolbar icons, and made some of them work
- Added "CD style" additional toolbar icons for animation control
- Roughed-in support for user-defined skeletons and several new file formats.
  (non-functional code in this release)
- Changed default controller to flying camera
- Changed flying controller to provide a more "game like" control set


Version Alpha 0.1a
------------------
- Coded from GwynFlex base
- Limited model viewing features only


Credits
-------

Pygmalion is Copyright 2001 by Christopher Burke.

Thanks to Paul McArthur, Chris Rhinehart, and Tim Gerritsen at Human Head
Studios for their help with the Rune model format. And to Trisha, for
understanding why I don't always go to bed at night...


