### MASON Version 1

This MASON version is the first public release on the website. An earlier version (Version 0) was released at the Agent2003 Conference; the new version differs in that the mason and mason3d packages have been unified. All the MASON 3D visualization tools stored in the display3d and portrayal3d directories, and in any app.foo3d directory. The Makefile by default makes just the 2d code: to make the 3d code as well, type `make 3d`. While the 2D code is pretty stable, the 3D code should be considered an unstable release at this time.

MacOS X users at present cannot run Java3D, so they cannot use the 3D visualization tools (we feel your pain -- most of MASON was developed on Macs!).

### MASON License

You must agree to the MASON Open Source License to use the software. This license may change for future versions of the code.

### MASON Documentation and Tutorials

Mason comes with Five Tutorials, located in the `mason/sim/app` directory. Each has an early HTML file walking through the tutorial, plus completed tutorial class files. Walking through these tutorials will help in learning MASON more than anything else, we think.

The Notes contain vital stuff that any MASON hacker should know. You'll want to check this out.

The Overview contains a rough overview of the basic MASON classes (not including the 3D visualization).

The Class Docs will prove useful to you. Again, they're only generated from the non-3D visualization stuff for now.

The Simulator Layout PDF file shows most important non-3D visualization class relationships. The OmniGraffle original is at SimulatorLayout.graffle.

### Setting up and Running MASON

Early versions of MASON will assume that you are experienced with setting up CLASSPATHs, running javac or jikes, and using a Makefile (if you're running Linux or MacOS X). Windows users will need to have appropriate tools to compile all the java files.

MASON's code at present is not stored in jar files: it's raw java files located in the mason directory. This directories must be placed in your CLASSPATH.

If you wish to produce Quicktime Movies using MASON, you must install Sun's Java Media Framework. MacOS X users should install the "Generic Java" version; at any rate, you need to make certain that the jmf.jar file in Sun's package is also located in your CLASSPATH. MASON can operate without JMF if you like.

If you wish to use the 3D toolkit, you need to download and install Sun's Java3D library. Get the version "for the JDK" rather than "for the JRE". We suggest that Windows users install the OpenGL version. Linux users can get Java3D Here. Java3D does not run on MacOS X, sorry.

MASON is running successfully if you can run:

               java sim.app.heatbugs.HeatBugsWithUI

To test the 3D tools, try (hint: increase the 'skip' value):

               java sim.app.mousetraps3d.MouseTraps3DWithUI

### How MASON applications work

Provided MASON applications are located in the sim/app folder. Many of these applications have two versions: a model application, which runs the model on the command line, occasionally checkpointing it out; and a visualizer application which calls up the visualizer toolkits and runs the model under a GUI. If a model application is run as `java sim.app.foo.Foo`, then the visualizer application is usually run as `java sim.app.foo.FooWithUI`.

Visualizer applications contain two windows usually: a Display and a Console (where the play/stop/etc. buttons are). The Console's menu lets you call forth another visualizer application (running in the same process) by providing the class name; loading from checkpoints with Open... ; and saving checkpoints with Save and Save As. In most cases you can start up a model application from a checkpoint (rather than starting from scratch) by including the argument `-checkpoint mycheckpointfile.checkpoint` on the command line.

If you close a visualizer window, it is "hidden" and can be recovered in the Console's Displays tab. If you close the Console, the simulation is quit.

Grids of rectangles can be displayed in two ways; either by drawing all the rectangles separately, or by creating an image and stretching it. The former is faster on Windows usually. The latter is faster on MacOS X always. The latter is also faster on Linux if you give the application lots (50-100 Megs?) of memory, because it will do lots of garbage-collects otherwise. Otherwise the former is faster. We've set the default on Linux to the former, but you can change that in the Options pane (the wrench icon). Java3D applications also tend to run well with lots of memory. You can set the application to 100 Megs with something along the lines of `java -Xmx100M -Xms100M ...` You can see the garbage-collects with `-verbose:gc` (only the "Full" collects matter).

### MASON apps to try

In most cases, the command-line version is shown first, followed by the visualizer version.

2D Apps

    sim.app.antsforage.AntsForage
    sim.app.antsforage.AntsForageWithUI

    sim.app.cto.CooperativeObservation
    sim.app.cto.CooperativeObservationWithUI

    sim.app.heatbugs.HeatBugs
    sim.app.heatbugs.HeatBugsWithUI

    sim.app.hexabugs.HexaBugs
    sim.app.hexabugs.HexaBugsWithUI

    sim.app.keepaway.Keepaway
    sim.app.keepaway.KeepawayWithUI

    sim.app.lightcycles.LightCycles
    sim.app.lightcycles.LightCyclesWithUI

    sim.app.lsystem.Lsystem
    sim.app.lsystem.LsystemWithUI

    sim.app.mav.MavDemo
    sim.app.mav.MavDemoWIthUI

    sim.app.networktest.NetworkTest
    sim.app.networktest.NetworkTestWithUI

    sim.app.virus.VirusInfectionDemo
    sim.app.virus.VirusInfectionDemoWithUI

    sim.app.woims.WoimsDemo
    sim.app.woims.WoimsDemoWithUI

2D Tutorial Apps

    sim.app.tutorial1and2.Tutorial1
    sim.app.tutorial1and2.Tutorial2

    sim.app.tutorial3.Tutorial3WithUI

    sim.app.tutorial4.Tutorial4WithUI

    sim.app.tutorial5.Tutorial5WithUI

3D Apps

    sim.app.crowd3d.Boids3dWithUI

    sim.app.heatbugs3d.HeatBugs3DWithUI

    sim.app.mousetraps3d.MouseTraps3DWithUI

    sim.app.woims3d.WoimsDemo3DWithUI