Class ScriptManager

All Implemented Interfaces:
IUpdateable
public final class ScriptManager extends Object implements IUpdateable

Coordinates script providers, definitions, bindings, lifecycles, diagnostics, and explicit reloads.

The game-wide instance is available from Game.scripts(). It attaches game bindings when the game starts, configures entity bindings when matching entities are loaded, and releases managed resources when their host is detached. After a failed reload(String), the manager attempts to restore the previous compiled generation and records any attachment failures as diagnostics.

See Also:

  • Field Details

    • BINDINGS_PROPERTY

      public static final String BINDINGS_PROPERTY
      Map property containing serialized entity script bindings.
      See Also:

  • Constructor Details

    • ScriptManager

      public ScriptManager()
      Creates a manager with Java support and discovers additional providers through ServiceLoader.

  • Method Details

    • isEnabled

      public boolean isEnabled()
      Returns whether lifecycle callbacks are dispatched to attached scripts.
      Returns:
      true when dispatch is enabled.

    • setEnabled

      public void setEnabled(boolean enabled)
      Enables or pauses callback dispatch without detaching scripts.
      Parameters:
      enabled - true to dispatch callbacks.

    • globals

      public ScriptGlobals globals()
      Returns the values shared by all managed scripts.
      Returns:
      The mutable global binding registry.

    • registerProvider

      public void registerProvider(ScriptProvider provider)
      Registers or replaces the provider for its case-insensitive language identifier.
      Parameters:
      provider - The provider to register.
      Throws:
      NullPointerException - if provider is null.

    • getProviders

      public Collection<ScriptProvider> getProviders()
      Returns a snapshot of registered language providers.
      Returns:
      The registered providers in unspecified order.

    • createLanguageService

      public Optional<ScriptLanguageService> createLanguageService(String language)
      Creates non-executing semantic tooling backed by the registered provider for a language.
      Parameters:
      language - The case-insensitive language identifier.
      Returns:
      A language service, or an empty optional if the language is unknown or unsupported.

    • setDefinitions

      public void setDefinitions(Collection<ScriptDefinition> definitions)

      Replaces all registered definitions with validated defensive copies.

      Invalid or duplicate definitions are skipped and recorded as diagnostics. Removing a definition detaches its instances and closes its compiled generation.

      Parameters:
      definitions - The replacement definitions, or null to clear them.

    • getDefinitions

      public Collection<ScriptDefinition> getDefinitions()
      Returns defensive copies of all definitions, sorted by identifier.
      Returns:
      An unmodifiable definition snapshot.

    • getDefinition

      public ScriptDefinition getDefinition(String id)
      Finds a registered definition.
      Parameters:
      id - The definition identifier.
      Returns:
      A defensive copy, or null if no definition is registered.

    • getPropertyMetadata

      public List<ScriptPropertyMetadata> getPropertyMetadata(String scriptId)
      Returns configurable fields from the currently compiled generation without compiling or executing new code.
      Parameters:
      scriptId - The script identifier.
      Returns:
      The configurable properties, or an empty list if the script has not been compiled.

    • setGameBindings

      public void setGameBindings(Collection<ScriptBinding> bindings)

      Replaces scripts attached to the game lifecycle.

      If the game is running, existing game scripts are detached and replacements attach immediately.

      Parameters:
      bindings - The replacement bindings, or null to clear them.

    • getGameBindings

      public List<ScriptBinding> getGameBindings()
      Returns defensive copies of the configured game bindings.
      Returns:
      An unmodifiable binding snapshot.

    • setEntityBindings

      public void setEntityBindings(Collection<EntityScriptBinding> bindings)
      Replaces reusable bindings that are automatically applied when matching entities are loaded.
      Parameters:
      bindings - The replacement bindings, or null to clear them.

    • getEntityBindings

      public List<EntityScriptBinding> getEntityBindings()
      Returns defensive copies of the configured entity binding rules.
      Returns:
      An unmodifiable binding snapshot.

    • configure

      public void configure(IEntity entity)
      Adds or refreshes the script controller that owns the default bindings for an entity type.
      Parameters:
      entity - The entity to configure.
      Throws:
      NullPointerException - if entity is null.

    • setProjectRoot

      public void setProjectRoot(Path projectRoot)
      Sets the directory against which relative development-time source paths are resolved.
      Parameters:
      projectRoot - The project root, or null to clear it.

    • getProjectRoot

      public Path getProjectRoot()
      Returns the normalized project root used to resolve script source paths.
      Returns:
      The project root, or null when none is configured.

    • setProjectClassLoader

      public void setProjectClassLoader(ClassLoader projectClassLoader)
      Sets the compiled project class loader used as the parent of runtime-compiled scripts.
      Parameters:
      projectClassLoader - The parent loader, or null to use the context or engine loader.

    • setProjectClasspath

      public void setProjectClasspath(Collection<Path> projectClasspath)
      Sets build-resolved locations used by development-time source compilation.
      Parameters:
      projectClasspath - The class-path entries; null clears the class path.

    • getDiagnostics

      public List<ScriptDiagnostic> getDiagnostics()
      Returns a snapshot of compilation and lifecycle diagnostics.
      Returns:
      The diagnostics in reporting order.

    • clearDiagnostics

      public void clearDiagnostics()
      Removes all recorded diagnostics.

    • clearDiagnostics

      public void clearDiagnostics(String scriptId)
      Removes diagnostics associated with a script identifier.
      Parameters:
      scriptId - The identifier to clear; null has no effect.

    • clearDiagnostics

      public void clearDiagnostics(Object host)

      Removes diagnostics whose messages identify an entity host.

      Diagnostics for other host types are not associated with their host and cannot be cleared by this method.

      Parameters:
      host - The entity host to clear; other values, including null, have no effect.

    • attachAll

      public List<ScriptInstance> attachAll(Object host, Collection<ScriptBinding> bindings)

      Attaches all enabled bindings to a host in ascending binding order.

      Failures are reported through getDiagnostics() and omitted from the result.

      Parameters:
      host - The object exposed as the script host.
      bindings - The bindings to attach, or null for none.
      Returns:
      An unmodifiable list of successfully attached instances.

    • attach

      public ScriptInstance attach(Object host, ScriptBinding binding)
      Attaches one binding to a host.
      Parameters:
      host - The object exposed as the script host.
      binding - The binding to attach.
      Returns:
      The attached instance, or null when attachment failed.
      Throws:
      NullPointerException - if host or binding is null.

    • reload

      public boolean reload(String scriptId)

      Recompiles a script and replaces all of its active attachments.

      Existing instances are detached before the replacement instances attach. If compilation or attachment fails, the replacement is discarded and the manager attempts to reattach the previous generation. Rollback attachment failures are recorded as diagnostics. Lifecycle callbacks therefore run during both replacement and rollback.

      Parameters:
      scriptId - The identifier of the script to reload.
      Returns:
      true if the replacement compiled and all desired bindings were attached.

    • detach

      public void detach(Object host)
      Detaches every script attached to a host and forgets its desired bindings.
      Parameters:
      host - The host identified by object identity.

    • setProjectJavaVersion

      public void setProjectJavaVersion(int projectJavaVersion)
      Sets the Java language level used for development-time source compilation.
      Parameters:
      projectJavaVersion - The positive Java feature version.
      Throws:
      IllegalArgumentException - if the version is not positive.

    • detachAll

      public void detachAll()
      Detaches all scripts, closes compiled generations, and unregisters from the update loop.

    • update

      public void update()
      Dispatches one update to non-controller-managed script attachments.
      Specified by:
      update in interface IUpdateable
      See Also: