JdNoa's AniCam (Beta 3) 0.3

AniCam
Author: JdNoa - [contact info in read-me]

Notes on dlg fields compiled from observations by Tupac Amaru, Dashus, and JdNoa.
Tupac Amaru did most of the testing for this.  Thanks!
Thanks also to tk102 for updating DlgEditor for us & Darth333 for passing it along quickly.  It made testing *much* less painful. 
Thanks to several people for their notes/code about the mdl format: Torlack for notes on binary mdl and for NWNMdlComp, sorcerer for notes on ascii mdl, and cchargin for MDLOps.

---------------
Version
---------------
Beta 3 - Dec 1 2005

History: beta 3 should fix the bug where cubic interpolation treats angles as numbers and so interpolates the wrong way across the 360 degree mark.

---------------
Description.
---------------
AniCam is an internal tool used by TSLRP (The Sith Lords Restoration Project).  It is being released to the public "as is".  There is no warranty, implicit or explicit, of any kind.

AniCam is an animated camera editor for KotOR 2.

Animated cameras are just models in a specific format.  AniCam lets you open & edit existing camera models or create your own.  You can then use the animated camera model in a .dlg.

---------------
Installation
---------------
Requirements:
    JRE 1.5 or newer.  (Developed with 1.5.0.04).
    AniCam will not run with JRE 1.4.

Simply extract this zip to your preferred install location and run the jar file, AniCam.jar.

---------------
Uninstallation
---------------
Delete the files that came in the .zip, plus the configuration file anicam.conf (if it was created).

---------------
1. How to use AniCam:
---------------

--- 1a. Basics:

Fill in your desired camera name and the length in seconds of the camera shot.

Add entries for your camera.  An entry needs the time in seconds, position as x,y,z, and orientation as h,p,r.  (heading, pitch, roll).

To add an entry, select "insert row" from the Edit menu or type ctrl-i.

Orientation is done in degrees.  Straight ahead is (0,90,0).  Left is (90,90,0).  Right is (-90,90,0).  And so on.

If you're getting position from WhereAmI, keep in mind that the Z location given is lower than what you see (I think it's the location of your feet).  You probably want to add 3 or 4 to get a shot at eye level.

When you have all of your entries, select save from the file menu.  The files cameraname.mdl and cameraname.mdx (which is an empty file) will be created.  These can go in your override folder.

To use the new model, set the camera model field in a dialog, then in the dialog entry/entries that will have the camera shot, set the CameraID to -1, use CameraAngle 4, and set CameraAnimation to a useful number (probably 1200 or 1000: see part 2 for details).

An example:
Entry  Time    x       y       z        h     p      r
1          0.0    -70      20    3.5     0    90    0
2          3.5    -70      30    3.5   70    90    0
3          4.5    -70   31.5    3.5   50    45    0
4          6.5    -72   31.5    3.0   30     0     0

with animation length 7.5.

This will (1) start looking straight ahead,
(1)->(2) move along the y axis and rotate left,
(2)->(3) rotate right and down while moving a little more along the y axis,
(3)->(4) rotate right and point straight down while moving a little along the x axis,
then (4) hold position for 1 second.

-- 1b. Interpolation:

If interpolation is selected, then when you save, extra intermediate entries will be generated to smooth out changes in position and orientation.  So, if your entries have the camera going straight forward, and then moving left, instead of an abrupt transition from forward to left, the camera will move in a curve.

If interpolation is not selected, what you entered is what you get.  Sudden changes in direction will be abrupt.

-- 1c. Importing:

You can import from a binary model, an ascii model, or xml.

For both binary and ascii models, I'm only looking for the data found in the standard animated camera models.  This means that there is a single node, called camerahook, with animations called CUT###W (where ### is a number, usually 001), which has positions and orientations.  The import routines can't handle anything else - no mesh nodes, no emitters, etc.
(Note that, if you're looking at the original camera models, importing 003EBOcam.mdl will fail because they misspelled "camerahook" - the camera won't work in-game, either.)

The XML import is *very* limited and has pretty much no error checking.  It was set up to import data from Excel.  If you enter your time, position, and orientation in Excel - like on the main screen for AniCam, but without the "entry" field - and then save as XML, you should be able to import into AniCam.

---------------
2. Indices, Multiple Animations, and your Dialog
---------------

-- 2a. Multiple Animations and their Indices

One camera model can have multiple animations.  As a .dlg file can only have one associated camera model, this lets you do multiple animated camera shots in one dialog.  (An example: kreiatch.dlg in 301NAR uses 2 of the 3 animations from 301narcam).

Each animation has a name of the form CUT###W, where ### is a 3-digit number.  The number should be 001 or greater.  If there is only one animation, usually the single animation is called CUT001W.  This is not required (101percam uses CUT002W).

