Interface VariableAPI

All Known Subinterfaces:
GameAPI
public interface VariableAPI
Game variable access: varps (player variables), varbits (bit-ranges of a base variable), and varcs (client variables, int- and string-valued).

These are on-demand reads of the live client state — each call is a pipe round-trip to the producer, which walks the relevant variable hashmap on the game thread. To observe changes instead of polling, subscribe to VarChangeEvent / VarbitChangeEvent / VarcChangeEvent on the EventBus.

Set, default, missing, unknown

Varps are set lazily by the server, so a varp at its default usually has no entry in the client. readVarp(int) says which of four things is true, as a VarpState: the varp is SET; it exists but is at its default (DEFAULT_NOT_SET_CLIENTSIDE); there is no such varp (NO_SUCH_VARP); or the read could not be made (UNAVAILABLE: not in game, still entering the world, a timed-out read). Use the state, never the value, to tell these apart. A set object-typed varp legitimately holds -1, and so does such a varp at its default.

The plain int accessors (getVarp(int), getVarps(List), getVarbit(int), queryVarbits(List)) return the same value the read* methods do: what the game itself would read when that is knowable (the stored value, or the type default from the cache definition), and -1 for a missing varp or a failed read.

Varbit values are decoded consumer-side from the base variable and the varbit's bit range in the cache config. A varbit takes its base's state. Over a base at its default, it decodes the base's default, as the game does: for a varp whose default is -1, every bit of the range reads as set.

The varc accessors are raw: the agent reports no per-id state for client variables, so an unset varc reads -1.

See Also:

  • Method Details

    • getVarp

      int getVarp(int varId)
      Returns the value of a player variable (varp): what the game reads for it.

      For a LONG varp this is the low 32 bits; use getVarpLong(int) for the whole value. To learn whether the varp is set rather than at its default, use readVarp(int).

      Parameters:
      varId - the variable ID
      Returns:
      the stored value, or the type default when the client holds no entry, or -1 when there is no such varp or the read could not be made

    • getVarpLong

      long getVarpLong(int varId)
      The full 64-bit value of a player variable, for LONG varps whose value does not fit an int. For any other varp it equals getVarp(int), sign-extended.
      Parameters:
      varId - the variable ID
      Returns:
      as getVarp(int), at full width

    • readVarp

      VarpRead readVarp(int varId)
      Reads a varp with its state.
      Parameters:
      varId - the variable ID
      Returns:
      the read; never null

    • readVarps

      List<VarpRead> readVarps(List<Integer> varIds)
      Batch form of readVarp(int): one read per input id, in order. Any number of ids may be passed; the agent's per-request cap is handled here.
      Parameters:
      varIds - the variable IDs
      Returns:
      one read per id, in order

    • varpState

      default VarpState varpState(int varId)
      Just the state of a varp: whether it is set, at its default, missing, or unknown.
      Parameters:
      varId - the variable ID
      Returns:
      the state

    • readVarbit

      VarbitRead readVarbit(int varbitId)
      Reads a varbit with the state of its base variable.
      Parameters:
      varbitId - the varbit ID
      Returns:
      the read; never null

    • readVarbits

      List<VarbitRead> readVarbits(List<Integer> varbitIds)
      Batch form of readVarbit(int): one read per input id, in order.
      Parameters:
      varbitIds - the varbit IDs
      Returns:
      one read per id, in order

    • getVarbit

      int getVarbit(int varbitId)
      Returns the value of a variable bit (varbit), decoded from its base variable and bit range.

      A base variable the client holds no entry for decodes its type default, the same answer the engine's own bit extractor gives: 0 for most varps, so a single-bit unlock flag reads "locked" on an account that never set it; every bit set for a varp whose default is -1. When the cache cannot supply the default, 0 is used; readVarbit(int) reports that case.

      A base the agent could not read at all (not in game, a timed-out read) is not unset: nothing is known about it, so it reads -1, never a cleared 0. Code that tracks a value over time should keep its last known value on -1.

      Parameters:
      varbitId - the varbit ID
      Returns:
      the decoded varbit value; the decoded default when the varbit's base variable is unset, or -1 when the varbit id or its base is unknown to the cache (or its bit range is malformed) or its base could not be read

    • getVarcInt

      int getVarcInt(int varcId)
      Returns the value of an integer client variable (varc).
      Parameters:
      varcId - the varc ID
      Returns:
      the varc value, or -1 if not set

    • getVarcString

      String getVarcString(int varcId)
      Returns the value of a string client variable (varc).
      Parameters:
      varcId - the varc ID
      Returns:
      the varc string value, or the empty string if not set

    • queryVarbits

      List<VarbitValue> queryVarbits(List<Integer> varbitIds)
      Batch-resolves multiple varbit values. Each value carries the same contract as getVarbit(int), and the two agree for every id.
      Parameters:
      varbitIds - the varbit IDs to query
      Returns:
      one VarbitValue per input id, in order, each valued as getVarbit(int) would value it

    • getVarps

      List<Integer> getVarps(List<Integer> varIds)
      Batch counterpart of getVarp(int). One pipe round-trip and one game-thread visit for the whole batch, instead of one per id.
      Parameters:
      varIds - the varp IDs to read
      Returns:
      one value per input id, in order, each valued as getVarp(int) would value it

    • getVarcInts

      List<Integer> getVarcInts(List<Integer> varcIds)
      Batch counterpart of getVarcInt(int).
      Parameters:
      varcIds - the varc IDs to read
      Returns:
      one value per input id, in order; unset entries are -1

    • getVarcStrings

      List<String> getVarcStrings(List<Integer> varcIds)
      Batch counterpart of getVarcString(int).
      Parameters:
      varcIds - the varc IDs to read
      Returns:
      one string per input id, in order; unset entries are empty