Package squidpony.squidgrid

Class Spill

java.lang.Object
squidpony.squidgrid.Spill
All Implemented Interfaces:
Serializable
public class Spill
extends Object
implements Serializable
A randomized flood-fill implementation that can be used for level generation (e.g. filling ponds and lakes), for gas propagation, or for all sorts of fluid-dynamics-on-the-cheap. Created by Tommy Ettinger on 4/7/2015.
See Also:
Serialized Form

  • Field Summary

    Fields 
    Modifier and Type Field Description
    int filled
    The amount of cells filled by this Spill, which may be less than the volume passed to start() if the boundaries are reached on all sides and the Spill has no more room to fill.
    int height
    Height of the map.
    Measurement measurement
    This affects how distance is measured on diagonal directions vs.
    boolean[][] physicalMap
    Stores which parts of the map are accessible (with a value of true) and which are not (with a value of false, including both walls and unreachable sections of the map).
    IStatefulRNG rng
    The IStatefulRNG used to decide which one of multiple equally-short paths to take.
    boolean[][] spillMap
    The cells that are filled by the Spill when it reaches its volume or limits will be true; others will be false.
    ArrayList<Coord> spreadPattern
    The list of points that the Spill will randomly fill, starting with what is passed to start(), in order of when they are reached.
    int width
    Width of the map.

  • Constructor Summary

    Constructors 
    Constructor Description
    Spill()
    Construct a Spill without a level to actually scan.
    Spill​(boolean[][] level)
    Used to construct a Spill from the output of another.
    Spill​(boolean[][] level, Measurement measurement)
    Used to construct a Spill from the output of another, specifying a distance calculation.
    Spill​(char[][] level)
    Constructor meant to take a char[][] returned by IDungeonGenerator.generate(), or any other char[][] where '#' means a wall and anything else is a walkable tile.
    Spill​(char[][] level, char alternateWall)
    Constructor meant to take a char[][] returned by DungeonBoneGen.generate(), or any other char[][] where one char means a wall and anything else is a walkable tile.
    Spill​(char[][] level, Measurement measurement)
    Constructor meant to take a char[][] returned by DungeonBoneGen.generate(), or any other char[][] where '#' means a wall and anything else is a walkable tile.
    Spill​(char[][] level, Measurement measurement, IRNG random)
    Constructor meant to take a char[][] returned by DungeonBoneGen.generate(), or any other char[][] where '#' means a wall and anything else is a walkable tile.
    Spill​(char[][] level, Measurement measurement, IStatefulRNG random)
    Constructor meant to take a char[][] returned by DungeonBoneGen.generate(), or any other char[][] where '#' means a wall and anything else is a walkable tile.
    Spill​(IRNG random)
    Construct a Spill without a level to actually scan.
    Spill​(IStatefulRNG random)
    Construct a Spill without a level to actually scan.

  • Method Summary

    Modifier and Type Method Description
    Spill initialize​(boolean[][] level)
    Used to initialize or re-initialize a Spill that needs a new PhysicalMap because it either wasn't given one when it was constructed, or because the contents of the terrain have changed permanently.
    Spill initialize​(char[][] level)
    Used to initialize or re-initialize a Spill that needs a new PhysicalMap because it either wasn't given one when it was constructed, or because the contents of the terrain have changed permanently.
    Spill initialize​(char[][] level, char alternateWall)
    Used to initialize or re-initialize a Spill that needs a new PhysicalMap because it either wasn't given one when it was constructed, or because the contents of the terrain have changed permanently.
    void reset()
    Resets this Spill to a state with an empty spillMap and an empty spreadPattern.
    void resetCell​(int x, int y)
    Reverts a cell to an unfilled state (false in spillMap).
    void resetCell​(Coord pt)
    Reverts a cell to an unfilled state (false in spillMap).
    void resetMap()
    Resets the spillMap to being empty.
    protected void setFresh​(int x, int y)
    Used internally to mark a cell as just-now being expanded from.
    protected void setFresh​(Coord pt)
    Used internally to mark a cell as just-now being expanded from.
    ArrayList<Coord> start​(Coord entry, int volume, Set<Coord> impassable)
    Recalculate the spillMap and return the spreadPattern.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • measurement

      public Measurement measurement
      This affects how distance is measured on diagonal directions vs. orthogonal directions. MANHATTAN should form a diamond shape on a featureless map, while CHEBYSHEV and EUCLIDEAN will form a square. If you only call Spill.start() once, you should strongly prefer MANHATTAN, even if the rest of the game uses another measurement, because CHEBYSHEV and EUCLIDEAN can produce odd, gap-filled flood-fills. Any case where you have too many gaps can be corrected to varying extent by calling start() more than once with slowly increasing values. Because start() will extend from the existing area of the Spill, holes are likely to be filled after a few calls, but if the last call to start() tries to fill too many more cells than the previous one, it can cause holes on the periphery of the Spill area.

    • physicalMap

      public boolean[][] physicalMap
      Stores which parts of the map are accessible (with a value of true) and which are not (with a value of false, including both walls and unreachable sections of the map). Should not be changed unless the actual physical terrain has changed. You should call initialize() with a new map instead of changing this directly.

    • spillMap

      public boolean[][] spillMap
      The cells that are filled by the Spill when it reaches its volume or limits will be true; others will be false.

    • spreadPattern

      public ArrayList<Coord> spreadPattern
      The list of points that the Spill will randomly fill, starting with what is passed to start(), in order of when they are reached.

    • height

      public int height
      Height of the map. Exciting stuff. Don't change this, instead call initialize().

    • width

      public int width
      Width of the map. Exciting stuff. Don't change this, instead call initialize().

    • filled

      public int filled
      The amount of cells filled by this Spill, which may be less than the volume passed to start() if the boundaries are reached on all sides and the Spill has no more room to fill.

    • rng

      public IStatefulRNG rng
      The IStatefulRNG used to decide which one of multiple equally-short paths to take. Typically, this is a GWTRNG or StatefulRNG.

  • Constructor Details

    • Spill

      public Spill()
      Construct a Spill without a level to actually scan. If you use this constructor, you must call an initialize() method before using this class.

    • Spill

      public Spill​(IRNG random)
      Construct a Spill without a level to actually scan. This constructor allows you to specify an RNG, but the actual RandomnessSource the RNG that this object uses will not be identical to the one passed as random (two ints will be requested from the passed RNG, and that will be used to seed this class' RNG). If you use this constructor, you must call an initialize() method before using this class.

    • Spill

      public Spill​(IStatefulRNG random)
      Construct a Spill without a level to actually scan. This constructor allows you to specify an IStatefulRNG such as StatefulRNG or GWTRNG, which will be referenced in this class (if the state of random changes because this object needed a random number, the state change will be reflected in the code that passed random to here). If you use this constructor, you must call an initialize() method before using this class.

    • Spill

      public Spill​(boolean[][] level)
      Used to construct a Spill from the output of another.
      Parameters:
      level - the level as a 2D rectangular boolean array, using false to represent walls

    • Spill

      public Spill​(boolean[][] level, Measurement measurement)
      Used to construct a Spill from the output of another, specifying a distance calculation.
      Parameters:
      level - the level as a 2D rectangular boolean array, using false to represent walls
      measurement - a Measurement enum; usually Measurement.MANHATTAN is ideal

    • Spill

      public Spill​(char[][] level)
      Constructor meant to take a char[][] returned by IDungeonGenerator.generate(), or any other char[][] where '#' means a wall and anything else is a walkable tile. If you only have a map that uses box-drawing characters, use DungeonUtility.linesToHashes() to get a map that can be used here.
      Parameters:
      level - the level as a 2D rectangular char array, using '#' to represent walls

    • Spill

      public Spill​(char[][] level, char alternateWall)
      Constructor meant to take a char[][] returned by DungeonBoneGen.generate(), or any other char[][] where one char means a wall and anything else is a walkable tile. If you only have a map that uses box-drawing characters, use DungeonUtility.linesToHashes() to get a map that can be used here. You can specify the character used for walls.
      Parameters:
      level - the level as a 2D rectangular char array, using alternateWall to represent walls
      alternateWall - the char that will be interpreted as a wall in level

    • Spill

      public Spill​(char[][] level, Measurement measurement)
      Constructor meant to take a char[][] returned by DungeonBoneGen.generate(), or any other char[][] where '#' means a wall and anything else is a walkable tile. If you only have a map that uses box-drawing characters, use DungeonUtility.linesToHashes() to get a map that can be used here. This constructor specifies a distance measurement.
      Parameters:
      level - the level as a 2D rectangular char array, using '#' to represent walls
      measurement - a Measurement enum; usually Measurement.MANHATTAN is ideal

    • Spill

      public Spill​(char[][] level, Measurement measurement, IRNG random)
      Constructor meant to take a char[][] returned by DungeonBoneGen.generate(), or any other char[][] where '#' means a wall and anything else is a walkable tile. If you only have a map that uses box-drawing characters, use DungeonUtility.linesToHashes() to get a map that can be used here. This constructor specifies a distance measurement. This constructor allows you to specify an RNG, but the actual RandomnessSource the RNG that this object uses will not be identical to the one passed as random (two ints will be requested from the passed RNG, and that will be used to seed this class' RNG).
      Parameters:
      level - the level as a 2D rectangular char array, using '#' to represent walls
      measurement - a Measurement enum; usually Measurement.MANHATTAN is ideal

    • Spill

      public Spill​(char[][] level, Measurement measurement, IStatefulRNG random)
      Constructor meant to take a char[][] returned by DungeonBoneGen.generate(), or any other char[][] where '#' means a wall and anything else is a walkable tile. If you only have a map that uses box-drawing characters, use DungeonUtility.linesToHashes() to get a map that can be used here. This constructor specifies a distance measurement. This constructor allows you to specify an IStatefulRNG such as GWTRNG or StatefulRNG, which will be referenced in this class (if the state of random changes because this object needed a random number, the state change will be reflected in the code that passed random to here).
      Parameters:
      level - the level as a 2D rectangular char array, using '#' to represent walls
      measurement - a Measurement enum; usually Measurement.MANHATTAN is ideal

  • Method Details

    • initialize

      public Spill initialize​(boolean[][] level)
      Used to initialize or re-initialize a Spill that needs a new PhysicalMap because it either wasn't given one when it was constructed, or because the contents of the terrain have changed permanently.
      Parameters:
      level - the level as a 2D rectangular boolean array, using false to represent walls
      Returns:
      this Spill after initialization has completed, for chaining

    • initialize

      public Spill initialize​(char[][] level)
      Used to initialize or re-initialize a Spill that needs a new PhysicalMap because it either wasn't given one when it was constructed, or because the contents of the terrain have changed permanently.
      Parameters:
      level - the level as a 2D rectangular char array, using '#' to represent walls
      Returns:
      this Spill after initialization has completed, for chaining

    • initialize

      public Spill initialize​(char[][] level, char alternateWall)
      Used to initialize or re-initialize a Spill that needs a new PhysicalMap because it either wasn't given one when it was constructed, or because the contents of the terrain have changed permanently. This initialize() method allows you to specify an alternate wall char other than the default character, '#'.
      Parameters:
      level - the level as a 2D rectangular char array, using alternateWall to represent walls
      alternateWall - the char that will be interpreted as a wall in level
      Returns:
      this Spill after initialization has completed, for chaining

    • resetMap

      public void resetMap()
      Resets the spillMap to being empty.

    • reset

      public void reset()
      Resets this Spill to a state with an empty spillMap and an empty spreadPattern.

    • resetCell

      public void resetCell​(int x, int y)
      Reverts a cell to an unfilled state (false in spillMap).
      Parameters:
      x - the x position of the cell to reset
      y - the y position of the cell to reset

    • resetCell

      public void resetCell​(Coord pt)
      Reverts a cell to an unfilled state (false in spillMap).
      Parameters:
      pt - the position of the cell to reset

    • setFresh

      protected void setFresh​(int x, int y)
      Used internally to mark a cell as just-now being expanded from.
      Parameters:
      x - the x position of the cell to reset
      y - the y position of the cell to reset

    • setFresh

      protected void setFresh​(Coord pt)
      Used internally to mark a cell as just-now being expanded from.
      Parameters:
      pt - the position of the cell to reset

    • start

      public ArrayList<Coord> start​(Coord entry, int volume, Set<Coord> impassable)
      Recalculate the spillMap and return the spreadPattern. The cell corresponding to entry will be true, the cells near that will be true if chosen at random from all passable cells adjacent to a filled (true) cell, and all other cells will be false. This takes a total number of cells to attempt to fill (the volume parameter), and will fill less if it has completely exhausted all passable cells. If the measurement this Spill uses is anything other than MANHATTAN, you can expect many gaps in the first filled area. Subsequent calls to start() with the same entry and a higher volume will expand the area of the Spill, and are likely to fill any gaps after a few subsequent calls. Increasing the volume slowly is the best way to ensure that gaps only exist on the very edge if you use a non-MANHATTAN measurement.
      Parameters:
      entry - The first cell to spread from, which should really be passable.
      volume - The total number of cells to attempt to fill, which must be non-negative.
      impassable - A Set of Position keys representing the locations of moving obstacles to a path that cannot be moved through; this can be null if there are no such obstacles.
      Returns:
      An ArrayList of Points that this will enter, in order starting with entry at index 0, until it reaches its volume or fills its boundaries completely.