Package com.valhalla.sdk

Interface ScriptContext

All Known Implementing Classes:
FakeScriptContext
public interface ScriptContext
Runtime context supplied to each script lifecycle callback.

The context exposes launch settings, permission checks, and script-scoped logging. A permission in the package manifest authorizes an operation; it does not guarantee that the active client adapter advertises the corresponding capability. Use Client.supports(...) before optional native features.

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    debug(String message)
    Logs a debug message.
    default void
    error(String message)
    Logs an error message.
    default boolean
    getBooleanSetting(String name, boolean fallback)
    Reads common boolean spellings such as true, yes, and 1.
    default double
    getDoubleSetting(String name, double fallback)
    Reads a finite floating-point setting.
    default <E extends Enum<E>>
    E
    getEnumSetting(String name, Class<E> type, E fallback)
    Reads an enum constant case-insensitively, treating spaces and hyphens as underscores.
    default List<GameMessage>
    getGameMessages()
    Returns the game-message lines currently retained by the client.
    default List<Integer>
    getIntListSetting(String name)
    Reads a comma-separated list while silently omitting malformed integers.
    default int
    getIntSetting(String name, int fallback)
    Reads a base-10 integer setting without propagating parse errors.
    default int
    getIntSetting(String name, int fallback, int minimum, int maximum)
    Reads and clamps an integer setting to an inclusive range.
    default List<String>
    getListSetting(String name)
    Reads a comma-separated setting as trimmed, non-empty strings.
    default long
    getLongSetting(String name, long fallback)
    Reads a base-10 long setting without propagating parse errors.
    String
    getScriptId()
    Returns the stable package identifier from manifest.json.
    default String
    getSetting(String name, String fallback)
    Returns a launch-time script setting supplied by the Command Center.
    boolean
    hasPermission(String permission)
    Tests whether the installed package was granted a manifest permission.
    default void
    info(String message)
    Logs an informational message.
    default boolean
    isBreakRequested()
    Returns whether Command Center has requested the script's next safe scheduled-break boundary.
    void
    log(String level, String message)
    Publishes a script-scoped log entry.
    default void
    publishTelemetry(String json)
    Publishes a small JSON telemetry snapshot for the Command Center paint.
    default void
    requirePermission(String permission)
    Requires a package permission before continuing.
    default void
    warn(String message)
    Logs a warning message.

  • Method Details

    • getScriptId

      String getScriptId()
      Returns the stable package identifier from manifest.json.
      Returns:
      script identifier used to prefix logs and runtime state

    • log

      void log(String level, String message)
      Publishes a script-scoped log entry.
      Parameters:
      level - severity label such as DEBUG, INFO, or ERROR
      message - human-readable message; avoid credentials and other secrets

    • hasPermission

      boolean hasPermission(String permission)
      Tests whether the installed package was granted a manifest permission.
      Parameters:
      permission - permission string, preferably from Permissions
      Returns:
      true when the package grants the permission

    • getSetting

      default String getSetting(String name, String fallback)
      Returns a launch-time script setting supplied by the Command Center.
      Parameters:
      name - setting key declared in the package manifest
      fallback - value returned when the key is absent
      Returns:
      configured string value, or fallback when absent

    • publishTelemetry

      default void publishTelemetry(String json)
      Publishes a small JSON telemetry snapshot for the Command Center paint.

      An older runtime that predates this additive API resolves this default body, which forwards the snapshot through log(java.lang.String, java.lang.String) using the runtime's long-established "Telemetry: " bridge. That bridge applies the same permission, size, and JSON checks as the override and never writes telemetry values to Android's shared log buffer, so a runtime that does not implement this method degrades to the bridge instead of discarding the snapshot.

      A runtime predating the bridge does not recognize the prefix and records the line as an ordinary script log entry instead, which is why this snapshot must hold no credentials or secrets - the same contract log(java.lang.String, java.lang.String) already states.

      Parameters:
      json - valid JSON object, containing no credentials or secrets

    • isBreakRequested

      default boolean isBreakRequested()
      Returns whether Command Center has requested the script's next safe scheduled-break boundary.

      The request is advisory: scripts should finish indivisible work and publish their existing safe-boundary telemetry before yielding. Older runtimes return false through this additive default method.

      Returns:
      true while a scheduled break is due and awaiting a safe boundary

    • getGameMessages

      default List<GameMessage> getGameMessages()
      Returns the game-message lines currently retained by the client.

      This data stays inside the Android script runtime and is never forwarded to Command Center telemetry. Packages must request Permissions.GAME_READ_MESSAGES; older runtimes return an empty list through this default implementation.

      Returns:
      immutable snapshot of retained game messages

    • getIntSetting

      default int getIntSetting(String name, int fallback)
      Reads a base-10 integer setting without propagating parse errors.
      Parameters:
      name - setting key
      fallback - value used for missing or malformed input
      Returns:
      parsed value or fallback

    • getIntSetting

      default int getIntSetting(String name, int fallback, int minimum, int maximum)
      Reads and clamps an integer setting to an inclusive range.
      Parameters:
      name - setting key
      fallback - value used for missing or malformed input before clamping
      minimum - inclusive lower bound
      maximum - inclusive upper bound
      Returns:
      parsed value constrained to [minimum, maximum]
      Throws:
      IllegalArgumentException - when maximum < minimum

    • getLongSetting

      default long getLongSetting(String name, long fallback)
      Reads a base-10 long setting without propagating parse errors.
      Parameters:
      name - setting key
      fallback - value used for missing or malformed input
      Returns:
      parsed value or fallback

    • getDoubleSetting

      default double getDoubleSetting(String name, double fallback)
      Reads a finite floating-point setting.
      Parameters:
      name - setting key
      fallback - value used for missing, malformed, infinite, or NaN input
      Returns:
      finite parsed value or fallback

    • getBooleanSetting

      default boolean getBooleanSetting(String name, boolean fallback)
      Reads common boolean spellings such as true, yes, and 1.
      Parameters:
      name - setting key
      fallback - value used for missing or unrecognized input
      Returns:
      parsed boolean or fallback

    • getEnumSetting

      default <E extends Enum<E>> E getEnumSetting(String name, Class<E> type, E fallback)
      Reads an enum constant case-insensitively, treating spaces and hyphens as underscores.
      Type Parameters:
      E - enum type
      Parameters:
      name - setting key
      type - enum class used for parsing
      fallback - value used for missing or unrecognized input
      Returns:
      parsed enum constant or fallback
      Throws:
      NullPointerException - when type is null

    • getListSetting

      default List<String> getListSetting(String name)
      Reads a comma-separated setting as trimmed, non-empty strings.
      Parameters:
      name - setting key
      Returns:
      immutable list, empty when the setting is absent or blank

    • getIntListSetting

      default List<Integer> getIntListSetting(String name)
      Reads a comma-separated list while silently omitting malformed integers.
      Parameters:
      name - setting key
      Returns:
      immutable list of successfully parsed integers

    • debug

      default void debug(String message)
      Logs a debug message.
      Parameters:
      message - message logged at DEBUG severity

    • info

      default void info(String message)
      Logs an informational message.
      Parameters:
      message - message logged at INFO severity

    • warn

      default void warn(String message)
      Logs a warning message.
      Parameters:
      message - message logged at WARN severity

    • error

      default void error(String message)
      Logs an error message.
      Parameters:
      message - message logged at ERROR severity

    • requirePermission

      default void requirePermission(String permission)
      Requires a package permission before continuing.
      Parameters:
      permission - permission string, preferably from Permissions
      Throws:
      SecurityException - when the permission is not granted