JS API - updates required

Objects:

Will require a new object type (and associated constant):

Duration / easing:

Many of the features mentioned below have duration and easing params – Both are optional:

The easing equation functions would be called with fixed params as shown below:

function whatever(elapsedTime, originalVal, delta, duration) {
	// elapsedTime = number of ms since tween started
	// originalVal = value at start of twean
	// delta = targetValue-originalValue
	//         ...where targetValue is what you want at the end of the tween
	//         The C++ code only needs to calculate the delta once at start of tween
	// duration = total duration of the tween in ms
 
	var valAtCurrentTime = // some math
	return valAtCurrentTime;
}

(This would also mean other things could use those easing functions - such as setSunIntensity() and setSunPosition(). You could even have an AI that tweens it's aggression from A to B during the first 10 mins of the game.)

Demos of the various algorithms can be seen here, and BSD-licensed source code (in actionscript) is available here – very easy to port to JS. Functions requiring additional params can be curried.

I don't know how the C++ code will be implemented, but if one aspect of the camera is already being animated and then something else happens that affects the same properties, the previous animation should be cancelled.

For example:

Another example:

Hope that makes sense! (smile)

Camera position:

Note: cameraSlide(x, y, 0) == centreView(x, y)

Is it worth ditching the individual functions for walk, crab and float to reduce number of functions?

(The events are important in the case of "recording" manual camera moves in a cut-scene editor.)

Camera lens:

Note: As it's a virtual camera, I've treated roll as if it's an attribute of the lens (whereas in real-life you actually roll the entire camera). Roll just seemed to fit better here, as it doesn't change the POINT position of the camera.

Would azimuth and altitude make more sense than angles for pan and tilt?

Is it worth ditching the individual functions for pan, tilt, roll and zoom to reduce number of functions?

Watching objects:

Automates the camera pan/tilt and (optionally) zoom to make camera watch an object...

Does not trigger eventCameraLens() or eventCameraPosition().

Camera will stop watching target if:

Parameters:

Following objects:

The camera position can be automated by making it follow an object (usually a droid object)...

Following non-droid objects is useful if you just want to anchor the camera to some static object but with an offset, and then be able to call the function again with a different object (basically moving camera in relation to static object).

Camera will stop following target if:

Parameters:

The camera transitions to the offset position (unless duration is 0 or null). The offset can be changed while the droid is in motion by calling cameraAnchorTo() again for the same target, but with a different offset.

Once the camera reaches the object, or offset from that object, the camera's position and roll settings get linked to the object – if the object changes position, the camera follows by the same amount. However, there needs to be some 'damping' applied so the camera position/roll updates lag behind the a little. This is to avoid "camera whiplash" (drive mode a circling VTOL and you'll see what I mean) and also avoid a visual effect that makes it look like it's the world, and not the droid, that's moving. For example, if the camera is behind the droid and watching the droid, then the droid suddenly stops, the camera should almost crash in to the back of it!

Strafing:

The camera can be moved in a circular motion on the horizontal plane around an object ("strafing")...

Once started, strafing can be stopped by:

Parameters:

The duration and easing, if set, cause the camera to transition from it's current location to the circumference before it starts to strafe.

Watching & Following a droid:

Anchoring the camera to a droid doesn't make the camera watch at the droid. In fact, the camera could be watching something completely different, or not watching anything (static pan/tilt/zoom values). For example, the camera could be watching the HQ, then I tell it to anchor to a VTOL – it's like I'm looking at the HQ from the window of the VTOL. If allowMove is set on cameraWatch(), and the camera decides to move to get a better look at the watch target, the camera will stop following its anchor.

Sometimes you just want a "drive mode" effect which is what cameraTrack() function is for - it's effectively the same as doing:

cameraWatch(someDroid); // camera will keep looking at someDroid
cameraAnchorTo(someDroid); // camera snaps to a short distance behind droid

The cameraTrack() function is still useful, but would ideally be altered to do the C++ equivalent of:

function cameraTrack(droid, duration, easing) {
	cameraWatch(droid);
	cameraAnchorTo(droid, null, duration, easing);
}

This way, the watch and follow events get called, and I can stop one or the other independently.