wyvern.lib
Interface GameMap

All Superinterfaces:
Container, Hookable, MethodHookable, wyvern.kernel.lighting.Obstructions, PropertyList
All Known Implementing Classes:
AbstractGameMap

public interface GameMap
extends Hookable, PropertyList, wyvern.kernel.lighting.Obstructions, Container

A GameMap represents an area that players can visit; a game server will have thousands of individual maps.

A map is a 2D coordinate space. You can do all the standard things you'd expect to be able to do:

You can also perform various queries on the map:

When you're looking for objects in a map, you're usually only interested in a subset of the objects. For example, you might only want the Living objects. The Map interface supports passing a filter function, called a Predicate, so you only get the objects you're interested in. A Predicate simply looks at an Object and returns true if it's interesting, false otherwise. There are a few predefined predicates in wyvern.lib.predicates, and you can also define your own.

Sometimes you want to do something to a set of objects in a map. For example, you might want to blast all the living things in rectangle R with a fireball. The map supports this by allowing you to pass in a Visitor object that is allowed to process each object in turn.

Version:
1.0, Aug 14, 1997
Author:
Steve Yegge

Nested Class Summary
static interface GameMap.UnloadMapConstants
          Codes returned by the GameMap.dismantle() method, which attempts to unload a map from memory.
 
Field Summary
static int MAX_HEIGHT
           
static int MAX_SEARCH_RADIUS
          The max distance from the center that findFreeSpot() will search for an unblocked location.
static int MAX_WIDTH
          Dense maps use normal arrays to store their contents, so we limit the size of dense maps so that the arrays don't get too big.
 
Fields inherited from interface wyvern.lib.PropertyList
PROPERTY_PACKAGE
 
