ScriptEngine.cpp

Go to the documentation of this file.

/*
    This source file is part of Rigs of Rods
    Copyright 2005-2012 Pierre-Michel Ricordel
    Copyright 2007-2012 Thomas Fischer
    Copyright 2013-2020 Petr Ohlidal
 
    For more information, see http://www.rigsofrods.org/
 
    Rigs of Rods is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License version 3, as
    published by the Free Software Foundation.
 
    Rigs of Rods is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    GNU General Public License for more details.
 
    You should have received a copy of the GNU General Public License
    along with Rigs of Rods. If not, see <http://www.gnu.org/licenses/>.
*/
 
 
#include "ScriptEngine.h"
 
// AS addons start
#include "scriptstdstring/scriptstdstring.h"
#include "scriptmath/scriptmath.h"
#include "scriptany/scriptany.h"
#include "scriptarray/scriptarray.h"
#include "scripthelper/scripthelper.h"
// AS addons end
 
#ifdef USE_CURL
#include <stdio.h>
#include <curl/curl.h>
//#include <curl/types.h>
#include <curl/easy.h>
#endif //USE_CURL
 
#include <cfloat>
 
#include "Application.h"
#include "Actor.h"
#include "ActorManager.h"
#include "Collisions.h"
#include "Console.h"
#include "GameContext.h"
#include "GameScript.h"
#include "LocalStorage.h"
#include "OgreScriptBuilder.h"
#include "PlatformUtils.h"
#include "ScriptEvents.h"
#include "ScriptUtils.h"
#include "Utils.h"
#include "VehicleAI.h"
 
#include "InputEngine.h"
 
using namespace Ogre;
using namespace RoR;
using namespace AngelScript;
 
const char* RoR::ScriptCategoryToString(ScriptCategory c)
{
    switch (c)
    {
    case ScriptCategory::INVALID: return "INVALID";
    case ScriptCategory::ACTOR: return "ACTOR";
    case ScriptCategory::TERRAIN: return "TERRAIN";
    case ScriptCategory::CUSTOM: return "CUSTOM";
    default: return "";
    }
}
 
ScriptUnit::ScriptUnit()
{
    // Constructs `ActorPtr` - doesn't compile without `#include Actor.h` - not pretty if in header (even if auto-generated by C++).
}
 
ScriptUnit::~ScriptUnit()
{
    // Destructs `ActorPtr` - doesn't compile without `#include Actor.h` - not pretty if in header (even if auto-generated by C++).
}
 
// some hacky functions
 
void logString(const std::string &str)
{
    App::GetScriptEngine()->SLOG(str);
}
 
// the class implementation
 
ScriptEngine::ScriptEngine() :
     context(0)
    , engine(0)
    , scriptLog(0)
{
    scriptLog = LogManager::getSingleton().createLog(PathCombine(App::sys_logs_dir->getStr(), "Angelscript.log"), false);
    this->init();
}
 
ScriptEngine::~ScriptEngine()
{
    // Clean up
    if (engine)  engine->Release();
    if (context) context->Release();
}
 
void ScriptEngine::messageLogged( const String& message, LogMessageLevel lml, bool maskDebug, const String &logName, bool& skipThisMessage)
{
    RoR::App::GetConsole()->forwardLogMessage(Console::CONSOLE_MSGTYPE_SCRIPT, message, lml);
}
 
// continue with initializing everything
void ScriptEngine::init()
{
    SLOG("ScriptEngine initializing ...");
    int result;
 
    // Create the script engine
    engine = AngelScript::asCreateScriptEngine(ANGELSCRIPT_VERSION);
 
    engine->SetEngineProperty(AngelScript::asEP_ALLOW_UNSAFE_REFERENCES, true); // Needed for ImGui
 
    // Set the message callback to receive information on errors in human readable form.
    // It's recommended to do this right after the creation of the engine, because if
    // some registration fails the engine may send valuable information to the message
    // stream.
    result = engine->SetMessageCallback(AngelScript::asMETHOD(ScriptEngine,msgCallback), this, AngelScript::asCALL_THISCALL);
    if (result < 0)
    {
        if (result == AngelScript::asINVALID_ARG)
        {
            SLOG("One of the arguments is incorrect, e.g. obj is null for a class method.");
            return;
        }
        else if (result == AngelScript::asNOT_SUPPORTED)
        {
            SLOG("  The arguments are not supported, e.g. asCALL_GENERIC.");
            return;
        }
        SLOG("Unkown error while setting up message callback");
        return;
    }
 
    // AngelScript doesn't have a built-in string type, as there is no definite standard
    // string type for C++ applications. Every developer is free to register it's own string type.
    // The SDK do however provide a standard add-on for registering a string type, so it's not
    // necessary to register your own string type if you don't want to.
    AngelScript::RegisterScriptArray(engine, true);
    AngelScript::RegisterStdString(engine);
    AngelScript::RegisterStdStringUtils(engine);
    AngelScript::RegisterScriptMath(engine);
    static float SCRIPT_FLT_MAX = FLT_MAX;
    static int SCRIPT_INT_MAX = INT_MAX;
    result = engine->RegisterGlobalProperty("const float FLT_MAX", &SCRIPT_FLT_MAX); ROR_ASSERT( result >= 0 );
    result = engine->RegisterGlobalProperty("const int INT_MAX", &SCRIPT_INT_MAX); ROR_ASSERT(result >= 0);
    AngelScript::RegisterScriptAny(engine);
    AngelScript::RegisterScriptDictionary(engine);
 
    // some useful global functions
    result = engine->RegisterGlobalFunction("void log(const string &in)", AngelScript::asFUNCTION(logString), AngelScript::asCALL_CDECL); ROR_ASSERT( result >= 0 );
    result = engine->RegisterGlobalFunction("void print(const string &in)", AngelScript::asFUNCTION(logString), AngelScript::asCALL_CDECL); ROR_ASSERT( result >= 0 );
 
    RegisterOgreObjects(engine);   // vector2/3, degree, radian, quaternion, color
    RegisterLocalStorage(engine);  // LocalStorage
    RegisterInputEngine(engine);   // InputEngineClass, inputEvents
    RegisterImGuiBindings(engine); // ImGUi::
    RegisterVehicleAi(engine);     // VehicleAIClass, aiEvents, AiValues
    RegisterConsole(engine);       // ConsoleClass, CVarClass, CVarFlags
    RegisterEngine(engine);     // EngineClass, enum autoswitch, enum
    RegisterActor(engine);         // BeamClass
    RegisterProceduralRoad(engine);// procedural_point, ProceduralRoadClass, ProceduralObjectClass, ProceduralManagerClass
    RegisterTerrain(engine);       // TerrainClass
    RegisterMessageQueue(engine);  // enum MsgType
    RegisterSoundScript(engine);   // SoundTriggers, ModulationSource, SoundScriptTemplate...
    RegisterGameScript(engine);    // GameScriptClass
    RegisterScriptEvents(engine);  // scriptEvents
    RegisterGenericFileFormat(engine); // TokenType, GenericDocumentClass, GenericDocReaderClass
    RegisterCacheSystem(engine);   // LoaderType, CacheEntryClass, CacheSystemClass
 
    // now the global instances
    result = engine->RegisterGlobalProperty("GameScriptClass game", &m_game_script); ROR_ASSERT(result>=0);
    result = engine->RegisterGlobalProperty("ConsoleClass console", App::GetConsole()); ROR_ASSERT(result>=0);
    result = engine->RegisterGlobalProperty("InputEngineClass inputs", App::GetInputEngine()); ROR_ASSERT(result>=0);
    result = engine->RegisterGlobalProperty("CacheSystemClass modcache", App::GetCacheSystem()); ROR_ASSERT(result>=0);
 
    SLOG("Type registrations done. If you see no error above everything should be working");
 
    context = engine->CreateContext();
}
 
