Engine

Engine

ScriptEngine is the central object. It holds the global variable environment, the native function registry, and all runtime state.

Creating an engine

using DScript;
using DScript.Extras;

var engine = new ScriptEngine();

// Register the DScript.Extras standard library (optional but recommended)
new EngineFunctionLoader().RegisterFunctions(engine);

To restrict system access, pass an EnginePermissions value — see Permissions.

new EngineFunctionLoader().RegisterFunctions(engine, EnginePermissions.FileSystem);

Running code

Execute

engine.Execute("var x = 6 * 7;");

Execute compiles and runs the code in one step. ScriptException and JITException are caught internally and written to Console.Error; all other exceptions propagate. Use Run when you want exceptions to propagate.

Run

try
{
    engine.Run(ScriptEngine.Compile("var x = undeclaredFn();"));
}
catch (JITException ex)
{
    Console.Error.WriteLine(ex.ToString()); // includes script stack trace
}

Compile once, run many times

ScriptEngine.Compile is a static method — the resulting Chunk is engine-independent and can be shared or cached.

var program = ScriptEngine.Compile("var answer = 6 * 7;");

engine.Run(program); // fast — no re-parsing

EvalComplex

Evaluate a single expression and return its value as a ScriptVarLink.

var link = engine.EvalComplex("2 + 2");
Console.WriteLine(link.Var.Int); // 4

Reading variables

After execution, global variables are accessible via engine.Root:

engine.Execute("var name = 'Alice'; var age = 30;");

string name = engine.Root.GetParameter("name").String; // "Alice"
int    age  = engine.Root.GetParameter("age").Int;     // 30

GetParameter returns a ScriptVar. Use .Int, .String, .Double, .Bool, or .IsUndefined / .IsNull to read its value.

Calling script functions from C#

engine.Execute("function square(n) { return n * n; }");

var fn     = engine.Root.GetParameter("square");
var result = engine.CallFunction(fn, null, new ScriptVar(9));

Console.WriteLine(result.Int); // 81

CallFunction(fn, thisArg, params...) accepts any number of ScriptVar arguments. Pass null for thisArg to use the global scope.

Registering native functions

engine.AddNative("function add(a, b)", (scope, userData) =>
{
    int a = scope.GetParameter("a").Int;
    int b = scope.GetParameter("b").Int;
    scope.ReturnVar.Int = a + b;
}, null);

engine.Execute("console.log(add(3, 4));"); // 7

The first argument is a function signature string — the parameter names declared here are how values are retrieved inside the callback. userData is the third argument passed to AddNative and is forwarded to every invocation.

State serialisation

Save all script-side variables to a byte array and restore them later on a fresh engine (natives must be re-registered first):

engine.Execute("var counter = 42;");
byte[] snapshot = engine.SerializeState();

var engine2 = new ScriptEngine();
new EngineFunctionLoader().RegisterFunctions(engine2);
engine2.DeserializeState(snapshot);

Console.WriteLine(engine2.Root.GetParameter("counter").Int); // 42

Module loader

Supply a callback to resolve require() and import paths:

engine.ModuleLoader = (path, fromPath) =>
    File.ReadAllText(Path.Combine(baseDir, path + ".ds"));

See Modules for the full module system.

ScriptVar

ScriptVar represents any DScript value — number, string, boolean, object, array, function, null, or undefined.

Member	Description
new ScriptVar(int)	Create an integer value
new ScriptVar(double)	Create a floating-point value
new ScriptVar(string)	Create a string value
new ScriptVar(bool)	Create a boolean value
new ScriptVar(ScriptVar.Flags.Null)	Create a null value
new ScriptVar(ScriptVar.Flags.Undefined)	Create undefined
.Int	Read/write as integer
.Double	Read/write as double
.String	Read/write as string
.Bool	Read as boolean (non-zero / non-empty)
.IsNull	True if the value is null
.IsUndefined	True if the value is undefined
.IsArray	True if the value is an array
.IsFunction	True if the value is a function
.GetArrayLength()	Number of array elements
.GetArrayIndex(i)	Get element at index i
.SetArrayIndex(i, val)	Set element at index i
.FindChild(name)	Find a named property (returns ScriptVarLink?)
.AddChild(name, val)	Add a named property
.GetParsableString()	Stringify the value (for display)
.SetData(obj) / .GetData()	Attach/retrieve a native CLR object

Exceptions

Type	When thrown
JITException	Runtime error in script code (carries .ScriptStackTrace)
ScriptException	Explicit throw in script, or native code calling throw new ScriptException(msg)
ScriptTimeoutException	Wall-clock or instruction limit exceeded — cannot be caught by script try/catch
PermissionException	Script attempted an operation denied by EnginePermissions