HScript

Kind	class
Package	psychlua
Full name	psychlua.HScript
Source	source/psychlua/HScript.hx

Haxe/HScript host (CodenameCrew hscript-improved), in two flavours:

• Embedded — one interpreter lazily created per Lua script so Lua mods can escape into Haxe through runHaxeCode / runHaxeFunction / addHaxeLibrary (see implement()). parentLua is the owning script.
• Standalone — a first-class mod script loaded straight from a .hx or .hscript file, with no Lua parent. It mirrors FunkinLua / PythonScript: the engine discovers it in the usual script folders, registers it in PlayState.hscriptArray, runs its top-level code, then dispatches the same lifecycle hooks (onCreate, onBeatHit, ...) and control-flow sentinels (Function_Stop, ...).

Each instance owns its own Interp, so top-level variables and functions are private to that script. Scripts share state explicitly through game (the PlayState), PlayState.instance.variables (setVar/getVar) or the inter-script calls seeded by seedScriptApi().

Not to be confused with psychlua.HaxeScript, the separate host for data/states/<Name>.hx scripted states/substates (psychlua.StateScripts).

Public fields

Name	Type	Static	Default	Notes
Function_Stop	Dynamic	yes	"##PSYCHLUA_FUNCTIONSTOP"	Sentinel values are intentionally the SAME strings as FunkinLua's so the existing ret != FunkinLua.Function_Stop checks keep working for HScript.
Function_Continue	Dynamic	yes	"##PSYCHLUA_FUNCTIONCONTINUE"	—
Function_StopLua	Dynamic	yes	"##PSYCHLUA_FUNCTIONSTOPLUA"	—
Function_StopAll	Dynamic	yes	"##PSYCHLUA_FUNCTIONSTOPLUA"	—
parser	Parser	yes	new Parser()	—
interp	Interp	no	—	—
variables	Map<String, Dynamic>	no	—	property (get, never)
parentLua	FunkinLua	no	—	#if LUA_ALLOWED · Owning Lua script in embedded mode; always null for standalone mods.
scriptName	String	no	''	Resolved file path for standalone scripts; the Lua parent's path when embedded.
modFolder	String	no	null	—
closed	Bool	no	false	—
standalone	Bool	no	false	true when this interpreter was loaded from its own .hx/.hscript file.
lastCalledFunction	String	no	''	—
lastCalledScript	HScript	yes	null	—
sandboxed	Bool	no	false	Runtime half of the softmod sandbox; standalone scripts only (embedded mode delegates to the Lua parent).
securityModName	String	no	null	—
securityAllowlist	Array<String>	no	[]	—
customFunctions	Map<String, Dynamic>	yes	[]	—
registeredFunctions	Map<String, Dynamic>	yes	[]	—

Public methods

get_variables

function get_variables()

View source

isHScriptFile

static function isHScriptFile(file:String):Bool

Whether file names a standalone HScript mod file (extension check is case-insensitive).

Parameter	Type	Default
file	String	—

View source

scriptBaseName

static function scriptBaseName(file:String):String

Logical script name used to deduplicate discovery: scripts/hud.hx and scripts/hud.hscript are the same script, so a higher-priority folder (or a .hx in the same folder) shadows the other spelling.

Parameter	Type	Default
file	String	—

View source

registerFunction

static function registerFunction(name:String, func:Dynamic):Void

Parameter	Type	Default
name	String	—
func	Dynamic	—

View source

fromFile

static function fromFile(scriptName:String, ?scriptCode:String):HScript

Load a standalone script from scriptName (a resolved path, or a Paths-relative key) without any Lua parent.

Parameter	Type	Default
scriptName	String	—
scriptCode (optional)	String	—

View source

new (constructor)

