\label{sec:game-system}

The game system module, implemented in the \texttt{gizmoball.game}
package, contains the classes necessary to represent a game state and
simulate it.

The design of the game system is extremely general, and can handle not
only the specified \Gizmoball behavior, but many additions of various
kinds.

\subsubsection{Architecture}
\label{sec:game-system-architecture}

The principal interface to this module is through the
\texttt{GameBoard} class, which captures the state of a \Gizmoball
game board. A \texttt{GameBoard} can be constructed in an empty
state, or it can be generated by a factory function in
\texttt{gizmoball.xml.GizmoballReader} (Section~\ref{sec:serializer}).

Intuitively, a game board can be represented as a collection of
gizmos, in addition to a few additional pieces of state information
associated with the board itself. This is the representation used by
the \texttt{GameBoard} class, a composite object that contains gizmos.
We model the ball as a gizmo, so the ball does not need to be
considered separately. Each gizmo maintains its own state information,
including its position on the board.

Each type of gizmo is represented by its own class which inherits from the
\texttt{AbstractGizmo} class. A gizmo class must support three types
of operations:

\begin{itemize}
\item simulation for a given time duration. The \texttt{GameBoard}
  will call the gizmo's \texttt{tick} method with the time duration.
\item collision handling. A gizmo class must indicate (through the
  \texttt{canCollideWith} call) which other classes of gizmos it has
  collision handlers for. Then, for any gizmo that it has a handler
  for, it must be able to calculate and return the \emph{time until
    next collision} with the other gizmo. Finally, it should also have
  a collision handler that resolves collisions with other gizmos it
  can collide with once they have occurred.
\item triggering. The \texttt{GameBoard} handles the management
  and firing of triggers, but a gizmo must implement a (possibly
  trivial) \texttt{fireTrigger} handler that is called when it is
  triggered.
\end{itemize}

The gizmos are also \emph{propertyified}, i.e. they contain properties
as used in the properties system (Section~\ref{sec:properties}). This
allows properties of the gizmos to be accessed and manipulated by the
editor and serializer in a standard menu. Gizmo properties include:

\begin{itemize}
\item the gizmo's name (a string used by the editor to identify a
  specific gizmo to the user)
\item the gizmo's position on the board
\item the gizmo's orientation, if appropriate for the gizmo type
\item for a ball, its current velocity
\item for an absorber, its size
\item for a flipper, its handedness (whether it is a left flipper or a
  right flipper)
\end{itemize}


An \texttt{AbstractGizmoWithPolygonalGeometry} abstract class is used
to represent gizmos that have polygonal geometry: square and triangular
bumpers, absorbers, and the game walls. It provides an implementation
of the collision routines that handles collisions between any of the
sides of the polygon and the ball. For the absorber, we override the
collision handler to capture the ball, but use the same
time-until-collision method. Initially, we did not plan on using this
design; however, it quickly became apparent that there was a
substantial body of code that could be reused this way.

Initially we planned to use \texttt{AbstractFixedGizmo} and
\texttt{AbstractTranslatableGizmo} classes that derived from
\texttt{AbstractGizmo} to separate stationary and mobile gizmos. Upon
further reflection\footnote{Not the kind used by the properties
  system}, we concluded that this dichotomy did not provide
significant benefits. This was especially true in light of the fact
that there was only one translatable gizmo: the ball.

The \texttt{GameBoard} tracks the triggers in the system. Triggers are
represented using a \texttt{AbstractTrigger} class that implements the
triggering of the target gizmo, and \texttt{CollisionTrigger} and
\texttt{KeypressTrigger} classes that capture the semantics of
collision and keypress triggers. The \texttt{GameBoard} fires the
triggers at the appropriate times.


\subsubsection{Collision System}
\label{sec:collision-system}

As hinted at above, collision detection and resolution are performed
using a method in which the individual gizmo classes have collision
handlers for collisions with other gizmo types. The
\texttt{canCollideWith} method indicates whether a gizmo has support
for colliding with another type of gizmo. It can return three
responses: \emph{can collide}, indicating that it has a handler for
collisions with the other gizmo type; \emph{defer collisions},
indicating that it has no knowledge of the other gizmo type and defers
collision handling to it; or \emph{never collides}, which indicates
that the gizmo knows it will never collide with the other gizmo type
(this is used for optimizing the collision recalculation process).