Method Summary
 void add(int x, int y, GameObject obj)
          Adds the specified object to the map at the specified location.
 void add(int x, int y, GameObject obj, boolean invalidate)
          Adds specified object to the map, optionally invalidating the map.
 void addLight(int x, int y, LightSource light)
          Adds a light source to the map.
 void addLocalArchetype(Archetype arch)
          Adds a local archetype to this map.
 void addMapLifecycleListener(MapLifecycleListener listener)
          Registers with the map to be notified whenever it loads, unloads, suspends, or resumes.
 void addPlayerListener(MapPlayerListener listener)
          Registers with the map to be notified whenever players enter or leave the map, or move within the map.
 void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
          Adds a PropertyChangeListener to the listener list.
 void addPropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
          Adds a PropertyChangeListener for a specific property.
 void addProximityHook(ProximityCallback callback, java.lang.String hookName, GameObject target, Rectangle range)
          Registers for hook notifications for events occurring within a fixed range of a given object.
 void addRoomHook(RoomHookCallback callback, java.lang.String hookName, Rectangle room)
          Registers for a specific area of interest in the map.
 void adjustIntensity(int x, int y, int intensity)
          Manually adjusts the light intensity by a fixed amount at the passed (x, y) location.
 void broadcast(java.lang.String msg)
          Broadcasts a message to every player in the map.
 void broadcast(java.lang.String msg, byte style)
          Broadcasts a message to every player in the map.
 int dismantle()
          Do NOT call this method - use World.unloadMap(mapname) instead, unless you have created the map yourself without registering it with the World.
 void doneLoading()
          Notification from the MapLoader that we've finished adding objects to the map.
 void enableVisUpdates(boolean enable)
          While the map is being loaded; that is, while objects are initially being added to it, turning off visual updates will improve the load time.
 GameObject findAt(int x, int y, Predicate p)
          Looks for an object at the passed map location that passes the specified Predicate.
 GameObject findByName(int x, int y, java.lang.String name)
          Finds the first object at the specified location that matches the passed name, using a standard NameMatchPredicate.
 GameObject findByName(Point p, java.lang.String name)
          Returns the topmost visible object at the passed location.
 Point findFreeSpot(Point request, GameObject obj)
          Tries to find a free spot to put this object in.
 GameObject findInRect(int x, int y, int w, int h, Predicate p)
          Searches the objects in the specified rectangle and returns the first one that satisfies the passed Predicate.
 GameObject findTop(int x, int y)
          Returns the "topmost" object at this location.
 GameObject findTop(int x, int y, Predicate p)
          Returns the topmost object at the specified location that passes a specified predicate.
 GameObject findUnder(GameObject obj, Predicate p)
          Looks under the passed GameObject's locations for an object that matches the passed Predicate.
 void firePropertyChange(java.beans.PropertyChangeEvent evt)
          Fires an existing PropertyChangeEvent to any registered listeners.
 void firePropertyChange(java.lang.String propertyName, boolean oldValue, boolean newValue)
          Reports a boolean bound property update to any registered listeners.
 void firePropertyChange(java.lang.String propertyName, int oldValue, int newValue)
          Reports an int bound property update to any registered listeners.
 void firePropertyChange(java.lang.String propertyName, java.lang.Object oldValue, java.lang.Object newValue)
          Reports a bound property update to any registered listeners.
 Area getArea()
          Returns the parent Area for this map.
 Rectangle getBounds()
          Returns the bounds of the map, in local coordinates.
 Player getClaim()
          Returns the player currently claiming the map, if any.
 Command getCommand(CommandEvent event, Commandable agent)
          Checks the list of Commands who have registered this command with the map, and returns the first one whose rectangle of interest contains the agent issuing the command.
 int getDangerLevel()
          Returns the danger level for this map.
 Terrain getDefaultTerrain()
          Returns the default terrain for this map.
 java.util.Set getExits()
          Returns the set of all teleporters in this map that happen to have destinations - even if the teleporter's destination is to another point in this map.
 java.util.Map getFavorites()
          Returns the set of favorite archetypes for this map, for use in the map editor.
 int getLightingLevel()
          Returns the lighting level of this map.
 int getLightLevel(int x, int y)
          Returns the lighting level at the specified location.
 Archetype getLocalArchetype(java.lang.String name)
          Retrieves a local archetype from the map's cache.
 java.util.List getLocalArchetypes()
          Returns a list of the names of all local archetypes registered with this map.
 java.util.Set getMonsterList()
          Returns the set of monsters currently active in this map.
 Music getMusic()
          Returns the background music for this map.
 java.lang.String getName()
          Returns the name of this map.
 int getObjectCount()
          Returns an approximate count of the GameObjects in this map, including terrain.
 java.util.List getObjectsAt(int x, int y)
          Returns a list of the objects at a location.
 Terrain getOutOfBoundsTerrain()
          Returns what we use for the out-of-bounds terrain.
 java.lang.String getPath()
          Returns the (relative) path to the map file this map was loaded from, e.g.
 java.util.Set getPlayerList()
          Returns the set of players currently playing in this map.
 PropertyList getProperties(int x, int y)
          You can get and set properties on a specific map location.
 java.beans.PropertyChangeListener[] getPropertyChangeListeners()
          Returns an array of all the PropertyChangeListeners added to this map with addPropertyChangeListener();
 java.beans.PropertyChangeListener[] getPropertyChangeListeners(java.lang.String propertyName)
          Returns an array of all the listeners which have been associated with the named property.
 PropertyList getPropertyList(int x, int y)
          Returns the property list for the given (x, y) map location, creating the list if necessary.
 ProximityHookList getProximityHookList()
          Returns the ProximityHookList containing the registered proximity-hooks for this map.
 Resource getResource()
          Returns the Resource for this map, so you can query if it's a wiz map, how big it is, what the relative file path is, and so on.
 Location getRestartLoc()
          Returns the restart-location for this map: where players teleport to when they die in this map.
 RoomHookList getRoomHookList()
          Returns the RoomHookList containing the registered room-hooks for this map.
 Dimension getSize()
          Returns the size of the map.
 Point getStartLocation()
          Returns the default starting location for the map.
 int getSuspendTime()
          Returns the length of time, in milliseconds, since this map was suspended.
 int[][] getTerrainInfo(int x, int y, int w, int h)
          Returns enough information about the terrain in the passed rectangle to be able to draw the terrain (with borders) in a client program.
 int getTerrainRecord(int x, int y)
          Returns a packed record describing the terrain at (x, y), suitable for use in drawing terrain borders.
 int getUnloadDelay()
          Returns the time, in milliseconds, that we'll wait, after we suspend, before unloading the map.
 MapDirtyRegions getUpdateList()
          Returns a list of updates that have occurred since the last query.
 java.lang.String getVirtualPath()
          This is exactly the same as getPath() normal maps, but returns "players/whoever/" + getPath() for per-player maps.
 boolean hasListeners(java.lang.String propertyName)
          Checks if there are any listeners for a specific property.
 void initialize(Dimension size)
          Initializes the map to the specified width and height.
 void initialize(int width, int height)
          Initializes the map to the specified width and height.
 boolean inMapEditor()
          Returns true if we're being loaded in the map editor.
 void invalidate(int x, int y, int w, int h)
          Forces the map to refresh a particular area.
 boolean isEmpty(int x, int y)
          Returns true if there's nothing in the map at the passed location except terrain.
 boolean isLit()
          Returns true if the map is completely lit, e.g. by daylight.
 boolean isPerPlayer()
          Returns true if this map is a per-player map, meaning it was loaded by a teleporter with the "per-player" property.
 boolean isSparse()
          Sparse maps have been retired, and this method will now always return false.
 boolean isSuspended()
          Returns true if the map is currently suspended.
 boolean isUnloaded()
          Returns true if the map has started the unload process.
 java.util.Set keySet()
          Returns the set of nonempty points in this map.
 void notifyPlayerListeners(int type, Player player, Point source)
          Don't call this.
 void registerAddRemoveListener(MapAddRemoveListener listener)
          Registers with the map to be notified whenever objects are added to, or removed from, the map.
 void registerCommand(java.lang.String command, Command handler, Rectangle room)
          Whenever someone enters a command that isn't in their local command-list, the game engine passes the command to the agent's GameMap to see if anyone has registered the command with the map itself.
 void remove(int x, int y, GameObject obj)
          Removes an object reference at the specified map location (x, y).
 void remove(int x, int y, GameObject obj, boolean invalidate)
          Removes an object from the map, optionally invalidating.
 GameObject removeFirst(int x, int y, Predicate p)
          Removes and returns the first object that satisfies the passed Predicate.
 void removeLight(int x, int y, LightSource light)
          Removes a light source from the map.
 Archetype removeLocalArchetype(java.lang.String name)
          Removes a local archetype from the map's cache.
 void removeMapLifecycleListener(MapLifecycleListener listener)
          Removes a MapLifecycleListener from this map.
 void removePlayerListener(MapPlayerListener listener)
          Removes an MapPlayerListener from this map.
 void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
          Removes a PropertyChangeListener from the listener list.
 void removePropertyChangeListener(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
          Removes a PropertyChangeListener for a specific property.
 void removeProximityHook(ProximityCallback callback, java.lang.String hookName, GameObject target, Rectangle range)
          Removes a callback from the specified proximity-hook.
 void removeRoomHook(RoomHookCallback callback, java.lang.String hookName, Rectangle room)
          Removes a callback from the specified room-hook.
 void resetOpaqueFlag(int x, int y)
          Tells the map to re-scan the specified location to see if there are any opaque objects there.
 void resume()
          Resumes the map (if it was suspended.)
 void setAutoload()
          Tells the map that it was autoloaded.
 void setDangerLevel(int level)
          Sets the danger level for this map.
 void setDefaultTerrain(java.lang.String terrain)
          Sets the default terrain for the map.
 void setDefaultTerrain(Terrain t)
          Sets the default terrain for the map: the terrain that will be returned if a query is made on a location where no terrain type has been set explicitly using setTerrain().
 void setFavorite(int index, Archetype arch)
          Adds a "favorite" archetype to the map, for use in the map editor.
 void setLightingLevel(int ambient)
          Sets the global, ambient lighting level for the map.
 void setLit(boolean lit)
          Marks the map as having lighting effects, or not.
 void setName(java.lang.String name)
          Sets the name of the map.
 void setOutOfBoundsTerrain(Terrain t)
          Sets the terrain to use outside the valid map bounds.
 void setPath(java.lang.String path)
          Sets the path to the map.
 void setPerPlayer(java.lang.String name)
          Marks the map as being a per-player map.
 void setSize(Dimension size)
          Changes the size of the map.
 void setStartLocation(Point start)
          Sets the location at which players start when they enter the map, if the teleporter asks the map where to start.
 void setTerrain(int x, int y, Terrain t)
          Sets (or removes) the terrain at the specified map location.
 void setUnloadDelay(int delay)
          Sets the amount of time to wait (in millis) after suspending before the map is unloaded.
 void suspend()
          Tells the map to suspend itself.
 Terrain terrainAt(int x, int y)
          Returns the Terrain at the passed location.
 void unload()
          Tells the map to unload.
 void unregisterAddRemoveListener(MapAddRemoveListener listener)
          Removes an MapAddRemoveListener from this map.
 void unregisterCommand(java.lang.String command, Command handler, Rectangle room)
          Removes the specified Command from the map's command-list.
 void updateTerrainCache(int x, int y, int w, int h)
          Call this whenever you change the appearance of a particular piece of terrain.
 void visitObjectsAt(int x, int y, Visitor v)
          Performs an operation on a set of objects at the specified location.
 void visitRect(int x, int y, int w, int h, Visitor v)
          Visits all the objects in the specified rectangle, optionally doing something to them.
 void visUpdate(GameObject m)
          Forces the map to refresh a particular area.
 void wakeAllMonsters()
          Wakes up all the monsters in the map, e.g. if a loud noise occurred.
 void wakeMonsters(Point loc, int range)
          Wakes up monsters near the specified point.
 
Methods inherited from interface wyvern.lib.Hookable
addHook, getHookList, getHooks, removeHook, runFailedPostHook, runPostHook, runPreHook
 
Methods inherited from interface wyvern.lib.MethodHookable
addMethodHook, removeMethodHook, runMethodHook
 
Methods inherited from interface wyvern.lib.PropertyList
addProperty, addTransientProperty, adjustDoubleProperty, adjustIntProperty, adjustLongProperty, adjustTransientDoubleProperty, adjustTransientIntProperty, adjustTransientLongProperty, countLocalProperties, getDoubleProperty, getInheritedProperty, getIntProperty, getLocalProperties, getLocalProperty, getLongProperty, getParent, getPersistentDoubleProperty, getPersistentIntProperty, getPersistentLocalProperties, getPersistentLongProperty, getPersistentProperty, getProperties, getProperties, getPropertiesIncludingTransients, getPropertiesIncludingTransients, getProperty, getSerializableProperties, getSerializableProperty, getStringProperty, getTransientDoubleProperty, getTransientIntProperty, getTransientLongProperty, getTransientProperties, getTransientProperty, hasLocalProperty, hasPersistentProperty, hasProperty, hasTransientProperty, inheritProperty, isReadOnly, isRemoved, isTransientlyRemoved, printLocalProperties, printProperties, printProperties, printTransientProperties, removeProperty, removeTransientProperty, setDoubleProperty, setIntProperty, setLongProperty, setParent, setProperty, setReadOnly, setTransientDoubleProperty, setTransientIntProperty, setTransientLongProperty, setTransientProperty, toString, transientlyRemoveProperty
 
Methods inherited from interface wyvern.kernel.lighting.Obstructions
hasObstructions, isOpaque
 
Methods inherited from interface wyvern.lib.Container
isBag, isInventory, isMap
 

Field Detail

MAX_WIDTH

public static final int MAX_WIDTH
Dense maps use normal arrays to store their contents, so we limit the size of dense maps so that the arrays don't get too big.

See Also:
Constant Field Values

MAX_HEIGHT

public static final int MAX_HEIGHT
See Also:
Constant Field Values

MAX_SEARCH_RADIUS

public static final int MAX_SEARCH_RADIUS
The max distance from the center that findFreeSpot() will search for an unblocked location.

See Also:
Constant Field Values
Method Detail

findAt

public GameObject findAt(int x,
                         int y,
                         Predicate p)
Looks for an object at the passed map location that passes the specified Predicate. It DOES check the terrain at the passed location, so it may return a terrain object if that's the first object that passes the predicate.

Parameters:
x - map x
y - map y
p - a Predicate to filter the objects at (x, y)
Returns:
the first object at (x, y) for which the predicate returns true, or null if none returned true
See Also:
Predicate

findUnder

public GameObject findUnder(GameObject obj,
                            Predicate p)
Looks under the passed GameObject's locations for an object that matches the passed Predicate. Uses the same rules as findAt().

Parameters:
obj - the object to look under
p - the Predicate for looking for a particular object
Returns:
the first GameObject under obj that matches the predicate, or null if none was found

isEmpty

public boolean isEmpty(int x,
                       int y)
Returns true if there's nothing in the map at the passed location except terrain.

Parameters:
x - x location
y - y location
Returns:
true if there are no objects at this location

terrainAt

public Terrain terrainAt(int x,
                         int y)
Returns the Terrain at the passed location. Always non-null.

Parameters:
x - x location
y - y location
Returns:
the Terrain object at (x, y)
See Also:
Terrain

visitObjectsAt

public void visitObjectsAt(int x,
                           int y,
                           Visitor v)
Performs an operation on a set of objects at the specified location. This is done by passing a Visitor object, which decides (for each object) whether to perform the operation. It visits the terrain at the passed location first, then the objects (if any).

Parameters:
x - x location
y - y location
v - the Visitor to send to each object at location (x, y)
See Also:
Visitor

visitRect

public void visitRect(int x,
                      int y,
                      int w,
                      int h,
                      Visitor v)
Visits all the objects in the specified rectangle, optionally doing something to them. Uses the same rules as visitObjectsAt().

Parameters:
x - x map coordinate
y - y map coordinate
w - rectangle width
h - rectangle height
v - a Visitor object. It checks each object in turn, and if the object satisfies whatever criteria the Visitor establishes, then it performs an operation on the object.
See Also:
Visitor

findInRect

public GameObject findInRect(int x,
                             int y,
                             int w,
                             int h,
                             Predicate p)
Searches the objects in the specified rectangle and returns the first one that satisfies the passed Predicate. Uses the same rules as findAt().

Parameters:
x - x (world coordinates)
y - y (world coordinates)
w - rectangle width
h - rectangle height
p - a Predicate filter to check each object in turn.
See Also:
Predicate

getTerrainInfo

public int[][] getTerrainInfo(int x,
                              int y,
                              int w,
                              int h)
Returns enough information about the terrain in the passed rectangle to be able to draw the terrain (with borders) in a client program.

Parameters:
x - map x
y - map y
w - rect width
h - rect height
Returns:
a 2D array with the passed dimensions (w,h). Each int in the array is a packed record, constructed as follows:
  • bits 0-15 are the (unsigned short) tile number.
  • bits 16-29 are a 14-bit 1's-complement layer priority.
  • bit 30 is set if the square lets borders in, else clear
  • bit 31 is set if the square lets borders out, else clear

getTerrainRecord

public int getTerrainRecord(int x,
                            int y)
Returns a packed record describing the terrain at (x, y), suitable for use in drawing terrain borders.

Parameters:
x - the map x coordinate
y - the map y coordinate
Returns:
A bitfield describing the terrain. The low 16 bits are the terrain tile number. Bits 17-28 are the terrain priority, a signed number. (Bit 28 is the sign bit). Bit 29 is the "has-borders" flag; true if the terrain has borders. Bit 30 is the "lets-in" flag: set if the terrain permits borders to encroach into it, clear if the square disallows incoming borders even from higher-priority squares. Bit 31 is the "lets-out" flag: set if the square wants to extend borders (only meaningful if the terrain type actually has borders), clear if the square doesn't want to use any borders it might normally have.

Here's a picture of it:

          +-------------------------------+
          |1|1|1| 13 bits  |   16 bits    |
          +-------------------------------+
          /         |            |
      border      layer         tile
       flags     priority       number

 

add

public void add(int x,
                int y,
                GameObject obj)
Adds the specified object to the map at the specified location.

Adding the same object to a position it already occupies is not recommended, but it's not explicitly prevented, either.

This method will attempt to add the object to *some* map, even if the requested position is out of this map's bounds. Typically this is handled by passing the request up to the map's parent, which finds the right place to put the object. If for some reason the object simply can't be placed at (x, y), an ArrayIndexOutOfBoundsException results.

This method will invalidate the map using the bounds of the passed object. It's the same as calling add(x, y, obj, true).

Parameters:
x - the map location x coordinate
y - the map location y coordinate
obj - the GameObject to add to the map at (x, y)
See Also:
GameObject

add

public void add(int x,
                int y,
                GameObject obj,
                boolean invalidate)
Adds specified object to the map, optionally invalidating the map. If you're adding references to an object to the map in multiple locations, you should call this method passing false in the invalidate parameter. When you've finished adding all the references, you should invalidate the map manually. Alternately you may choose to pass true when adding the last reference, if the object is rectangular, so that the entire bounds of the object are invalidated in the map at once.

Parameters:
x - the map location x coordinate
y - the map location y coordinate
obj - the GameObject to add to the map at (x, y)
invalidate - true to call visUpdate on the map, passing in the object's bounding rectangle. If false, you must call visUpdate manually on any locations that have been changed visibly by the add.

remove

public void remove(int x,
                   int y,
                   GameObject obj)
Removes an object reference at the specified map location (x, y).

Note: this is -not- the correct way to remove most objects from a map.

This method will remove the requested object no matter what kind of object it is (e.g. spell effect, static object), with one exception: it will not remove the default Terrain object at (x, y). You can try, but it won't work - there always has to be a Terrain object at each location, so if the location is empty, the game will use the default terrain for the map. This method automatically invalidates the map at each location the object occupies. If you want to remove it without invalidating the map (which would be weird, because everyone would think it was still there), you'd have to to call map.remove(x, y, obj, false).

Parameters:
x - the map location x coordinate
y - the map location y coordinate
obj - the object at (x, y) to remove.
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the point is invalid
See Also:
GameObject

remove

public void remove(int x,
                   int y,
                   GameObject obj,
                   boolean invalidate)
Removes an object from the map, optionally invalidating.

Parameters:
x - the map location x coordinate
y - the map location y coordinate
obj - the GameObject to remove from the map at (x, y)
invalidate - true to call visUpdate on the map, passing in the object's bounding rectangle. If false, you must invalidate the map manually by calling visUpdate() on any areas that have been changed visibly by the remove.

removeFirst

public GameObject removeFirst(int x,
                              int y,
                              Predicate p)
Removes and returns the first object that satisfies the passed Predicate.

Parameters:
x - the map location x coordinate
y - the map location y coordinate
p - the Predicate to filter the object. Returns null if no objects at (x, y) satisfy the predicate.
See Also:
Predicate, GameObject

setTerrain

public void setTerrain(int x,
                       int y,
                       Terrain t)
Sets (or removes) the terrain at the specified map location.

Parameters:
x - the map location x coordinate
y - the map location y coordinate
t - the Terrain object to place there. If null, sets the terrain at that location to the default terrain for the map.
Throws:
java.lang.ArrayIndexOutOfBoundsException - if (x, y) is out of bounds.

updateTerrainCache

public void updateTerrainCache(int x,
                               int y,
                               int w,
                               int h)
Call this whenever you change the appearance of a particular piece of terrain. You'll know when you need to call it, since the map view won't update properly with the terrain's new appearance. Called automatically when you do setTerrain(), so it's only required if you change a terrain's appearance, layer, priority, or whether it lets borders in/out.

Parameters:
x - map x coordinate where the terrain is located
y - map y coordinate where the terrain is located
w - the width of the rectangle to update (usually 1)
h - the height of the rectangle to update (usually 1)

setDefaultTerrain

public void setDefaultTerrain(Terrain t)
Sets the default terrain for the map: the terrain that will be returned if a query is made on a location where no terrain type has been set explicitly using setTerrain().

Parameters:
t - the Terrain object to use for the default locations.

setDefaultTerrain

public void setDefaultTerrain(java.lang.String terrain)
                       throws java.lang.Exception
Sets the default terrain for the map. For dense maps, this is the terrain that will be returned inside the bounds of the map. DenseMaps have an additional method for setting the terrain that shows up outside the map's bounds.

For sparse maps, the default terrain is what's used anywhere the terrain hasn't been set explicitly.

Parameters:
terrain - the archetype to use (e.g. "terrain/water")
Throws:
an - Exception if the passed archetype name is invalid
java.lang.Exception

setOutOfBoundsTerrain

public void setOutOfBoundsTerrain(Terrain t)
Sets the terrain to use outside the valid map bounds. Has no effect on sparse/unbounded maps.


getOutOfBoundsTerrain

public Terrain getOutOfBoundsTerrain()
Returns what we use for the out-of-bounds terrain. Has no effect on sparse/unbounded maps.


getDefaultTerrain

public Terrain getDefaultTerrain()
Returns the default terrain for this map.

Returns:
the default terrain object

setStartLocation

public void setStartLocation(Point start)
Sets the location at which players start when they enter the map, if the teleporter asks the map where to start.

Parameters:
start - the starting location

getStartLocation

public Point getStartLocation()
Returns the default starting location for the map.

Returns:
the position at (or near) which to position players entering the map, if the teleporter doesn't specify where to start explicitly.

findFreeSpot

public Point findFreeSpot(Point request,
                          GameObject obj)
Tries to find a free spot to put this object in. Uses a standard BlockingPredicate to decide whether a spot is available.

Parameters:
request - preferred map location
obj - the object to add to the map
Returns:
a free spot to put the object in, as near as possible to the requested location. Stops at max radius of 20 from requested location. Returns null if couldn't find a spot.

dismantle

public int dismantle()
Do NOT call this method - use World.unloadMap(mapname) instead, unless you have created the map yourself without registering it with the World. (E.g. a vehicle interior). Make sure there are no players in the map before calling this method; otherwise it will fail.

This method runs the method-hook "unload" before unloading the map.

Returns:
an UnloadMapConstants return value

unload

public void unload()
Tells the map to unload. The map will not be unloaded if it has players in it. After the map is successfully unloaded, it runs a method-hook called "unload", with no data parameter.


suspend

public void suspend()
Tells the map to suspend itself. You probably shouldn't call it yourself. It gets called by a timer that's set when the map is first loaded, and also when the last player leaves the map. A suspended map stops all the monsters and timers in the map, and when it's resumed, the monsters start up again. The map is automatically resumed if a player enters the map.

The map runs the "suspend" method-hook on this call.


isSuspended

public boolean isSuspended()
Returns true if the map is currently suspended.

Returns:
true if map is suspended (i.e. monsters, timers stopped)

getSuspendTime

public int getSuspendTime()
Returns the length of time, in milliseconds, since this map was suspended. Returns -1 if the map isn't suspended.

Returns:
suspend time

resume

public void resume()
Resumes the map (if it was suspended.) If it was suspended the map will un-suspend and run the "resume" method hook.


addRoomHook

public void addRoomHook(RoomHookCallback callback,
                        java.lang.String hookName,
                        Rectangle room)
Registers for a specific area of interest in the map. A "room" is any rectangular area; it doesn't have anything to do with walls per se.

Parameters:
callback - the RoomHookCallback to notify when the hook is run.
hookName - the name of the hook list to register on
room - the rectangle to listen in. Events outside the rectangle are not passed to the callback object.

removeRoomHook

public void removeRoomHook(RoomHookCallback callback,
                           java.lang.String hookName,
                           Rectangle room)
Removes a callback from the specified room-hook.

Parameters:
callback - the RoomHookCallback to remove from the list
hookName - the name of the hook list to unregister from rectangle are not passed to the callback object.
room - the room which the callback was interested in. It is necessary to pass the room so that if the callback was registered for more than one room, the map will know which room to remove it from.

getRoomHookList

public RoomHookList getRoomHookList()
Returns the RoomHookList containing the registered room-hooks for this map.

Returns:
the RoomHookList for room map hooks for this map, or null if no room hooks have been registered yet. The RoomHookList is instantiated lazily.

addProximityHook

public void addProximityHook(ProximityCallback callback,
                             java.lang.String hookName,
                             GameObject target,
                             Rectangle range)
Registers for hook notifications for events occurring within a fixed range of a given object. This is useful for objects that move about in the map. For fixed objects it's faster to register on a room-hook.

A proximity-hook is implemented by placing the target object within the passed range rectangle. The rectangle is translated to the target's reference location, which for rectangular targets is almost always its upper-left corner.

For example, to register interest in the 8 squares surrounding a 1x1 monster, pass a range of (-1, -1, 3, 3). If the monster is currently at (5, 5), the proximity area will extend from (4, 4) to (6, 6).

Parameters:
callback - the HookCallback to notify when the hook is run.
hookName - the name of the hook list to register on
target - the roaming object at the center of the range. May be the same as the callback object.
range - the local coordinates around the target object that define the bounding box of interest.

removeProximityHook

public void removeProximityHook(ProximityCallback callback,
                                java.lang.String hookName,
                                GameObject target,
                                Rectangle range)
Removes a callback from the specified proximity-hook.

Parameters:
callback - the HookCallback to remove from the list
hookName - the name of the hook list to unregister from rectangle are not passed to the callback object.
target - the roaming object at the center of the range. May be the same as the callback object.
range - the local coordinates around the target object that define the bounding box of interest. The range needs to be passed in case the target was registered for hooks in more than one range.

getProximityHookList

public ProximityHookList getProximityHookList()
Returns the ProximityHookList containing the registered proximity-hooks for this map.

Returns:
the ProximityHookList for proximity-hooks for this map, or null if no proximity-hooks have been registered. The ProximityHookList is instantiated lazily.

registerCommand

public void registerCommand(java.lang.String command,
                            Command handler,
                            Rectangle room)
Whenever someone enters a command that isn't in their local command-list, the game engine passes the command to the agent's GameMap to see if anyone has registered the command with the map itself.

For instance, the Shop object registers the "list" command with the map the Shop is in. Whenever a player types "list" in a Shop, and "list" isn't a command registered in their local command-list (usually it isn't), then the game engine checks whether someone has registered the command with the map the player is in, and if so, invokes that Command to handle it (via the Command's createEvent and execute methods).

Parameters:
command - the command to handle
handler - the callback object to handle the command
room - the map sub-rectangle in which to register interest. It can be the entire map bounds if the handler wants to handle the command no matter where the agent is. The rectangle is clipped against the map bounds, so it's not an error if it specifies an area outside the map bounds. (Optionally, you can pass null to use the map bounds).

unregisterCommand

public void unregisterCommand(java.lang.String command,
                              Command handler,
                              Rectangle room)
Removes the specified Command from the map's command-list. The Command may be registered for the command in multiple rectangles in the same map, so you need to pass in the rectangle that was passed to registerCommand().

Parameters:
command - the command to unregister
handler - the handler to unregister
room - the map sub-rectangle to unregister (Optionally, you can pass null to use the entire map bounds).

getCommand

public Command getCommand(CommandEvent event,
                          Commandable agent)
Checks the list of Commands who have registered this command with the map, and returns the first one whose rectangle of interest contains the agent issuing the command. Also checks the ground beneath the agent for a Command object that claims to know the command, even if it's not registered for it. (This is for the convenience of movable objects that don't want to have to register with the map every time they move).

