\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.

\begin{figure}[htbp]
  \centering
  \includegraphics[scale=0.55]{mddgame}
  \caption{Game system module dependency diagram}
  \label{fig:game-mdd}
\end{figure}

In keeping with the \Gizmoall design philosophy
(Section~\ref{sec:design-philosophy}), the design of the game system
is extremely general, and can handle not only the specified \Gizmoball
behavior, but many additions and even entirely different games.

Perhaps the most important form of generality is the decoupling of the
game system and the gizmos. The game simulator has no dependencies on
the specific types of gizmos, and makes no assumptions specific to the
gizmos in \Gizmoball. It is equally at home simulating other systems
such as Tetris or Traffick. It does not have concepts of motion,
friction, or gravity --- indeed, it has no concept of physics or
geometry at all. These decoupled concepts are left to the gizmos to
define, specify, and implement as they see fit. By giving the gizmos
such wide latitude in their behavior (see Section~\ref{sec:gizmos}), this
frees the system from the limitations of the \Gizmoball model.

Moreover, the game system does not rely on the concept of collisions.
Instead, it uses the more general notion of \emph{interactions}, which
is a totally general model for the ways in which gizmos interact with
each other. The interaction system, described extensively in
Section~\ref{sec:interaction-system}, provides a superset of \Gizmoball's
collision model, as well as allowing entirely different forms of
gizmo-gizmo interactions.

\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 needs only support one
type of operation: simulation for a given time duration. The
\texttt{GameBoard} will call the gizmo's \texttt{tick} method with the
time duration.

Optionally, it may also be triggerable. The \texttt{GameBoard} handles
the management and firing of triggers. A gizmo may implement a
\texttt{fireTrigger} handler that is called when it is triggered. This
handler may do anything at all, including nothing at all. 

Triggers are represented using a \texttt{AbstractTrigger} class that
implements the triggering of the target gizmo, and has
\texttt{CollisionTrigger} and \texttt{KeypressTrigger} subclasses. The
name \emph{collision trigger} is a misnomer: it should more accurately
be known as an \emph{interaction trigger}, since it is fired when an
interaction occurs; the \texttt{CollisionTrigger} class name is used
for historical reasons only. It is also associated with a source
gizmo; whenever that gizmo is involved in an interaction, the trigger
will be fired and trigger the target gizmo. A \texttt{KeypressTrigger}
is associated with a key, and can either be a ``key-down'' trigger
that triggers the target gizmo when the key is pressed, or a
``key-up'' trigger that triggers it when the key is
released\footnote{Note that the terms ``key-up'' and ``key-down'' will
  no longer be correct if the keyboard is used upside down.}. The
\texttt{GameBoard} maintains lists of each type of triggers, and fires
each trigger at the appropriate times.

A gizmo class may also define \emph{interaction handlers}\footnote{Not
  to be confused with \emph{interaction modes} --- the two concepts
  are entirely unrelated.} handlers and register them with the game
system's \emph{interaction manager}. These handlers describe
interactions that the gizmo may have with other types of gizmos. For
more information on the interaction system, see
Section~\ref{sec:interaction-system}.

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 way. The only properties a gizmo
is required to have are a name --- a string used to uniquely identify
the gizmo in the editor and in saved \Gizmoball XML files --- and the
position at which the gizmo will be drawn on the board.


\subsubsection{Interaction System}
\label{sec:interaction-system}

The interaction system manages the ability of gizmos to ``interact''.
Interactions are completely general and require nothing more than the
fact that they occur during the process of simulation and involve two
gizmos.  The standard \Gizmoball gizmos use the interaction system to
model collisions, though it is not necessary that interactions have
anything to do with the geometry or physics of the gizmos (again, the
game board has no concept of these).

Two classes sit at the core of the interaction system.  The
\texttt{InteractionManager} is a registry for
\texttt{InteractionHandlers}.  The interaction handler interface
provides two methods: one for getting the time until the next
interaction between two gizmos, and the other for actually performing
an interaction once it occurs.  Instances of interaction handlers are
registered with the interaction manager by the gizmos, and the manager
provides a method for later obtaining the appropriate interaction
handler for interactions between two gizmos.  Essentially, the
interaction system is an object-oriented approach to generic
programming.  By acting as a registry, the actual handlers can exist
in the gizmos and be loaded and registered as needed.

The \texttt{GameBoard} maintains a list of \emph{interaction pairs}:
pairs of gizmos that can interact.  The game board constructs this
list as gizmos are added so that the simulator can simply iterate over
exactly which interaction pairs need to be considered without
necessarily incurring $O(n^2)$ interaction checks during simulation
time.

Prior to the adoption of this general interaction system, three
alternatives were considered.  First, we considered using a
\emph{collision manager}, similar to our current one, but containing
methods for the collisions of gizmos.  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 third system we considered (and implemented for the
preliminary release, but have since discarded) involved a distributed
mechanism by which each gizmo could report what other gizmos it knew
how to collide with, didn't know how to collide with, or knew it would
never collide with.  This allowed the game board to deduce the same
interaction pairs that it maintains now, but required a great deal
more complexity in the gizmos, and made it unclear exactly what could
interact with what.


\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 game
simulator is decoupled from the user interface and the gizmos. The
user interface module regularly calls the \texttt{GameBoard}'s tick
method to request that the game state be simulated for a specified
time duration. Simulation is performed according to the description
and procedure 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 an interaction 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 interaction 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 interaction time recomputation.
    
    \begin{itemize}
    \item If the event represents an interaction, the interaction is
      processed using the interaction handler obtained from the
      interaction manager. Both gizmos involved in the interaction
      are scheduled for interaction time recomputation.
      
    \item If the event is a \emph{recalculate-interaction-time}
      event, both gizmos associated with it are scheduled for
      interaction time recomputation.
      
    \item If the event is the \emph{end-of-tick} event, the tick
      ends.
    \end{itemize}
    
  \item Interaction time recomputation is performed. First, every
    event involving any gizmo identified for interaction time
    recomputation is removed from the queue.
    
  \item Next, every pair involving any gizmo identified for
    interaction time recomputation earlier in this processing algorithm
    is processed:
    
    \begin{itemize}
    \item If the time to next interaction for the pair is less than the
      maximum tick length, an \emph{interaction} event is placed in
      the queue at the time the interaction will occur.
      
    \item Otherwise, if the time to interaction for the pair is
      greater than the maximum tick length, a
      \emph{recalculate-interaction-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. The game
  state is made available to the UI module and any other clients.
\end{enumerate}




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