org.mini2Dx.miniscript.core

Class GameScriptingEngine

java.lang.Object

org.mini2Dx.miniscript.core.GameScriptingEngine

All Implemented Interfaces:

java.lang.Runnable

public abstract class GameScriptingEngine
extends java.lang.Object
implements java.lang.Runnable

Provides scripting functionality to your game Note that this is a base class for each scripting language implementation.

Field Summary

Fields

Modifier and Type	Field and Description
static org.mini2Dx.lockprovider.Locks	LOCK_PROVIDER
static GameScriptingEngine	MOST_RECENT_INSTANCE Returns the most recently created GameScriptingEngine

Constructor Summary

Constructors

Constructor and Description
GameScriptingEngine() Constructs a scripting engine backed by a thread pool with the maximum amount of concurrent scripts set to 2.
GameScriptingEngine(boolean sandboxed) Constructs a scripting engine backed by a thread pool with the maximum amount of concurrent scripts set to the amount of processors + 1.
GameScriptingEngine(ClasspathScriptProvider classpathScriptProvider, boolean sandboxed) Constructs a scripting engine backed by a thread pool with the maximum amount of concurrent scripts set to 2.
GameScriptingEngine(ClasspathScriptProvider classpathScriptProvider, int maxConcurrentScripts) Constructs a scripting engine backed by a thread pool.
GameScriptingEngine(ClasspathScriptProvider classpathScriptProvider, int maxConcurrentScripts, boolean sandboxed) Constructs a scripting engine backed by a thread pool.
GameScriptingEngine(ClasspathScriptProvider classpathScriptProvider, int maxConcurrentScripts, ThreadPoolProvider threadPoolProvider)
GameScriptingEngine(ClasspathScriptProvider classpathScriptProvider, int maxConcurrentScripts, ThreadPoolProvider threadPoolProvider, boolean sandboxed)
GameScriptingEngine(ClasspathScriptProvider classpathScriptProvider, ThreadPoolProvider threadPoolProvider, boolean sandboxed)
GameScriptingEngine(int maxConcurrentScripts) Constructs a scripting engine backed by a thread pool.
GameScriptingEngine(int maxConcurrentScripts, boolean sandboxed) Constructs a scripting engine backed by a thread pool.
GameScriptingEngine(int maxConcurrentScripts, ThreadPoolProvider threadPoolProvider)
GameScriptingEngine(int maxConcurrentScripts, ThreadPoolProvider threadPoolProvider, boolean sandboxed)
GameScriptingEngine(ThreadPoolProvider threadPoolProvider)
GameScriptingEngine(ThreadPoolProvider threadPoolProvider, boolean sandboxed)

Method Summary