Parameters:
event - the event to look for a handler for
agent - the agent doing the command
Returns:
a Command to handle the command, or null if no Command was registered for that command where the agent is at.

registerAddRemoveListener

public void registerAddRemoveListener(MapAddRemoveListener listener)
Registers with the map to be notified whenever objects are added to, or removed from, the map. If you add a listener more than once, it'll get called more than once for each add/remove (so don't do it). If you're doing complex processing in your MapAddRemoveListener callback method, you should get on the map's done-loading hook, and only register your listener after the map is finished loading, so you don't get called thousands of times while the map is being built.

Parameters:
listener - the MapAddRemoveListener

unregisterAddRemoveListener

public void unregisterAddRemoveListener(MapAddRemoveListener listener)
Removes an MapAddRemoveListener from this map.

Parameters:
listener - the MapAddRemoveListener

addPlayerListener

public void addPlayerListener(MapPlayerListener listener)
Registers with the map to be notified whenever players enter or leave the map, or move within the map. This is faster and more specific than using registerAddRemoveListener(), if you're only interested in players moving around in the map.

Parameters:
listener - the MapPlayerListener

removePlayerListener

public void removePlayerListener(MapPlayerListener listener)
Removes an MapPlayerListener from this map.

Parameters:
listener - the MapPlayerListener

