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