Modifier and Type	Method and Description
void	cancelAllQueuedGameFutures() Removes all currently queued GameFutures without sending skipFuture event
void	cancelAllQueuedInteractiveScripts() Clears all interactive scripts queued
void	cancelAllQueuedInteractiveScripts(boolean notifyListeners) Clears all interactive scripts queued
void	cancelAllQueuedNonInteractiveScripts() Clears all non-interactive scripts queued
void	cancelAllQueuedNonInteractiveScripts(boolean notifyListeners) Clears all non-interactive scripts queued
void	cancelAllQueuedScripts() Removes all currently queued GameFutures without sending skipFuture event
void	cancelAllQueuedScripts(boolean notifyListeners) Removes all currently queued GameFutures without sending skipFuture event
void	cancelAllRunningGameFutures() Removes all currently running GameFutures without sending skipFuture event
void	cancelQueuedScript(int scriptId) Removes all currently queued scripts with a given script ID
void	cancelQueuedScript(int scriptId, boolean notifyListeners) Removes all currently queued scripts with a given script ID
void	cancelQueuedScriptByTaskId(int taskId) Removes a specific queued script by its task ID
void	cancelQueuedScriptByTaskId(int taskId, boolean notifyListeners) Removes a specific queued script by its task ID
int	compileScript(java.lang.String scriptContent) Compiles a script for execution.
int	compileScript(java.lang.String filepath, java.io.InputStream inputStream) Compiles a script for execution.
int	compileScript(java.lang.String filepath, java.lang.String scriptContent) Compiles a script for execution.
protected abstract ScriptExecutorPool<?>	createScriptExecutorPool(ClasspathScriptProvider classpathScriptProvider, int poolSize, boolean sandboxing)
void	dispose() Shuts down the thread pool and cleans up resources
void	dispose(boolean interruptScripts) Shuts down the thread pool and cleans up resources
int	getCompiledScriptId(java.lang.String filepath) Returns the script ID for a given filepath
java.util.List<java.lang.String>	getRunningScripts() Returns the list of currently running scripts.
int	getTotalInteractiveScriptsQueued() Returns the total interactive scripts queued
int	getTotalNonInteractiveScriptsQueued() Returns the total non-interactive scripts queued
int	getTotalScriptsQueued() Returns the total scripts (interactive + non-interactive) queued
int	invokeCompiledScript(int scriptId, ScriptBindings scriptBindings) Queues a compiled script for execution in the engine's thread pool
int	invokeCompiledScript(int scriptId, ScriptBindings scriptBindings, ScriptInvocationListener invocationListener) Queues a compiled script for execution in the engine's thread pool
int	invokeCompiledScript(int scriptId, ScriptBindings scriptBindings, ScriptInvocationListener invocationListener, int priority) Queues a compiled script for execution in the engine's thread pool
int	invokeCompiledScript(int scriptId, ScriptBindings scriptBindings, ScriptInvocationListener invocationListener, int priority, boolean interactive) Queues a compiled script for execution in the engine's thread pool
void	invokeCompiledScriptSync(int taskId, int scriptId, ScriptBindings scriptBindings) Executes a compiled script synchronously on the thread calling this method.
void	invokeCompiledScriptSync(int taskId, int scriptId, ScriptBindings scriptBindings, ScriptInvocationListener invocationListener) Executes a compiled script synchronously on the thread calling this method.
int	invokeScript(java.lang.String scriptContent, ScriptBindings scriptBindings) Compiles and queues a script for execution in the engine's thread pool
int	invokeScript(java.lang.String scriptContent, ScriptBindings scriptBindings, ScriptInvocationListener invocationListener) Compiles and queues a script for execution in the engine's thread pool
int	invokeScript(java.lang.String scriptContent, ScriptBindings scriptBindings, ScriptInvocationListener invocationListener, int priority) Compiles and queues a script for execution in the engine's thread pool
abstract boolean	isEmbeddedSynchronousScriptSupported() Checks if scripts can be synchronously run within other scripts
boolean	isInteractiveScriptRunning() Returns true if interactive script is running
abstract boolean	isSandboxingSupported() Checks if sandboxing is supported by the GameScriptingEngine implementation
void	run() This should not be invoked by the developer.
void	setCancelReallocatedFutures(boolean cancelReallocatedFutures) Sets if newly GameFutures should cancel a previously scheduled GameFuture with the same ID.
void	skipAllQueuedGameFutures() Skips all currently queued GameFutures
void	skipAllRunningGameFutures() Skips all currently running GameFutures
void	skipAllScripts() Skips all currently running scripts
void	skipOrCancelScript(int scriptId) Cancels a queued script or skips it if it is currently running
void	skipOrCancelScriptByTaskId(int taskId) Cancels a specific invocation of a script by its task ID, or skips it if it is currently running
void	skipScript(int scriptId) Skips all running instances of a script
void	skipScriptByTaskId(int taskId) Skips a specific running instance of a script
void	update(float delta) Updates all GameFutures

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MOST_RECENT_INSTANCE

public static GameScriptingEngine MOST_RECENT_INSTANCE

Returns the most recently created GameScriptingEngine

LOCK_PROVIDER

public static org.mini2Dx.lockprovider.Locks LOCK_PROVIDER

Constructor Detail

GameScriptingEngine

public GameScriptingEngine()

Constructs a scripting engine backed by a thread pool with the maximum amount of concurrent scripts set to 2. Sandboxing is enabled if the implementation supports it.

GameScriptingEngine

public GameScriptingEngine(ThreadPoolProvider threadPoolProvider)

GameScriptingEngine

public GameScriptingEngine(int maxConcurrentScripts)

Constructs a scripting engine backed by a thread pool. Sandboxing is enabled if the implementation supports it.

Parameters:

maxConcurrentScripts - The maximum amount of concurrently running scripts. WARNING: this is a 'requested' amount and may be less due to the amount of available processors on the player's machine.

GameScriptingEngine

public GameScriptingEngine(int maxConcurrentScripts,
                           ThreadPoolProvider threadPoolProvider)

GameScriptingEngine

public GameScriptingEngine(ClasspathScriptProvider classpathScriptProvider,
                           int maxConcurrentScripts)

Constructs a scripting engine backed by a thread pool. Sandboxing is enabled if the implementation supports it.

Parameters:

classpathScriptProvider - The auto-generated ClasspathScriptProvider for the game

maxConcurrentScripts - The maximum amount of concurrently running scripts. WARNING: this is a 'requested' amount and may be less due to the amount of available processors on the player's machine.

GameScriptingEngine

public GameScriptingEngine(ClasspathScriptProvider classpathScriptProvider,
                           int maxConcurrentScripts,
                           ThreadPoolProvider threadPoolProvider)

GameScriptingEngine

public GameScriptingEngine(boolean sandboxed)

Constructs a scripting engine backed by a thread pool with the maximum amount of concurrent scripts set to the amount of processors + 1.

Parameters:

sandboxed - True if script sandboxing should be enabled

GameScriptingEngine

public GameScriptingEngine(ThreadPoolProvider threadPoolProvider,
                           boolean sandboxed)

GameScriptingEngine

public GameScriptingEngine(ClasspathScriptProvider classpathScriptProvider,
                           boolean sandboxed)

Constructs a scripting engine backed by a thread pool with the maximum amount of concurrent scripts set to 2.

Parameters:

classpathScriptProvider - The auto-generated ClasspathScriptProvider for the game

sandboxed - True if script sandboxing should be enabled

GameScriptingEngine

public GameScriptingEngine(ClasspathScriptProvider classpathScriptProvider,
                           ThreadPoolProvider threadPoolProvider,
                           boolean sandboxed)

GameScriptingEngine

public GameScriptingEngine(int maxConcurrentScripts,
                           boolean sandboxed)

Constructs a scripting engine backed by a thread pool.

Parameters:

maxConcurrentScripts - The maximum amount of concurrently running scripts. WARNING: this is a 'requested' amount and may be less due to the amount of available processors on the player's machine.

sandboxed - True if script sandboxing should be enabled

GameScriptingEngine

public GameScriptingEngine(int maxConcurrentScripts,
                           ThreadPoolProvider threadPoolProvider,
                           boolean sandboxed)

GameScriptingEngine

public GameScriptingEngine(ClasspathScriptProvider classpathScriptProvider,
                           int maxConcurrentScripts,
                           boolean sandboxed)

Constructs a scripting engine backed by a thread pool.

Parameters:

classpathScriptProvider - The auto-generated ClasspathScriptProvider for the game

maxConcurrentScripts - The maximum amount of concurrently running scripts. WARNING: this is a 'requested' amount and may be less due to the amount of available processors on the player's machine.

sandboxed - True if script sandboxing should be enabled

GameScriptingEngine

public GameScriptingEngine(ClasspathScriptProvider classpathScriptProvider,
                           int maxConcurrentScripts,
                           ThreadPoolProvider threadPoolProvider,
                           boolean sandboxed)

Method Detail

dispose

public void dispose()

Shuts down the thread pool and cleans up resources

dispose

public void dispose(boolean interruptScripts)

Shuts down the thread pool and cleans up resources

Parameters:

interruptScripts - True if running scripts should be interrupted

isSandboxingSupported

public abstract boolean isSandboxingSupported()

Checks if sandboxing is supported by the GameScriptingEngine implementation

Returns:

True if sandboxing is supported

isEmbeddedSynchronousScriptSupported

public abstract boolean isEmbeddedSynchronousScriptSupported()

Checks if scripts can be synchronously run within other scripts

Returns:

True if scripts can be invoke synchronously within scripts

createScriptExecutorPool

protected abstract ScriptExecutorPool<?> createScriptExecutorPool(ClasspathScriptProvider classpathScriptProvider,
                                                                  int poolSize,
                                                                  boolean sandboxing)

update

public void update(float delta)

Updates all GameFutures

Parameters:

delta - The time (in seconds) since the last frame update

run

public void run()

This should not be invoked by the developer. Call update(float) instead.

Specified by:

run in interface java.lang.Runnable

skipAllScripts

public void skipAllScripts()

Skips all currently running scripts

skipScript

public void skipScript(int scriptId)

Skips all running instances of a script

Parameters:

scriptId - The ID of the script to skip

skipScriptByTaskId

public void skipScriptByTaskId(int taskId)

Skips a specific running instance of a script

Parameters:

taskId - The ID of the task to skip

skipAllRunningGameFutures

public void skipAllRunningGameFutures()

Skips all currently running GameFutures

skipAllQueuedGameFutures

public void skipAllQueuedGameFutures()

Skips all currently queued GameFutures

cancelAllRunningGameFutures

public void cancelAllRunningGameFutures()

Removes all currently running GameFutures without sending skipFuture event

cancelAllQueuedGameFutures

public void cancelAllQueuedGameFutures()

Removes all currently queued GameFutures without sending skipFuture event

cancelAllQueuedScripts

public void cancelAllQueuedScripts()

Removes all currently queued GameFutures without sending skipFuture event