notifyPlayerListeners

public void notifyPlayerListeners(int type,
                                  Player player,
                                  Point source)
Don't call this. Used by game engine only.


addMapLifecycleListener

public void addMapLifecycleListener(MapLifecycleListener listener)
Registers with the map to be notified whenever it loads, unloads, suspends, or resumes. Normally you don't need to call this. Just have your object implement the MapLifecycleListener interface, and it'll automatically start receiving the events after it's added to the map.

Parameters:
listener - the MapLifecycleListener

removeMapLifecycleListener

public void removeMapLifecycleListener(MapLifecycleListener listener)
Removes a MapLifecycleListener from this map. You don't normally need to call this. Simply removing/destroying the object will remove it from the listener list. However, if you have a MapLifecycleListener that's not a MapObject sitting in the map, you'll need to call this method when you want it to stop receiving the map events.

Parameters:
listener - the MapLifecycleListener

getProperties

public PropertyList getProperties(int x,
                                  int y)
You can get and set properties on a specific map location.

This can be handy, for example, if you want to do a very fast check to see if a particular kind of object is at some location (x, y). The object should set a property on the cell saying that it's there, and then others can look for that property. It's faster than going through all the objects at (x, y), checking each one to see if it's the type you're looking for.

Parameters:
x - map x location
y - map y location
Returns:
the list of properties at that location, or NULL if nobody has set any properties at that location.

getPropertyList

public PropertyList getPropertyList(int x,
                                    int y)
Returns the property list for the given (x, y) map location, creating the list if necessary.

You call this method if you're about to set a property in the list. It creates an empty PropertyList for this map location, if nobody has set any properties at that (x, y) yet.

PLEASE don't call this if you're just checking to see if a location has a certain property. Only call it if you're going to set or adjust a property value for the location.

Parameters:
x - map x location
y - map y location
Returns:
the list of properties at (x, y) for this map. Creates the list if necessary, so the return value will always be non-null.

getName

public java.lang.String getName()
Returns the name of this map. By default it gets set to the map's filename (minus the extension) but you can change it to something more descriptive, such as "underground lake".

Returns:
the name of the map, as shown to players

setName

public void setName(java.lang.String name)
Sets the name of the map. Should only be called when creating or loading a map.


getPath

public java.lang.String getPath()
Returns the (relative) path to the map file this map was loaded from, e.g. "aston/town1/chapel". For maps that were constructed on the fly, it returns a name suitable for retrieving the map by calling World.getMap().


getVirtualPath

public java.lang.String getVirtualPath()
This is exactly the same as getPath() normal maps, but returns "players/whoever/" + getPath() for per-player maps.

Returns:
the relative path for the map, with a prefix of "players/playername/" in front of the map path, if it's a per-player map.

