Package com.valhalla.sdk.api.methods

Class GroundItems

java.lang.Object

com.valhalla.sdk.api.methods.GroundItems

public final class GroundItems
extends Object

Queries ground-item snapshots and dispatches native ground-item actions.

Nearest queries are same-plane distance searches. Prefer nearestReachable() when movement matters, while remembering that reachability falls back to loaded-tile validation if collision data is absent. A successful interaction confirms action acceptance only; verify inventory or ground-item state afterward.

Method Summary

Modifier and Type	Method	Description
static List<GroundItem>	all()	Returns all decoded ground-item stacks.
static List<GroundItem>	all(Filter<GroundItem> filter)	Selects all ground items accepted by a filter.
static List<GroundItem>	all(Integer... ids)	Selects ground items matching any non-null identifier.
static List<GroundItem>	all(String... names)	Selects ground items matching any exact name, ignoring case.
static Optional<GroundItem>	closest()	Finds the nearest same-plane ground item.
static Optional<GroundItem>	closest(Filter<GroundItem> filter)	Alias for nearest(Filter).
static Optional<GroundItem>	closest(Filter<GroundItem> filter, Tile toTile)	Finds the filtered stack nearest to an arbitrary tile.
static Optional<GroundItem>	closest(Integer... ids)	Finds the nearest same-plane stack matching any identifier.
static Optional<GroundItem>	closest(String... names)	Finds the nearest same-plane stack matching any exact name, ignoring case.
static int	count(Filter<GroundItem> filter)	Counts ground items accepted by a filter.
static boolean	exists(Filter<GroundItem> filter)	Tests whether a filtered ground item exists.
static boolean	exists(Integer... ids)	Tests whether any candidate identifier exists.
static boolean	exists(String... names)	Tests whether any candidate name exists.
static List<GroundItem>	getById(int id)	Selects every ground-item stack with an identifier.
static List<GroundItem>	getByName(String name)	Selects every stack with an exact name, ignoring case.
static List<GroundItem>	getForTile(Tile tile)	Returns every ground-item stack on an exact world tile.
static boolean	interact(int id, int x, int y, int plane, int action)	Dispatches a raw action using explicit coordinates.
static boolean	interact(int id, int x, int y, int plane, GroundItemAction action)	Dispatches a typed action using explicit coordinates.
static boolean	interact(int id, Tile tile, int action)	Dispatches a raw action to an exact ground-item identity and tile.
static boolean	interact(int id, Tile tile, GroundItemAction action)	Dispatches a typed action to an exact ground-item identity and tile.
static boolean	interact(int id, GroundItemAction action)	Dispatches to the nearest same-plane stack with an identifier.
static boolean	interact(GroundItem item, GroundItemAction action)	Dispatches a typed action to a current ground-item snapshot.
static boolean	interact(Filter<GroundItem> filter, GroundItemAction action)	Dispatches to the nearest same-plane stack accepted by a filter.
static boolean	interact(String name, GroundItemAction action)	Dispatches to the nearest same-plane stack with an exact name.
static Optional<GroundItem>	nearest()	Finds the nearest same-plane ground item.
static Optional<GroundItem>	nearest(Filter<GroundItem> filter)	Finds the filtered same-plane stack nearest to the local player.
static Optional<GroundItem>	nearestReachable()	Finds the nearest reachable ground item.
static Optional<GroundItem>	nearestReachable(Filter<GroundItem> filter)	Finds the nearest reachable item accepted by a filter.
static Optional<GroundItem>	nearestReachable(Filter<GroundItem> filter, int maximumDistance)	Finds the nearest reachable filtered item within a distance limit.
static List<GroundItem>	reachable()	Returns same-plane items accepted by local collision reachability.
static List<GroundItem>	reachable(int maximumDistance)	Returns same-plane reachable items within a direct-distance limit.
static List<GroundItem>	reachable(Filter<GroundItem> filter)	Returns filtered same-plane items accepted by local collision reachability.
static List<GroundItem>	reachable(Filter<GroundItem> filter, int maximumDistance)	Returns filtered same-plane reachable items within a distance limit.

Methods inherited from class java.lang.Object

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

Method Details

all

public static List<GroundItem> all()

Returns all decoded ground-item stacks.

Returns:

all ground-item stacks from the latest native scene snapshot

all

public static List<GroundItem> all(Filter<GroundItem> filter)

Selects all ground items accepted by a filter.

Parameters:

filter - item predicate

Returns:

matching snapshots in native enumeration order

all

public static List<GroundItem> all(Integer... ids)

Selects ground items matching any non-null identifier.

Parameters:

ids - candidate item identifiers

Returns:

matching snapshots, or an empty list for no candidates

all

public static List<GroundItem> all(String... names)

Selects ground items matching any exact name, ignoring case.

Parameters:

names - candidate names

Returns:

matching snapshots, or an empty list for no candidates

getById

public static List<GroundItem> getById(int id)

Selects every ground-item stack with an identifier.

Parameters:

id - item definition identifier

Returns:

matching snapshots

getByName

public static List<GroundItem> getByName(String name)

Selects every stack with an exact name, ignoring case.

Parameters:

name - exact item name

Returns:

matching snapshots, or an empty list for null

nearest

public static Optional<GroundItem> nearest()

Finds the nearest same-plane ground item.

Returns:

nearest same-plane ground item by Chebyshev distance, or empty

closest

public static Optional<GroundItem> closest()

Finds the nearest same-plane ground item.

Returns:

nearest same-plane ground item; alias for nearest()

closest

public static Optional<GroundItem> closest(Filter<GroundItem> filter)