cancelAllQueuedScripts

public void cancelAllQueuedScripts(boolean notifyListeners)

Removes all currently queued GameFutures without sending skipFuture event

Parameters:

notifyListeners - If true will notify invocation listeners of script cancellation

cancelQueuedScript

public void cancelQueuedScript(int scriptId)

Removes all currently queued scripts with a given script ID

cancelQueuedScriptByTaskId

public void cancelQueuedScriptByTaskId(int taskId)

Removes a specific queued script by its task ID

cancelQueuedScript

public void cancelQueuedScript(int scriptId,
                               boolean notifyListeners)

Removes all currently queued scripts with a given script ID

Parameters:

notifyListeners - If true will notify invocation listeners of script cancellation

cancelQueuedScriptByTaskId

public void cancelQueuedScriptByTaskId(int taskId,
                                       boolean notifyListeners)

Removes a specific queued script by its task ID

Parameters:

notifyListeners - If true will notify invocation listeners of script cancellation

cancelAllQueuedInteractiveScripts

public void cancelAllQueuedInteractiveScripts()

Clears all interactive scripts queued

cancelAllQueuedNonInteractiveScripts

public void cancelAllQueuedNonInteractiveScripts()

Clears all non-interactive scripts queued

cancelAllQueuedInteractiveScripts

public void cancelAllQueuedInteractiveScripts(boolean notifyListeners)

Clears all interactive scripts queued

Parameters:

notifyListeners - If true will send the scriptSkipped event any listener associated with a cancelled invoke

cancelAllQueuedNonInteractiveScripts

public void cancelAllQueuedNonInteractiveScripts(boolean notifyListeners)

Clears all non-interactive scripts queued

Parameters:

notifyListeners - If true will send the scriptSkipped event any listener associated with a cancelled invoke

skipOrCancelScript

public void skipOrCancelScript(int scriptId)

Cancels a queued script or skips it if it is currently running

Parameters:

scriptId - The script ID

skipOrCancelScriptByTaskId

public void skipOrCancelScriptByTaskId(int taskId)

Cancels a specific invocation of a script by its task ID, or skips it if it is currently running

Parameters:

taskId - The task ID

compileScript

public int compileScript(java.lang.String filepath,
                         java.lang.String scriptContent)
                  throws InsufficientCompilersException

Compiles a script for execution. Note it is best to call this sequentially before any script executions to avoid throwing a InsufficientCompilersException. Note: If the filepath has already been compiled, the script will not be compiled and the previous compilation is used.

Parameters:

filepath - The filepath to store for the script

scriptContent - The text contents of the script

Returns:

The unique id for the script

Throws:

InsufficientCompilersException - Thrown if there are no script compilers available

InsufficientCompilersException - Thrown if there are no script compilers available

compileScript

public int compileScript(java.lang.String scriptContent)
                  throws InsufficientCompilersException

Compiles a script for execution. Note it is best to call this sequentially before any script executions to avoid throwing a InsufficientCompilersException.

Parameters:

scriptContent - The text contents of the script

Returns:

The unique id for the script

Throws:

InsufficientCompilersException - Thrown if there are no script compilers available

InsufficientCompilersException - Thrown if there are no script compilers available

getCompiledScriptId

public int getCompiledScriptId(java.lang.String filepath)

Returns the script ID for a given filepath

Parameters:

filepath - The filepath to lookup

Returns:

-1 if the script has not been compiled

compileScript

public int compileScript(java.lang.String filepath,
                         java.io.InputStream inputStream)
                  throws InsufficientCompilersException,
                         java.io.IOException

Compiles a script for execution. Note it is best to call this sequentially before any script executions to avoid throwing a InsufficientCompilersException

Parameters:

inputStream - The InputStream to read the script contents from

Returns:

The unique id for the script

Throws:

InsufficientCompilersException - Thrown if there are no script compilers available

java.io.IOException - Throw if the InputStream could not be read or closed

invokeCompiledScript

public int invokeCompiledScript(int scriptId,
                                ScriptBindings scriptBindings)

Queues a compiled script for execution in the engine's thread pool

Parameters:

scriptId - The id of the script to run

scriptBindings - The variable bindings for the script

Returns:

The unique task ID for this invocation

invokeCompiledScript

public int invokeCompiledScript(int scriptId,
                                ScriptBindings scriptBindings,
                                ScriptInvocationListener invocationListener)

Queues a compiled script for execution in the engine's thread pool

Parameters:

scriptId - The id of the script to run

scriptBindings - The variable bindings for the script

invocationListener - A ScriptInvocationListener to list for invocation results

