Interface GamevalIndex

All Superinterfaces:
AutoCloseable
public interface GamevalIndex extends AutoCloseable
Resolves gameval symbolic names to entity ids and back.

A gameval is the stable name the game itself ships for an entity — YEW_LOGS, BANK__BANK_INV_BUTTON, ZAROS_SPELLBOOK. Unlike a display name it is unique within its GamevalType, is not localised, and exists for things that have no display name at all (interface components, varbits, params). Unlike a raw id it survives a game update, so a renumber is fixed by refreshing the index rather than editing scripts.

int yew = api.gamevals().require(GamevalType.ITEM, "YEW_LOGS");
api.components().get("BANK__BANK_INV_BUTTON").interact(1);

Obtain one from GameAPI.gamevals(); it is never null. When no index is deployed every lookup returns empty and isAvailable() is false, so a script can degrade rather than crash — see empty().

Names are matched case-insensitively; the index stores them upper-case. Implementations are safe for concurrent use.

  • Field Details

    • INTERFACE_ID_SHIFT

      static final int INTERFACE_ID_SHIFT
      Bit position the interface id occupies in a packed component id.
      See Also:

    • COMPONENT_ID_MASK

      static final int COMPONENT_ID_MASK
      Mask selecting the component-id half of a packed component id.
      See Also:

  • Method Details

    • id

      OptionalInt id(GamevalType type, String gameval)
      The id for a name, or empty when the name is unknown.

    • require

      default int require(GamevalType type, String gameval)
      The id for a name, or throw.
      Throws:
      GamevalNotFoundException - when the name is unknown or no index is deployed

    • gameval

      Optional<String> gameval(GamevalType type, int id)
      The name for an id, or empty when the id has none.

    • startingWith

      List<GamevalEntry> startingWith(GamevalType type, String prefix, int limit)
      Names in type starting with prefix, ordered by name. Intended for tooling and diagnostics — a script that needs one id should name it exactly.
      Parameters:
      limit - maximum results; must be positive

    • component

      default Optional<ComponentRef> component(String gameval)
      Splits a GamevalType.COMPONENT name into the interface and component ids it packs, e.g. "BANK__BANK_INV_BUTTON" → interface 517, component 39. Empty when the name is unknown.

    • interfaceId

      default OptionalInt interfaceId(String gameval)
      Shorthand for id(GamevalType.INTERFACE, gameval).

    • isAvailable

      boolean isAvailable()
      False when no index is deployed and every lookup will return empty.

    • meta

      Optional<String> meta(String key)
      A value from the index's build stamp — built, source_mtime, rows, groups, schema_version. Empty when absent.

    • close

      default void close()
      Releases any resources held. Idempotent.
      Specified by:
      close in interface AutoCloseable

    • empty

      static GamevalIndex empty()
      An index that resolves nothing — the fallback when none is deployed. Test for it with isAvailable(), never by identity.