void ScriptEngine::msgCallback(const AngelScript::asSMessageInfo *msg)
{
    const char *type = "Error";
    if ( msg->type == AngelScript::asMSGTYPE_INFORMATION )
        type = "Info";
    else if ( msg->type == AngelScript::asMSGTYPE_WARNING )
        type = "Warning";
 
    char tmp[1024]="";
    sprintf(tmp, "%s (%d, %d): %s = %s", msg->section, msg->row, msg->col, type, msg->message);
    SLOG(tmp);
 
    TRIGGER_EVENT_ASYNC(SE_ANGELSCRIPT_MSGCALLBACK,
        m_currently_executing_script_unit, msg->type, msg->row, msg->col, // ints
        msg->section, msg->message); // strings
}
 
std::string ptr2str(const char* ptr) { if (ptr) return ptr; else return ""; }
 
void ScriptEngine::lineCallback(AngelScript::asIScriptContext* ctx)
{
    std::string funcName, funcObjTypeName, objName;
    if (ctx->GetFunction())
    {
        funcName = ptr2str(ctx->GetFunction()->GetName());
        objName = ptr2str(ctx->GetFunction()->GetObjectName());
        if (ctx->GetFunction()->GetObjectType())
            funcObjTypeName = ptr2str(ctx->GetFunction()->GetObjectType()->GetName());
    }
    TRIGGER_EVENT_ASYNC(SE_ANGELSCRIPT_LINECALLBACK,
       // ints
        m_currently_executing_script_unit, ctx->GetLineNumber(), ctx->GetCallstackSize(), 0,
       // strings
        funcName, funcObjTypeName, objName
    ); 
}
 
void ScriptEngine::exceptionCallback(AngelScript::asIScriptContext* ctx)
{
    //Disabled, too noisy//this->logExceptionDetails();
    std::string funcName;
    if (ctx->GetExceptionFunction())
    {
        funcName = ptr2str(ctx->GetExceptionFunction()->GetName());
    }
    TRIGGER_EVENT_ASYNC(SE_ANGELSCRIPT_EXCEPTIONCALLBACK,
        m_currently_executing_script_unit, 0, ctx->GetExceptionLineNumber(), 0, // ints
        funcName, ctx->GetExceptionString()); // strings
}
 
void ScriptEngine::forwardExceptionAsScriptEvent(const std::string& from)
{
    // Forwards useful info from C++  exceptions to script in the form of game event.
    // AngelScript doesn't have exceptions in the `try{}catch{}` sense
    // (in AS jargon, 'Exception' means basically 'panic' as in Lua/Rust...)
    // and most exceptions this game encounters (`Ogre::Exception`) are trivially recoverable,
    // so it doesn't make sense to panic AngelScript when they happen.
    // =======================================================================================
 
    try { throw; } // Rethrow
 
    // OGRE
    catch (Ogre::IOException& e                ) { TRIGGER_EVENT_ASYNC(SE_GENERIC_EXCEPTION_CAUGHT, m_currently_executing_script_unit,0,0,0, from, "IOException", e.getDescription());                   }
    catch (Ogre::InvalidStateException& e      ) { TRIGGER_EVENT_ASYNC(SE_GENERIC_EXCEPTION_CAUGHT, m_currently_executing_script_unit,0,0,0, from, "InvalidStateException", e.getDescription());         }
    catch (Ogre::InvalidParametersException& e ) { TRIGGER_EVENT_ASYNC(SE_GENERIC_EXCEPTION_CAUGHT, m_currently_executing_script_unit,0,0,0, from, "InvalidParametersException", e.getDescription());    }
    catch (Ogre::RenderingAPIException& e      ) { TRIGGER_EVENT_ASYNC(SE_GENERIC_EXCEPTION_CAUGHT, m_currently_executing_script_unit,0,0,0, from, "RenderingAPIException", e.getDescription());         }
    catch (Ogre::ItemIdentityException& e      ) { TRIGGER_EVENT_ASYNC(SE_GENERIC_EXCEPTION_CAUGHT, m_currently_executing_script_unit,0,0,0, from, "ItemIdentityException", e.getDescription());         }
    catch (Ogre::FileNotFoundException& e      ) { TRIGGER_EVENT_ASYNC(SE_GENERIC_EXCEPTION_CAUGHT, m_currently_executing_script_unit,0,0,0, from, "FileNotFoundException", e.getDescription());         }
    catch (Ogre::InternalErrorException& e     ) { TRIGGER_EVENT_ASYNC(SE_GENERIC_EXCEPTION_CAUGHT, m_currently_executing_script_unit,0,0,0, from, "InternalErrorException", e.getDescription());        }
    catch (Ogre::RuntimeAssertionException& e  ) { TRIGGER_EVENT_ASYNC(SE_GENERIC_EXCEPTION_CAUGHT, m_currently_executing_script_unit,0,0,0, from, "RuntimeAssertionException", e.getDescription());     }
    catch (Ogre::UnimplementedException& e     ) { TRIGGER_EVENT_ASYNC(SE_GENERIC_EXCEPTION_CAUGHT, m_currently_executing_script_unit,0,0,0, from, "UnimplementedException", e.getDescription());        }
    catch (Ogre::InvalidCallException& e       ) { TRIGGER_EVENT_ASYNC(SE_GENERIC_EXCEPTION_CAUGHT, m_currently_executing_script_unit,0,0,0, from, "InvalidCallException", e.getDescription());          }
    catch (Ogre::Exception& e                  ) { TRIGGER_EVENT_ASYNC(SE_GENERIC_EXCEPTION_CAUGHT, m_currently_executing_script_unit,0,0,0, from, "Exception", e.getDescription());                     }
 
    // STD
    catch (std::exception& e) { TRIGGER_EVENT_ASYNC(SE_GENERIC_EXCEPTION_CAUGHT, m_currently_executing_script_unit,0,0,0, from, "std::exception", e.what()); }
 
    // Unrecognized
    catch (...) { TRIGGER_EVENT_ASYNC(SE_GENERIC_EXCEPTION_CAUGHT, m_currently_executing_script_unit,0,0,0, from); }
}
 
