Class ScriptContext<T>

Type Parameters:
T - The type of object hosting the script.
All Implemented Interfaces:
AutoCloseable
public final class ScriptContext<T> extends Object implements AutoCloseable

Runtime services and binding values supplied to a script instance.

A context owns the input listeners, scheduled actions, UI elements, and other subscriptions registered through it. close() releases those resources when the script detaches or reloads.

See Also:

  • Constructor Details

    • ScriptContext

      public ScriptContext(ScriptDefinition definition, ScriptBinding binding, T host)
      Creates a context for one attached script instance.
      Parameters:
      definition - The registered script definition.
      binding - The binding that created the instance.
      host - The object hosting the script.

  • Method Details

    • definition

      public ScriptDefinition definition()
      Returns the definition used to create the script.
      Returns:
      The script definition.

    • binding

      public ScriptBinding binding()
      Returns the binding applied to this instance.
      Returns:
      The script binding.

    • host

      public T host()
      Returns the object hosting this script.
      Returns:
      The script host.

    • logger

      public Logger logger()
      Returns a logger named for the script definition.
      Returns:
      The script logger.

    • globals

      public ScriptGlobals globals()
      Returns the game-wide script globals.
      Returns:
      The shared global registry.

    • parameters

      public Map<String,String> parameters()
      Returns the parameters configured by the binding.
      Returns:
      The binding parameters.

    • parameter

      public String parameter(String name)
      Looks up a binding parameter.
      Parameters:
      name - The parameter name.
      Returns:
      The configured value, or null if absent.

    • parameter

      public String parameter(String name, String defaultValue)
      Looks up a binding parameter with a fallback.
      Parameters:
      name - The parameter name.
      defaultValue - The value returned when the parameter is absent.
      Returns:
      The configured value or defaultValue.

    • environment

      public Environment environment()

      Returns the environment associated with this host.

      Entity hosts use their current environment; environment hosts return themselves.

      Returns:
      The associated environment, or null if neither the host nor the game world has one.

    • entities

      public <E> EntityQuery<E> entities(Class<? extends E> type)
      Starts a fluent query against the current environment.
      Type Parameters:
      E - The entity type.
      Parameters:
      type - The entity type to query.
      Returns:
      A query over matching entities in the current environment.

    • createAbility

      public ScriptedAbilityBuilder createAbility(String name)
      Begins building a scripted ability executed by the current host creature.
      Parameters:
      name - The ability name.
      Returns:
      A builder for the new ability.
      Throws:
      IllegalStateException - if the host is not a creature.

    • createAbility

      public ScriptedAbilityBuilder createAbility(Creature executor, String name)
      Begins building a scripted ability for a specific executor creature.
      Parameters:
      executor - The creature that will execute the ability.
      name - The ability name.
      Returns:
      A builder for the new ability.

    • cast

      public AbilityExecution cast(String name)
      Casts an ability on the current host creature by name.
      Parameters:
      name - The registered ability name.
      Returns:
      The ability execution, or null when the ability cannot be cast.
      Throws:
      IllegalStateException - if the host is not a creature.

    • cast

      public AbilityExecution cast(Creature executor, String name)
      Casts an ability on a specific executor creature by name.
      Parameters:
      executor - The creature that will execute the ability.
      name - The registered ability name.
      Returns:
      The ability execution, or null when the executor is absent or cannot cast it.

    • canCast

      public boolean canCast(String name)
      Checks if an ability on the current host creature can currently be cast.
      Parameters:
      name - The registered ability name.
      Returns:
      true if the host is a creature and can cast the ability.

    • canCast

      public boolean canCast(Creature executor, String name)
      Checks if an ability on a specific executor creature can currently be cast.
      Parameters:
      executor - The creature to check.
      name - The registered ability name.
      Returns:
      true if the executor exists and can cast the ability.

    • isOnCooldown

      public boolean isOnCooldown(String name)
      Checks if an ability on the current host creature is currently on cooldown.
      Parameters:
      name - The registered ability name.
      Returns:
      true if the host is a creature and the ability is cooling down.

    • isOnCooldown

      public boolean isOnCooldown(Creature executor, String name)
      Checks if an ability on a specific executor creature is currently on cooldown.
      Parameters:
      executor - The creature to check.
      name - The registered ability name.
      Returns:
      true if the executor exists and the ability is cooling down.

    • spawnProjectile

      public ScriptedProjectileBuilder spawnProjectile()
      Begins building and spawning a scripted projectile in the current environment.
      Returns:
      A projectile builder bound to the current environment.

    • ui

      public ScriptUiOverlay ui()
      Returns the scripted UI overlay service owned by this context.
      Returns:
      The lazily created overlay service.

    • camera

      public ICamera camera()
      Returns the active camera from the game world.
      Returns:
      The active camera, or null if none is configured.

    • input

      public ScriptInput input()
      Returns the managed input helper owned by this context.
      Returns:
      The lazily created input helper.

    • spawner

      public ScriptedSpawner spawner()
      Returns a fluent spawner for creating entities in the current environment.
      Returns:
      A spawner bound to the current environment.
      Throws:
      IllegalStateException - if no environment is active.

    • spawnCreature

      public Creature spawnCreature(String spritePrefix, double x, double y)
      Spawns a creature with the given sprite prefix at the specified coordinates.
      Parameters:
      spritePrefix - The animation sprite prefix.
      x - The map x-coordinate.
      y - The map y-coordinate.
      Returns:
      The spawned creature.

    • spawnCreature

      public Creature spawnCreature(String spritePrefix, Point2D location)
      Spawns a creature with the given sprite prefix at the specified location.
      Parameters:
      spritePrefix - The animation sprite prefix.
      location - The location in map coordinates.
      Returns:
      The spawned creature.

    • spawnProp

      public Prop spawnProp(String spriteSheet, double x, double y)
      Spawns a prop with the given spritesheet at the specified coordinates.
      Parameters:
      spriteSheet - The spritesheet name.
      x - The map x-coordinate.
      y - The map y-coordinate.
      Returns:
      The spawned prop.

    • spawnProp

      public Prop spawnProp(String spriteSheet, Point2D location)
      Spawns a prop with the given spritesheet at the specified location.
      Parameters:
      spriteSheet - The spritesheet name.
      location - The location in map coordinates.
      Returns:
      The spawned prop.

    • spawn

      public <E extends IEntity> E spawn(Class<E> entityType, double x, double y)
      Spawns an entity of the given type at the specified coordinates.
      Type Parameters:
      E - The entity type.
      Parameters:
      entityType - The concrete type, which must have a no-argument constructor.
      x - The map x-coordinate.
      y - The map y-coordinate.
      Returns:
      The spawned entity.

    • spawn

      public <E extends IEntity> E spawn(Class<E> entityType, Point2D location)
      Spawns an entity of the given type at the specified location.
      Type Parameters:
      E - The entity type.
      Parameters:
      entityType - The concrete type, which must have a no-argument constructor.
      location - The location in map coordinates.
      Returns:
      The spawned entity.

    • spawn

      public <E extends IEntity> E spawn(E entity, double x, double y)
      Spawns the given entity at the specified coordinates.
      Type Parameters:
      E - The entity type.
      Parameters:
      entity - The entity to add to the environment.
      x - The map x-coordinate.
      y - The map y-coordinate.
      Returns:
      The supplied entity.

    • spawn

      public <E extends IEntity> E spawn(E entity, Point2D location)
      Spawns the given entity at the specified location.
      Type Parameters:
      E - The entity type.
      Parameters:
      entity - The entity to add to the environment.
      location - The location in map coordinates.
      Returns:
      The supplied entity.

    • manage

      public <S extends Subscription> S manage(S subscription)
      Adds a registration that will be released when the script is detached or reloaded.
      Type Parameters:
      S - The subscription type.
      Parameters:
      subscription - The subscription to own.
      Returns:
      The supplied subscription.

    • manage

      public <R> R manage(R resource, Consumer<? super R> release)
      Owns an arbitrary resource and invokes its release action when the script detaches or reloads.
      Type Parameters:
      R - The resource type.
      Parameters:
      resource - The resource to own.
      release - The action that releases it.
      Returns:
      The supplied resource.

    • listen

      public <L> L listen(Consumer<? super L> add, Consumer<? super L> remove, L listener)
      Registers a listener and automatically removes it when the script detaches or reloads.
      Type Parameters:
      L - The listener type.
      Parameters:
      add - The operation that registers the listener.
      remove - The operation that unregisters it.
      listener - The listener instance.
      Returns:
      The supplied listener.

    • schedule

      public Subscription schedule(int delay, Runnable action)
      Schedules a cancellable action on the game loop.
      Parameters:
      delay - The delay in milliseconds.
      action - The action to invoke.
      Returns:
      A subscription that cancels the scheduled action.

    • sequence

      public ScriptSequence sequence()
      Creates an ordered, cancellable sequence of actions and delays owned by this context.
      Returns:
      A new sequence owned by this context.

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable