Package dev.twilite.game.common

Class InteractionScope

java.lang.Object
dev.twilite.game.common.InteractionScope
public class InteractionScope extends Object
World-scoped interaction helpers for simple step-based plugin flows.

Each method performs one tick-friendly action: continue/select dialogue, walk toward a fallback coordinate, interact with a loaded target, use an item on a target, or pick up a ground item. Plugins should call these methods repeatedly until their state changes.

Usage:


 Game.interactionScope().talkTo(
     npcs -> npcs.id(NpcId.GOTR_CORDELIA).nearestTo(Constants.CELL_TABLE),
     Constants.CELL_TABLE,
     "repair my pouches",
     "yes"
 );

  • Constructor Details

    • InteractionScope

      public InteractionScope(World world)
      Creates a scope backed by a loaded world.
      Parameters:
      world - world to query for NPCs, scene objects, and tile items

  • Method Details

    • talkTo

      public boolean talkTo(Function<NpcView,Optional<Npc>> query, Coord fallback, String... dialog)
      Selects matching dialogue or talks to an NPC, walking to fallback if the NPC is not available.
      Parameters:
      query - query selecting the NPC from this scope's NPC view
      fallback - coordinate used when the NPC is missing or too far away
      dialog - dialogue option text fragments to select before talking
      Returns:
      true if a dialogue, walk, or talk action was performed

    • talkTo

      public boolean talkTo(Function<NpcView,Optional<Npc>> query, Coord fallback, boolean skipReachableCheck, String... dialog)
      Selects matching dialogue or talks to an NPC with optional local reachability checks.
      Parameters:
      query - query selecting the NPC from this scope's NPC view
      fallback - coordinate used when the NPC is missing or too far away
      skipReachableCheck - whether to skip loaded collision reachability before interacting
      dialog - dialogue option text fragments to select before talking
      Returns:
      true if a dialogue, walk, or talk action was performed

    • component

      public boolean component(int id, String op)
      Interacts with a component by packed id.
      Parameters:
      id - packed interface component id
      op - component option to invoke
      Returns:
      true if the component was found and interacted with

    • component

      public boolean component(int id, int cc, String op)
      Interacts with a dynamic child component by parent packed id and child index.
      Parameters:
      id - packed parent interface component id
      cc - dynamic child index
      op - component option to invoke
      Returns:
      true if the child component was found and interacted with

    • component

      public boolean component(int id, Function<ComponentView,Optional<IfComponent>> ccQuery, String op)
      Interacts with a dynamic child component selected from a parent component's child view.
      Parameters:
      id - packed parent interface component id
      ccQuery - query selecting a child component from the parent's dynamic children
      op - component option to invoke
      Returns:
      true if the child component was found and interacted with

    • resumePause

      public boolean resumePause(int id)
      Enqueues a resume/pause-button action on a component by packed id.
      Parameters:
      id - packed interface component id
      Returns:
      true if the component was found and the action was enqueued

    • resumePause

      public boolean resumePause(int id, int cc)
      Enqueues a resume/pause-button action on a dynamic child component.
      Parameters:
      id - packed parent interface component id
      cc - dynamic child index
      Returns:
      true if the child component was found and the action was enqueued

    • resumePause

      public boolean resumePause(int id, Function<ComponentView,Optional<IfComponent>> ccQuery)
      Enqueues a resume/pause-button action on a dynamic child selected from a parent component's child view.
      Parameters:
      id - packed parent interface component id
      ccQuery - query selecting a child component from the parent's dynamic children
      Returns:
      true if the child component was found and the action was enqueued

    • object

      public boolean object(Function<SceneObjectView,Optional<SceneObject>> query, Coord fallback, String op)
      Interacts with an object, walking to fallback if the object is not available.
      Parameters:
      query - query selecting the object from this scope's object view
      fallback - coordinate used when the object is missing or too far away
      op - object option to invoke
      Returns:
      true if a walk or object interaction was performed

    • object

      public boolean object(Function<SceneObjectView,Optional<SceneObject>> query, Coord fallback, String op, boolean skipReachableCheck)
      Interacts with an object using optional local reachability checks.
      Parameters:
      query - query selecting the object from this scope's object view
      fallback - coordinate used when the object is missing or too far away
      op - object option to invoke
      skipReachableCheck - whether to skip loaded collision reachability before interacting
      Returns:
      true if a walk or object interaction was performed

    • object

      public boolean object(Function<SceneObjectView,Optional<SceneObject>> query, Coord fallback, String op, boolean skipReachableCheck, int distance)
      Interacts with an object using optional reachability checks and a custom walk distance.
      Parameters:
      query - query selecting the object from this scope's object view
      fallback - coordinate used when the object is missing or too far away
      op - object option to invoke
      skipReachableCheck - whether to skip loaded collision reachability before interacting
      distance - maximum Chebyshev distance considered close enough
      Returns:
      true if a walk or object interaction was performed

    • npc

      public boolean npc(Function<NpcView,Optional<Npc>> query, Coord fallback, String op)
      Interacts with an NPC, walking to fallback if the NPC is not available.
      Parameters:
      query - query selecting the NPC from this scope's NPC view
      fallback - coordinate used when the NPC is missing or too far away
      op - NPC option to invoke
      Returns:
      true if a walk or NPC interaction was performed

    • npc

      public boolean npc(Function<NpcView,Optional<Npc>> query, Coord fallback, String op, boolean skipReachableCheck)
      Interacts with an NPC using optional local reachability checks.
      Parameters:
      query - query selecting the NPC from this scope's NPC view
      fallback - coordinate used when the NPC is missing or too far away
      op - NPC option to invoke
      skipReachableCheck - whether to skip loaded collision reachability before interacting
      Returns:
      true if a walk or NPC interaction was performed

    • npc

      public boolean npc(Function<NpcView,Optional<Npc>> query, Coord fallback, String op, boolean skipReachableCheck, int distance)
      Interacts with an NPC using optional reachability checks and a custom walk distance.
      Parameters:
      query - query selecting the NPC from this scope's NPC view
      fallback - coordinate used when the NPC is missing or too far away
      op - NPC option to invoke
      skipReachableCheck - whether to skip loaded collision reachability before interacting
      distance - maximum Chebyshev distance considered close enough
      Returns:
      true if a walk or NPC interaction was performed

    • player

      public boolean player(Function<PlayerView,Optional<Player>> query, Coord fallback, String op)
      Interacts with a player, walking to fallback if the player is not available.
      Parameters:
      query - query selecting the player from this scope's player view
      fallback - coordinate used when the player is missing or too far away
      op - player option to invoke
      Returns:
      true if a walk or player interaction was performed

    • player

      public boolean player(Function<PlayerView,Optional<Player>> query, Coord fallback, String op, boolean skipReachableCheck)
      Interacts with a player using optional local reachability checks.
      Parameters:
      query - query selecting the player from this scope's player view
      fallback - coordinate used when the player is missing or too far away
      op - player option to invoke
      skipReachableCheck - whether to skip loaded collision reachability before interacting
      Returns:
      true if a walk or player interaction was performed

    • player

      public boolean player(Function<PlayerView,Optional<Player>> query, Coord fallback, String op, boolean skipReachableCheck, int distance)
      Interacts with a player using optional reachability checks and a custom walk distance.
      Parameters:
      query - query selecting the player from this scope's player view
      fallback - coordinate used when the player is missing or too far away
      op - player option to invoke
      skipReachableCheck - whether to skip loaded collision reachability before interacting
      distance - maximum Chebyshev distance considered close enough
      Returns:
      true if a walk or player interaction was performed

    • tileItem

      public boolean tileItem(Function<TileItemView,Optional<TileItem>> query, Coord fallback, String op)
      Interacts with a ground item, walking to fallback if the item is not available.
      Parameters:
      query - query selecting the ground item from this scope's tile-item view
      fallback - coordinate used when the item is missing or too far away
      op - ground item option to invoke
      Returns:
      true if a walk or ground item interaction was performed

    • tileItem

      public boolean tileItem(Function<TileItemView,Optional<TileItem>> query, Coord fallback, String op, boolean skipReachableCheck)
      Interacts with a ground item using optional local reachability checks.
      Parameters:
      query - query selecting the ground item from this scope's tile-item view
      fallback - coordinate used when the item is missing or too far away
      op - ground item option to invoke
      skipReachableCheck - whether to skip loaded collision reachability before interacting
      Returns:
      true if a walk or ground item interaction was performed

    • tileItem

      public boolean tileItem(Function<TileItemView,Optional<TileItem>> query, Coord fallback, String op, boolean skipReachableCheck, int distance)
      Interacts with a ground item using optional reachability checks and a custom walk distance.
      Parameters:
      query - query selecting the ground item from this scope's tile-item view
      fallback - coordinate used when the item is missing or too far away
      op - ground item option to invoke
      skipReachableCheck - whether to skip loaded collision reachability before interacting
      distance - maximum Chebyshev distance considered close enough
      Returns:
      true if a walk or ground item interaction was performed

    • useItemOnItem

      public boolean useItemOnItem(int primary, int target)
      Uses one inventory item on another inventory item.
      Parameters:
      primary - item id to select first
      target - item id to target after selecting primary
      Returns:
      true if both items were present and the use-on-item action was enqueued

    • useItemOnObject

      public boolean useItemOnObject(int item, Function<SceneObjectView,Optional<SceneObject>> query, Coord fallback)
      Uses an inventory item on an object, walking to fallback if the object is not available.
      Parameters:
      item - inventory item id to use
      query - query selecting the object from this scope's object view
      fallback - coordinate used when the object is missing or too far away
      Returns:
      true if a walk or item-on-object action was performed

    • useItemOnObject

      public boolean useItemOnObject(int item, Function<SceneObjectView,Optional<SceneObject>> query, Coord fallback, boolean skipReachableCheck)
      Uses an inventory item on an object with optional local reachability checks.
      Parameters:
      item - inventory item id to use
      query - query selecting the object from this scope's object view
      fallback - coordinate used when the object is missing or too far away
      skipReachableCheck - whether to skip loaded collision reachability before using the item
      Returns:
      true if a walk or item-on-object action was performed

    • useItemOnNpc

      public boolean useItemOnNpc(int item, Function<NpcView,Optional<Npc>> query, Coord fallback)
      Uses an inventory item on an NPC, walking to fallback if the NPC is not available.
      Parameters:
      item - inventory item id to use
      query - query selecting the NPC from this scope's NPC view
      fallback - coordinate used when the NPC is missing or too far away
      Returns:
      true if a walk or item-on-NPC action was performed

    • useItemOnNpc

      public boolean useItemOnNpc(int item, Function<NpcView,Optional<Npc>> query, Coord fallback, boolean skipReachableCheck)
      Uses an inventory item on an NPC with optional local reachability checks.
      Parameters:
      item - inventory item id to use
      query - query selecting the NPC from this scope's NPC view
      fallback - coordinate used when the NPC is missing or too far away
      skipReachableCheck - whether to skip loaded collision reachability before using the item
      Returns:
      true if a walk or item-on-NPC action was performed

    • useItemOnPlayer

      public boolean useItemOnPlayer(int item, Function<PlayerView,Optional<Player>> query, Coord fallback)
      Uses an inventory item on a player, walking to fallback if the player is not available.
      Parameters:
      item - inventory item id to use
      query - query selecting the player from this scope's player view
      fallback - coordinate used when the player is missing or too far away
      Returns:
      true if a walk or item-on-player action was performed

    • useItemOnPlayer

      public boolean useItemOnPlayer(int item, Function<PlayerView,Optional<Player>> query, Coord fallback, boolean skipReachableCheck)
      Uses an inventory item on a player with optional local reachability checks.
      Parameters:
      item - inventory item id to use
      query - query selecting the player from this scope's player view
      fallback - coordinate used when the player is missing or too far away
      skipReachableCheck - whether to skip loaded collision reachability before using the item
      Returns:
      true if a walk or item-on-player action was performed

    • castSpellOnItem

      public boolean castSpellOnItem(Spell spell, int target)
      Casts a spell on an inventory item.
      Parameters:
      spell - spell to cast
      target - item id to target after selecting spell
      Returns:
      true if the spell and item were present and the action was enqueued

    • castSpellOnObject

      public boolean castSpellOnObject(Spell spell, Function<SceneObjectView,Optional<SceneObject>> query, Coord fallback)
      Casts a spell on an object, walking to fallback if the object is not available.
      Parameters:
      spell - spell to cast
      query - query selecting the object from this scope's object view
      fallback - coordinate used when the object is missing or too far away
      Returns:
      true if a walk or spell-on-object action was performed

    • castSpellOnObject

      public boolean castSpellOnObject(Spell spell, Function<SceneObjectView,Optional<SceneObject>> query, Coord fallback, boolean skipReachableCheck)
      Casts a spell on an object with optional local reachability checks.
      Parameters:
      spell - spell to cast
      query - query selecting the object from this scope's object view
      fallback - coordinate used when the object is missing or too far away
      skipReachableCheck - whether to skip loaded collision reachability before casting
      Returns:
      true if a walk or spell-on-object action was performed

    • castSpellOnNpc

      public boolean castSpellOnNpc(Spell spell, Function<NpcView,Optional<Npc>> query, Coord fallback)
      Casts a spell on an NPC, walking to fallback if the NPC is not available.
      Parameters:
      spell - spell to cast
      query - query selecting the NPC from this scope's NPC view
      fallback - coordinate used when the NPC is missing or too far away
      Returns:
      true if a walk or spell-on-NPC action was performed

    • castSpellOnNpc

      public boolean castSpellOnNpc(Spell spell, Function<NpcView,Optional<Npc>> query, Coord fallback, boolean skipReachableCheck)
      Casts a spell on an NPC with optional local reachability checks.
      Parameters:
      spell - spell to cast
      query - query selecting the NPC from this scope's NPC view
      fallback - coordinate used when the NPC is missing or too far away
      skipReachableCheck - whether to skip loaded collision reachability before casting
      Returns:
      true if a walk or spell-on-NPC action was performed

    • castSpellOnPlayer

      public boolean castSpellOnPlayer(Spell spell, Function<PlayerView,Optional<Player>> query, Coord fallback)
      Casts a spell on a player, walking to fallback if the player is not available.
      Parameters:
      spell - spell to cast
      query - query selecting the player from this scope's player view
      fallback - coordinate used when the player is missing or too far away
      Returns:
      true if a walk or spell-on-player action was performed

    • castSpellOnPlayer

      public boolean castSpellOnPlayer(Spell spell, Function<PlayerView,Optional<Player>> query, Coord fallback, boolean skipReachableCheck)
      Casts a spell on a player with optional local reachability checks.
      Parameters:
      spell - spell to cast
      query - query selecting the player from this scope's player view
      fallback - coordinate used when the player is missing or too far away
      skipReachableCheck - whether to skip loaded collision reachability before casting
      Returns:
      true if a walk or spell-on-player action was performed

    • castSpellOnTileItem

      public boolean castSpellOnTileItem(Spell spell, Function<TileItemView,Optional<TileItem>> query, Coord fallback)
      Casts a spell on a ground item, walking to fallback if the item is not available.
      Parameters:
      spell - spell to cast
      query - query selecting the ground item from this scope's tile-item view
      fallback - coordinate used when the item is missing or too far away
      Returns:
      true if a walk or spell-on-ground-item action was performed

    • castSpellOnTileItem

      public boolean castSpellOnTileItem(Spell spell, Function<TileItemView,Optional<TileItem>> query, Coord fallback, boolean skipReachableCheck)
      Casts a spell on a ground item with optional local reachability checks.
      Parameters:
      spell - spell to cast
      query - query selecting the ground item from this scope's tile-item view
      fallback - coordinate used when the item is missing or too far away
      skipReachableCheck - whether to skip loaded collision reachability before casting
      Returns:
      true if a walk or spell-on-ground-item action was performed

    • pickUp

      public boolean pickUp(int item, Coord fallback)
      Picks up the nearest matching ground item to fallback.
      Parameters:
      item - item id to take
      fallback - coordinate used when the item is missing or too far away
      Returns:
      true if a walk or pickup action was performed

    • pickUp

      public boolean pickUp(int item, Coord fallback, boolean skipReachableCheck)
      Picks up the nearest matching ground item with optional local reachability checks.
      Parameters:
      item - item id to take
      fallback - coordinate used when the item is missing or too far away
      skipReachableCheck - whether to skip loaded collision reachability before taking the item
      Returns:
      true if a walk or pickup action was performed

    • pickUp

      public boolean pickUp(int item, Function<TileItemView,Optional<TileItem>> query, Coord fallback, boolean skipReachableCheck)
      Picks up a ground item selected from this scope's tile-item view.
      Parameters:
      item - item id used for logging
      query - query selecting the ground item from this scope's tile-item view
      fallback - coordinate used when the item is missing or too far away
      skipReachableCheck - whether to skip loaded collision reachability before taking the item
      Returns:
      true if a walk or pickup action was performed