int ScriptEngine::executeContextAndHandleErrors(ScriptUnitID_t nid)
{
    // Helper for executing any script function/snippet;
    // * sets LineCallback (on demand - when script registers for SE_ANGELSCRIPT_LINECALLBACK event)
    // * sets ExceptionCallback (on demand - when script registers for SE_ANGELSCRIPT_EXCEPTIONCALLBACK event)
    // * sets currently executed NID;
    // IMPORTANT: The `asIScriptContext::Prepare()` must be already done (this enables programmer to set args).
    // IMPORTANT: `m_currently_executing_event_trigger` must be set externally!
    // =========================================================================================================
 
    // Automatically attach the LineCallback if the script registered for the event.
    // (except if we're about to run that callback - that would trap us in loop)
    if (m_currently_executing_event_trigger != SE_ANGELSCRIPT_LINECALLBACK
        && m_script_units[nid].eventMask & SE_ANGELSCRIPT_LINECALLBACK)
    {
        int result = context->SetLineCallback(asMETHOD(ScriptEngine, lineCallback), this, asCALL_THISCALL);
        if (result < 0)
        {
            SLOG(fmt::format("Warning: Could not attach LineCallback to NID {}, error code {}; continuing without it...", result, nid));
        }
    }
 
    // Attach the ExceptionCallback if the script registered for the event.
    if (m_script_units[nid].eventMask & SE_ANGELSCRIPT_EXCEPTIONCALLBACK)
    {
        int result = context->SetExceptionCallback(asMETHOD(ScriptEngine, exceptionCallback), this, asCALL_THISCALL);
        if (result < 0)
        {
            SLOG(fmt::format("Warning: Could not attach ExceptionCallback to NID {}, error code {}; continuing without it...", result, nid));
        }
    }
 
    // Run the script
    m_currently_executing_script_unit = nid;
    int result = context->Execute();
    m_currently_executing_script_unit = SCRIPTUNITID_INVALID;
 
    if ( result != AngelScript::asEXECUTION_FINISHED )
    {
        // The execution didn't complete as expected. Determine what happened.
        if ( result == AngelScript::asEXECUTION_ABORTED )
        {
            SLOG("The script was aborted before it could finish. Probably it timed out.");
        }
        else if ( result == AngelScript::asEXECUTION_EXCEPTION )
        {
            // An exception occurred, let the script writer know what happened so it can be corrected.
            // NOTE: this result is only reported if exception callback is not registered, see `SetExceptionCallback()`
            SLOG("The script ended with exception; details below:");
            // Write some information about the script exception
            SLOG("\tcontext.ExceptionLineNumber: " + TOSTRING(context->GetExceptionLineNumber()));
            SLOG("\tcontext.ExceptionString: " + ptr2str(context->GetExceptionString()));
            AngelScript::asIScriptFunction* func = context->GetExceptionFunction();
            if (func)
            {
                SLOG("\tcontext.ExceptionFunction.Declaration: " + ptr2str(func->GetDeclaration()));
                SLOG("\tcontext.ExceptionFunction.ModuleName: " + ptr2str(func->GetModuleName()));
                SLOG("\tcontext.ExceptionFunction.ScriptSectionName: " + ptr2str(func->GetScriptSectionName()));
                SLOG("\tcontext.ExceptionFunction.ObjectName: " + ptr2str(func->GetObjectName()));
            }
        }
        else if (result == AngelScript::asCONTEXT_NOT_PREPARED)
        {
            if (context->GetFunction())
            {
                SLOG(fmt::format("The script ended with error code asCONTEXT_NOT_PREPARED; Function to execute: {},currently triggered event: {}, NID: {}",
                    context->GetFunction()->GetName(), fmt::underlying(m_currently_executing_event_trigger), nid));
            }
            else
            {
                SLOG(fmt::format("The script ended with error code asCONTEXT_NOT_PREPARED; Function to execute NOT SET,currently triggered event: {}, NID: {}",
                    fmt::underlying(m_currently_executing_event_trigger), nid));
            }
        }
        else
        {
            SLOG("The script ended for some unforeseen reason " + TOSTRING(result));
        }
    }
 
    // Clear the callbacks so they don't intercept unrelated operations.
    context->ClearLineCallback();
    context->ClearExceptionCallback();
 
    return result;
}
 
