Package com.valhalla.sdk.api.methods

Class Npcs

java.lang.Object
com.valhalla.sdk.api.methods.Npcs
public final class Npcs extends Object
Queries immutable NPC snapshots and dispatches native NPC menu actions.

NPC indices are live scene references and can be reused by the client after a despawn. Re-query before acting on long-held snapshots. Nearest searches use same-plane Chebyshev distance rather than collision reachability. A successful interaction confirms native dispatch, not completion of dialogue or combat.

  • Method Details

    • all

      public static List<Npc> all()
      Returns all decoded NPCs.
      Returns:
      all NPCs from the latest native scene snapshot

    • all

      public static List<Npc> all(Filter<Npc> filter)
      Selects every NPC accepted by a filter.
      Parameters:
      filter - NPC predicate
      Returns:
      matching snapshots in native enumeration order

    • all

      public static List<Npc> all(Integer... ids)
      Selects NPCs matching any non-null definition identifier.
      Parameters:
      ids - candidate NPC identifiers
      Returns:
      matching snapshots, or an empty list for no candidates

    • all

      public static List<Npc> all(String... names)
      Selects NPCs matching any exact name, ignoring case.
      Parameters:
      names - candidate names
      Returns:
      matching snapshots, or an empty list for no candidates

    • getByIndex

      public static Optional<Npc> getByIndex(int index)
      Finds the NPC currently occupying a scene index.
      Parameters:
      index - live scene index
      Returns:
      current matching snapshot, or empty

    • getAtIndex

      public static Optional<Npc> getAtIndex(int index)
      Alias for getByIndex(int).
      Parameters:
      index - live scene index
      Returns:
      current matching snapshot, or empty

    • referenceExists

      public static boolean referenceExists(int index)
      Tests whether an NPC currently occupies a scene index.
      Parameters:
      index - live scene index
      Returns:
      true when the latest snapshot contains that index

    • getArray

      public static Npc[] getArray()
      Copies all NPC snapshots into an array.
      Returns:
      all NPC snapshots as a newly allocated array

    • getById

      public static List<Npc> getById(int id)
      Selects every NPC with a definition identifier.
      Parameters:
      id - NPC definition identifier
      Returns:
      matching snapshots

    • getByName

      public static List<Npc> getByName(String name)
      Selects every NPC with an exact name, ignoring case.
      Parameters:
      name - exact NPC name
      Returns:
      matching snapshots, or an empty list for null

    • nearest

      public static Optional<Npc> nearest()
      Finds the nearest same-plane NPC.
      Returns:
      nearest same-plane NPC by Chebyshev distance, or empty

    • closest

      public static Optional<Npc> closest()
      Finds the nearest same-plane NPC.
      Returns:
      nearest same-plane NPC; alias for nearest()

    • closest

      public static Optional<Npc> closest(Filter<Npc> filter)
      Alias for nearest(Filter).
      Parameters:
      filter - NPC predicate
      Returns:
      nearest matching same-plane NPC, or empty

    • closest

      public static Optional<Npc> closest(Filter<Npc> filter, Tile toTile)
      Finds the filtered NPC nearest to an arbitrary tile.
      Parameters:
      filter - NPC predicate
      toTile - comparison tile and required plane
      Returns:
      nearest matching NPC on that plane, or empty

    • closest

      public static Optional<Npc> closest(Integer... ids)
      Finds the nearest same-plane NPC matching any identifier.
      Parameters:
      ids - candidate NPC identifiers
      Returns:
      nearest match, or empty

    • closest

      public static Optional<Npc> closest(String... names)
      Finds the nearest same-plane NPC matching any exact name, ignoring case.
      Parameters:
      names - candidate names
      Returns:
      nearest match, or empty

    • nearest

      public static Optional<Npc> nearest(Filter<Npc> filter)
      Finds the filtered same-plane NPC nearest to the local player.
      Parameters:
      filter - NPC predicate
      Returns:
      nearest matching NPC by Chebyshev distance, or empty

    • interact

      public static boolean interact(int index, int action)
      Dispatches a raw action to a current NPC scene index.
      Parameters:
      index - live NPC scene index
      action - native NPC action opcode
      Returns:
      true when the client was ready and accepted dispatch

    • interact

      public static boolean interact(Npc npc, int action)
      Dispatches a raw action to an NPC snapshot.
      Parameters:
      npc - current NPC snapshot
      action - native NPC action opcode
      Returns:
      true when dispatch was accepted

    • interact

      public static boolean interact(Npc npc, NpcAction action)
      Dispatches a typed menu action to an NPC snapshot.
      Parameters:
      npc - current NPC snapshot
      action - ordered NPC menu action
      Returns:
      true when accepted; gameplay completion is not implied

    • interactNearestId

      public static boolean interactNearestId(int id, NpcAction action)
      Dispatches to the nearest same-plane NPC with an identifier.
      Parameters:
      id - NPC definition identifier
      action - ordered NPC menu action
      Returns:
      true when a match existed and dispatch was accepted

    • interact

      public static boolean interact(String name, NpcAction action)
      Dispatches to the nearest same-plane NPC with an exact name.
      Parameters:
      name - exact case-insensitive NPC name
      action - ordered NPC menu action
      Returns:
      true when a match existed and dispatch was accepted

    • interact

      public static boolean interact(Filter<Npc> filter, NpcAction action)
      Dispatches to the nearest same-plane NPC accepted by a filter.
      Parameters:
      filter - NPC predicate
      action - ordered NPC menu action
      Returns:
      true when a match existed and dispatch was accepted

    • count

      public static int count(Filter<Npc> filter)
      Counts NPCs accepted by a filter.
      Parameters:
      filter - NPC predicate
      Returns:
      number of matching snapshots

    • exists

      public static boolean exists(Filter<Npc> filter)
      Tests whether a filtered NPC exists.
      Parameters:
      filter - NPC predicate
      Returns:
      whether a same-plane matching NPC exists

    • exists

      public static boolean exists(Integer... ids)
      Tests whether any candidate identifier exists.
      Parameters:
      ids - candidate identifiers
      Returns:
      whether a same-plane matching NPC exists

    • exists

      public static boolean exists(String... names)
      Tests whether any candidate name exists.
      Parameters:
      names - candidate exact names
      Returns:
      whether a same-plane matching NPC exists