Returns:

The unique task ID for this invocation

invokeCompiledScript

public int invokeCompiledScript(int scriptId,
                                ScriptBindings scriptBindings,
                                ScriptInvocationListener invocationListener,
                                int priority)

Queues a compiled script for execution in the engine's thread pool

Parameters:

scriptId - The id of the script to run

scriptBindings - The variable bindings for the script

invocationListener - A ScriptInvocationListener to list for invocation results

priority - The script execution priority (higher value = higher priority)

Returns:

The unique task ID for this invocation

invokeCompiledScript

public int invokeCompiledScript(int scriptId,
                                ScriptBindings scriptBindings,
                                ScriptInvocationListener invocationListener,
                                int priority,
                                boolean interactive)

Queues a compiled script for execution in the engine's thread pool

Parameters:

scriptId - The id of the script to run

scriptBindings - The variable bindings for the script

invocationListener - A ScriptInvocationListener to list for invocation results

priority - The script execution priority (higher value = higher priority)

Returns:

The unique task ID for this invocation

invokeScript

public int invokeScript(java.lang.String scriptContent,
                        ScriptBindings scriptBindings)
                 throws InsufficientCompilersException

Compiles and queues a script for execution in the engine's thread pool

Parameters:

scriptContent - The text content of the script

scriptBindings - The variable bindings for the script

Returns:

The unique id for the script

Throws:

InsufficientCompilersException - Thrown if there are no script compilers available

invokeScript

public int invokeScript(java.lang.String scriptContent,
                        ScriptBindings scriptBindings,
                        ScriptInvocationListener invocationListener)
                 throws InsufficientCompilersException

Compiles and queues a script for execution in the engine's thread pool

Parameters:

scriptContent - The text content of the script

scriptBindings - The variable bindings for the script

invocationListener - A ScriptInvocationListener to list for invocation results

Returns:

The unique id for the script

Throws:

InsufficientCompilersException - Thrown if there are no script compilers available

invokeScript

public int invokeScript(java.lang.String scriptContent,
                        ScriptBindings scriptBindings,
                        ScriptInvocationListener invocationListener,
                        int priority)
                 throws InsufficientCompilersException

Compiles and queues a script for execution in the engine's thread pool

Parameters:

scriptContent - The text content of the script

scriptBindings - The variable bindings for the script

invocationListener - A ScriptInvocationListener to list for invocation results

priority - The script execution priority (higher value = higher priority)

Returns:

The unique id for the script

Throws:

InsufficientCompilersException - Thrown if there are no script compilers available

invokeCompiledScriptSync

public void invokeCompiledScriptSync(int taskId,
                                     int scriptId,
                                     ScriptBindings scriptBindings)

Executes a compiled script synchronously on the thread calling this method. Warning: If no ScriptExecutors are available this will block until one is available

Parameters:

taskId - The task id

scriptId - The script id

scriptBindings - The variable bindings for the script

invokeCompiledScriptSync

public void invokeCompiledScriptSync(int taskId,
                                     int scriptId,
                                     ScriptBindings scriptBindings,
                                     ScriptInvocationListener invocationListener)

Executes a compiled script synchronously on the thread calling this method. Warning: If no ScriptExecutors are available this will block until one is available

Parameters:

taskId - The task id

scriptId - The script id

scriptBindings - The variable bindings for the script

invocationListener - A ScriptInvocationListener to list for invocation results

getRunningScripts

public java.util.List<java.lang.String> getRunningScripts()

Returns the list of currently running scripts. Note: This list reference is re-used on every invocation of this method

Returns:

An empty list if nothing running

getTotalScriptsQueued

public int getTotalScriptsQueued()

Returns the total scripts (interactive + non-interactive) queued

Returns:

0 if none

getTotalInteractiveScriptsQueued

public int getTotalInteractiveScriptsQueued()

Returns the total interactive scripts queued

Returns:

0 if none

getTotalNonInteractiveScriptsQueued

public int getTotalNonInteractiveScriptsQueued()

Returns the total non-interactive scripts queued

Returns:

0 if none

isInteractiveScriptRunning

public boolean isInteractiveScriptRunning()

Returns true if interactive script is running

Returns:

setCancelReallocatedFutures

public void setCancelReallocatedFutures(boolean cancelReallocatedFutures)

Sets if newly GameFutures should cancel a previously scheduled GameFuture with the same ID. IDs attempt be unique but if there are GameFutures that never complete IDs may come into conflict after millions of generated GameFutures. Defaults to true.

Parameters:

cancelReallocatedFutures - True if existing GameFutures with same ID should be cancelled