bool ScriptEngine::prepareContextAndHandleErrors(ScriptUnitID_t nid, int asFunctionID)
{
    asIScriptFunction* scriptFunc = this->engine->GetFunctionById(asFunctionID);
    if (!scriptFunc)
    {
        SLOG(fmt::format("Cannot execute script function with ID {} - not found", asFunctionID));
        return false;
    }
 
    int result = this->context->Prepare(scriptFunc);
    if (result < 0)
    {
        SLOG(fmt::format("Cannot execute script function '{}': `AngelScript::Context::Prepare()` reported error code {}",
            scriptFunc->GetName(), result));
        return false;
    }
 
    return true;
}
 
ScriptRetCode_t ScriptEngine::validateScriptModule(ScriptUnitID_t nid, asIScriptModule*& out_mod)
{
    if (!engine)
        return SCRIPTRETCODE_ENGINE_NOT_CREATED;
 
    if (!context)
        return SCRIPTRETCODE_CONTEXT_NOT_CREATED;
 
    if (!this->scriptUnitExists(nid))
        return SCRIPTRETCODE_SCRIPTUNIT_NOT_EXISTS;
 
    out_mod = this->getScriptUnit(nid).scriptModule;
    if (!out_mod)
        return SCRIPTRETCODE_SCRIPTUNIT_NO_MODULE;
 
    return SCRIPTRETCODE_SUCCESS;
}
 
void ScriptEngine::framestep(Real dt)
{
    // Check if we need to execute any strings
    std::vector<String> tmpQueue;
    stringExecutionQueue.pull(tmpQueue);
    std::vector<String>::iterator it;
    for (it=tmpQueue.begin(); it!=tmpQueue.end();it++)
    {
        executeString(*it);
    }
 
    // framestep stuff below
    if (!engine || !context) return;
 
    for (auto& pair: m_script_units)
    {
        ScriptUnitID_t nid = pair.first;
        if (m_script_units[nid].frameStepFunctionPtr)
        {
            // Set the function pointer and arguments
            context->Prepare(m_script_units[nid].frameStepFunctionPtr);
            context->SetArgFloat(0, dt);
 
            // Run the context via helper
            this->executeContextAndHandleErrors(nid);
        }
    }
}
 
int ScriptEngine::fireEvent(std::string instanceName, float intensity)
{
    if (!engine || !context)
        return 0;
 
    for (auto& pair: m_script_units)
    {
        ScriptUnitID_t id = pair.first;
        AngelScript::asIScriptFunction* func = m_script_units[id].scriptModule->GetFunctionByDecl(
            "void fireEvent(string, float)"); // TODO: this shouldn't be hard coded --neorej16
 
        context->Prepare(func);
 
        // Set the function arguments
        context->SetArgObject(0, &instanceName);
        context->SetArgFloat (1, intensity);
 
        m_currently_executing_script_unit = id;
        int r = context->Execute();
        m_currently_executing_script_unit = SCRIPTUNITID_INVALID;
        if ( r == AngelScript::asEXECUTION_FINISHED )
        {
          // The return value is only valid if the execution finished successfully
            AngelScript::asDWORD ret = context->GetReturnDWord();
        }
    }
 
    return 0;
}
 
void ScriptEngine::envokeCallback(int _functionId, eventsource_t *source, NodeNum_t nodenum, int type)
{
    // THIS IS OBSOLETE - Use `eventCallbackEx()` and `SE_EVENTBOX_ENTER` instead.
    // ################
    // Legacy eventbox handler, specified by name in .TOBJ file or in call to `game.spawnObject()`
    // ===========================================================================================
    if (!engine || !context)
        return;
 
    for (auto& pair: m_script_units)
    {
        ScriptUnitID_t id = pair.first;
        int functionId = _functionId;
        if (functionId <= 0 && (m_script_units[id].defaultEventCallbackFunctionPtr != nullptr))
        {
            // use the default event handler instead then
            functionId = m_script_units[id].defaultEventCallbackFunctionPtr->GetId();
        }
 
        if (this->prepareContextAndHandleErrors(id, functionId))
        {
            // Set the function arguments
            context->SetArgDWord (0, type);
            context->SetArgObject(1, &source->es_instance_name);
            context->SetArgObject(2, &source->es_box_name);
            if (nodenum != NODENUM_INVALID)
                context->SetArgDWord (3, static_cast<AngelScript::asDWORD>(nodenum));
            else
                context->SetArgDWord (3, static_cast<AngelScript::asDWORD>(-1));
 
            this->executeContextAndHandleErrors(id);
        }
    }
}
 
void ScriptEngine::queueStringForExecution(const String command)
{
    stringExecutionQueue.push(command);
}
 
ScriptRetCode_t ScriptEngine::executeString(String command)
{
    int result = 0;
    AngelScript::asIScriptModule* mod = nullptr;
    // Only works with terrain script module (classic behavior)
    result = this->validateScriptModule(m_terrain_script_unit, /*[out]*/ mod);
    if (result == 0)
    {
        result = ExecuteString(engine, command.c_str(), mod, context);
        if (result < 0)
        {
            SLOG(fmt::format("Error {} while executing string `{}`", result, command));
        }
    }
    return result;
}
 
ScriptRetCode_t ScriptEngine::addFunction(const String &arg, const ScriptUnitID_t nid /*= SCRIPTUNITID_DEFAULT*/)
{
    int result = 0;
    AngelScript::asIScriptModule* mod = nullptr;
    result = this->validateScriptModule(nid, /*[out]*/ mod);
    if (result == 0)
    {
        AngelScript::asIScriptFunction* func = nullptr;
        result = mod->CompileFunction("addfunc", arg.c_str(), 0, AngelScript::asCOMP_ADD_TO_MODULE, &func);
        if (result == 0)
        {
            // successfully added function; Check if we added a "special" function
 
            if (func == mod->GetFunctionByDecl("void frameStep(float)"))
            {
                if (m_script_units[m_terrain_script_unit].frameStepFunctionPtr == nullptr)
                    m_script_units[m_terrain_script_unit].frameStepFunctionPtr = func;
            }
            else if (func == mod->GetFunctionByDecl("void eventCallback(int, int)"))
            {
                if (m_script_units[m_terrain_script_unit].eventCallbackFunctionPtr == nullptr)
                    m_script_units[m_terrain_script_unit].eventCallbackFunctionPtr = func;
            }
            else if (func == mod->GetFunctionByDecl("void eventCallbackEx(scriptEvents,   int, int, int, int,   string, string, string, string)"))
            {
                if (m_script_units[m_terrain_script_unit].eventCallbackExFunctionPtr == nullptr)
                    m_script_units[m_terrain_script_unit].eventCallbackExFunctionPtr = func;
            }
            // THIS IS OBSOLETE - Use `eventCallbackEx()` and `SE_EVENTBOX_ENTER` instead. See commentary in `envokeCallback()`
            else if (func == this->getFunctionByDeclAndLogCandidates(
                m_terrain_script_unit, GETFUNCFLAG_OPTIONAL,
                GETFUNC_DEFAULTEVENTCALLBACK_NAME, GETFUNC_DEFAULTEVENTCALLBACK_SIGFMT))
            {
                if (m_script_units[m_terrain_script_unit].defaultEventCallbackFunctionPtr == nullptr)
                    m_script_units[m_terrain_script_unit].defaultEventCallbackFunctionPtr = func;
            }
        }
        else
        {
            SLOG(fmt::format("Error {} adding function `{}` to script module '{}'", result, arg, mod->GetName()));
        }
        // We must release the function object
        if (func)
            func->Release();
    }
 
    return result;
}
 