The \texttt{GameBoard} maintains a list of \emph{collision pairs}:
pairs of gizmos that can collide. For each pair, one gizmo is
designated as the \emph{collider} and the other as the
\emph{collidee}; the collider's collision handlers are used to detect
and resolve the collision with the collidee.

Prior to the adoption of this general, distributed collision system,
two alternatives were considered.  First, we considered using a
separate \emph{collision manager} class that would contain methods for
handling the collision of any pair of gizmos using an approach similar
to generic programming.  However, this would have had the disadvantage
of requiring all gizmo types to be known about by this collision
manager, making it more difficult to add new gizmos.  We also
considered using a technique similar to the operator overloading
mechanism of the Python language.  In this model, collision resolution
would first attempt to notify the collider of the collision with the
colidee.  If this reported that it did not know how to resolve such a
collision, a \emph{reverse resolution} would be attempted, in which
the collidee would be notified of the collision with the collider.  If
both of these resolution attempts failed, then it would be assumed
that the two gizmos could not collide with each other (such as two
fixed bumper gizmos).  However, the resolution methods would have been
difficult to implement, could have led to bizarre cases of infinite
recursion, and may have resulted in code duplication.  The current
system side-steps many of these issues by distributing the collision
resolution into the gizmos themselves, and by separating the process
of discovering which gizmos know how to collide with each other and
the process of collision resolution.


\subsubsection{Game Simulation}
\label{sec:game-loop}

After the \texttt{GameBoard} is constructed by either the serializer
or the user interface (in edit mode), it can be simulated. The user
interface module regularly calls the \texttt{GameBoard}'s tick method,
which performs simulation for a specified time duration. Simulation is
performed according to the description and procedure in
Section~\ref{sec:game-loop} below. Once simulation is complete, the UI
module may access the new states of the gizmos.

Game simulation is performed by a \emph{modified dynamic adaptive
  continuous-time discrete-event simulator}\footnote{Buzzword bingo!}.
This divides a given time interval into time segments bounded by
\emph{events}. The archetypical simulator event is a collision between
two gizmos. In addition, the simulator makes use of two types of
events that do not have an obvious concrete meaning: an event
representing the end of the current tick, and periodic events to
ensure that all collision times are recalculated regularly.  The
simulation of each gizmo is performed in continuous time in the
intervals between discrete events.

A timer in the UI triggers the \texttt{GameBoard}'s \texttt{tick}
method regularly. This initiates the following procedure:

\begin{enumerate}
\item If the specified tick time is greater than the maximum tick
  length (a constant), it is divided into multiple ticks whose
  length is the maximum tick length or less. The remainder of the
  procedure assumes that the tick has been divided up.
  
\item An \emph{end-of-tick} event is placed in the queue
  \texttt{time} seconds in the queue.
  
\item The earliest event in the queue is repeatedly processed,
  until the \emph{end-of-tick} event is reached:
  
  \begin{enumerate}
  \item All gizmos on the board are simulated up to the event.
    Their \texttt{tick} method is called. If it returns true for
    any gizmo, indicating that the gizmo's velocity changed,
    that gizmo is scheduled for collision recomputation.
    
    \begin{itemize}
    \item If the event represents a collision, the collider
      gizmo's \texttt{collide} method is called. Collision
      triggers for both gizmos are fired. Both the collider and
      collidee are scheduled for collision recomputation.
      
    \item If the event is a \emph{recalculate-collision-time}
      event, both gizmos associated with it are scheduled for
      collision recomputation.
      
    \item If the event is the \emph{end-of-tick} event, the tick
      ends.
    \end{itemize}
    
  \item Collision recomputation is performed. First, every event
    involving any gizmo identified for collision recomputation
    is removed from the queue.
    
  \item Next, every pair involving any gizmo identified for
    collision recomputation earlier in this processing algorithm
    is processed:
    
    \begin{itemize}
    \item If the time to collision for the pair is less than the
      maximum tick length, a \emph{collision} event is placed in
      the queue at the time the collision will occur.
      
    \item Otherwise, if the time to collision for the pair is
      greater than the maximum tick length, a
      \emph{recalculate-collision-time} event is placed in the
      queue, the maximum tick length in the future.
      
    \end{itemize}
  \end{enumerate}
  
\item The remaining events in the event queue are stored so that
  they can be reused for the next event \texttt{tick} call.
\end{enumerate}




% Local Variables:
% TeX-master: "fdd.tex"
% End: