Camera Update

UNFINISHED

Each game tracks the camera's current progress within a level with the following: ...
 * Current zone in which the camera resides
 * Current path, in that zone, that the camera is travelling
 * Current progress of the camera along that path

Camera Follow Mode
In Camera Follow Mode, updating the camera refers to the process of recalculating the camera's current progress and updating the level [with the recalculated progress] as the player progresses towards (or digresses from) the goal. This may include updating the current zone if the camera and player venture into a neighboring zone and/or updating the current path if the camera and player pass either of its endpoints into territory of a neighboring path, along which the camera would follow closer to-providing a more appropriate view of the player.

The camera's current progress is determined by the index of the point in the current path that is closest to-not the player, but instead-a point otherwise known as the unprojected camera location, which is located a number of units to the left or right (in the X direction), above or below (in the Y direction), and behind the player (in the Z direction). The camera is ultimately positioned at the location of the point with index equal to the current progress value. Note that, without the additional adjustments, the camera would be positioned directly at the player's approximate location along the path [i.e. closest point], which may fail to provide a full view of the player. For example, in forward/backward zones this would provide a sort of first-person view rather than a full view of the player; however, if the point were adjusted somewhat backwards, its closest point on the path would be a point that were approximately behind the player. In left/right zones this may not matter as their paths span left to right and are typically already positioned somewhat behind the player's roaming area.

At any instant there may be some point among [the current path's] neighboring paths that is closer to the unprojected camera location than any other point in the current path. This would mean that the player has progressed/retrogressed so far such that the unprojected camera location is now closer to [the point in] some neighboring path-and thus projects to a point that either passes the end or backtracks before the beginning of the current path. In these cases, the neighboring path with the point closest to the unprojected camera location is chosen to replace the current path.

Camera Follow Routine
The camera follow routine handles updating the camera in Camera Follow Mode. Its generalized operation is as follows:
 * 1) Calculate [updated] unprojected camera location
 * 2) Find the path among the current path and its neighbors [with point] closest to the unprojected camera location
 * 3) Update level with potentially any combination of the following:
 * 4) * A new current zone = if it is different from the current, the parent zone of the path closest to the unprojected camera location
 * 5) * A new current path = if it is different from the current, the path closest to the unprojected camera location
 * 6) * A new current progress = the index of the point closest to the unprojected camera location, in the path that contains it

