SScript

SScript is an easy to use Haxe script tool that aims to be simple while supporting all Haxe structures.

Contribution

If you have an issue with SScript or have a suggestion, you can always open an issue here. However, pull requests are NOT welcome and will be ignored.

Installation

haxelib git SScript https://github.com/ShadowEngineTeam/SScript.git

Enter this command in command prompt to get the latest git release from Github. Git releases have the latest features but they are unstable and can cause problems.

After installing SScript, don't forget to add it to your Haxe project.

---

OpenFL projects

Add this to Project.xml to add SScript to your OpenFL project:

<haxelib name="SScript"/>

Haxe Projects

Add this to build.hxml to add SScript to your Haxe build.

-lib SScript

Usage

To use SScript, you will need a file or a script. Using a file is recommended.

Using without a file

var script:hscript.SScript = {}; // Create a new SScript class
script.doScript("
	function returnRandom():Float
		return Math.random() * 100;
"); // Implement the script
var call = script.call('returnRandom');
var randomNumber:Float = call.returnValue; // Access the returned value with returnValue

Using with a file

var script:hscript.SScript = new hscript.SScript("script.hx"); // Has the same contents with the script above
var randomNumber:Float = script.call('returnRandom').returnValue;

Using Haxe 4.3.0 Syntaxes

SScript supports both ?. and ?? syntaxes including ??=.

import hscript.SScript;
class Main 
{
	static function main()
	{
		var script:SScript = {};
		script.doScript("
			var string:String = null;
			trace(string.length); // Throws an error
			trace(string?.length); // Doesn't throw an error and returns null
			trace(string ?? 'ss'); // Returns 'ss';
			trace(string ??= 'ss'); // Returns 'ss' and assigns it to `string` variable
		");
	}
}

Extending SScript

You can create a class extending SScript to customize it better.

class SScriptEx extends hscript.SScript
{  
	override function preset():Void
	{
		super.preset();
		
		// Only use 'set', 'setClass' or 'setClassString' in preset
		// Macro classes are not allowed to be set
		setClass(StringTools);
		set('NaN', Math.NaN);
		setClassString('sys.io.File');
	}
}

Extend other functions only if you know what you're doing.

Calling Methods from Scripts

You can call methods and receive their return value from Scripts using call function. It needs one obligatory argument (function name) and one optional argument (function arguments array).

using call will return a structure that contains the return value, if calling has been successful, exceptions if it did not, called function name and script file name of the Script.

Example:

var script:hscript.SScript = {};
script.doScript('
	function method()
	{
		return 2 + 2;
	}
');
var call = script.call('method');
trace(call.returnValue); // 4

script.doScript('
	function method()
	{
		var num:Int = 1.1;
		return num;
	}
')

var call = script.call('method');
trace(call.returnValue, call.exceptions[0]); // null, Float should be Int

Global Variables

With SScript, you can set variables to all running Scripts. Example:

var script:hscript.SScript = {};
script.set('variable', 1);
script.doScript('
	function returnVar()
	{
		return variable + variable2;
	}
');

hscript.SScript.globalVariables.set('variable2', 2);
trace(script.call('returnVar').returnValue); // 3

Special Object

Special object is an object that'll get checked if a variable is not found in a Script. A special object cannot be a basic type like Int, Float, String, Array and Bool.

Special objects are useful for OpenFL and Flixel states.

Example:

import hscript.SScript;

class PlayState extends flixel.FlxState 
{
	var sprite:flixel.FlxSprite;
	override function create()
	{
		sprite = new flixel.FlxSprite();

		var newScript:SScript = new SScript();
		newScript.setSpecialObject(this);
		newScript.doScript("sprite.visible = false;");
	}
}