vooga.engine.resource.clock
Class GameClock

java.lang.Object
  vooga.engine.resource.clock.GameClock

public class GameClock
extends java.lang.Object

Keeps track of the game time, manages timers which should occur based on passing of in game time, and allows for setting markers in time to determine how much time has elapsed from a point in time. The time kept by this class should be used in all part of the game which pass according to time elapsed in game in order to keep timed events synchronized. The primary usefulness of GameClock is the ability for pausing in the game to pause the game time, which allows real world time to elapse without in game time elapsing. Therefore, any objects which move/draw/update based on in game time will automatically stop when the game is paused. This includes timers which GameClock is set to manage. Time markers simplify updating time in a game loop as well as allow the developer to determine time elapsed since certain in game events. In order to perform a simple time elapsed calculation in a game loop one could use: { GameClock.beginTime(); GameClock.setMarker("gameLoop"); while(true){ updateGame(GameClock.advanceMarker("gameLoop"); } } This sets a marker at the beginning of game time and moves the marker up to the current game time each time the game loop is executed, returning the time elapsed since the last update of the "gameLoop" marker for use in update calculations. The first operation of the game clock is to start it with GameClock.start(). Until the clock is started, resetting, pausing, and unpausing will throw exceptions. Once time is started it can be paused, unpaused, or reset to time zero. However, if the game is paused while it is already paused or unpaused while it is running, it will throw an exception.

Constructor Summary

GameClock()

Method Summary

static long	createMarker(java.lang.String markerUSID) Create a new time marker to later determine how much time has elapsed from this point.
static long	getMarkerAge(java.lang.String markerUSID) Return how much game time has elapsed sine the marker was created or last updated
static long	getMarkerTime(java.lang.String markerUSID) Find the time at which a marker was set or last updated.
static long	getTime() Returns the amount of time since the game has started excepting time passed while the game was paused.
static boolean	isRunning() Return whether or not the GameClock is currently running/progressing in time
static boolean	isStarted() Returns whether or not the GameClock has been initialized
static void	pause() Stop the GameClock from and all timers from advancing.
static void	pauseAllTimers() Stop all Timers managed by GameClock from advancing.
static void	reset() Resets the GameClock so that current time is considered time zero and time paused is set to zero.
static void	reset(boolean preserveTimers) Resets the GameClock so that current time is considered time zero and time paused is set to zero.
static void	setTimer(java.util.Collection<Timer> timers) Add a Collection of GTGE Timer objects to the collection of GameClock managed timers to automatically stop and start the timers as the game pauses and unpauses.
static void	setTimer(Timer timer) Add a GTGE Timer object to the collection of GameClock managed timers to automatically stop and start that timer as the game pauses and unpauses.
static void	start() Initializes the GameClock at zero time.
static void	unpause() Start the GameClock and resume advance of all timers.
static void	unpauseAllTimers() Resume or start advancement of all Timers managed by GameClock from advancing.
static long	updateMarker(java.lang.String markerUSID) Bring the identified marker up to the current game time and return the difference between its former time and its new time which is the game time elapsed since the marker was created or last updated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GameClock

public GameClock()

Method Detail

pause

public static void pause()
                  throws GameClockException

Stop the GameClock from and all timers from advancing. If time is already paused or has not begun, no change will occur and an error message is produced.

Throws:

GameClockException

unpause

public static void unpause()
                    throws GameClockException

Start the GameClock and resume advance of all timers. It time is already progressing or has not begun, no change will occure and an error message is produced.

Throws:

GameClockException

start

public static void start()
                  throws GameClockException

Initializes the GameClock at zero time. If time has already begun, no change occurs and an error message is produced.

Throws:

GameClockException

reset

public static void reset()
                  throws GameClockException

Resets the GameClock so that current time is considered time zero and time paused is set to zero. All timers are paused to render them inactive and ArrayList of timers is reset so that GameClock no longer manages any timer.

Throws:

GameClockException

reset

public static void reset(boolean preserveTimers)
                  throws GameClockException

Resets the GameClock so that current time is considered time zero and time paused is set to zero. If preserveTimers parameter is false, all timers are paused to render them inactive and ArrayList of timers is reset so that GameClock no longer manages any timer. If preserveTimers parameter is true the Timers continue to operate as normal.

Throws:

GameClockException

getTime

public static long getTime()

Returns the amount of time since the game has started excepting time passed while the game was paused.

Returns:

time elapsed in game

isStarted

public static boolean isStarted()

Returns whether or not the GameClock has been initialized

Returns:

true if game has been initialized

isRunning

public static boolean isRunning()

Return whether or not the GameClock is currently running/progressing in time

Returns:

true if time is not paused

setTimer

public static void setTimer(Timer timer)

Add a GTGE Timer object to the collection of GameClock managed timers to automatically stop and start that timer as the game pauses and unpauses. The Timer is automatically started if the time is unpaused. If the game is paused the Timer will be started when time is unpaused.

Parameters:

timer - Timer to be managed by GameClock

setTimer

public static void setTimer(java.util.Collection<Timer> timers)

Add a Collection of GTGE Timer objects to the collection of GameClock managed timers to automatically stop and start the timers as the game pauses and unpauses. The Timers are automatically started if the time is unpaused. If the game is paused the Timers will be started when time is unpaused.

Parameters:

custTimers - a Collection Timers to be managed by GameClock

pauseAllTimers

public static void pauseAllTimers()

Stop all Timers managed by GameClock from advancing.

unpauseAllTimers

public static void unpauseAllTimers()

Resume or start advancement of all Timers managed by GameClock from advancing.

createMarker

public static long createMarker(java.lang.String markerUSID)

Create a new time marker to later determine how much time has elapsed from this point. Each marker is assigned a unique String id for tracking

Parameters:

markerUSID - The unique String id of the time marker for later reference

Returns:

the game time in milliseconds when the marker is created

getMarkerTime

public static long getMarkerTime(java.lang.String markerUSID)

Find the time at which a marker was set or last updated. Effectively, this is the current location of the marker in time.

Parameters:

markerUSID - the unique string id of the marker

Returns:

the game time at which the marker was last created or updated

updateMarker

public static long updateMarker(java.lang.String markerUSID)

Bring the identified marker up to the current game time and return the difference between its former time and its new time which is the game time elapsed since the marker was created or last updated.

Parameters:

markerUSID - the unique string id of the marker

Returns:

the time elapsed since the marker was last created or updated

getMarkerAge

public static long getMarkerAge(java.lang.String markerUSID)

Return how much game time has elapsed sine the marker was created or last updated

Parameters:

markerUSID - the unique string id of the marker

Returns:

the time elapsed since the marker was last created or updated