You must agree to the MASON Open Source License to use the software. This license may change for future versions of the code.
When you're ready to start coding, go through our seven 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 to code with MASON more than anything else, we think.
The Notes contain vital stuff that any MASON hacker should know. There is also an overview of the basic MASON classes. The Simulator Layout PDF file shows most important non-3D visualization class relationships. The OmniGraffle original is at SimulatorLayout.graffle.
Last but hardly least, we predict that the Class Docs will prove useful to you.
This version of MASON presumes 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. Steps:
cd mason; make 3d; make docs
If you've not installed Java3D and just want to play with the 2D stuff, try:
cd mason; make; make docs
If you don't have jikes installed, you may need to first change the JAVAC variable in the Makefile to javac.
MASON is a library, not an application. Each application which uses it will probably be run with a different command.
Here are two such applications. MASON is running successfully if you can run:
java sim.app.heatbugs.HeatBugsWithUI
To test the 3D system, you might try:
java sim.app.mousetraps3d.MouseTraps3DWithUI
You can also select classes from a predefined list (in the sim/display/simulation.classes file, which you're welcome to edit). Normally this list is displayed when you choose "New Simulation" from the menu. But you can also go straight to the list when you launch MASON like this (try it!):
java sim.display.Console
Provided MASON applications are located in the Visualizer applications contain at least two windows: at least one 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; load from checkpoints with Open... ; and save checkpoints with Save and Save As.
In most cases you can start up a model application to start running at a checkpoint 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 better with lots of memory. For example, you can set the application to 100 Megs with something along the lines of java -Xmx100M -Xms100M ... You can see how often garbage-collection happens with the -verbose:gc option (only the "Full" collects matter).
MacOS X presents a special gotcha. The 2D MASON code runs much faster on MacOS X when using Java 1.3.1, as 1.4.1 is not presently hardware accelerated on the Mac. But the 3D MASON code only runs on 1.4.1. So if you're doing a MASON 3D app you must run 1.4.1 on the Mac; but if you're doing a MASON 2D app, you'll probably be much happier running 1.3.1. Sorry about that!
If you've upgraded to the latest Java on the Mac, you're running 1.4.1 or later. You can make a given Terminal window use 1.3.1 instead of 1.4.1 java with the command:
alias java /System/Library/Frameworks/JavaVM.framework/Versions/1.3.1/Home/bin/java
MASON apps to try
In most cases, the command-line (model application) 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
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
sim.app.tutorial6.Tutorial6WithUI
sim.app.tutorial7.Tutorial7WithUI