Simulator

java.lang.Object
- Simulator

All Implemented Interfaces:

Icon
```
public final class Simulator
extends Object
implements Icon
```
Darwin 2.1 simulator. Executes the simulation on a set of Creatures.
To play Darwin, you do not need to read the source code for this class or understand how it works.

The array passed to the Simulator constructor indicates maps spawn point labels (numbers in the map source) to subclasses to be loaded for them. The outer edge of the map is forced to wall blocks regardless of whether it is specified that way or not.

Simulator implements Icon so that it can be rendered. It can also be displayed in text mode in text mode using toString().

Check Simulator.getResult to see if the simulation has ended.

The "time" referred to in the player's guide is virtual. Taking actions does not consume wall-clock time. Instead, the creature's time accumulator is penalized as if the action had occured. This enables the simulator to run faster than real-time. The different speed modes create wall-clock delays between turns (for which no creature is penalized) so that humans can watch the action at a comfortable pace.

All public methods are synchronized unless provably threadsafe.

Morgan McGuire
morgan@cs.williams.edu

Inspired by the RoboRally board game, Steve Freund's "Darwin" lab assignment, and Nick Parlante's "Darwin's World" assignment.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`Simulator.Condition`
`static class`	`Simulator.QuietRunnable` A version of Runnable that suppresses output
`static class`	`Simulator.Result` Return value of `getResult()`
`static class`	`Simulator.Species` Aggregate information about the performance of an entire species

Field Summary

Fields
Modifier and Type	Field and Description
`static long`	`ATTACK_COST`
`static long`	`DELAY_COST`
`static long`	`EMIT_PHEROMONE_COST`
`static long`	`FOG_MOVE_FORWARD_PENTALTY_COST` The additional cost of a move forward operation that enters fog.
`static long`	`KILL_TIME` Any creature that takes more wall-clock time than this is automatically converted into an Apple (killed).
`static long`	`LOOK_COST` Deprecated.
`static long`	`MILLISECONDS` One millisecond in nanoseconds.
`static long`	`MOVE_BACKWARD_COST`
`static long`	`MOVE_FORWARD_COST`
`static long`	`MUD_PENALTY_COST` Additional cost for moving, turning, or attacking while in mud.
`static long`	`MZ_TIME_LIMIT` A maze game ends after this many virtual nanoseconds, even if no Creature has won.
`static int`	`NS_ASCENSIONS_TO_WIN`
`static long`	`NS_TIME_LIMIT` A non-maze game ends after this many virtual nanoseconds, even if no Creature has won.
`static long`	`OBSERVE_COST`
`static int`	`SCALE_2D` 2D grid size in pixels.
`static long`	`SECONDS` One second in nanoseconds.
`static Class[]`	`sharedClasses` Shared between ClassLoader (Sandbox) instances
`static long`	`TURN_COST`

Constructor Summary

