Package itumulator.world

Class World

java.lang.Object
itumulator.world.World
public class World extends Object
The World class provides an abstraction for our simulated worlds. A world contains beneficial abstractions for interacting with the world, some of which are used by the Simulator itself. World contains a landscape / 'map' (a three-dimensional array) wherein objects can be placed. The world class / object provides abstractions for manipulating this. Furthermore, World can contain objects not currently existing on the map, e.g., when objects are not visible. This is primarily used by the simulator to ensure all Actor can act without being on the 'map'.

  • Constructor Details

    • World

      public World(int size)
      initializes a World with a map of size. A day is defined in steps (i.e., 20) and day time is decided by before the first 10 steps.
      Parameters:
      size - of the map within the world (size defines both x and y).

  • Method Details

    • step

      public void step()
      Increases the step of the world to progress time.

    • isDay

      public boolean isDay()
      Provides an indicator of whether it is day.
      Returns:
      true if it is day time.

    • isNight

      public boolean isNight()
      Provides an indicator of whether it is night.
      Returns:
      true if it is night time.

    • getSize

      public int getSize()
      Provides the size of the world (it is square)
      Returns:
      the x and y of the world.

    • setDay

      public void setDay()
      Sets the time to day.

    • setNight

      public void setNight()
      Sets the time of the world to beginning of night, according to IS_DAY_TIME.

    • getCurrentTime

      public int getCurrentTime()
      Provides the current time of day
      Returns:
      the current time as an integer

    • getTotalDayDuration

      public static int getTotalDayDuration()
      Provides the total amount of ticks of a day
      Returns:
      the total amount of ticks of a day

    • getDayDuration

      public static int getDayDuration()
      Provides the amount of day time ticks
      Returns:
      the amount of ticks the world is in day time

    • setCurrentLocation

      public void setCurrentLocation(Location current)
      Sets the location which is deemed as the 'current' location. This is the location used when calling parameterless methods normally requiring a parameter (e.g., getSurroundingTiles). Please note that methods like move and setTile do not update this location. You have to do that manually using setCurrentLocation(itumulator.world.Location) if you want to keep using the parameterless methods.
      Parameters:
      current - the location which will be set as currently under examination (can be null). Eg. when the actor is not on the map but exists in the world.
      Throws:
      IllegalArgumentException - thrown if the location is out of bounds.

    • getCurrentLocation

      public Location getCurrentLocation()
      Provides the current location of the world. This is the location which the world uses for the overloaded methods (e.g., getSurroundingTiles()). This does not provide any object.
      Returns:
      the current location.

    • getLocation

      public Location getLocation(Object object)
      Retrieves the current location of a specified object within the world. If the object is in the world but not currently on the map (i.e., its location is null), this method throws an exception.
      Parameters:
      object - The object whose location is to be retrieved.
      Returns:
      The current location of the object on the map.
      Throws:
      IllegalArgumentException - if the object does not exist in the world, or if it exists but is not currently placed on the map.

    • getSurroundingTiles

      public Set<Location> getSurroundingTiles()
      Get immediate tiles surrounding the current location (as defined by getCurrentLocation and setLocation). The method only returns existing locations within the map.
      Returns:
      set of immediate surrounding locations.
      Throws:
      IllegalStateException - thrown if current location not set.

    • getSurroundingTiles

      public Set<Location> getSurroundingTiles(int radius)
      Get tiles (up to the radius provided) surrounding the current location which are not filled (as defined by getCurrentLocation and setCurrentLocation). The method only returns existing locations within the map.
      Parameters:
      radius - the number of locations to include in each direction.
      Returns:
      set of surrounding locations.
      Throws:
      IllegalStateException - thrown if current location not set.

    • getEmptySurroundingTiles

      public Set<Location> getEmptySurroundingTiles()
      Get tiles which are not filled surrounding the current location (as defined by getCurrentLocation and setLocation) and isTileEmpty(Location)). The method only returns existing locations within the map.
      Returns:
      set of surrounding tiles which are empty.
      Throws:
      IllegalStateException - thrown if current location not set.

    • remove

      public void remove(Object object)
      Removes an object from its current location on the map, but retains its existence in the world. This method is particularly useful for temporarily 'hiding' an object from the map without deleting it (if an actor, its act method will continuously be called). Note: this does not delete the object from the world's entity list. Furthermore, remove does not update the current location. Thus, calling overloaded methods (e.g., getEmptySurroundingTiles()) will still provide the tiles surrounding the location you removed from.
      Parameters:
      object - The object to be removed from the map.
      Throws:
      IllegalArgumentException - if the object does not exist in the world, or is not currently placed on the map.

    • delete

      public void delete(Object object)
      Completely removes an object from the world, both from the map and the world's entity list. This method is used when an object is no longer needed in the simulation and should be permanently deleted. If the object is currently on the map, it is first removed using remove(Object) method. Then, the object is removed from the world's entity list, ensuring that it no longer exists within the world context.
      Parameters:
      object - The object to delete from the world.
      Throws:
      IllegalArgumentException - if the object does not exist in the world.

    • setTile

      public void setTile(Location location, Object object)
      Places a given object at a specified location on the map. If the location already contains an object of the same type (blocking/non-blocking), an exception is thrown. Additionally, if the object already exists elsewhere in the world, it cannot be placed again. Note that setTile does not update the current location. Thus, one cannot after using setTile use the overloaded methods (e.g., getEmptySurroundingTiles()) as the current location is not set.
      Parameters:
      location - The location where the object will be placed.
      object - The object to place at the specified location.
      Throws:
      IllegalArgumentException - if the tile is occupied by the same type of object, or if the object already exists on the map, or if the location is out of bounds.

    • move

      public void move(Object object, Location to)
      Moves an object from its current location to a new location.
      Parameters:
      object - The object to be moved.
      to - The destination location for the object.
      Throws:
      IllegalArgumentException - if the object is not in the world, is not on the map, or if the destination tile is occupied by a blocking object.

    • getTile

      public Object getTile(Location location)
      Retrieves an object from a specified location, prioritizing blocking objects over non-blocking ones. If a blocking object exists at the location, it is returned; otherwise, the non-blocking object is returned. If multiple objects are present (one blocking and one non-blocking), the blocking one is always returned. If no objects are present at the location, null is returned.
      Parameters:
      location - The location from which to retrieve the object.
      Returns:
      The object at the specified location, prioritizing blocking objects. Returns null if no object is present.

    • add

      public void add(Object object)
      Adds an object to the world without placing it on the map. The object's location is set to null, indicating it is not currently on the map. This method is useful for adding objects that exist in the world but are not visible or interactable on the map.
      Parameters:
      object - The object to add to the world.
      Throws:
      IllegalArgumentException - if the object already exists in the world.

    • getNonBlocking

      public Object getNonBlocking(Location location)
      Retrieves a non-blocking object from a specified location. If a non-blocking object is present at the location, it is returned. If no non-blocking object is present, an exception is thrown.
      Parameters:
      location - The location to check for a non-blocking object.
      Returns:
      The non-blocking object at the specified location.

    • isTileEmpty

      public boolean isTileEmpty(Location location)
      Checks if a specified location is empty. A tile is considered empty if it does not contain any blocking objects. Non-blocking objects do not affect the emptiness status of a tile.
      Parameters:
      location - The location to check.
      Returns:
      true if the tile is empty (no blocking objects present), false otherwise.

    • containsNonBlocking

      public boolean containsNonBlocking(Location location)
      Determines whether a specified location contains a non-blocking object. This method checks if there is an object at the location that implements the NonBlocking interface.
      Parameters:
      location - The location to check.
      Returns:
      true if a non-blocking object is present, false otherwise.

    • getSurroundingTiles

      public Set<Location> getSurroundingTiles(Location location)
      Retrieves a set of locations immediately surrounding the specified location, including diagonals. The method calculates the surrounding tiles within a radius of 1 tile. Tiles outside the bounds of the world are excluded.
      Parameters:
      location - The central location for which surrounding tiles are to be found.
      Returns:
      A set of locations immediately surrounding the specified location.
      Throws:
      IllegalArgumentException - if the specified location is out of bounds.

    • getSurroundingTiles

      public Set<Location> getSurroundingTiles(Location location, int radius)
      Retrieves a set of locations surrounding the specified location within a given radius. This method includes all tiles within the radius. Tiles outside the world's bounds are excluded.
      Parameters:
      location - The location for which surrounding tiles are to be found.
      radius - The radius within which to find surrounding tiles. Must be non-negative.
      Returns:
      A set of locations surrounding the specified location within the radius.
      Throws:
      IllegalArgumentException - if the specified location is out of bounds or if the radius is negative.

    • getEmptySurroundingTiles

      public Set<Location> getEmptySurroundingTiles(Location location)
      Retrieves a set of locations immediately surrounding the specified location that are 'empty'. A location is considered 'empty' based on the criteria defined in isTileEmpty(Location) method, typically meaning it does not contain a blocking object. This method is useful for determining potential movement or placement options around a given location, particularly in scenarios where blocking objects restrict certain actions. It includes all adjacent tiles, both orthogonal and diagonal, within a radius of 1 tile from the given location. Locations outside the bounds of the world are not included in the returned set.
      Parameters:
      location - The central location from which to find empty surrounding tiles.
      Returns:
      A set of locations around the specified location that are empty, as per the definition in isTileEmpty(Location).
      Throws:
      IllegalArgumentException - if the specified location is out of bounds.

    • getTiles

      public Object[][][] getTiles()
      Retrieves a copy of the three-dimensional array representing the current state of the world map. Each element in this array corresponds to a specific location in the world, with the first two dimensions representing the x and y coordinates, and the third dimension representing layers (0 for non-blocking, 1 for blocking objects). Note that the returned array is a copy, ensuring that modifications to it do not affect the actual world state.
      Returns:
      A copy of the three-dimensional array representing the world's map.

    • getEntities

      public Map<Object,Location> getEntities()
      Gets all objects within the world (including those who do not currently reside on the map).
      Returns:
      Map where keys are the objects and their value is the location they are currently placed on (can be null if not currently on the map). The map returned is a copy of the internal map to avoid concurrent modification exceptions.

    • contains

      public boolean contains(Object o)
      Determines whether an object exists in world
      Parameters:
      o - object to check
      Returns:
      true if the object exists in the world

    • isOnTile

      public boolean isOnTile(Object o)
      Determines whether an object is placed on a tile
      Parameters:
      o - object to check
      Returns:
      true if the object exists on a tile

    • getAll

      public <T> Set<T> getAll(Class<T> type, Collection<Location> locations)
      Returns all objects at a location which is an instance of the type given, or an empty set if none matches the type.
      Parameters:
      type - the class we are looking for.
      locations - the locations from where we want to collect all objects of a certain instance
      Returns:
      a set of the type we are looking for (decided by the parameter 'type') containing all (if any) objects that are instances of this.