When you add an animation to your camera model, the ### is what you're putting in the "New Index" box - so if you enter 5 and click New Animation, you'll get a new animation called CUT005W.

-- 2b. Some general notes on using animated shots

1. Once you start an animated camera shot running, it *keeps* running, in real-time, even if you've switched to static shots.  If you do 'start animation'->static shot->'continue animation', the second animated shot will probably be at a different position/orientation if the user clicked to skip one of the earlier nodes in your dialog, or if they had to choose a response.

2. Only one animation will run at a time.  If you 'start animation' with CUT001W, then 'start animation' with CUT002W, then 'start animation' CUT001W again, the final call will start back at the beginning of CUT001W's camera shot... it won't pick up where it left off the first time.  And if you do 'start animation' CUT001W -> 'start animation' cut002W -> 'continue animation' cut001W, the 'continue animation' will continue with cut002w, not cut001w.  Once you start a given animation running, it's the only one you can use until you start another one.

-- 2c. Your .dlg file:

Useful fields are Camera Model in your dlg header, and CameraID, CameraAngle, CameraAnimation, Delay, and WaitFlags in your entries.

-- 2c.1 Camera Model

In the dialog header ("General Properties" in DLGEditor), set the Camera Model to your new camera's name.  

-- 2c.2 CameraID and CameraAngle

Every node that is animated uses CameraID -1 and CameraAngle 4.
(Although all the Obsidian .dlg's use CameraAngle 4, other CameraAngle values will also work.)

-- 2c.3 CameraAnimation

You also need a CameraAnimation field in each entry using an animated camera shot.
CameraAnimation is where you specify which animation to use if you have multiple animations.

'start animation' is 1200, 1201, etc.
To start CUT001W running, use CameraAnimation 1200.  To start CUT002W, CameraAnimation 1201.  And so on.

'continue animation' is 1000.  Or 1001, 1002, but...
...in the official .dlg's, at the very least, 1000, 1001, 1002, and 1401 are used - but testing doesn't show any difference in using them.  If you start with 1200, then call 1001, it's not going to jump to the other animation.  If anybody sees a difference between these, please let me know!

-- 2c.3a Start/Continue and the end of the animation

Your animated shot is 20 seconds long, but you gave the user a choice of responses in between animated shots, and they took 30 seconds to pick a line.  What do animated .dlg entries do after the end of the animation?

If the entry is set to 'continue animation', it will hold the last position/orientation from the animation.

If the entry is set to 'start animation', it will re-start the animation.  You could probably do some looping with this.

If you reach a 'start animation' entry and the current animation hasn't finished, the behaviour depends on which animation you specify.  If it's the same one that's already running, it won't restart - it'll continue, acting like a 'continue animation' entry.

-- 2c.4 WaitFlags

If you set WaitFlags to 1 and use 'start animation', the entire camera shot (or the remaining portion) will be used in one entry.  This won't work if you use 'continue animation'.
If you leave WaitFlags at 0, the camera shot will run for as long as the entry does, so you can either have VO or set the Delay field.
(WaitFlags = 3 is used in kreiatch.dlg, but I've seen no difference between WaitFlags=3 and WaitFlags=0 in my testing).
Setting WaitFlags doesn't block the user from skipping the entry.

-- 2c.5 Delay

If WaitFlags is not 1, the animated shot in your entry will last as long as the VO lasts, or for the length of your Delay field if it's set.  If there's no VO, like the long animated shot of the ruined Dantooine enclave, then you'll want to set Delay to specify how long your camera shot lasts.  Delay is set in seconds.  Note that if you set Delay=0, it seems to override your VO length, so it may skip lines.  If you're not using Delay it should be -1, not 0.

-- 2c.6 CamVidEffect doesn't work

CamVidEffect will *not* be applied to animated camera shots, but you can use a script to turn video effects on and off.  Check out the first two nodes in intro.dlg in 001EBO: they call a_video_effect to turn T3M4's freelook on and off.  (Notice that the developers tried to use CamVidEffect!)  The a_video_effect script simply calls EnableVideoEffect(VIDEO_EFFECT_FREELOOK_T3M4) or DisableVideoEffect().  Don't forget to disable your video effect, or it will stay on forever.

---------------
3. Some examples from the original files:
---------------

These are a few places where camera models are used in different ways:

kreia_kr.dlg in 701KOR has a camera shot that spans several entries.  Under "{Intro to 701KOR...", it starts at "{Animated camera begins}" and ends at "{Angry at end...".

kreiatch.dlg in 301NAR has an animated camera that plays intermittently.  It has animated angles followed by static angles followed by animated angles.  It also uses two different animations, CUT001W and CUT003W.

enc_ruin.dlg in 605DAN consists of one long animated shot.