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

    CS 318: MP3 -- The World in Motion
	see http://www-courses.cs.uiuc.edu/~cs318/mp/mp3/mp3.html for details

     First Name : Benjamin
      Last Name : Gottemoller
	  NetID : gottemol

    Enrolled as : [X] Undergrad   [ ] 3/4-unit grad  [ ] 1-unit grad

    (Estimated) Number of hours spent: 45 ack!!!


==============================================================================
[Camera Movement]:

    ----Keys->

        Toggle Mouse Look...........M

        Yaw Left....................Left Arrow
        Yaw Right...................Right Arrow
        Pitch Forward...............Up Arrow
        Pitch Backward..............Down Arrow
        Move Forward................W
        Move Backward...............S
        Strafe Left.................A
        Strafe Right................D
        Ascend......................Left Shift
        Descend.....................Left Ctrl
        Fire Weapon.................Space Bar
                

    ----Mouse->

        (If mouse is toggled 'ON' by pressing M):
        
        Yaw/Pitch...................Mouse Movement
        Fire Weapon.................Left Mouse Button

        NOTE: When the mouse cursor hits the edge of the screen you
              unfortunately can't turn any further in that direction. 


==============================================================================
[Key Frame Animation]:

    ----Playing Animations->

        1. From the menu select "Animation"
        2. In the drop down list there are 3 sub-menus
                - Camera
                - Character1 (Flying Cone)
                - Character2 (Clunky the hierarchical object)
           Select the one you want and another sub-menu will appear
        3. From this sub-menu select "Play", "Stop", or "Reset" to 
           Start/Stop/Reset the animation sequence.

        NOTE: The "Character1" object is the cone located near the 
              ceiling of the world. The "Character2" object is located 
              near the ceiling but towards the center.

        NOTE: If "Show Interpolation Path" is selected from the 
              animation menu the animation paths for the the camera, 
              character1, and character2 will appear outlined in green.


    ----Editing Animations->

       *Key frame data is stored in *.cfg files and can be edited with 
        notepad.
       
       *The key frame files for the camera, character1, and character2
        can be found in the project's "key_frames" directory. (character2
        is somewhat complicated since it is hierarchical so it will be 
        covered in the next section)

       *The key frame (*.cfg) file format is as follows:

        -------------------------------------------------------------------
        NumKeys: N
        Time: [T]     Position: [X, Y, Z]     Rotation: [Yaw, Pitch, Roll]
        Time: [T]     Position: [X, Y, Z]     Rotation: [Yaw, Pitch, Roll]
        ...
        Time: [T]     Position: [X, Y, Z]     Rotation: [Yaw, Pitch, Roll]
        -------------------------------------------------------------------
        
        -'N' is the (integer) number of keys
        -'T' is the (float) time stamp for the key
        -'X', 'Y', and 'Z' represent the (float) position for the given 
         timestamp 'T'
        -'Yaw', 'Pitch', 'Roll' represent the (float) orientation for the 
         given time stamp 'T'

        NOTE: spacing is very important so if you need to add keys it is 
              recommended that you copy and paste a key that already exists
              and then modify its values.

       *You can take a look at "character_key_frames.cfg" in the "key_frames" 
        directory to see an example.

       *The 'camera' key frame file is labelled "camera_key_frames.cfg"

       *The 'character1' key frame file is labelled "character_key_frames.cfg"

       *The 'character2' (clunky) key frame files that control the hierarchy
        are located throughout the "clunky" directory and its sub directories.


==============================================================================
[Hierarchical Motion]:

    ----Playing The Hierarchical Model Animation->

        1. From the menu select "Animation"
        2. In the drop down menu select "Character2 
           (Clunky the hierarchical object)"
        3. Select "Play"
        4. You should see the object near the ceiling towards the center.


    ----Editing The Character2 Animation->

       *Since Clunky is a hierarchical model it needs key frames for *each*
        of its components. The hierarchy is stored in memory as a tree with
        each node having a variable number of children. File trees have the 
        *same architecture* so that's why Clunky's key frame (*.cfg) files are 
        spread out through a bunch of sub directories in the key_frames folder. 
        If you really need to edit Clunky's animation you can look at the 
        rendering of him in the demo and determine what the tree looks like (The 
        blue sphere is the root node). From that you can see what location in 
        the *file tree* corresponds to what component of Clunky. Once you know
        the key frame (*.cfg) file you want to edit you can follow the procedure
        described in the "Key Frame Animation" section.

        NOTE: The Position[] components of ALL *CHILDREN* NODES is ignored since
              position is determined by their rotations off of the root node.

       *Starting at approximately line 228 of mp3.cpp you will find the function
        "CreateClunky()". This is where the Clunky character is setup. I've 
        formatted the code to make it easier to see the tree layout of the object.
        This layout exactly matches the "clunky" file tree. Hopefully this will help
        if you want to make changes to the key frame data.


==============================================================================
[Physical Particles]:

        NOTE: The particles are billboarded textured quads with alpha 
              transparency. The video cards in the lab don't seem to have any
              problems with them, but there could possibly be problems with 
              really old video cards that don't support hardware alpha 
              transparency.

        NOTE: All particles are given a 'life' when they are created. Eventually
              this value gets to zero and the particle disappears. This was done
              to keep the particle count down, so don't be surprised to see 
              particles vanish after a certain amount of time.

       *Particles (normal and spring particles) should be all over the place 
        shortly after you start the demo.

       *You can create more by firing your weapon.

       *If things get choppy because there are too many particles, you can disable 
        them by selecting "Particles" and then "Disabled" from the menu.


==============================================================================
[Spring Forces]:

       *You can identify spring particles because they are connected together
        by a semi transparent blue line.

       *There are 2 fountains spraying spring particles from the side walls and
        one in the center of the world on the floor spraying a mix of both spring
        and regular particles.


==============================================================================
[Particle Collision]:

       *All particles bounce when they strike a side of the world. You can fire 
        the weapon at any side to test this.


==============================================================================
[Texture Mapping]:

        NOTE: All textures must be in the *.bmp file format and of a size that is
              a power of 2.

       *Textures are applied to all particles as well as the cube that makes up
        the world.

       *All the texture files used in the project can be found in the "textures"
        folder.

    ----Changing Textures->

        1. Select "Set Textures" from the menu
        2. Select the item you want to change the texture for.
        3. In the file browser that appears locate the texture file you want 
           (MUST BE A BMP FILE).
        4. Select "OK"