Constructors
Constructor and Description
`Simulator(String mapFilename, Class[] creatures)` Loads the specified map, instantiating each of the creatures for the numbered spots in the map.

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`attack(Creature e)` Attack the creature in front of this one.
`static void`	`beginSecureExecution()` Turns on the MaximumSecurityManager and prevents Observations from containing classNames.
`void`	`delay(Creature c)` Take the delay action
`void`	`emitPheromone(Creature e, String p)`
`long`	`getComputeTimeSinceSpawn(Creature e)`
`Creature`	`getCreature(int x, int y)` Returns the creature at x, y on the grid.
`Color`	`getCreatureColor(Class c)`
`Color`	`getCreatureColor(int classId)`
`int`	`getCreatureCount(Class c)` Returns the number of creatures of this species alive in the map.
`Dimension`	`getDimensions()` Returns the size of the map.
`Direction`	`getDirection(Creature e)` Throws a ConvertedError if the Creature is not in the world.
`int`	`getIconHeight()`
`int`	`getIconWidth()`
`static Image`	`getImage(Class cs, Direction d)` Returns the image for this Creature subclass.
`static Image`	`getImage(Creature c, Direction d)`
`String`	`getInfo()` Returns a description of the simulator
`long`	`getIntraTurnTime()` Returns the wall-clock time of waitBetweenTurns() in nanoseconds.
`static Color`	`getMostCommonColor(Map<Integer,Integer> map)`
`int`	`getNaturalHeight()`
`int`	`getNaturalWidth()`
`int`	`getNumSpeciesLeft()` Returns the number of different species left alive, excluding Flytraps.
`String`	`getPheromone(Creature e)` Throws a ConvertedError if the Creature is not in the world.
`Point`	`getPosition(Creature e)` Clones the position.
`Simulator.Result`	`getResult()` Returns a description of the final outcome, or null if the game has not yet ended.
`static Sound`	`getSound(Class cs, Simulator.Condition condition)`
`static Sound`	`getSound(Creature c, Simulator.Condition condition)` Returns the appropriate sound for this creature.
`long`	`getTime()` Returns the number of virtual milliseconds since the game began.
`long`	`getTime(Creature e)` Total time for this creature; on spawn, this is inherited from the parent.
`String`	`getTitle()` Name of this map
`String`	`getToolTip(Point p)` Assumes that p is in bounds
`long`	`getTotalTimeSinceSpawn(Creature e)`
`int`	`getTurns(Creature e)` Returns the number of turns this creature has taken.
`long`	`getTurnTime()` Returns the time in virtual nanoseconds since the current creature's current turn started.
`static String`	`getVersion()` Reports the version of this simulator.
`boolean`	`getView3D()`
`boolean`	`inFog(Creature e)` Returns true if the Creature's current location is in fog.
`boolean`	`inMud(Creature e)` Returns true if the Creature's current location is in mud.
`boolean`	`isAlive(Creature c)` A creature's thread can't be stopped without potentially releasing locks that it is using for synchronization, so this method tells a creature when it should die.
`boolean`	`isEnchanted(Creature e)` Throws a ConvertedError if the Creature is not in the world.
`boolean`	`isRunning()` True while the simulation is running (not stopped).
`static Class`	`loadClass(String name, boolean secure)` Loads a class in its own Sandbox.
`boolean`	`move(Creature e, int distance)` Moves this creature forward if the space in front if it is empty, otherwise does not move.
`static void`	`nanoSleep(long t)` On some systems, Thread.sleep(long, int) has a minimum sleep time of 1ms.
`Observation[]`	`observe(Creature e)`
`void`	`paintIcon(Component c, Graphics _g, int tx, int ty)`
`static String`	`readMapTitle(String mapFilename)`
`Point`	`screenPointToLocation(int x, int y)` Returns the location under the position (x, y) if in 2D mode and in bounds, and null otherwise
`void`	`setIntraTurnTime(long t)` Set the wall-clock time to wait between turns in nanoseconds.
`void`	`setSelectedCreature(Creature c)`
`void`	`setView3D(boolean b)` If true, the view renders in 3D
`static String`	`shortName(String s)` Strips the capital letters off the right of a creature name.
`int`	`shrineClassId(Creature e)` If this creature is on a shrine, returns the classID of the creatures that own the shrine.
`void`	`start(String mapfile, Class[] creatures)` Load a new map and start a simulation.
`void`	`stop()` End simulation, without destroying final state.
`long`	`timeLimit()` Total time allowed in virtual nanoseconds for the game on the current map.
`String`	`toString()` Returns a printable text representation of the map
`void`	`turnLeft(Creature e)`
`void`	`turnRight(Creature e)` Called by a creature to turn

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - sharedClasses
```
public static final Class[] sharedClasses
```
    Shared between ClassLoader (Sandbox) instances
  - SECONDS
```
public static final long SECONDS
```
    One second in nanoseconds.
    
    See Also:
    Constant Field Values
  - MILLISECONDS
```
public static final long MILLISECONDS
```
    One millisecond in nanoseconds.
    
    See Also:
    Constant Field Values
  - KILL_TIME
