SuperlativeScript is an easy to use Haxe script tool that aims to be simple while supporting all Haxe structures. It aims to be like native Haxe while staying easy to use.

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

haxelib install SScript

Enter this command in command prompt to get the latest release from Haxe library.

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

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

<haxelib name="SScript"/>

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

-lib SScript

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

var script:tea.SScript = {}; // Create a new SuperlativeScript class
script.doString("
	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

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

With SuperlativeScript 17.0.618; a new mode is added to as an alternative to Haxe, 3LLua. 3LLua is basically Lua with Haxe features. It can handle, create and access Haxe objects. However, it is not the top priority and because of this it is disabled by default and cannot be used if not enabled.

To enable, add THREELLUA to defines or if you have an OpenFL project add it to project.xml.

You can force interpreter to use a mode, with @force at the start of your scripts. For example, to force 3LLua mode you can use @force(threellua) at the start of your scripts (To force haxe, use @force(haxe). Anything other than haxe and threellua will be ignored). Interpreter will detect and force the provided mode, and your scripts won't be affected and interpreter will be slightly faster.

3LLua is not meant to replace Lua, as it is extremely limited compared to its parent. Lua scripts will not work with this mode, as it only exists if you want to use a language similar to Lua with Haxe features.

Example:

class Main {
	static function main() 
	{
		var s = new tea.SScript();
		tea.SScript.global3llVariables['Main'] = Main;

		s.doString("
			function a(b) 
				if b > 1 then
					print(b + 1);
				else 
					print(b)
				end
			end

			a(2); -- 3
		");
	}
}

With SuperlativeScript 10.0.618, classes are supported in teas and can be accessed from other teas.

Example:

class Main {
	static function main()
	{
		var script = new tea.SScript();
		script.doString("
				class ScriptClass {
					public static function returnMinus(e:Int) {
						return -e;
					}
				}
		");

		var scriptTwo = new tea.SScript();
		script.doString("
			trace(ScriptClass.returnMinus(1)); // -1
		");
	}
}

Teas with class(es) should be initialized first to be accessible to other teas. If a Tea Class is tried to be accessed without it being initialized, it will throw an exception.

Extending is not supported, so it is not possible to create a real class from a Tea Class. Only static variables and functions are allowed in Tea Classes.

If a tea contains a class, it cannot have any other expressions other than classes, imports, package and enum abstracts. For example, this script is not valid.

class ScriptClass {

}	
trace(1); // Exception: Unexpected trace

With 11.0.618, enum abstracts are supported in teas and can be accessed from other teas.

Example:

enum abstract EnumAbstract(Int) from Int to Int {
	public var One = 1;
	public var Two; // Omitted and deduced by the interpreter, so the value is 2
}

Just like classes, if a tea contains enum abstract the other expressions cannot be other than classes, imports, package and enum abstracts.

from and to are parsed but ignored completely by the interpreter.

Function arguments have been reworked, so optional arguments will work like native Haxe.

Example:

function add(a:Int, ?b:Int = 1) 
{
	return a + b;
}
trace(add()); // Exception: Invalid number of parameters. Got 0, required 1 for function 'add'
trace(add(0)) // 1 
trace(add(0, 2)) // 2

Initialization order is this:

• Package
• Imports
• Classes
• Functions and variables (if there are no classes)
• Other (if there are no classes)

This means you can use functions after creating a variable, for example:

trace(a);
var a = 1;

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

import tea.SScript;
class Main 
{
	static function main()
	{
		var script:SScript = {};
		script.doString("
			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
		");
	}
}

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

class SScriptEx extends tea.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.

You can call methods and receive their return value from Tea's 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 Tea.

Example:

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

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

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

With SuperlativeScript, you can set variables to all running Tea's. Example:

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

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

Variables from globalVariables can be changed in script. If you do not want this, use strictGlobalVariables instead. They will act as a final and cannot be changed in script.

Special object is an object that'll get checked if a variable is not found in a Tea. 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 tea.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.doString("sprite.visible = false;");
	}
}