ScriptRetCode_t ScriptEngine::functionExists(const String& arg, const ScriptUnitID_t nid /*= SCRIPTUNITID_DEFAULT*/)
{
    int result = 0;
    AngelScript::asIScriptModule* mod = nullptr;
    result = this->validateScriptModule(nid, /*[out]*/ mod);
    if (result == 0)
    {
        if (mod->GetFunctionByDecl(arg.c_str()) != nullptr)
            result = SCRIPTRETCODE_FUNCTION_NOT_EXISTS;
    }
    return result;
}
 
ScriptRetCode_t ScriptEngine::deleteFunction(const String &arg, const ScriptUnitID_t nid /*= SCRIPTUNITID_DEFAULT*/)
{
    int result = 0;
    AngelScript::asIScriptModule* mod = nullptr;
    result = this->validateScriptModule(nid, /*[out]*/ mod);
    if (result == 0)
    {
        AngelScript::asIScriptFunction* func = mod->GetFunctionByDecl(arg.c_str());
        if (func != nullptr)
        {
            // Warning: The function is not destroyed immediately, only when no more references point to it.
            result = mod->RemoveFunction(func);
            if (result != 0)
            {
                SLOG(fmt::format("Error {} removing function `{}` from module '{}' - continuing anyway (compatibility).", result, arg, mod->GetName()));
            }
 
            // Since functions can be recursive, we'll call the garbage
            // collector to make sure the object is really freed
            engine->GarbageCollect();
 
            // Check if we removed a "special" function
 
            if (m_script_units[m_terrain_script_unit].frameStepFunctionPtr == func)
                m_script_units[m_terrain_script_unit].frameStepFunctionPtr = nullptr;
 
            if (m_script_units[m_terrain_script_unit].eventCallbackFunctionPtr == func)
                m_script_units[m_terrain_script_unit].eventCallbackFunctionPtr = nullptr;
 
            if (m_script_units[m_terrain_script_unit].eventCallbackExFunctionPtr == func)
                m_script_units[m_terrain_script_unit].eventCallbackExFunctionPtr = nullptr;
 
            if (m_script_units[m_terrain_script_unit].defaultEventCallbackFunctionPtr == func)
                m_script_units[m_terrain_script_unit].defaultEventCallbackFunctionPtr = nullptr;
        }
        else
        {
            SLOG(fmt::format("Could not remove function `{}` from module '{}' - not found.", arg, mod->GetName()));
        }
    }
    return result;
}
 
ScriptRetCode_t ScriptEngine::addVariable(const String &arg, const ScriptUnitID_t nid /*= SCRIPTUNITID_DEFAULT*/)
{
    int result = 0;
    AngelScript::asIScriptModule* mod = nullptr;
    result = this->validateScriptModule(nid, /*[out]*/ mod);
    if (result == 0)
    {
        result = mod->CompileGlobalVar("addvar", arg.c_str(), 0);
        if (result < 0)
        {
            SLOG(fmt::format("Error {} while adding variable `{}` to module '{}'", result, arg, mod->GetName()));
        }
    }
    return result;
}
 
ScriptRetCode_t ScriptEngine::variableExists(const String& arg, const ScriptUnitID_t nid /*= SCRIPTUNITID_DEFAULT*/)
{
    int result = 0;
    AngelScript::asIScriptModule* mod = nullptr;
    result = this->validateScriptModule(nid, /*[out]*/ mod);
    if (result == 0)
    {
        result = mod->GetGlobalVarIndexByName(arg.c_str());
        if (result >= 0)
        {
            result = 0;
        }
    }
    return result;
}
 
ScriptRetCode_t ScriptEngine::deleteVariable(const String &arg, const ScriptUnitID_t nid /*= SCRIPTUNITID_DEFAULT*/)
{
    int result = 0;
    AngelScript::asIScriptModule* mod = nullptr;
    result = this->validateScriptModule(nid, /*[out]*/ mod);
    if (result == 0)
    {
        result = mod->GetGlobalVarIndexByName(arg.c_str());
        if (result >= 0)
        {
            result = mod->RemoveGlobalVar(result);
        }
    }
    if (result < 0)
    {
        SLOG(fmt::format("Error {} while removing variable `{}` from module '{}'", result, arg, mod->GetName()));
    }
    return result;
}
 