Operation
Note: camera looks forward or looks backward do not actually refer to the camera looking forward or back. Instead, these refer to the camera looking to a point that is adjusted either forward or backward as the player looks forward or back.
 * 1) Calculate [updated] unprojected camera location
 * 2) * Determine the nearest neighboring camera paths [to the camera]
 * 3) ** If current progress at less than half way or at most 50 points into the current path, nearest neighbors include all preceding neighbors
 * 4) ** If current progress at or more than half way or at most 50 points from the end of the current path, nearest neighbors include all proceeding neighbors
 * 5) * Determine z look/x pan flags
 * 6) ** If current zone intended for forward/backward travel
 * 7) *** If up is pressed, [set flag for] camera looks forward
 * 8) *** If down is pressed, [set flag for] camera looks backward
 * 9) ** If current zone intended for left/right travel
 * 10) *** If left pressed, [set flag for] camera pans left
 * 11) *** If right pressed, [set flag for] camera pans right
 * 12) ** If current zone not intended for forward/backward travel
 * 13) *** Camera is forced to either look forward or back, depending on zone flag
 * 14) * Determine z look/x pan factors
 * 15) ** Increase or decrease z look factor at rate of 50 m/frame, depending on whether cam looks forward or backward; restrict this factor to the range -300m to 300m (*Cortex Power: -1200m to 1200m)
 * 16) ** Increase or decrease x pan factor at rate of 100 m/frame, depending on whether cam pans left or right; restrict this factor to the range -300m to 0m [offsets left] if the current path travels left or to the range 0m to 300m [offsets right] if the current path travels right
 * 17) * Determine y pan/z zoom factors
 * 18) ** If the current or at least one nearest neighbor path travels forward/backward and the current progress is at least 10 points into and from the end of the current path
 * 19) *** If the current path travels forward/backward, seek z zoom factor from its previous value towards the current path's  value at a rate of 25 m/frame.
 * 20) *** Else if there exists a nearest forward/backward [travelling] neighbor, set z zoom factor to the neighbor's  value
 * 21) ** If the current or at least one nearest neighbor path travels up/down
 * 22) *** If the current path travels up/down, seek y pan factor from its previous value towards the current path's  value at a rate of 100 m/frame.
 * 23) *** Else if there exists a nearest up/down [travelling] neighbor, set y pan factor to the neighbor's  value.
 * 24) * Determine total z adjustment factor by sum of z look, z zoom, and player's  value; let total x and y adjustment factors be x and y pan factors, respectively.
 * 25) * Calculate unprojected camera location by adding x, y, and z adjustment factors respectively to player location.
 * 26) Find the path among the current path and its neighbors that is closest to the unprojected camera location
 * 27) * For the current path
 * 28) ** If the current path travels forward/backward
 * 29) *** TBD
 * 30) ** If the current path does not travel forward/backward
 * 31) *** Calculate the unprojected camera location's projected progress along the current path
 * 32) **** Calculate vector a as the direction vector that spans from the current path's start location (i.e. position of initial point 0) to the unprojected camera location
 * 33) **** Let vector b be the current path's direction vector; graphically this refers to a unit vector that is a linear approximation of the path, starting at its start location and pointing in its direction
 * 34) **** Calculate the camera's projected distance along the current path by computing the scalar projection of a onto b. Since b-the path's direction vector-is already a unit vector, this is just the dot product of a and b.
 * 35) **** Divide the camera's projected distance along the current path by the average distance between its path points. This directly converts the camera's projected distance along the path to the index of a point [along the path]-i.e. the camera's projected progress along the path.
 * 36) *** If the projected progress refers to a point before the path entrance or past the path exit (i.e. is an invalid point index)
 * 37) **** Reset progress to either the index of the first point or the last point in the path
 * 38) **** Mark the projected change in progress as non-existent
 * 39) *** Get the actual [projected] camera location at the projected progress point
 * 40) **** If this camera location is any more than 12.5 m from the unprojected camera location in either the x, y, or z dimension, then eliminate this path from being a potential closest
 * 41) *** Calculate and record euclidean distance from unprojected camera location to actual camera location; this is the equivalently the distance from the unprojected camera location to the [nearest point on the] path
 * 42) ** If the path is still a potential closest
 * 43) *** Calculate and record the [absolute] projected change in progress by computing absolute value of the difference between current progress and projected progress
 * 44) *** If the [non-absolute] projected change shows a decrease in progress, mark the projected change as a digression; else if it shows an increase in progress, mark it as a progression
 * 45) * For each of the current path's nearest neighbors
 * 46) ** If that neighbor path travels forward/backward
 * 47) *** TBD
 * 48) ** If that neighbor path does not travel forward/backward
 * 49) *** Calculate the unprojected camera location's projected progress along that [neighbor] path
 * 50) **** This is done in the same way as for the current path
 * 51) *** If the path's parent zone header flags bit 19 set: if the path travels left/right and the unprojected camera location is more than 50m under the [initial point of] the path, eliminate this path from being a potential closest
 * 52) *** If this path and the current path both travel in the same y and z direction (i.e. either up-left, up-right, down-left, down-right, or do not at all travel up/down and left/right)
 * 53) **** If this path is in front of the current path (i.e. such that, if chosen as the new/closest path, the camera would 'enter' at its entrance point)
 * 54) ***** If the projected progress lies before the path's entrance cutoff point, then eliminate this path from being a potential closest
 * 55) ***** Else if the projected progress lies before the path's default entrance point (0), eliminate this path from being a potential closest
 * 56) **** Else if this path is behind the current path (i.e. such that, if chosen as the new/closest path, the camera would 'enter' at its exit point)
 * 57) ***** If the projected progress lies after the path's exit cutoff point, then eliminate this path from being a potential closest
 * 58) ***** Else if the projected progress lies after the end of the path/the path's default exit point, eliminate this path from being a potential closest
 * 59) *** Get the actual [projected] camera location at the projected progress point
 * 60) **** If this camera location is any more than 12.5 meters from the unprojected camera location in either the x, y, or z dimension, then eliminate this path from being a potential closest
 * 61) *** Calculate and record euclidean distance from unprojected camera location to actual camera location
 * 62) ** If this path is still a potential closest, then calculate and record the total [absolute] projected change in progress:
 * 63) *** If this path is further from the goal than the current path
 * 64) **** From the perspective of the player as it faces towards the goal: if this path is in front of the current path
 * 65) ***** This doesn't make sense. From the perspective of the player as it faces towards the goal, a path that is further from the goal than the current path must either be behind, to the left, to the right, above, or below it. this path could not possibly be in front of the current path if it is supposedly further from the goal; such paths do not exist in any zone entry of any NSF; an incorrect progress calculation will ensue for such paths
 * 66) **** From the perspective of the player as it faces towards the goal: if this path is behind the current path
 * 67) ***** -the camera will 'exit' from the current path's front endpoint as the exit point
 * 68) ***** -the camera will 'enter' at the new path's back endpoint as the entrance point
 * 69) ***** Get the amount of progress so far accumulated in relation to the exit point or front of the current path-this is just the current progress. (The camera would first have to move back this amount to reach this path.)
 * 70) ***** Get the projected amount of progress along this path [if it were chosen] in relation to its back endpoint (i.e. last point) as the entrance point
 * 71) ****** Compute the absolute difference between current progress and projected progress
 * 72) ****** Subtract the computed difference from the length of the path/index of its last progress point
 * 73) ***** Sum the 2 progress amounts to get the total projected change in progress; record this value
 * 74) *** If this path is closer to the goal than the current path
 * 75) **** From the perspective of the player as it faces towards the goal: If this path is in front of the current path
 * 76) ***** - the camera will 'exit' from the current path's back endpoint as the exit point
 * 77) ***** - the camera will 'enter' at the new path's front endpoint as the entrance point
 * 78) ***** Get the amount of progress that would need to be accumulated to reach the exit point of the current path
 * 79) ****** Compute difference of current path length [index of its last progress point] and current progress to find remaining progress
 * 80) ***** Get projected amount of progress along this path [if it were chosen] in relation to its front endpoint (i.e. first point) as the entrance point
 * 81) ****** Compute the absolute difference between current progress and projected progress
 * 82) ***** Sum the 2 progress amounts to get the total projected change in progress; record this value
 * 83) **** From the perspective of the player as it faces towards the goal: If this path is behind the current path
 * 84) ***** This doesn't make sense; see above. An incorrect progress calculation will ensue.
 * 85) * Using the information recorded for each of the potentially closest paths
 * 86) ** Choose the closest path to the unprojected [updated] camera location (i.e. with minimum euclidean distance) for which it, preferably, would exhibit a projected change in progress [upon updating current progress using the total projected change]
 * 87) ** If no path exists for which the updated camera location corresponds to a projected change in progress
 * 88) *** Return without updating level; not necessary
 * 89) Update level:
 * 90) * Approximate the distance between the current camera location and the new [updated] projected camera location: multiply change in progress recorded [for the chosen path] by the average distance between points in the current path (this converts the change in progress to a change in distance).
 * 91) ** If this distance is less than .45778m?
 * 92) *** Record the projected change in progress as camera speed
 * 93) *** Update the level with new projected progress as the current progress; the camera will not have moved far and will thus remain on the current path, so there will be no change in and no updating of current path or zone
 * 94) ** If this distance is greater than [or equal to] .45778m?
 * 95) *** Update camera speed
 * 96) **** If the projected change in progress is less than or equal to 2 points
 * 97) ***** Set camera speed to half the projected change in progress
 * 98) **** If the projected change in progress is between 2 and 5 points
 * 99) ***** Set camera speed to 2 points/frame
 * 100) **** If the projected change in progress is 5 or more points (impossible delta)
 * 101) ***** Set camera speed to half the projected change in progress if it is more than camera speed; else increment camera speed by 1 point/frame
 * 102) *** Update the level with a new progress, given the updated camera speed
 * 103) **** If the projected change in progress would bring the camera closer to the goal
 * 104) ***** If the chosen path [closest to the approximate camera location] is the current path
 * 105) ****** Calculate an alternate new progress (used rather than the new projected progress) by adding camera speed to the current progress.
 * 106) ****** Update the level with the alternate new progress as the current progress; the camera will remain on the current path, so there will be no change in and no updating of current path or zone
 * 107) ***** If the chosen path is a neighboring path [rather than the current path], then the projected change in progress should bring the camera out of the current path and into that neighboring path-which is past the current path:
 * 108) ****** Also, calculate an alternate new progress by adding camera speed to the current progress. For further verification that, at its ultimate new progress, the camera will indeed be brought into that neighboring path, if the alternate new progress would exceed the length of the path (i.e. cross the back endpoint), then it would be an invalid progress-a progress which would instead refer to a point in the neighboring path past the current path:   (else treat as if the chosen path were the current path; see above)
 * 109) ******* Readjust the alternate new progress in relation to the front endpoint of the neighboring path
 * 110) ******** Subtract length of the current path from the alternate new progress to get the amount of [the alternate new] progress that would exceed the back endpoint of the current path into the neighboring path
 * 111) ******** If the neighboring path is behind the current path, negate the amount of exceeding progress
 * 112) ******** Add this to the index of the neighboring path's front endpoint
 * 113) ******** Set the alternate new progress to this readjusted value
 * 114) ******* Update the level with:
 * 115) ******** The neighboring path's parent zone as the current zone
 * 116) ******** The neighboring path as the current path
 * 117) ******** Whichever is less: either the projected new progress or the alternate new progress, as the current progress.
 * 118) **** If the projected change in progress would bring the camera further from the goal
 * 119) ***** If the chosen path [closest to the approximate camera location] is the current path
 * 120) ****** Calculate an alternate new progress [used rather than the new projected progress] by subtracting camera speed from the current progress.
 * 121) ****** Update the level with the alternate new progress as the current progress; the camera will remain on the current path, so there will be no change in and no updating of current path or zone
 * 122) ***** If the chosen path is a neighboring path [rather than the current path], then the projected change in progress should bring the camera out of the current path and into that neighboring path-which is behind the current path.
 * 123) ****** Also, calculate an alternate new progress by subtracting camera speed from the current progress. For further verification that, at its ultimate new progress, the camera will indeed be brought into that neighboring path, if the alternate new progress would be less than 0 (i.e. cross the front endpoint), then it would be an invalid progress-a progress which would instead refer to a point in the neighboring path that falls short of the current path:  (else treat as if the chosen path were the current path; see above)
 * 124) ******* Readjust the alternate new progress in relation to the back endpoint of the neighboring path
 * 125) ******** The amount of progress that exceeds the front endpoint of the current path into the neighboring path is just the current progress
 * 126) ******** If the neighboring path is in front of the current path, negate the amount of exceeding progress
 * 127) ******** Add this to the index of the neighboring path's back endpoint
 * 128) ******** Set the alternate new progress to this readjusted value
 * 129) ******* Update the level with:
 * 130) ******** The neighboring path's parent zone as the current zone
 * 131) ******** The neighboring path as the current path
 * 132) ******** Whichever is less: either the projected new progress or the alternate new progress, as the current progress.