```
public static final long KILL_TIME
```
    Any creature that takes more wall-clock time than this is automatically converted into an Apple (killed). Because the garbage collector can run and slow a creature unreasonable on one turn, this must be at least 0.1 seconds.
    
    See Also:
    Constant Field Values
  - EMIT_PHEROMONE_COST
```
public static final long EMIT_PHEROMONE_COST
```
    See Also:
    Constant Field Values
  - DELAY_COST
```
public static final long DELAY_COST
```
    See Also:
    Constant Field Values
  - OBSERVE_COST
```
public static final long OBSERVE_COST
```
    See Also:
    Constant Field Values
  - LOOK_COST
```
public static final long LOOK_COST
```
    Deprecated.
    
    See Also:
    Constant Field Values
  - ATTACK_COST
```
public static final long ATTACK_COST
```
    See Also:
    Constant Field Values
  - TURN_COST
```
public static final long TURN_COST
```
    See Also:
    Constant Field Values
  - MOVE_FORWARD_COST
```
public static final long MOVE_FORWARD_COST
```
    See Also:
    Constant Field Values
  - MOVE_BACKWARD_COST
```
public static final long MOVE_BACKWARD_COST
```
    See Also:
    Constant Field Values
  - FOG_MOVE_FORWARD_PENTALTY_COST
```
public static final long FOG_MOVE_FORWARD_PENTALTY_COST
```
    The additional cost of a move forward operation that enters fog. Note that other actions, including moving backwards and exiting fog, incur no additional penalty.
    
    See Also:
    Constant Field Values
  - MUD_PENALTY_COST
```
public static final long MUD_PENALTY_COST
```
    Additional cost for moving, turning, or attacking while in mud.
    
    See Also:
    Constant Field Values
  - NS_ASCENSIONS_TO_WIN
```
public static final int NS_ASCENSIONS_TO_WIN
```
    See Also:
    Constant Field Values
  - MZ_TIME_LIMIT
```
public static final long MZ_TIME_LIMIT
```
    A maze game ends after this many virtual nanoseconds, even if no Creature has won.
    
    See Also:
    Constant Field Values
  - NS_TIME_LIMIT
```
public static final long NS_TIME_LIMIT
```
    A non-maze game ends after this many virtual nanoseconds, even if no Creature has won.
    
    See Also:
    Constant Field Values
  - SCALE_2D
```
public static final int SCALE_2D
```
    2D grid size in pixels. Must be an odd number
    
    See Also:
    Constant Field Values
- Constructor Detail
  - Simulator
```
public Simulator(String mapFilename,
         Class[] creatures)
```
    Loads the specified map, instantiating each of the creatures for the numbered spots in the map.
- Method Detail
  - loadClass
```
public static Class loadClass(String name,
              boolean secure)
                       throws ClassNotFoundException,
                              IOException
```
    Loads a class in its own Sandbox. secure: if true, security is enforced and the class is not allowed to access the file system, Simulator, etc.
    
    Throws:
    
    ClassNotFoundException
    
    IOException
  - beginSecureExecution
```
public static void beginSecureExecution()
```
    Turns on the MaximumSecurityManager and prevents Observations from containing classNames. There is no way to turn security off once it has been enabled.
  - getInfo
```
public String getInfo()
```
    Returns a description of the simulator
  - getToolTip
```
public String getToolTip(Point p)
```
    Assumes that p is in bounds
  - timeLimit
```
public long timeLimit()
```
    Total time allowed in virtual nanoseconds for the game on the current map.
  - getTime
```
public long getTime(Creature e)
```
    Total time for this creature; on spawn, this is inherited from the parent.
  - getTotalTimeSinceSpawn
```
public long getTotalTimeSinceSpawn(Creature e)
```
  - getComputeTimeSinceSpawn
```
public long getComputeTimeSinceSpawn(Creature e)
```
  - getTurns
```
public int getTurns(Creature e)
```
    Returns the number of turns this creature has taken. Spawning is the first turn.
  - getPosition
```
public Point getPosition(Creature e)
```
    Clones the position. Throws a ConvertedError if the Creature is not in the world.
  - getDirection