setPath

public void setPath(java.lang.String path)
Sets the path to the map. For maps created dynamically with no map-file representation, this can be anything at all, such as the name of the map. It needs to be unique among all maps that can be loaded by a given server.

This method is typically only used for maps that are created dynamically by some other means than reading them from a map file.

Parameters:
path - the new path to the map.

setPerPlayer

public void setPerPlayer(java.lang.String name)
Marks the map as being a per-player map. You should never have to call this function - it's invoked after a map is loaded using a per-player teleporter. It sets the virtual path to "players/" + name + "/" + getPath().

Parameters:
name - the player name for whom this map is unique

isPerPlayer

public boolean isPerPlayer()
Returns true if this map is a per-player map, meaning it was loaded by a teleporter with the "per-player" property. It means that each player winds up in his/her own copy of the map. For per-player maps, the path obtained from getPath() is the same as it is for global maps. The "virtual path", obtained via getVirtualPath(), has "players/{playername}/" prepended in front of the map path. Per-player map instances are stored in the World list by their virtual paths, so you could have, for example, "players/joe/village/tutorial" and "players/sheila/village/tutorial" in the World map list.

Returns:
true if this is a per-player map

getPlayerList

public java.util.Set getPlayerList()
Returns the set of players currently playing in this map. Don't modify it.

Returns:
a Set containing references to all players in the map. May be empty, but will never be null.

getMonsterList

public java.util.Set getMonsterList()
Returns the set of monsters currently active in this map. Don't modify it.

Returns:
a Set containing references to all monsters in the map. May be empty, but will never be null.

getExits

public java.util.Set getExits()
Returns the set of all teleporters in this map that happen to have destinations - even if the teleporter's destination is to another point in this map.

Returns:
a Set containing references to all the teleporters in this map. May be empty, but will never be null. The set is a *copy* of the map's internal teleporter set, so you are free to modify it if you wish - however, it will have no effect on the actual map.

invalidate

public void invalidate(int x,
                       int y,
                       int w,
                       int h)
Forces the map to refresh a particular area. Called automatically when an object is added, removed or moved in the map. Also called by GameObject.setBitmap(). Clients should call it whenever they cause part of the map to change its appearance using some mechanism the map isn't aware of.

Parameters:
x - the left side of the update rectangle
y - the right side of the update rectangle
w - the width of the update rect
h - the height of the update rect

visUpdate

public void visUpdate(GameObject m)
Forces the map to refresh a particular area. Called automatically when an object is added, removed or moved in the map. Also called by GameObject.setBitmap(). Clients should call it whenever they cause part of the map to change its appearance using some mechanism that the map isn't aware of.

Parameters:
m - the GameObject whose appearance has changed. Its bounds (via getBounds()) will be used to determine the update region.

getUpdateList

public MapDirtyRegions getUpdateList()
Returns a list of updates that have occurred since the last query.

Returns:
the update list, which is then set to a new, blank list

enableVisUpdates

public void enableVisUpdates(boolean enable)
While the map is being loaded; that is, while objects are initially being added to it, turning off visual updates will improve the load time. Normally you don't have to call this - the MapLoader will do it automatically for you. If you're creating a map on the fly, consider disabling updates after calling the constructor, and re-enabling them when you've added the initial set of objects to the map.

Caution: if you accidentally leave updates off, changes to the map won't get propagated to the cameras, and players in the map will have a "frozen" map display.

Parameters:
enable - true to turn on updates, false to turn them off

getSize

public Dimension getSize()
Returns the size of the map. For sparse maps, this will be a very large number (Integer.MAX_VALUE, in each dimension).

Returns:
a dimension containing the width & height of the map.

getBounds

public Rectangle getBounds()
Returns the bounds of the map, in local coordinates.

Returns:
a Rectangle with the map bounds. For sparse maps, this will be -Integer.MAX_VALUE/2 to Integer.MAX_VALUE/2. For dense maps, this will be (0, 0) to (width-1, height-1).

getObjectsAt

public java.util.List getObjectsAt(int x,
                                   int y)
