Implementation Nodes for Balancing Act

Note: This description uses type names from the source code.  While these
type names are unlikely to change much after initial deployment of this
simulation, it is still possible that they will, so please read accordingly
(and update if possible).

Model

The primary model classes for this simulation, which at the time of this
writing are BalanceModel, IntroModel, BalanceLabModel, and BalanceGameModel,
act primarily as composite classes that contain the various model elements that
comprise the balance, or that can be placed on the balance.  Most of the
mathematical modeling, and indeed most of the model complexity, is in the
“Plank” class.  This is where the torque equation (t = r X F) is calculated at
periodic intervals defined by the simulation clock.  The plank also tracks
model elements as they are added to and removed from its surface, and it
controls the position of model elements that are on its surface.  In other
words, it is the class that rotates and positions the various masses.
There is an explicit model-view transform between the model and the view.
Model units are in meters, kilograms, and seconds.  The distance unit – meters –
is converted into screen units by this transform.

Masses and Mass Nodes

One of the key classes in the model is the “Mass” class, which is the base
class for everything that can be put on to the balance.  There are two main
subclass branches: ShapeMass and ImageMass.  As the names suggest, the
appearance of shape masses is defined by a Java Shape instance which they
maintain.  The stacks of bricks are one example of this.  The image masses are
masses whose appearance is defined by an image resource.

In the view, there is a corresponding class hierarchy of PNode-based classes
that encapsulate the information for presenting these to the user and allowing
the user to move them around and otherwise manipulate them.

Game Classes

The game module presents various challenges to the user that they solve in
order to earn points.  The creation of these challenges is probably one of the
more complex portions of the code.  The BalanceGameChallengeFactory is the
class that is responsible for creating the challenges, and it uses pseudo-
random algorithms to generate challenges that use the set of masses that are
available.  There are several approaches used for this.  In some cases,
challenges are generated by first randomly choosing the fixed mass or masses
(the one(s) that the user can’t move), then iterates through the possible
movable masses determining whether solvable challenges can be created with a
particular combination of fixed and movable masses.  When a solvable challenge
is found, it is added to a list, and another random choice is then made from
this list of solvable challenges.

The BalanceGameChallengeFactory also maintains lists of challenges that have
been presented to the user so that it can compare against this list to
determine whether a given challenge is “unique”, meaning that the user has not
yet seen one that is similar.  These lists are maintained as FIFOs, so that
when the user has seen all of the challenges on one of the lists, the oldest
items are removed, thus making it so that the user never sees two similar
challenges in close temporal proximity.

There are three main types of challenges, balance challenges, mass deduction
challenges, and tip prediction challenges.  They derive from the same base
class, and have a list of fixed masses and a list of movable masses.  In
balance challenges, the user moves the movable mass in order to balance the
fixed masses, and all masses are labeled to make this possible.  In the mass
deduction challenges, users balance a “mystery mass” (a mass of unknown value)
with one whose value is known in order to determine the mass of the mystery
mass, which they then enter in a dialog.  Note that, while all challenges
maintain a list of movable masses, none of the challenges created at the time
of this writing uses more than one mystery mass.  This is because such
challenges were deemed too difficult at one point during the development of
this simulation.  The capability is being left in the code in case such
challenges are some day desired, and because it is more consistent with the
way the fixed masses are handled.

JP Blanco, 11/11/2011, moved to JavaScript version 10/28/2013