```
public Direction getDirection(Creature e)
```
    Throws a ConvertedError if the Creature is not in the world.
  - isEnchanted
```
public boolean isEnchanted(Creature e)
```
    Throws a ConvertedError if the Creature is not in the world.
  - inFog
```
public boolean inFog(Creature e)
```
    Returns true if the Creature's current location is in fog. Fog is an experimental feature that will not appear on any tournament map in 2011. Throws a ConvertedError if the Creature is not in the world.
  - inMud
```
public boolean inMud(Creature e)
```
    Returns true if the Creature's current location is in mud. Throws a ConvertedError if the Creature is not in the world.
  - shrineClassId
```
public int shrineClassId(Creature e)
```
    If this creature is on a shrine, returns the classID of the creatures that own the shrine. Otherwise, returns Creature.UNINITIALIZED_CLASS_ID Throws a ConvertedError if the Creature is not in the world.
  - getPheromone
```
public String getPheromone(Creature e)
```
    Throws a ConvertedError if the Creature is not in the world.
  - getCreature
```
public Creature getCreature(int x,
                   int y)
```
    Returns the creature at x, y on the grid. Called by the Darwin.click method for debugger support.
  - getVersion
```
public static String getVersion()
```
    Reports the version of this simulator.
  - getTitle
```
public String getTitle()
```
    Name of this map
  - getTime
```
public long getTime()
```
    Returns the number of virtual milliseconds since the game began. This is the total time consumed by creatures, which is typically much longer than the wall-clock time for the simulation if run with no delay between turns.
  - getDimensions
```
public Dimension getDimensions()
```
    Returns the size of the map.
  - getIntraTurnTime
```
public long getIntraTurnTime()
```
    Returns the wall-clock time of waitBetweenTurns() in nanoseconds. Initially huge, so that the simulator is "paused".
  - setIntraTurnTime
```
public void setIntraTurnTime(long t)
```
    Set the wall-clock time to wait between turns in nanoseconds. 1 millisecond = 1e6 nanoseconds, 1 second = 1e9 nanoseconds Minimum value is 10000.
  - setSelectedCreature
```
public void setSelectedCreature(Creature c)
```
  - setView3D
```
public void setView3D(boolean b)
```
    If true, the view renders in 3D
  - getView3D
```
public boolean getView3D()
```
  - isRunning
```
public boolean isRunning()
```
    True while the simulation is running (not stopped).
  - getCreatureColor
```
public Color getCreatureColor(Class c)
```
  - getCreatureColor
```
public Color getCreatureColor(int classId)
```
  - getNumSpeciesLeft
```
public int getNumSpeciesLeft()
```
    Returns the number of different species left alive, excluding Flytraps.
  - getCreatureCount
```
public int getCreatureCount(Class c)
```
    Returns the number of creatures of this species alive in the map.
  - getTurnTime
```
public long getTurnTime()
```
    Returns the time in virtual nanoseconds since the current creature's current turn started. Updated continuously.
  - getResult
```
public Simulator.Result getResult()
```
    Returns a description of the final outcome, or null if the game has not yet ended. A creature has won if:
    - It is the only species other than Flytraps and Apples remaining, OR
    - Time has elapsed and it has more instances than any other Creature and there are no Treasures on the map.
  - readMapTitle
```
public static String readMapTitle(String mapFilename)
```
  - start
```
public void start(String mapfile,
         Class[] creatures)
```
    Load a new map and start a simulation. The simulation is initially paused. Called from the start button and the constructor.
  - stop
```
public void stop()
```
    End simulation, without destroying final state.
  - nanoSleep
```
public static void nanoSleep(long t)
                      throws InterruptedException
```
    On some systems, Thread.sleep(long, int) has a minimum sleep time of 1ms. This implements true nano-second sleep intervals even on such systems.
    
    Throws:
    
    InterruptedException
  - toString
```
public String toString()
```
    Returns a printable text representation of the map
    
    Overrides:
    
    toString in class Object
  - turnRight