Alias for nearest(Filter).

Parameters:

filter - item predicate

Returns:

nearest matching same-plane stack, or empty

closest

public static Optional<GroundItem> closest(Filter<GroundItem> filter,
 Tile toTile)

Finds the filtered stack nearest to an arbitrary tile.

Parameters:

filter - item predicate

toTile - comparison tile and required plane

Returns:

nearest matching stack on the tile's plane, or empty

closest

public static Optional<GroundItem> closest(Integer... ids)

Finds the nearest same-plane stack matching any identifier.

Parameters:

ids - candidate identifiers

Returns:

nearest match, or empty

closest

public static Optional<GroundItem> closest(String... names)

Finds the nearest same-plane stack matching any exact name, ignoring case.

Parameters:

names - candidate names

Returns:

nearest match, or empty

nearest

public static Optional<GroundItem> nearest(Filter<GroundItem> filter)

Finds the filtered same-plane stack nearest to the local player.

Parameters:

filter - item predicate

Returns:

nearest matching stack by Chebyshev distance, or empty

reachable

public static List<GroundItem> reachable()

Returns same-plane items accepted by local collision reachability.

Returns:

reachable items; loaded same-plane items are used as a fallback without collision

reachable

public static List<GroundItem> reachable(Filter<GroundItem> filter)

Returns filtered same-plane items accepted by local collision reachability.

Parameters:

filter - item predicate

Returns:

reachable matching items

reachable

public static List<GroundItem> reachable(int maximumDistance)

Returns same-plane reachable items within a direct-distance limit.

Parameters:

maximumDistance - inclusive Chebyshev distance

Returns:

reachable items within the limit

reachable

public static List<GroundItem> reachable(Filter<GroundItem> filter,
 int maximumDistance)

Returns filtered same-plane reachable items within a distance limit.

If live collision is unavailable, a loaded same-plane tile is treated as a permissive fallback and may still be separated by an obstacle.

Parameters:

filter - item predicate

maximumDistance - inclusive non-negative Chebyshev distance

Returns:

matching reachable snapshots

nearestReachable

public static Optional<GroundItem> nearestReachable()

Finds the nearest reachable ground item.

Returns:

nearest reachable ground item, or empty

nearestReachable

public static Optional<GroundItem> nearestReachable(Filter<GroundItem> filter)

Finds the nearest reachable item accepted by a filter.

Parameters:

filter - item predicate

Returns:

nearest reachable match, or empty

nearestReachable

public static Optional<GroundItem> nearestReachable(Filter<GroundItem> filter,
 int maximumDistance)

Finds the nearest reachable filtered item within a distance limit.

Parameters:

filter - item predicate

maximumDistance - inclusive Chebyshev distance

Returns:

nearest reachable match, or empty

interact

public static boolean interact(int id,
 Tile tile,
 int action)

Dispatches a raw action to an exact ground-item identity and tile.

Parameters:

id - item definition identifier

tile - loaded scene tile

action - native ground-item action opcode

Returns:

true when the client was ready and accepted dispatch

interact

public static boolean interact(int id,
 Tile tile,
 GroundItemAction action)

Dispatches a typed action to an exact ground-item identity and tile.

Parameters:

id - item definition identifier

tile - loaded scene tile

action - ground-item menu action

Returns:

true when accepted; item collection is not implied

interact

public static boolean interact(GroundItem item,
 GroundItemAction action)

Dispatches a typed action to a current ground-item snapshot.

Parameters:

item - current stack snapshot

action - ground-item menu action

Returns:

true when accepted

interact

public static boolean interact(int id,
 GroundItemAction action)

Dispatches to the nearest same-plane stack with an identifier.

Parameters:

id - item definition identifier

action - ground-item menu action

Returns:

true when a match existed and dispatch was accepted

interact

public static boolean interact(String name,
 GroundItemAction action)

Dispatches to the nearest same-plane stack with an exact name.

Parameters:

name - exact case-insensitive item name

action - ground-item menu action

Returns:

true when a match existed and dispatch was accepted

interact

public static boolean interact(Filter<GroundItem> filter,
 GroundItemAction action)

Dispatches to the nearest same-plane stack accepted by a filter.

Parameters:

filter - item predicate

action - ground-item menu action

Returns:

true when a match existed and dispatch was accepted

getForTile

public static List<GroundItem> getForTile(Tile tile)

Returns every ground-item stack on an exact world tile.

Parameters:

tile - exact world tile

Returns:

matching snapshots

interact

public static boolean interact(int id,
 int x,
 int y,
 int plane,
 int action)

Dispatches a raw action using explicit coordinates.

Parameters:

id - item definition identifier

x - world X

y - world Y

plane - world plane

action - native action opcode

Returns:

true when dispatch was accepted

interact

public static boolean interact(int id,
 int x,
 int y,
 int plane,
 GroundItemAction action)

Dispatches a typed action using explicit coordinates.

Parameters:

id - item definition identifier

x - world X

y - world Y

plane - world plane

action - ground-item menu action

Returns:

true when dispatch was accepted

count

public static int count(Filter<GroundItem> filter)

Counts ground items accepted by a filter.

Parameters:

filter - item predicate

Returns:

number of matching ground-item stacks

exists

public static boolean exists(Filter<GroundItem> filter)

Tests whether a filtered ground item exists.

Parameters:

filter - item predicate

Returns:

whether a same-plane matching stack exists

exists

public static boolean exists(Integer... ids)

Tests whether any candidate identifier exists.

Parameters:

ids - candidate identifiers

Returns:

whether a same-plane matching stack 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 stack exists