function new(parent:#if LUA_ALLOWED FunkinLua #else Dynamic #end, ?scriptName:String, ?scriptCode:String)

@param parent owning Lua script for embedded mode, or null together with scriptName to load a standalone .hx/.hscript mod file.

Parameter	Type	Default
parent	#if LUA_ALLOWED FunkinLua #else Dynamic #end	—
scriptName (optional)	String	—
scriptCode (optional)	String	—

View source

initHaxeModule

static function initHaxeModule(parent:FunkinLua)

Only compiled when #if LUA_ALLOWED.

Parameter	Type	Default
parent	FunkinLua	—

View source

addLibrary

function addLibrary(libName:String, libPackage:String = ''):Bool

Bring a host class into this script's scope under its short name. Returns whether a class was resolved; sandboxed scripts are refused privileged classes (see backend.ModSecurity).

Parameter	Type	Default
libName	String	—
libPackage (optional)	String	''

View source

call

function call(func:String, args:Array<Dynamic>):Dynamic

Call a function defined by the script (engine hooks land here).

Parameter	Type	Default
func	String	—
args	Array<Dynamic>	—

View source

set

function set(variable:String, data:Dynamic)

Write a global into the script's scope (engine state, callbacks, ...).

Parameter	Type	Default
variable	String	—
data	Dynamic	—

View source

get

function get(variable:String):Dynamic

Read a global back out of the script's scope, or null when unset.

Parameter	Type	Default
variable	String	—

View source

addLocalCallback

function addLocalCallback(name:String, myFunction:Dynamic)

Parameter	Type	Default
name	String	—
myFunction	Dynamic	—

View source

stop

function stop()

View source

hxTrace

function hxTrace(text:String, ignoreCheck:Bool = false, deprecated:Bool = false, color:FlxColor = FlxColor.WHITE)

Script-visible logging. Embedded mode forwards to the Lua parent's trace channel ( honouring luaDebugMode there); standalone mode writes to the PlayState debug text, gated by hscriptDebugMode exactly like luaTrace/pyTrace.

Parameter	Type	Default
text	String	—
ignoreCheck (optional)	Bool	false
deprecated (optional)	Bool	false
color (optional)	FlxColor	FlxColor.WHITE

View source

allowsSecurityRule

function allowsSecurityRule(rule:String):Bool

Parameter	Type	Default
rule	String	—

View source

allowClassAccess

function allowClassAccess(className:String):Bool

Parameter	Type	Default
className	String	—

View source

reportSecurityRuntime

function reportSecurityRuntime(capability:String, line:Int = 0):String

Log a runtime guard failure to both the mod console and process log.

Parameter	Type	Default
capability	String	—
line (optional)	Int	0

View source

reportSecurityFinding

function reportSecurityFinding(context:String, finding:ScriptSecurityFinding):Void

Parameter	Type	Default
context	String	—
finding	ScriptSecurityFinding	—

View source

execute

function execute(codeToRun:String, funcToRun:String = null, ?funcArgs:Array<Dynamic>):Dynamic

Only compiled when #if HSCRIPT_ALLOWED.

Parameter	Type	Default
codeToRun	String	—
funcToRun (optional)	String	null
funcArgs (optional)	Array<Dynamic>	—

View source

executeFunction

function executeFunction(funcToRun:String = null, funcArgs:Array<Dynamic>)

Only compiled when #if HSCRIPT_ALLOWED.

Parameter	Type	Default
funcToRun (optional)	String	null
funcArgs	Array<Dynamic>	—

View source

implement

static function implement(funk:FunkinLua)

Only compiled when #if LUA_ALLOWED.

Parameter	Type	Default
funk	FunkinLua	—

View source

Internals

Private / internal members

Field	Type	Static
_parsedCache	Map<String, Expr>	no
_missingCalls	Map<String, Bool>	no

Method
function loadStandalone(scriptName:String, ?scriptCode:String)
static function preprocessHScriptCode(code:String):String
function seedInitialGlobals()
function seedScriptApi()
function getRunningScriptNames():Array<String>
function seedScope()
function resolveScriptVar(name:String):Dynamic
function getBoolVar(variable:String):Bool
function effectiveSandboxed():Bool
function effectiveAllowlist():Array<String>