ScriptRetCode_t ScriptEngine::getVariable(const Ogre::String& varName, void *ref, int refTypeId, const ScriptUnitID_t nid /*= SCRIPTUNITID_DEFAULT*/)
{
    AngelScript::asIScriptModule* mod = nullptr;
    int modResult = this->validateScriptModule(nid, /*[out]*/ mod);
    if (modResult < 0)
        return modResult;
 
    int index = mod->GetGlobalVarIndexByName(varName.c_str());
    if (index < 0)
    {
        return index;
    }
 
    const char* asVarName = nullptr;
    const char* asNamespace = nullptr;
    int asTypeId = 0;
    bool asConst = false;
    int getResult = mod->GetGlobalVar(index, &asVarName, &asNamespace, &asTypeId, &asConst);
    if (getResult < 0)
    {
        return getResult;
    }
 
    LOG(fmt::format("[RoR|Scripting] getScriptVariable() - '{}' global var info: name='{}', namespace='{}', typeid={}, const={}",
        varName, asVarName, asNamespace, asTypeId, asConst));
 
    // ~~ DEV NOTE: The following code is adopted from AngelScript's add-on 'scriptany.cpp', function `Retrieve()` ~~
 
    if( refTypeId & asTYPEID_OBJHANDLE )
    {
        // Is the handle type compatible with the stored value?
 
        // A handle can be retrieved if the stored type is a handle of same or compatible type
        // or if the stored type is an object that implements the interface that the handle refer to.
        if( (asTypeId & asTYPEID_MASK_OBJECT) )
        {
            // Don't allow the retrieval if the stored handle is to a const object but not the wanted handle
            if( (asTypeId & asTYPEID_HANDLETOCONST) && !(refTypeId & asTYPEID_HANDLETOCONST) )
            {
                SLOG(fmt::format("Error in `getScriptVariable()` - '{}' is a handle to `const` object but the requested type is not.", varName));
                return SCRIPTRETCODE_UNSPECIFIED_ERROR;
            }
 
            // RefCastObject will increment the refCount of the returned pointer if successful
            engine->RefCastObject(mod->GetAddressOfGlobalVar(index), engine->GetTypeInfoById(asTypeId), engine->GetTypeInfoById(refTypeId), reinterpret_cast<void**>(ref));
            if( *(asPWORD*)ref == 0 )
            {
                SLOG(fmt::format("Error in `getScriptVariable()` - '{}': reference-cast from '{}' to '{}' yielded null",
                    varName, engine->GetTypeDeclaration(asTypeId), engine->GetTypeDeclaration(refTypeId)));
                return SCRIPTRETCODE_UNSPECIFIED_ERROR;
            }
            return 0;
        }
    }
    else if( refTypeId & asTYPEID_MASK_OBJECT )
    {
        // Is the object type compatible with the stored value?
 
        // Copy the object into the given reference
        if( asTypeId == refTypeId )
        {
            engine->AssignScriptObject(ref, mod->GetAddressOfGlobalVar(index), engine->GetTypeInfoById(asTypeId));
            return 0;
        }
    }
    else
    {
        // Is the primitive type _IDENTICAL TO_ the stored value?
        // NOTE: implicit conversions are not done automatically, we would have to write code for each case separately
 
        if( asTypeId == refTypeId )
        {
            int size = engine->GetSizeOfPrimitiveType(refTypeId);
            memcpy(ref, mod->GetAddressOfGlobalVar(index), size);
            return 0;
        }
    }
 
    SLOG(fmt::format("Error in `getScriptVariable()` - '{}' has incompatible type, expected '{}' (typeid {}), got '{}' (typeid {})",
        varName, engine->GetTypeDeclaration(refTypeId), refTypeId, engine->GetTypeDeclaration(asTypeId), asTypeId));
    return SCRIPTRETCODE_UNSPECIFIED_ERROR;
}
 
asIScriptFunction* ScriptEngine::getFunctionByDeclAndLogCandidates(ScriptUnitID_t nid, GetFuncFlags_t flags, const std::string& funcName, const std::string& fmtFuncDecl)
{
    std::string decl = fmt::format(fmtFuncDecl, funcName);
    asIScriptFunction* retval = m_script_units[nid].scriptModule->GetFunctionByDecl(decl.c_str());
    if (!retval)
    {
        asIScriptFunction* candidate = m_script_units[nid].scriptModule->GetFunctionByName(funcName.c_str());
        if (candidate && BITMASK_IS_0(flags, GETFUNCFLAG_SILENT))
        {
            SLOG(fmt::format("Warning: a callback function with signature '{}' was not found"
                " but a function with given name exists: '{}' - did you make a typo in arguments?",
                decl, candidate->GetDeclaration()));
        }
        else if (!candidate && BITMASK_IS_1(flags, GETFUNCFLAG_REQUIRED))
        {
            SLOG(fmt::format("Warning: a callback function with signature '{}' was not found",
                decl));
        }
    }
    return retval;
}
 
void ScriptEngine::triggerEvent(scriptEvents eventnum, int arg1, int arg2ex, int arg3ex, int arg4ex, std::string arg5ex, std::string arg6ex, std::string arg7ex, std::string arg8ex)
{
    if (!engine || !context || !m_events_enabled) return;
 
    for (auto& pair: m_script_units)
    {
        ScriptUnitID_t id = pair.first;
        asIScriptFunction* callback = m_script_units[id].eventCallbackExFunctionPtr;
        if (!callback)
            callback = m_script_units[id].eventCallbackFunctionPtr;
        if (!callback)
            continue;
 
        if (m_script_units[id].eventMask & eventnum)
        {
            // script registered for that event, so sent it
            if (this->prepareContextAndHandleErrors(id, callback->GetId()))
            {
 
                // Set the function arguments
                context->SetArgDWord(0, eventnum);
                context->SetArgDWord(1, arg1);
                if (callback == m_script_units[id].eventCallbackExFunctionPtr)
                {
                    // Extended arguments
                    context->SetArgDWord(2, arg2ex);
                    context->SetArgDWord(3, arg3ex);
                    context->SetArgDWord(4, arg4ex);
                    context->SetArgObject(5, &arg5ex);
                    context->SetArgObject(6, &arg6ex);
                    context->SetArgObject(7, &arg7ex);
                    context->SetArgObject(8, &arg8ex);
                }
            }
 
            m_currently_executing_event_trigger = eventnum;
            this->executeContextAndHandleErrors(id);
            m_currently_executing_event_trigger = SE_NO_EVENTS;
        }
    }
}
 
String ScriptEngine::composeModuleName(String const& scriptName, ScriptCategory origin, ScriptUnitID_t id)
{
    return fmt::format("{}(category:{},unique ID:{})", scriptName, ScriptCategoryToString(origin), id);
}
 
