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 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 the amount of processors + 1.
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(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.

Method Summary

Modifier and Type	Method and Description
int	compileScript(java.io.InputStream inputStream) Compiles a script for execution.
int	compileScript(java.lang.String scriptContent) Compiles a script for execution.
protected abstract ScriptExecutorPool<?>	createScriptExecutorPool(int poolSize, boolean sandboxing)
void	dispose() Shuts down the thread pool and cleans up resources
void	invokeCompiledScript(int scriptId, ScriptBindings scriptBindings) Queues a compiled script for execution in the engine's thread pool
void	invokeCompiledScript(int scriptId, ScriptBindings scriptBindings, ScriptInvocationListener invocationListener) Queues a compiled script for execution in the engine's thread pool
void	invokeCompiledScriptLocally(int scriptId, ScriptBindings scriptBindings) Executes a compiled script immediately on the thread calling this method.
void	invokeCompiledScriptLocally(int scriptId, ScriptBindings scriptBindings, ScriptInvocationListener invocationListener) Executes a compiled script immediately 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
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	skipAllGameFutures() Skips all currently running GameFutures
void	skipAllScripts() Skips all currently running scripts
void	skipScript(int scriptId) Skips a currently running 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

Constructor Detail

GameScriptingEngine

public GameScriptingEngine()

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

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(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(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

Method Detail

dispose

public void dispose()

Shuts down the thread pool and cleans up resources

isSandboxingSupported

public abstract boolean isSandboxingSupported()

Checks if sandboxing is supported by the GameScriptingEngine implementation

Returns:

True if sandboxing is supported

createScriptExecutorPool

protected abstract ScriptExecutorPool<?> createScriptExecutorPool(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 a currently running script

Parameters:

scriptId - The ID of the script to skip

skipAllGameFutures

public void skipAllGameFutures()

Skips all currently running GameFutures

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

compileScript

public int compileScript(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 void 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

invokeCompiledScript

public void 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

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

invokeCompiledScriptLocally

public void invokeCompiledScriptLocally(int scriptId,
                                        ScriptBindings scriptBindings)

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

Parameters:

scriptId - The script id

scriptBindings - The variable bindings for the script

invokeCompiledScriptLocally

public void invokeCompiledScriptLocally(int scriptId,
                                        ScriptBindings scriptBindings,
                                        ScriptInvocationListener invocationListener)

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

Parameters:

scriptId - The script id

scriptBindings - The variable bindings for the script

invocationListener - A ScriptInvocationListener to list for invocation results

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