Returns a list of the objects at a location. Game code should *never* modify this list unless it has the implicit "map exclusive" (only obtained when the kernel calls a Command's handleEvent method).

Parameters:
x - map x coordinate
y - map y coordinate
Returns:
null if there are no objects there. Might include the terrain at that location, if it's non-default. Callers should not perform mutative operations on this list, as other threads may have iterators on the list.

isSparse

public boolean isSparse()
Sparse maps have been retired, and this method will now always return false.


inMapEditor

public boolean inMapEditor()
Returns true if we're being loaded in the map editor.


setAutoload

public void setAutoload()
Tells the map that it was autoloaded. This sets a shorter unload delay than normal, since it's statistically less likely that someone will actually enter the map.


getDangerLevel

public int getDangerLevel()
Returns the danger level for this map. Danger level is stored in an int property on the map called "danger-level". However, the int property doesn't exist on all maps, for backwards-compatibility reasons, so a level of zero should be interpreted to mean danger level 1. If you call this function, it will return a value of 1 if the underlying property's value is zero or one.

Returns:
the map's danger level (1-20)

setDangerLevel

public void setDangerLevel(int level)
Sets the danger level for this map. You can set it to higher than 20, but some functions in the game will treat a number higher than 20 as equivalent to 20.

Parameters:
level - the new danger level (1-20)
Throws:
java.lang.IllegalArgumentException - if the passed level is zero or negative.

getClaim

public Player getClaim()
Returns the player currently claiming the map, if any.

Returns:
a player claiming the map, or null if there's no claim on the map

getObjectCount

public int getObjectCount()
Returns an approximate count of the GameObjects in this map, including terrain. It actually returns a higher number, since it's really counting object references, so a 3x3 object will add 9 to the count. The method is used to get an approximate in-game indication of the memory usage for the map, since the map dimensions aren't always a good indicator, e.g. if the map is using a lot of flyweight terrain.

Returns:
the count of object references in this map. Only counts each Terrain object once, even if the Terrain object has multiple references in the map. For instance, in most maps, grass is a flyweight, and there's only one instance of a Terrain object for all the grass in the map.

getMusic

public Music getMusic()
Returns the background music for this map. Looks for a "music" property, and if that isn't present, looks for the map's parent Area to see if it specifies a "music" property.

Returns:
a Soundtrack object representing the music to play for this map. Can be null if the map hasn't specified any music to play.

getArea

public Area getArea()
Returns the parent Area for this map. If you put a

Returns:
the Area for this map. Always non-null, but if the "area.arch" file wasn't present, or didn't have any properties, then the Area won't either.

getResource

public Resource getResource()
Returns the Resource for this map, so you can query if it's a wiz map, how big it is, what the relative file path is, and so on.

Returns:
a Resource describing the file this map was loaded from. Always non-null. If the map was constructed dynamically, the Resource's exists() method will return false, since there's no corresponding disk file. It may have other accurate information, however.

getRestartLoc

public Location getRestartLoc()
Returns the restart-location for this map: where players teleport to when they die in this map. It should specify a chapel or save haven, preferably one that's always loaded and never resets.

Returns:
the restart location for this map. Looks in the parent Area if not specified in a "restart-loc" property on the map. Can be null, in which case the World object figures out a default restart location for the map.

addLight

public void addLight(int x,
                     int y,
                     LightSource light)
Adds a light source to the map. The map will call the LightSource back to get its intensity array, so before calling this method, the LightSource should already have computed the array.

Parameters:
x - the x location of the light source
y - the y location of the light source
light - the light source

removeLight

public void removeLight(int x,
                        int y,
                        LightSource light)
Removes a light source from the map. The map will immediately call the LightSource back, asking for its intensity array, so that the map can subtract the intensity contribution of the LightSource from its global lighting array. Therefore it's important that the LightSource's intensity be valid when calling removeLight().

Parameters:
x - the x location of the light source
y - the y location of the light source
light - the light source

adjustIntensity

public void adjustIntensity(int x,
                            int y,
                            int intensity)
Manually adjusts the light intensity by a fixed amount at the passed (x, y) location. Useful for objects that want to manage their own illumination, or for tweaking an area of a map to be brighter or darker than the ambient intensity.

Parameters:
x - the x location to adjust
y - the y location to adjust
intensity - the +/- amount by which to adjust the lighting level

isLit

public boolean isLit()
Returns true if the map is completely lit, e.g. by daylight. No lighting effects will be computed if the map is lit. By default, maps are lit. If a map has a property called "dark", then this method returns false.

Returns:
true if the map is lit, so light sources have no effect

setLit

public void setLit(boolean lit)
Marks the map as having lighting effects, or not.

Parameters:
lit - true if the map is completely lit, false if it's dark

getLightingLevel

public int getLightingLevel()
Returns the lighting level of this map. For lit maps, this returns the value for daylight. For darkened maps, it returns the value of the int property "ambient", which like all int properties defaults to zero if not present. A negative value will make the map extra-dark; e.g. a -1 will make a torch's illumination radius smaller by 1.

Returns:
the ambient lighting level for the map

setLightingLevel

public void setLightingLevel(int ambient)
Sets the global, ambient lighting level for the map. Not normally set directly (except by the night/day code), but it's possible that a spell might want to adjust the overall map lighting level, which is why this method is provided.

Parameters:
ambient - the new ambient lighting level for the map

getLightLevel

public int getLightLevel(int x,
                         int y)
Returns the lighting level at the specified location. Takes into account the ambient (overall) intensity, as well as contributions from any local light sources. This is used, for instance, by the camera system to decide how dark to draw the square.

Parameters:
x - map x location
y - map y location
Returns:
the cumulative lighting level at (x, y). If zero or negative, the square is completely dark.

resetOpaqueFlag

public void resetOpaqueFlag(int x,
                            int y)
Tells the map to re-scan the specified location to see if there are any opaque objects there. If it finds that the current state is different from its cached state, it updates the cached state and notifes all the cameras and light sources to redo their raycasting.

Parameters:
x - map x location to rescan
y - map y location to rescan

broadcast

public void broadcast(java.lang.String msg)
Broadcasts a message to every player in the map.

Parameters:
msg - the message to broadcast.

broadcast

public void broadcast(java.lang.String msg,
                      byte style)
Broadcasts a message to every player in the map.

Parameters:
msg - the message to broadcast.
style - the RPCConstants.TextStyle to use
See Also:
RPCConstants

wakeMonsters

public void wakeMonsters(Point loc,
                         int range)
Wakes up monsters near the specified point.

Parameters:
loc - the point near which to wake monsters
range - the radius within which to wake them

wakeAllMonsters

public void wakeAllMonsters()
Wakes up all the monsters in the map, e.g. if a loud noise occurred.


findTop

public GameObject findTop(int x,
                          int y)
Returns the "topmost" object at this location. That is, it visits all the objects at the location and returns the one whose getLayer() returns the highest number. If there is a tie, it returns the object with the highest hashcode, which is consistent with the way objects are rendered in displays of the map.

Parameters:
x - the map x location
y - the map y location
Returns:
the "top" object at that location

findTop

public GameObject findTop(int x,
                          int y,
                          Predicate p)
Returns the topmost object at the specified location that passes a specified predicate. "Top" is defined as for the overloaded findTop() method that takes no predicate parameter.

Parameters:
x - the map x location
y - the map y location
p - the predicate to use: returns true if it likes the object
Returns:
the "top" object at that location that passes the predicate, or null if no object there passes the predicate

findByName

public GameObject findByName(int x,
                             int y,
                             java.lang.String name)
Finds the first object at the specified location that matches the passed name, using a standard NameMatchPredicate.

Parameters:
name - the name to match
x - the x location to look at
y - the y location to look at
Returns:
the first matching object at (x, y) or null if none found

findByName

public GameObject findByName(Point p,
                             java.lang.String name)
Returns the topmost visible object at the passed location.

Parameters:
p - the map (x, y) coordinates
name - the name to match
See Also:
findByName(int, int, java.lang.String)

addLocalArchetype

public void addLocalArchetype(Archetype arch)
Adds a local archetype to this map. Usually called by the MapLoader or map editor. Local archetypes are used in maps to share properties among many objects specific to that map. For instance, a cave.map might want every terrain square to have the short description "cave floor". Rather than add a new system archetype for cave_floor, or add the property "cave floor" to every square in the map, we can create a local archetype inside the map and have all the terrain square refer to it.

As useful as they are for cutting down map sizes (both on disk and in-memory), we're not sure yet how to handle an instance of a local archetype moving out of its map, so be careful only to use local archetypes for immovable objects like walls and terrain.

Parameters:
arch - the local archetype to add to the cache. The name must be set via setName() before calling this method. If another archetype was already registered under this name, the previous archetype will be replaced by the new one.
Throws:
java.lang.IllegalArgumentException - if the archetype has no name to use as a key in the cache.

getLocalArchetype

public Archetype getLocalArchetype(java.lang.String name)
Retrieves a local archetype from the map's cache.

Parameters:
name - the name, in the form "local/whatever".
Returns:
the archetype stored under that name in the map, or null if not found.

removeLocalArchetype

public Archetype removeLocalArchetype(java.lang.String name)
Removes a local archetype from the map's cache.

Parameters:
name - the name, in the form "local/whatever"
Returns:
the Archetype that was stored under that name, or null if there was none.

getLocalArchetypes

public java.util.List getLocalArchetypes()
Returns a list of the names of all local archetypes registered with this map.

Returns:
a List of String objects, which will be empty if there are no map-local archetypes in this map.

setFavorite

public void setFavorite(int index,
                        Archetype arch)
Adds a "favorite" archetype to the map, for use in the map editor. The archetype will be displayed in the map editor for easy access. Favorites are saved out with the map and restored when the map is reloaded in the editor. Not really useful for Wizards, since it's an editor-specific function.

Parameters:
index - the index in the favorites list to set it at
arch - the archetype to set; null to clear it

getFavorites

public java.util.Map getFavorites()
Returns the set of favorite archetypes for this map, for use in the map editor. Not really useful for Wizards, since it's an editor-specific function.

Favorites are stored in the map file as string properties, where the property name is "favorite-n" (n being the index), and the property value is the path to the archetype. This method enumerates over the map's properties and retrieves any of them that match "favorite-n", and puts them in the return map.

Returns:
a map whose keys are Integers corresponding to the index of each favorite in the map. The values are the paths generated by calling arch.provideName() for each favorite archetype in the map. Returns null if the map has no favorites set. We don't currently support saving out favorites with local properties - a favorite is just a reference to an existing archetype, either a system archetype or a wizard archetype.


doneLoading

public void doneLoading()
Notification from the MapLoader that we've finished adding objects to the map. This method runs a method-hook called "done-loading" with no data object argument. If you load a map without using a MapLoader, you should call doneLoading() when you've finished constructing the map and adding all the objects to it.


isUnloaded

public boolean isUnloaded()
Returns true if the map has started the unload process. It could be partially or completely unloaded, but in either case you should treat it as if it has been unloaded.

Returns:
true if this map has been unloaded

getUnloadDelay

public int getUnloadDelay()
Returns the time, in milliseconds, that we'll wait, after we suspend, before unloading the map.

Returns:
the number of milliseconds to remain suspended before unloading

setUnloadDelay

public void setUnloadDelay(int delay)
Sets the amount of time to wait (in millis) after suspending before the map is unloaded.

Parameters:
delay - the length of time (in millis) to remain suspended

keySet

public java.util.Set keySet()
Returns the set of nonempty points in this map. May not be implemented for all map types, but it's guaranteed to be implemented if isSparse() returns true for this map. You really shouldn't call this method; it could easily destabilize the game if you misuse it. May throw a SecurityException if called from Wizard code.


setSize

public void setSize(Dimension size)
Changes the size of the map. This should never be done when the map is active, i.e. if events are occurring in the map. It's here largely for the benefit of the map editor.

Parameters:
size - the size for the map

initialize

public void initialize(int width,
                       int height)
Initializes the map to the specified width and height. You can only call this one time per map. The map uses this to create its internal data structures, if you didn't call one of the constructors that takes a size.

Parameters:
width - the map width
height - the map height
Throws:
java.lang.IllegalStateException - if the map has already been initialized

initialize

public void initialize(Dimension size)
Initializes the map to the specified width and height. You can only call this one time per map. The map uses this to create its internal data structures, if you didn't call one of the constructors that takes a size.

Parameters:
size - the size for the map
Throws:
java.lang.IllegalStateException - if the map has already been initialized

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list.


addPropertyChangeListener

public void addPropertyChangeListener(java.lang.String propertyName,
                                      java.beans.PropertyChangeListener listener)
Adds a PropertyChangeListener for a specific property.


firePropertyChange

public void firePropertyChange(java.beans.PropertyChangeEvent evt)
Fires an existing PropertyChangeEvent to any registered listeners. No event is fired if the given event's old and new values are equal and non-null.

Parameters:
evt - the PropertyChangeEvent object

firePropertyChange

public void firePropertyChange(java.lang.String propertyName,
                               boolean oldValue,
                               boolean newValue)
Reports a boolean bound property update to any registered listeners.


firePropertyChange

public void firePropertyChange(java.lang.String propertyName,
                               int oldValue,
                               int newValue)
Reports an int bound property update to any registered listeners.


firePropertyChange

public void firePropertyChange(java.lang.String propertyName,
                               java.lang.Object oldValue,
                               java.lang.Object newValue)
Reports a bound property update to any registered listeners.


getPropertyChangeListeners

public java.beans.PropertyChangeListener[] getPropertyChangeListeners()
Returns an array of all the PropertyChangeListeners added to this map with addPropertyChangeListener();


getPropertyChangeListeners

public java.beans.PropertyChangeListener[] getPropertyChangeListeners(java.lang.String propertyName)
Returns an array of all the listeners which have been associated with the named property.


hasListeners

public boolean hasListeners(java.lang.String propertyName)
Checks if there are any listeners for a specific property.


removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list.


removePropertyChangeListener

public void removePropertyChangeListener(java.lang.String propertyName,
                                         java.beans.PropertyChangeListener listener)
Removes a PropertyChangeListener for a specific property.