Class LogicalWorld

java.lang.Object
edu.uky.cs.nil.tt.world.World
edu.uky.cs.nil.tt.world.WorldModel
edu.uky.cs.nil.tt.world.LogicalWorld
All Implemented Interfaces:
Named
public class LogicalWorld extends WorldModel
A logical world model implements the internal logic of a story world using logical propositions and describes its elements using a rule-based describer.
Author:
Stephen G. Ware

  • Constructor Details

    • LogicalWorld

      public LogicalWorld(String name, Collection<Entity> entities, Collection<Variable> variables, Collection<Action> actions, Collection<Ending> endings)
      Constructs a logical world model with the given assets.
      Parameters:
      name - a unique name for the story world
      entities - a collection of objects that exist in the world
      variables - a collection of variables whose values can change and whose current values reflect the current state of the world
      actions - a collection of ways the world state can change
      endings - a collection of ways a story in this world can end
      Throws:
      IllegalArgumentException - if the provided assets do not meet the required format, such as two assets of the same type having the same name

    • LogicalWorld

      public LogicalWorld(AssetBuilder builder)
      Constructs a logical world model from the assets defined in an asset builder.
      Parameters:
      builder - the asset builder that defines the assets to be used in this story world
      Throws:
      IllegalArgumentException - if the provided assets do not meet the required format, such as two assets of the same type having the same name

  • Method Details

    • isVisible

      public boolean isVisible(Role role, Entity entity, State state)
      Checks whether the given role can see the given entity in the given state. The game master can always see all entities. Whether the player can see an entity depends on the entity's visibility.
      Parameters:
      role - the role whose ability to see is being checked
      entity - the entity whose viability is being checked
      state - the state in which the check will occur
      Returns:
      true if the role can see the entity in the given state, false otherwise

    • getVisibility

      public Proposition getVisibility(Entity entity)
      Returns a logical proposition that defines when the player can see an entity. If no proposition has been set, this method returns the constant false.
      Parameters:
      entity - an entity from this story world
      Returns:
      a proposition that will evaluate to true in states where the player can see the entity and false in states where the player cannot see the entity

    • setVisibility

      public void setVisibility(Entity entity, Proposition visibility)
      Sets the logical proposition that defines when the player can see an entity.
      Parameters:
      entity - an entity from this story world
      visibility - a logical proposition that evaluates to true in states where the player can see the entity and false in states where the player cannot see the entity

    • getInitialValue

      public Value getInitialValue(Variable variable)
      Returns the value a given variable has when the story first begins.
      Parameters:
      variable - the variable whose value is desired
      Returns:
      the value that variable has when the story begins

    • setInitialValue

      public void setInitialValue(Variable variable, Value value)
      Sets the value a given variable has when the story first begins.
      Parameters:
      variable - the variable whose value will be set
      value - the value that variable will have when the story begins

    • isVisible

      public boolean isVisible(Role role, Variable variable, State state)
      Checks whether the given role can see the value of the given variable in the given state. The game master can always see all variable values. Whether the player can see a variable's value depends on the variable's visibility.
      Parameters:
      role - the role whose ability to see is being checked
      variable - the variable whose visibility is being checked
      state - the state in which the check will occur
      Returns:
      true if the role can see the variable's value in the given state, false otherwise

    • getVisibility

      public Proposition getVisibility(Variable variable)
      Returns a logical proposition that defines when the player can see a varaiable's value. If no proposition has been set, this method returns the constant true.

      Note that if a player sees an action that updates the value of a variable, they will observe the update, even if the variable is not visible. Variable visibility is intended for situations where a variable changed because of an action that the player did not observe, but the player should (either immediately or later) see this change.

      For example, suppose there are three rooms: A, B, and C. The player is in room A and a second non-player character is in room C. Suppose the location of the second character is visible to the player when the player and that second character are in the same room together. Now suppose the second character walks to room B. The player does not see this action happen, so they do not know about the change to that character's location, and the player's status continues to report that the second character is in room C. Now suppose the player walks into room B. The player should notice the other character. This is accomplished via variable visibility. The player's status will now report that the second character is in room B, because the variable for that character's location is visible.

      When a player cannot see a variable's value, the player's status should report the last known value of that variable.

      Parameters:
      variable - a variable from this story world
      Returns:
      a proposition that will evaluate to true in states where the player can see the variable's value and false in states where the player cannot see the variable's value

    • setVisibility

      public void setVisibility(Variable variable, Proposition visibility)
      Sets the logical proposition that defines when the player can see the value of a variable.
      Parameters:
      variable - a variable from this story world
      visibility - a logical proposition that evaluates to true in states where the player can see the variable's value and false in states where the player cannot see the variable's value

    • isAvailable

      public boolean isAvailable(Role role, Action action, State state)
      Checks whether the given action is available is available to the given role in the given state. An action is available to a role when its precondition is satisfied in the current state and the role consents to the action (i.e. has to approve taking the action).
      Parameters:
      role - the role whose consent is being checked
      action - the action whose precondition is being checked
      state - the state in which the check will occur
      Returns:
      true if the action is possible and the role consents to it, false otherwise

    • getPrecondition

      public Proposition getPrecondition(Action action)
      Returns a logical proposition that defines when an action can be taken. If no proposition has been set, this method returns the constant true.
      Parameters:
      action - an action from this story world
      Returns:
      a proposition that will evaluate to true in states where the action can be taken and false in states where the action cannot be taken

    • setPrecondition

      public void setPrecondition(Action action, Proposition precondition)
      Sets the logical proposition that defines when an action can be taken.
      Parameters:
      action - an action from this story world
      precondition - a logical proposition that evaluates to true in states where the action can be taken and false in states where the action cannot be taken

    • getEffects

      public Effect[] getEffects(Action action)
      Returns an array of effects which express how an action modifies the state of a story world when it happens. If no effects have been set, this method returns an empty array.
      Parameters:
      action - an action from this story world
      Returns:
      an (possibly empty) array of effects that express how the action modifies a state

    • setEffects

      public void setEffects(Action action, Effect... effects)
      Sets the arrays of effects which express how an action modifies the state of a story world when it happens.
      Parameters:
      action - an action from this story world
      effects - the effects which express how the action modifies the state

    • isVisible

      public boolean isVisible(Role role, Action action, State state)
      Checks whether the given action would be seen by the given role if it happened in the given state. The game master can always see all actions. Whether the player can see a an action occur depends on the action's visibility.
      Parameters:
      role - the role whose ability to see is being checked
      action - the action whose visibility is being checked
      state - the state in which the check will occur
      Returns:
      true if the role would see the action occurs in the given state, false otherwise

    • getVisibility

      public Proposition getVisibility(Action action)
      Returns a logical proposition that defines when the player would see an action happen. If no proposition has been set, this method returns the constant true.

      When the player sees an action, it means the action will appear in the history of the story world and the changes to the state caused by the action's effects are reflected in the state. When the player does not see an action, their status will appear as if the action did not happen, meaning it will not appear in the history and the variables changed by the action's effects will not be reflected in the current state.

      Parameters:
      action - an action from this story world
      Returns:
      a proposition that will evaluate to true in states where the player would see the action occur and false in states where the player would not see the action occur

    • setVisibility

      public void setVisibility(Action action, Proposition visibility)
      Sets the logical proposition that defines when the player can see an action happen.
      Parameters:
      action - an action from this story world
      visibility - a logical proposition that evaluates to true in states where the player would see the action occur and false in states where the player would not see the action occur

    • getCondition

      public Proposition getCondition(Ending ending)
      Returns a logical proposition that defines when an ending should occur. If no proposition has been set, this method returns the constant false. These conditions are checked an action changes the story state, in order by ending. If any conditions evaluates to true, the story immediately ends with the corresponding ending.
      Parameters:
      ending - an ending from this story world
      Returns:
      a proposition that will evaluate to true in states where the ending occurs and false in states where the ending does not occur

    • setCondition

      public void setCondition(Ending ending, Proposition condition)
      Sets the logical proposition that defines when an ending should occur.
      Parameters:
      ending - an ending from this story world
      condition - a logical proposition that evaluates to true in states where the ending should occur and false in states where the ending should not occur

    • getDescription

      public String getDescription(Object object, Role to)
      Returns a phrase or sentence to describe an object to the given role using this world models' describer.

      If the object given is an Assignment or Turn, the description will be a sentence. For all other objects, the description will be a phrase.

      Parameters:
      object - the object to describer
      to - the role to whom the object will be described
      Returns:
      a description of the object as a phrase or sentence

    • getDescriber

      public Describer getDescriber()
      Returns the describer this world model uses to describe its objects.
      Returns:
      the describer used by this world model

    • setDescriber

      public void setDescriber(Describer describer)
      Sets the describer used by this world model to describe its objects.
      Parameters:
      describer - the new describer this world model should use to describe its objects

    • start

      public Status start(Role role)
      Description copied from class: WorldModel
      Returns the initial state of the story world for a given role as a status object. For the game master, the initial status should completely and accurately define the initial state of all variables and entities. For the player, the initial status should should define the initial state of all variables and entities that the player knows about at the start of the story. The initial status should have no history.
      Specified by:
      start in class WorldModel
      Parameters:
      role - the role whose initial status is desired
      Returns:
      the initial status of the story world for that role

    • transition

      public Status transition(Status status, State actual, Turn turn)
      Description copied from class: WorldModel
      Given the current status of a story world (actual or perceived), the actual current status of a story world, and a turn, this method simulates that turn and returns the new perceived status of the story world. The status returned will be for the same role as the first status argument. Since the game master should always know the actual status of the story world, when calculating a new status for the game master, the first two status arguments should be the same. When calculating a new status for the player, the first status argument should be the player's perceived status and the second should be the actual status available to the game master. The status returned will be the new status as perceived by that role (the new actual status for the game master or the new perceived status for the player).
      Specified by:
      transition in class WorldModel
      Parameters:
      status - the current status of the story world as perceived by the status' participant
      actual - the actual current status of the story world
      turn - the turn to be taken
      Returns:
      the new story world status as perceived by the status' participant

    • getStatus

      protected Status getStatus(Role role, Turn[] history, State actual, State observed)
      Calculates the ending (if any), entity descriptions, and turns available to include in a status.
      Parameters:
      role - the role for the status
      history - the history of turns so far in the session
      actual - the actual current state
      observed - the perceived current state
      Returns:
      the story world status implied by those inputs

    • getEnding

      protected Ending getEnding(Role role, Turn[] history, State state)
      Determines whether the story has ended and, if so, returns the ending.
      Parameters:
      role - the role to whom the ending (if any) will be described
      history - the history of turns so far in the session
      state - the current state of the story world
      Returns:
      an ending, if one has been reached, or null

    • getEntityDescriptions

      protected Entity[] getEntityDescriptions(Role role, Turn[] history, State state)
      Returns an array of entities visible to a given role which have useful descriptions.
      Parameters:
      role - the role for whom visibility will be checked and to whom the entities will be described
      history - the history of turns so far in the session
      state - the current state as perceived by the given role
      Returns:
      an array of entities that are currently visible to that role with helpful descriptions

    • getEntityDescription

      protected String getEntityDescription(Role role, Turn[] history, State state, Entity entity)
      Returns a longer, more helpful description of an entity based on the current state of a story world.
      Parameters:
      role - the role to whom the entity is being described
      history - the history of turns so far in the session
      state - the current state of the story world
      entity - the entity being described
      Returns:
      a description of the entity that includes relevant details from the current state

    • getChoices

      protected Turn[] getChoices(Role role, Turn[] history, State state, Ending ending)
      Returns an array of choices available to a given role based on the current state of a story world, or null if no choices are available.
      Parameters:
      role - the role to whom the choices are available and to whom the choices will be described
      history - the history of turns so far in the session
      state - the current actual state of the story world
      ending - the ending of the story, if any
      Returns:
      an array of choices available to the given role, or null if no choices are available

    • current

      protected static final Role current(Turn[] history)
      Determines whose turn it is based on the history of a session.
      Parameters:
      history - the history of turns so far in the session
      Returns:
      the role whose turn it is to act

    • describe

      public String describe()
      Returns a long string describing every element of a story world model for use in debugging.
      Returns:
      a long string describing every element of this story world model

    • read

      public static LogicalWorld read(Reader reader) throws IOException
      Reads a serialized logical world model from some input source.
      Parameters:
      reader - the input source
      Returns:
      a logical world model
      Throws:
      IOException - if a problem occurs when reading from the input source
      com.google.gson.JsonIOException - if there was a problem reading JSON data from the Reader
      com.google.gson.JsonSyntaxException - if the JSON read from the source cannot be parsed as a logical world model

    • read

      public static LogicalWorld read(File file) throws IOException
      Reads a serialized logical world model from a file.
      Parameters:
      file - the file to which a logical world model has been serialized
      Returns:
      a logical world model
      Throws:
      IOException - if a problem occurs when reading from the file
      com.google.gson.JsonIOException - if there was a problem reading JSON data from the Reader
      com.google.gson.JsonSyntaxException - if the JSON read from the source cannot be parsed as a logical world model

    • write

      public void write(Writer writer) throws IOException
      Serializes this logical world model to an output stream.
      Parameters:
      writer - the output to which the logical world model will be serialized
      Throws:
      IOException - if a problem occurs when writing to the output source
      com.google.gson.JsonIOException - if a problem occurs when writing JSON data to the output source

    • write

      public void write(File file) throws IOException
      Serializes this logical world model to a file.
      Parameters:
      file - the file to which the logical world model will be serialized
      Throws:
      IOException - if a problem occurs when writing to the output source
      com.google.gson.JsonIOException - if a problem occurs when writing JSON data to the output source