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
    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);
 
    this->triggerEvent(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;
}
 
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);
}
 
int ScriptEngine::executeString(String command)
{
    if (!engine || !context)
        return 1;
 
    // Only works with terrain script module (classic behavior)
    if (m_terrain_script_unit == SCRIPTUNITID_INVALID)
        return 1;
 
    AngelScript::asIScriptModule *mod = m_script_units[m_terrain_script_unit].scriptModule;
    int result = ExecuteString(engine, command.c_str(), mod, context);
    if (result < 0)
    {
        SLOG("error " + TOSTRING(result) + " while executing string: " + command + ".");
    }
    return result;
}
 
int ScriptEngine::addFunction(const String &arg)
{
    if (!engine || !context)
        return 1;
 
    if (!context)
        
 
    // Only works with terrain script module (classic behavior)
    if (m_terrain_script_unit == SCRIPTUNITID_INVALID)
        return 1;
 
    AngelScript::asIScriptModule *mod = m_script_units[m_terrain_script_unit].scriptModule;
 
    AngelScript::asIScriptFunction *func = 0;
    int r = mod->CompileFunction("addfunc", arg.c_str(), 0, AngelScript::asCOMP_ADD_TO_MODULE, &func);
    
    if ( r < 0 )
    {
        char tmp[512] = "";
        snprintf(tmp, 512, "An error occurred while trying to add a function ('%s') to script module '%s'.", arg.c_str(), mod->GetName());
        SLOG(tmp);
    }
    else
    {
        // 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;
        }
    }
 
    // We must release the function object
    if ( func )
        func->Release();
 
    return r;
}
 
int ScriptEngine::functionExists(const String &arg)
{
    if (!engine || !context) // WTF? If the scripting engine failed to start, how would it invoke this function?
        return -1; // ... OK, I guess the author wanted the fn. to be usable both within script and C++, but IMO that's bad design (generally good, but bad for a game.. bad for RoR), really ~ only_a_ptr, 09/2017
 
    // Only works with terrain script module (classic behavior)
    if (m_terrain_script_unit == SCRIPTUNITID_INVALID)
        return -1;
 
    AngelScript::asIScriptModule *mod = m_script_units[m_terrain_script_unit].scriptModule;
 
    if (mod == 0)
    {
        return AngelScript::asNO_FUNCTION; // Nope, it's an internal error, not a "function not found" case ~ only_a_ptr, 09/2017
    }
    else
    {
        AngelScript::asIScriptFunction* fn = mod->GetFunctionByDecl(arg.c_str());
        if (fn != nullptr)
            return fn->GetId();
        else
            return AngelScript::asNO_FUNCTION;
    }
}
 
int ScriptEngine::deleteFunction(const String &arg)
{
    if (!engine || !context)
        return AngelScript::asERROR;
 
    // Only works with terrain script module (classic behavior)
    if (m_terrain_script_unit == SCRIPTUNITID_INVALID)
        return -1;
 
    AngelScript::asIScriptModule *mod = m_script_units[m_terrain_script_unit].scriptModule;
 
    if ( mod->GetFunctionCount() == 0 )
    {
        char tmp[512] = "";
        sprintf(tmp, "An error occurred while trying to remove a function ('%s') from script module '%s': No functions have been added (and consequently: the function does not exist).", arg.c_str(), mod->GetName());
        SLOG(tmp);
        return AngelScript::asNO_FUNCTION;
    }
 
    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.
        mod->RemoveFunction(func);
 
        // 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;
 
        return func->GetId();
    }
    else
    {
        char tmp[512] = "";
        sprintf(tmp, "An error occurred while trying to remove a function ('%s') from script module '%s'.", arg.c_str(), mod->GetName());
        SLOG(tmp);
        return AngelScript::asERROR;
    }
}
 
int ScriptEngine::addVariable(const String &arg)
{
    if (!engine || !context) return 1;
    // Only works with terrain script module (classic behavior)
    if (m_terrain_script_unit == SCRIPTUNITID_INVALID)
        return 1;
 
    AngelScript::asIScriptModule *mod = m_script_units[m_terrain_script_unit].scriptModule;
 
    int r = mod->CompileGlobalVar("addvar", arg.c_str(), 0);
    if ( r < 0 )
    {
        char tmp[512] = "";
        sprintf(tmp, "An error occurred while trying to add a variable ('%s') to script module '%s'.", arg.c_str(), mod->GetName());
        SLOG(tmp);
    }
 
    return r;
}
 
int ScriptEngine::deleteVariable(const String &arg)
{
    if (!engine || !context) return 1;
    // Only works with terrain script module (classic behavior)
    if (m_terrain_script_unit == SCRIPTUNITID_INVALID)
        return 1;
    AngelScript::asIScriptModule *mod = m_script_units[m_terrain_script_unit].scriptModule;
 
    if ( mod == 0 || mod->GetGlobalVarCount() == 0 )
    {
        char tmp[512] = "";
        sprintf(tmp, "An error occurred while trying to remove a variable ('%s') from script module '%s': No variables have been added (and consequently: the variable does not exist).", arg.c_str(), mod->GetName());
        SLOG(tmp);
        return AngelScript::asNO_GLOBAL_VAR;
    }
 
    int index = mod->GetGlobalVarIndexByName(arg.c_str());
    if ( index >= 0 )
    {
        index = mod->RemoveGlobalVar(index);
    }
    else
    {
        char tmp[512] = "";
        sprintf(tmp, "An error occurred while trying to remove a variable ('%s') from script module '%s'.", arg.c_str(), mod->GetName());
        SLOG(tmp);
    }
 
    return index;
}
 
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 scriptName, 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;
 
    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;
    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);
    }
 
    // 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];
}