```
public void turnRight(Creature e)
```
    Called by a creature to turn
  - turnLeft
```
public void turnLeft(Creature e)
```
  - emitPheromone
```
public void emitPheromone(Creature e,
                 String p)
```
  - observe
```
public Observation[] observe(Creature e)
```
  - move
```
public boolean move(Creature e,
           int distance)
```
    Moves this creature forward if the space in front if it is empty, otherwise does not move. Moving into a Thorn causes a Creature to be converted into an Apple.
    Throws ConvertedError if the Creature is not in the world.
    
    Parameters:
    distance - must be -1 or +1
    
    Returns:
    true if moved.
  - delay
```
public void delay(Creature c)
```
    Take the delay action
  - attack
```
public boolean attack(Creature e)
```
    Attack the creature in front of this one. If there is a creature there that is not the same class as this creature, kill it and spawn another instace of this creature facing in the same direction as this creature. If the creature in front is of the same class as this creature and this creature is enchanted, move the enchantment to the attacked creature.
  - isAlive
```
public boolean isAlive(Creature c)
```
    A creature's thread can't be stopped without potentially releasing locks that it is using for synchronization, so this method tells a creature when it should die. Creatures are not allowed to move when dead.
    All creatures are considered dead once the simulator is stopped.
  - getIconHeight
```
public int getIconHeight()
```
    Specified by:
    
    getIconHeight in interface Icon
  - getNaturalHeight
```
public int getNaturalHeight()
```
  - getIconWidth
```
public int getIconWidth()
```
    Specified by:
    
    getIconWidth in interface Icon
  - getNaturalWidth
```
public int getNaturalWidth()
```
  - paintIcon
```
public void paintIcon(Component c,
             Graphics _g,
             int tx,
             int ty)
```
    Specified by:
    
    paintIcon in interface Icon
  - screenPointToLocation
```
public Point screenPointToLocation(int x,
                          int y)
```
    Returns the location under the position (x, y) if in 2D mode and in bounds, and null otherwise
  - getImage
```
public static Image getImage(Creature c,
             Direction d)
```
  - getImage
```
public static Image getImage(Class cs,
             Direction d)
```
    Returns the image for this Creature subclass.
  - getSound
```
public static Sound getSound(Creature c,
             Simulator.Condition condition)
```
    Returns the appropriate sound for this creature.
  - getSound
```
public static Sound getSound(Class cs,
             Simulator.Condition condition)
```
  - shortName
```
public static String shortName(String s)
```
    Strips the capital letters off the right of a creature name.
  - getMostCommonColor
```
public static Color getMostCommonColor(Map<Integer,Integer> map)
```

Class Simulator

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

sharedClasses

SECONDS

MILLISECONDS

KILL_TIME

EMIT_PHEROMONE_COST

DELAY_COST

OBSERVE_COST

LOOK_COST

ATTACK_COST

TURN_COST

MOVE_FORWARD_COST

MOVE_BACKWARD_COST

FOG_MOVE_FORWARD_PENTALTY_COST

MUD_PENALTY_COST

NS_ASCENSIONS_TO_WIN

MZ_TIME_LIMIT

NS_TIME_LIMIT

SCALE_2D

Constructor Detail

Simulator

Method Detail

loadClass

beginSecureExecution

getInfo

getToolTip

timeLimit

getTime

getTotalTimeSinceSpawn

getComputeTimeSinceSpawn

getTurns

getPosition

getDirection

isEnchanted

inFog

inMud

shrineClassId

getPheromone

getCreature

getVersion

getTitle

getTime

getDimensions

getIntraTurnTime

setIntraTurnTime

setSelectedCreature

setView3D

getView3D

isRunning

getCreatureColor

getCreatureColor

getNumSpeciesLeft

getCreatureCount

getTurnTime

getResult

readMapTitle

start

stop

nanoSleep

toString

turnRight

turnLeft

emitPheromone

observe

move

delay

attack

isAlive

getIconHeight

getNaturalHeight

getIconWidth

getNaturalWidth

paintIcon

screenPointToLocation