ScriptUnitID_t ScriptEngine::loadScript(
    String scriptOrGadgetFileName, ScriptCategory category/* = ScriptCategory::TERRAIN*/,
    ActorPtr associatedActor /*= nullptr*/, std::string buffer /* =""*/)
{
    // This function creates a new script unit, tries to set it up and removes it if setup fails.
    // -----------------------------------------------------------------------------------------
    // A script unit is how Rigs of Rods organizes scripts from various sources.
    // Because the script is executed during loading, it's wrapping unit must
    // be created early, and removed if setup fails.
    static ScriptUnitID_t id_counter = 0;
 
    std::string basename, ext, scriptName;
    Ogre::StringUtil::splitBaseFilename(scriptOrGadgetFileName, basename, ext);
    CacheEntryPtr originatingGadget;
    if (ext == "gadget")
    {
        originatingGadget = App::GetCacheSystem()->FindEntryByFilename(LT_Gadget, /* partial: */false, scriptOrGadgetFileName);
        if (!originatingGadget)
        {
            App::GetConsole()->putMessage(Console::CONSOLE_MSGTYPE_INFO, Console::CONSOLE_SYSTEM_ERROR,
                fmt::format("Could not load script '{}' - gadget not found.", scriptOrGadgetFileName));
            return SCRIPTUNITID_INVALID;
        }
        App::GetCacheSystem()->LoadResource(originatingGadget);
        scriptName = fmt::format("{}.as", basename);
        // Ensure a .gadget file is always loaded as `GADGET`, even if requested as `CUSTOM`
        category = ScriptCategory::GADGET;
    }
    else if (ext == "as")
    {
        scriptName = scriptOrGadgetFileName;
    }
    else
    {
        App::GetConsole()->putMessage(Console::CONSOLE_MSGTYPE_INFO, Console::CONSOLE_SYSTEM_ERROR,
            fmt::format("Could not load script '{}' - unknown file extension.", scriptOrGadgetFileName));
        return SCRIPTUNITID_INVALID;
    }
 
    ScriptUnitID_t unit_id = id_counter++;
    auto itor_pair = m_script_units.insert(std::make_pair(unit_id, ScriptUnit()));
    m_script_units[unit_id].uniqueId = unit_id;
    m_script_units[unit_id].scriptName = scriptName;
    m_script_units[unit_id].scriptCategory = category;
    m_script_units[unit_id].scriptBuffer = buffer;
    m_script_units[unit_id].originatingGadget = originatingGadget;
    if (category == ScriptCategory::TERRAIN)
    {
        m_terrain_script_unit = unit_id;
    }
    else if (category == ScriptCategory::ACTOR)
    {
        m_script_units[unit_id].associatedActor = associatedActor;
    }
 
    // Perform the actual script loading, building and running main().
    int result = this->setupScriptUnit(unit_id);
 
    // Regardless of result, add to recent script list. Running scripts are filtered out when displaying.
    if (category == ScriptCategory::CUSTOM && buffer == "")
    {
        CvarAddFileToList(App::app_recent_scripts, scriptName);
    }
    else if (category == ScriptCategory::GADGET && originatingGadget)
    {
        CvarAddFileToList(App::app_recent_scripts, originatingGadget->fname);
    }
 
    // If setup failed, remove the unit.
    if (result != 0)
    {
        m_script_units.erase(itor_pair.first);
        if (category == ScriptCategory::TERRAIN)
        {
            m_terrain_script_unit = SCRIPTUNITID_INVALID;
        }
        return SCRIPTUNITID_INVALID;
    }
 
    return unit_id;
}
 
