Page Comparison

JS API - updates required

...

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.

...

• getCameraPosition() – returns current position of camera (POINT object)
• cameraPosition([walk[, crab[, float[, duration[, easing]]]]]) – a combination of the 3 functions below, specify null for any of walk/crab/float if you don't want to alter. Call function without any params to stop all position transitions.
  • cameraWalk(distance[, duration[, easing]]) – like ↑ and ↓ keyboard shortcuts in-game, +ve distance = forward, -ve = backwards, 0 = stop
  • cameraCrab(distance[, duration[, easing]]) – like ← and → keyboard shortcuts in-game, -ve distance = left, +ve distance = right, 0 = stop
  • cameraFloat(distance[, duration[, easing]]) – lift or drop the height of the camera, +ve distance = move up, -ve distance = move down, 0 = stop
• centreView(x, y) – the camera instantly moves to look at an x,y location (ie. no transition or easing) [does this also change lens pan/tilt?]
• cameraSlide(x, y[, duration[, easing]]) – the camera slides over terrain to specified position – can we add 'duration' and 'easing' params, with duration defaulting to whatever current duration is?
• eventCameraMoveeventCameraPosition(beforeChange) –  – triggered before a settled (stationary) camera starts movingeventCameraSettle() – triggered after a moving camera settles (stops moving)just before a position change, or just after a position transition ends

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.

• getCameraLens() – return object with pan, tilt, roll, zoom properties
  
• cameraLens([pan[, tilt[, roll[, zoom[, duration[, easing]]]]]]) – a combination of the 4 functions below, specify null for any of pan/tilt/roll/zoom if you don't want to alter. call function without any params to stop all lens transitions.
  • cameraPan(angle[, duration[, easing]]) – look left (-ve angle) or right (+ve angle), in relation to north, like Ctrl + Left/Right mouse-drag in-game
  • cameraTilt(angle[, duration[, easing]]) – look up (+ve angle) or down (-ve angle), in relation to horizon, like Ctrl + Up/Down mouse-drag in-game
  • cameraRoll(angle[, duration[, easing]]) – like tilting your head to the side, +ve angle to the right, -ve angle to the left, 0º for no tilt (horizontal camera).
  • cameraZoom() – add optional 'easing' parameter, could 'time' param be renamed to 'duration'?
• eventLensChangeeventCameraLens(beforeChange) – triggered just before a settled lens starts panning/tilting/zoomingeventLensSettle() – triggered after a panning/tilting/zooming lens settleslens change occurs, or just after a lens transition ends

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 so the to make camera watches an object (POSITION, POINT or Game object)watch an object...

Note: The camera can only have one target at a time. Setting new target replaces old one.

• getCameraTargetgetCameraWatch() – returns current object with target,mode,allowMove properties, or null of no targetcameraLookAtif not watching anything
• cameraWatch([target[, allowMove[, duration[, easing]]]]) – camera pans/tilts to look at the target, optionally moving to get a better view, then settles (clears the target)cameraMonitor([targetmode[, allowMove[, zoomMode[, duration[, easing]]]]]) – similar to cameraLookAt(), but the camera will continue adjusting whenever the position of the camera or subject changeseventCameraTargetsee notes below
• eventCameraWatch([target]) – triggered when target changes, only passing in a target when a new target is set using functions above.

The cameraLookAt() and cameraMonitor() functions can be called with no parameters to cancel them (note: cameraLookAt() automatically stops when the target comes in to view).

Obviously, if the target is destroyed, that cancels the effects of the function, and still triggers eventCameraTarget().

Parameters:

• allowMove defaults to false. If true, the camera will slide to get a better view of the target but will not trigger eventCameraMove() or eventCameraSettle()
• zoomMode if just started watching, or null if just finished watching

Does not trigger eventCameraLens() or eventCameraPosition().

Camera will stop watching target if:

• cameraWatch() is called with no parameters
• The function is called again but with a different target
• The target gets destroyed
• Any other lens transition occurs

Parameters:

• target – a POSITION, POINT or Game object. If duration specified, camera will transition so that the target is in view, optionally moving (allowMove) to get a better view
• mode can be one of the following:
  • MANUAL_ZOOM – LOOK_AT (default) – camera transitions to look at target (auto-pan/tilt and optionally move) then stops (clears target)
  • MONITOR – camera continues to watch the target (auto-pan/tilt and optionally move), but the zoom won't be altered automatically (default)
  • TRACK_ZOOM – if the same as MONITOR, but zoom will automatically be adjusted whenever distance between the camera and target changes (ie. either the camera or the subject move), the zoom will be automatically adjusted so if either of them move) so that the target appears to remain roughly the same size
  • DOLLY_ZOOM – same as TRACK_ZOOM but also alters field of view (formulas)
• allowMove – if true, the camera can be moved to get a better view of the target, same duration/easing applied to the move. Default: false

Following objects:

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

• getCameraAnchor() – returns the object containing target (usually a droid object) and offset (POINT object)
• cameraAnchorTocameraAnchor([target[, offset[, duration[, easing]]]]) – see notes below
• eventCameraAnchor([droidtarget]) – triggered when anchor changes, only passing in a droid when a new anchor is set is set using cameraAnchor().

Calling cameraAnchor() with no parameters un-anchors the camera. Obviously, if the object gets destroyed, the camera is un-anchored.

Parameters:

• droid – the droid target if just started following, or null if just stopped following

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:

• cameraAnchor() is called with no parameters
• The function is called again but with a different target
• The target gets destroyed
• Any other position transition occurs

Parameters:

• target – the object to anchor to. default: un-anchor the camera
• offset – a POINT object defining the camera position's offset from the centre of the droidobject so, for example, so you can put camera behind / in front / at the side / under or over the droid and at any distance from it – default: behind the object like in drive mode

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

Once the camera reaches the droidobject, or offset from that object, the camera's position and roll settings are get linked to the droidthe 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 droid 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")...

• getCameraStrafe() – returns the current subject being strafed, or null of not strafing
• cameraStrafe([target[, speed[, radius[, duration[, easing]]]]]) – like in-game when you win/lose and the camera circles around the HQ
• eventCameraStrafe(target) – triggered when anchor changes, passing in a target if just started strafing, or null if just finished strafing

Once started, strafing can be stopped by:

• calling the function with no parameters
• object gets destroyed
• camera anchored to some other object
• any function that sets x,y of camera

Parameters:

• taret – the object to strafe, can be POSITION, POINT or Game object. Default: stop strafing
• speed – speed at which camera moves around circumference in tiles per second (-ve = anti-clockwise, +ve = clockwise). Default: whatever speed camera moves at when scores are shown at end of game.
• radius – distance between target (centre of circle) and circumference, in tiles. Default: same as VTOL circle radius

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 look watch at the droid. In fact, the camera could be monitoring watching something completely different, or not monitoring watching anything (static pan/tilt/zoom values). For example, the camera could be monitoring watching the HQ, then I tell it to anchor to a VTOL – it's like I'm in the VTOL looking out the window at the HQ.But sometimes 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:

...

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.