int ScriptEngine::setupScriptUnit(int unit_id)
{
    int result=0;
 
    String moduleName = this->composeModuleName(
        m_script_units[unit_id].scriptName, m_script_units[unit_id].scriptCategory, m_script_units[unit_id].uniqueId);
 
    // The builder is a helper class that will load the script file,
    // search for #include directives, and load any included files as
    // well.
    OgreScriptBuilder builder;
 
    // A script module is how AngelScript organizes scripts.
    // It contains the script loaded by user plus all `#include`-d scripts.
    result = builder.StartNewModule(engine, moduleName.c_str());
    if ( result < 0 )
    {
        App::GetConsole()->putMessage(Console::CONSOLE_MSGTYPE_INFO, Console::CONSOLE_SYSTEM_ERROR,
            fmt::format("Could not load script '{}' - failed to create module.", moduleName));
        return result;
    }
    m_script_units[unit_id].scriptModule = engine->GetModule(moduleName.c_str(), AngelScript::asGM_ONLY_IF_EXISTS);
 
    // For actor scripts, add global var `thisActor` to the module
    if (m_script_units[unit_id].scriptCategory == ScriptCategory::ACTOR)
    {
        result = m_script_units[unit_id].scriptModule->AddScriptSection(m_script_units[unit_id].scriptName.c_str(), "BeamClass@ thisActor;");
        if (result < 0)
        {
            App::GetConsole()->putMessage(Console::CONSOLE_MSGTYPE_INFO, Console::CONSOLE_SYSTEM_ERROR,
                fmt::format("Could not load script '{}' - failed to create global variable `thisActor`.", moduleName));
            return result;
        }
    }
 
    // add global var `thisScript` to the module (initialized in place).
    result = m_script_units[unit_id].scriptModule->AddScriptSection(m_script_units[unit_id].scriptName.c_str(), 
        fmt::format("const int thisScript = {};", unit_id).c_str());
    if (result < 0)
    {
        App::GetConsole()->putMessage(Console::CONSOLE_MSGTYPE_INFO, Console::CONSOLE_SYSTEM_ERROR,
            fmt::format("Could not load script '{}' - failed to create global variable `thisScript`.", moduleName));
        return result;
    }
 
    // If buffer is non-empty, load from memory; otherwise from filesystem as usual.
    if (m_script_units[unit_id].scriptBuffer != "")
    {
        result = builder.AddSectionFromMemory(m_script_units[unit_id].scriptName.c_str(), m_script_units[unit_id].scriptBuffer.c_str());
        if (result < 0)
        {
            App::GetConsole()->putMessage(Console::CONSOLE_MSGTYPE_INFO, Console::CONSOLE_SYSTEM_ERROR,
                fmt::format("Could not load script '{}' from buffer", moduleName));
            return result;
        }
    }
    else
    {
        // Load the script from the file system.
        result = builder.AddSectionFromFile(m_script_units[unit_id].scriptName.c_str());
        if ( result < 0 )
        {
            App::GetConsole()->putMessage(Console::CONSOLE_MSGTYPE_INFO, Console::CONSOLE_SYSTEM_ERROR,
                fmt::format("Could not load script '{}' - failed to process file.", moduleName));
            return result;
        }
    }
 
    // Build the AngelScript module - this loads `#include`-d scripts
    // and runs any global statements, for example constructors of
    // global objects like raceManager in 'races.as'. For this reason,
    // the game must already be aware of the script, but only temporarily.
    m_currently_executing_script_unit = unit_id; // for `BuildModule()` below.
    result = builder.BuildModule();
    m_currently_executing_script_unit = SCRIPTUNITID_INVALID; // Tidy up.
    if ( result < 0 )
    {
        App::GetConsole()->putMessage(Console::CONSOLE_MSGTYPE_INFO, Console::CONSOLE_SYSTEM_ERROR,
            fmt::format("Could not load script '{}' - failed to build module. See 'Angelscript.log' for more info.", moduleName));
        return result;
    }
 
    String scriptHash;
    if (m_script_units[unit_id].scriptCategory == ScriptCategory::TERRAIN) // Classic behavior
        scriptHash = builder.GetHash();
 
    // get some other optional functions
    m_script_units[unit_id].frameStepFunctionPtr = m_script_units[unit_id].scriptModule->GetFunctionByDecl("void frameStep(float)");
 
    m_script_units[unit_id].eventCallbackFunctionPtr = m_script_units[unit_id].scriptModule->GetFunctionByDecl("void eventCallback(int, int)");
    m_script_units[unit_id].eventCallbackExFunctionPtr = m_script_units[unit_id].scriptModule->GetFunctionByDecl("void eventCallbackEx(scriptEvents,   int, int, int, int,   string, string, string, string)");
 
    // THIS IS OBSOLETE - Use `eventCallbackEx()` and `SE_EVENTBOX_ENTER` instead. See commentary in `envokeCallback()`
    m_script_units[unit_id].defaultEventCallbackFunctionPtr = this->getFunctionByDeclAndLogCandidates(
        unit_id, GETFUNCFLAG_OPTIONAL, GETFUNC_DEFAULTEVENTCALLBACK_NAME, GETFUNC_DEFAULTEVENTCALLBACK_SIGFMT);
 
    // Find the function that is to be called.
    auto main_func = m_script_units[unit_id].scriptModule->GetFunctionByDecl("void main()");
    if ( main_func == nullptr )
    {
        // The function couldn't be found. Continue without invoking it - other callbacks like `frameStep()` can still run.
        return 0;
    }
 
    // Prepare the script context with the function we wish to execute. Prepare()
    // must be called on the context before each new script function that will be
    // executed. Note, that if you intend to execute the same function several
    // times, it might be a good idea to store the function id returned by
    // GetFunctionIDByDecl(), so that this relatively slow call can be skipped.
    result = context->Prepare(main_func);
    if (result < 0)
    {
        App::GetConsole()->putMessage(Console::CONSOLE_MSGTYPE_INFO, Console::CONSOLE_SYSTEM_ERROR,
            fmt::format("Could not load script '{}' - failed to build module.", moduleName));
        context->Release();
        return -1;
    }
 
    // For actor scripts, initialize the global var `thisActor`
    if (m_script_units[unit_id].scriptCategory == ScriptCategory::ACTOR)
    {
        int var_index = m_script_units[unit_id].scriptModule->GetGlobalVarIndexByName("thisActor");
        if (var_index < 0)
        {
            SLOG("Could not find global var `thisActor`");
            return -1;
        }
 
        // Example: https://www.gamedev.net/forums/topic/644188-angelscript-2263-global-property-issues-solved/5069638/
        Actor** thisActorAddr = (Actor**)m_script_units[unit_id].scriptModule->GetAddressOfGlobalVar(var_index);
        if (thisActorAddr == nullptr)
        {
            SLOG("Could not retrieve address of global var `thisActor`");
            return -1;
        }
        *thisActorAddr = m_script_units[unit_id].associatedActor.GetRef();
        (*thisActorAddr)->AddRef();
    }
 
    // Execute the `main()` function in the script.
    // The function must have full access to the game API.
    SLOG(fmt::format("Executing main() in {}", moduleName));
    int mainfunc_result = this->executeContextAndHandleErrors(unit_id);
    if ( mainfunc_result != AngelScript::asEXECUTION_FINISHED )
    {
        App::GetConsole()->putMessage(Console::CONSOLE_MSGTYPE_INFO, Console::CONSOLE_SYSTEM_ERROR,
            fmt::format("Could not load script '{}' - error running function `main()`, check AngelScript.log", moduleName));
    }
    else
    {
        SLOG("The script finished successfully.");
    }
 
    return mainfunc_result;
}
 
void ScriptEngine::unloadScript(ScriptUnitID_t nid)
{
    if (this->scriptUnitExists(nid))
    {
        if (m_script_units[nid].scriptModule != nullptr)
        {
            engine->DiscardModule(m_script_units[nid].scriptModule->GetName());
            m_script_units[nid].scriptModule = nullptr;
        }
        m_script_units.erase(nid);
    }
 
    if (m_terrain_script_unit == nid)
    {
        m_terrain_script_unit = SCRIPTUNITID_INVALID;
    }
}
 
void ScriptEngine::setForwardScriptLogToConsole(bool doForward)
{
    // Always remove right away, to avoid attaching twice
    scriptLog->removeListener(this);
 
    // Re-attach if requested
    if (doForward)
    {
        scriptLog->addListener(this);
    }
}
 
bool ScriptEngine::scriptUnitExists(ScriptUnitID_t nid)
{
    return nid != SCRIPTUNITID_INVALID 
        && m_script_units.find(nid) != m_script_units.end();
}
 
ScriptUnit& ScriptEngine::getScriptUnit(ScriptUnitID_t nid)
{
    ROR_ASSERT(this->scriptUnitExists(nid));
    return m_script_units[nid];
}