👼Script: 🧹 Fixed return codes of script-manip funcs.

Changes:
* added + registered `enum ScriptRetCode` - used by all script manipulation funcs (add/get/delete | funcs/variables)
* added func `scriptVariableExists()` to go with `scriptFunctionExists()`
* added internal helper `validateScriptModule`- used by all script manipulation funcs (add/get/delete | funcs/variables)

Following is analysis of former state (most but not all funcs returned 0 on success)
~ executeString() [script: not exported] - used to return 0 on success, 1 on internal error and negative number otherwise.
~ addFunction() [script: `game.addScriptFunction()`] - used to return 0 on success, 1 on internal error and negative number otherwise.
~ functionExists() [script: `game.scriptFunctionExists()`] - used to return function ID (always >0) on success, negative number on error.
~ deleteFunction() [script: `game.deleteScriptFunction()`] - used to return function ID (always >0) on success, negative number on error.
~ addVariable() [script: `game.addScriptVariable()` ] - used to return 0 on success, 1 on internal error and negative number otherwise.
~ variableExists() [script: `game.scriptVariableExists()`] - newly added, returns 0 on success  and negative number otherwise.
~ deleteVariable() [script: `game.deleteScriptVariable()` ] - used to return 0 on success, 1 on internal error and negative number otherwise.
~ getVariable() [script: `game.getScriptVariable()` ] - recently added, returns 0 on success  and negative number otherwise.

doc/angelscript/Script2Game/GameScriptClass.h

@@ -274,41 +274,59 @@ class GameScriptClass
 	/**
 	 * Adds a global function to the script.
 	 * @param func the function to be added, e.g.: "void func() { log('works'); }"
+     * @param nid ScriptUnitID to act upon, or -2 to fallback to the terrain script (defined in .terrn2 [Scripts], or 'default.as')
+     * @return 0 on success, negative number on error.
 	 */
-	int addScriptFunction(const string func);
+	ScriptRetCode addScriptFunction(const string func, ScriptUnitId_t nid = -2);
 
 	/**
 	 * Checks if a global function exists
 	 * @param func the declaration of the function that should be checked for existance, e.g.: "void func()"
+     * @param nid ScriptUnitID to act upon, or -2 to fallback to the terrain script (defined in .terrn2 [Scripts], or 'default.as')
+     * @return 0 on success, negative number on error.
 	 */
-	int scriptFunctionExists(const string func);
+	ScriptRetCode scriptFunctionExists(const string func, ScriptUnitId_t nid = -2);
 
 	/**
 	 * Removes a global function from the script.
 	 * @param func the declaration of the function that should be removed, e.g.: "void func()"
+     * @param nid ScriptUnitID to act upon, or -2 to fallback to the terrain script (defined in .terrn2 [Scripts], or 'default.as')
+     * @return 0 on success, negative number on error.
 	 */
-	int deleteScriptFunction(const string func);
+	ScriptRetCode deleteScriptFunction(const string func, ScriptUnitId_t nid = -2);
 
 	/**
 	 * Adds a global variable to the script.
 	 * @param var the declaration of the variable that should be added, e.g.: "int missionState;"
+     * @param nid ScriptUnitID to act upon, or -2 to fallback to the terrain script (defined in .terrn2 [Scripts], or 'default.as')
+     * @return 0 on success, negative number on error.
 	 */
-	int addScriptVariable(const string var);
+	ScriptRetCode addScriptVariable(const string var, ScriptUnitId_t nid = -2);
+
+	/**
+	 * Checks if a global variable exists in the script.
+	 * @param var the declaration of the variable that should be removed, e.g.: "int missionState;"
+     * @param nid ScriptUnitID to act upon, or -2 to fallback to the terrain script (defined in .terrn2 [Scripts], or 'default.as')
+     * @return 0 on success, negative number on error.
+	 */
+	ScriptRetCode scriptVariableExists(const string var, ScriptUnitId_t nid = -2);    
 
 	/**
 	 * Removes a global variable from the script.
 	 * @param var the declaration of the variable that should be removed, e.g.: "int missionState;"
+     * @param nid ScriptUnitID to act upon, or -2 to fallback to the terrain script (defined in .terrn2 [Scripts], or 'default.as')
+     * @return 0 on success, negative number on error.
 	 */
-	int deleteScriptVariable(const string var);
+	ScriptRetCode deleteScriptVariable(const string var, ScriptUnitId_t nid = -2);
 
     /**
-    * Retrieves a memory address of a global variable in any script.
-    * @param nid ScriptUnitID, ID of the running script, obtain one from global var `thisScript` or `game.getRunningScripts()`
-    * @param varName Name of the variable. Type must match the reference type.
-    * @param ref A variable-type parameter - accepts any reference.
-    * @return 0 on success, negative number on error.
-    */
-    int getScriptVariable(ScriptUnitId_t nid, const string&in varName, ?&ref);    
+     * Retrieves a memory address of a global variable in any script.
+     * @param nid ScriptUnitID to act upon, or -2 to fallback to the terrain script (defined in .terrn2 [Scripts], or 'default.as')
+     * @param varName Name of the variable. Type must match the reference type.
+     * @param ref A variable-type parameter - accepts any reference.
+     * @return 0 on success, negative number on error.
+     */
+    ScriptRetCode getScriptVariable(const string&in varName, ?&ref, ScriptUnitId_t nid = -2);    
 
 	/**
 	 * Clears the event cache

doc/angelscript/Script2Game/globals.h

@@ -666,6 +666,51 @@ enum MsgType
     MSG_EDI_CREATE_PROJECT_REQUESTED,          //!< Creates a subdir under 'projects/', pre-populates it and adds to modcache. Params: 'name' (string), 'ext' (string, optional), 'source_entry' (CacheEntryClass@)
 };
 
+/// Binding of `RoR::ScriptRetCode`; Common return codes for script manipulation funcs (add/get/delete | funcs/variables)
+enum ScriptRetCode
+{
+
+    SCRIPTRETCODE_SUCCESS = AngelScript::asSUCCESS, //!< Generic success - 0 by common convention.
+
+    // AngelScript technical codes
+    SCRIPTRETCODE_AS_ERROR = AngelScript::asERROR,
+    SCRIPTRETCODE_AS_CONTEXT_ACTIVE = AngelScript::asCONTEXT_ACTIVE,
+    SCRIPTRETCODE_AS_CONTEXT_NOT_FINISHED = AngelScript::asCONTEXT_NOT_FINISHED,
+    SCRIPTRETCODE_AS_CONTEXT_NOT_PREPARED = AngelScript::asCONTEXT_NOT_PREPARED,
+    SCRIPTRETCODE_AS_INVALID_ARG = AngelScript::asINVALID_ARG,
+    SCRIPTRETCODE_AS_NO_FUNCTION = AngelScript::asNO_FUNCTION,
+    SCRIPTRETCODE_AS_NOT_SUPPORTED = AngelScript::asNOT_SUPPORTED,
+    SCRIPTRETCODE_AS_INVALID_NAME = AngelScript::asINVALID_NAME,
+    SCRIPTRETCODE_AS_NAME_TAKEN = AngelScript::asNAME_TAKEN,
+    SCRIPTRETCODE_AS_INVALID_DECLARATION = AngelScript::asINVALID_DECLARATION,
+    SCRIPTRETCODE_AS_INVALID_OBJECT = AngelScript::asINVALID_OBJECT,
+    SCRIPTRETCODE_AS_INVALID_TYPE = AngelScript::asINVALID_TYPE,
+    SCRIPTRETCODE_AS_ALREADY_REGISTERED = AngelScript::asALREADY_REGISTERED,
+    SCRIPTRETCODE_AS_MULTIPLE_FUNCTIONS = AngelScript::asMULTIPLE_FUNCTIONS,
+    SCRIPTRETCODE_AS_NO_MODULE = AngelScript::asNO_MODULE,
+    SCRIPTRETCODE_AS_NO_GLOBAL_VAR = AngelScript::asNO_GLOBAL_VAR,
+    SCRIPTRETCODE_AS_INVALID_CONFIGURATION = AngelScript::asINVALID_CONFIGURATION,
+    SCRIPTRETCODE_AS_INVALID_INTERFACE = AngelScript::asINVALID_INTERFACE,
+    SCRIPTRETCODE_AS_CANT_BIND_ALL_FUNCTIONS = AngelScript::asCANT_BIND_ALL_FUNCTIONS,
+    SCRIPTRETCODE_AS_LOWER_ARRAY_DIMENSION_NOT_REGISTERED = AngelScript::asLOWER_ARRAY_DIMENSION_NOT_REGISTERED,
+    SCRIPTRETCODE_AS_WRONG_CONFIG_GROUP = AngelScript::asWRONG_CONFIG_GROUP,
+    SCRIPTRETCODE_AS_CONFIG_GROUP_IS_IN_USE = AngelScript::asCONFIG_GROUP_IS_IN_USE,
+    SCRIPTRETCODE_AS_ILLEGAL_BEHAVIOUR_FOR_TYPE = AngelScript::asILLEGAL_BEHAVIOUR_FOR_TYPE,
+    SCRIPTRETCODE_AS_WRONG_CALLING_CONV = AngelScript::asWRONG_CALLING_CONV,
+    SCRIPTRETCODE_AS_BUILD_IN_PROGRESS = AngelScript::asBUILD_IN_PROGRESS,
+    SCRIPTRETCODE_AS_INIT_GLOBAL_VARS_FAILED = AngelScript::asINIT_GLOBAL_VARS_FAILED,
+    SCRIPTRETCODE_AS_OUT_OF_MEMORY = AngelScript::asOUT_OF_MEMORY,
+    SCRIPTRETCODE_AS_MODULE_IS_IN_USE = AngelScript::asMODULE_IS_IN_USE,
+
+    // RoR ScriptEngine return codes
+    SCRIPTRETCODE_UNSPECIFIED_ERROR = -1001,
+    SCRIPTRETCODE_ENGINE_NOT_CREATED = -1002,
+    SCRIPTRETCODE_CONTEXT_NOT_CREATED = -1003,
+    SCRIPTRETCODE_SCRIPTUNIT_NOT_EXISTS = -1004,
+    SCRIPTRETCODE_SCRIPTUNIT_NO_MODULE = -1005,
+    SCRIPTRETCODE_FUNCTION_NOT_EXISTS = -1006,
+};
+
 } // namespace Script2Game
 
 /// @}    //addtogroup Script2Game

source/main/ForwardDeclarations.h

@@ -39,6 +39,7 @@ namespace RoR
 
     typedef int ScriptUnitID_t; //!< Unique sequentially generated ID of a loaded and running scriptin session. Use `ScriptEngine::getScriptUnit()`
     static const ScriptUnitID_t SCRIPTUNITID_INVALID = -1;
+    static const ScriptUnitID_t SCRIPTUNITID_DEFAULT = -2; //!< The script defined in .terrn2 [Scripts], or 'default.as' ~ classic behavior.
 
     typedef int PointidID_t; //!< index to `PointColDetector::hit_pointid_list`, use `RoR::POINTIDID_INVALID` as empty value.
     static const PointidID_t POINTIDID_INVALID = -1;
@@ -74,6 +75,8 @@ namespace RoR
     typedef int CommandkeyID_t; //!< Index into `Actor::ar_commandkeys` (BEWARE: indexed 1-MAX_COMMANDKEYS, 0 is invalid value, negative subscript of any size is acceptable, see `class CmdKeyArray` ).
     static const CommandkeyID_t COMMANDKEYID_INVALID = 0;
 
+    typedef int ScriptRetCode_t; //!< see enum `RoR::ScriptRetCode` - combines AngelScript codes and RoR internal codes.
+
     class  Actor;
     class  ActorManager;
     class  ActorSpawner;

source/main/scripting/GameScript.cpp

@@ -946,34 +946,39 @@ void GameScript::boostCurrentTruck(float factor)
     }
 }
 
-int GameScript::addScriptFunction(const String& arg)
+int GameScript::addScriptFunction(const String& arg, ScriptUnitID_t nid)
 {
-    return App::GetScriptEngine()->addFunction(arg);
+    return App::GetScriptEngine()->addFunction(arg, nid);
 }
 
-int GameScript::scriptFunctionExists(const String& arg)
+int GameScript::scriptFunctionExists(const String& arg, ScriptUnitID_t nid)
 {
-    return App::GetScriptEngine()->functionExists(arg);
+    return App::GetScriptEngine()->functionExists(arg, nid);
 }
 
-int GameScript::deleteScriptFunction(const String& arg)
+int GameScript::deleteScriptFunction(const String& arg, ScriptUnitID_t nid)
 {
-    return App::GetScriptEngine()->deleteFunction(arg);
+    return App::GetScriptEngine()->deleteFunction(arg, nid);
 }
 
-int GameScript::addScriptVariable(const String& arg)
+int GameScript::addScriptVariable(const String& arg, ScriptUnitID_t nid)
 {
-    return App::GetScriptEngine()->addVariable(arg);
+    return App::GetScriptEngine()->addVariable(arg, nid);
 }
 
-int GameScript::deleteScriptVariable(const String& arg)
+int GameScript::scriptVariableExists(const String& arg, ScriptUnitID_t nid)
 {
-    return App::GetScriptEngine()->deleteVariable(arg);
+    return App::GetScriptEngine()->variableExists(arg, nid);
 }
 
-int GameScript::getScriptVariable(ScriptUnitID_t nid, const Ogre::String& varName, void *ref, int refTypeId)
+int GameScript::deleteScriptVariable(const String& arg, ScriptUnitID_t nid)
 {
-    return App::GetScriptEngine()->getVariable(nid, varName, ref, refTypeId);
+    return App::GetScriptEngine()->deleteVariable(arg, nid);
+}
+
+int GameScript::getScriptVariable(const Ogre::String& varName, void *ref, int refTypeId, ScriptUnitID_t nid)
+{
+    return App::GetScriptEngine()->getVariable(varName, ref, refTypeId, nid);
 }
 
 int GameScript::sendGameCmd(const String& message)

source/main/scripting/GameScript.h

@@ -221,35 +221,42 @@ class GameScript
      * (Wrapper for ScriptEngine::addFunction)
      * @param arg A declaration for the function.
     */
-    int addScriptFunction(const Ogre::String& arg);
+    ScriptRetCode_t addScriptFunction(const Ogre::String& arg, ScriptUnitID_t nid);
 
     /**
      * Checks if a global function exists in the script
      * (Wrapper for ScriptEngine::functionExists)
      * @param arg A declaration for the function.
     */
-    int scriptFunctionExists(const Ogre::String& arg);
+    ScriptRetCode_t scriptFunctionExists(const Ogre::String& arg, ScriptUnitID_t nid);
 
     /**
      * Deletes a global function from the script
      * (Wrapper for ScriptEngine::deleteFunction)
      * @param arg A declaration for the function.
     */
-    int deleteScriptFunction(const Ogre::String& arg);
+    ScriptRetCode_t deleteScriptFunction(const Ogre::String& arg, ScriptUnitID_t nid);
 
     /**
      * Adds a global variable to the script
      * (Wrapper for ScriptEngine::addVariable)
      * @param arg A declaration for the variable.
     */
-    int addScriptVariable(const Ogre::String& arg);
+    ScriptRetCode_t addScriptVariable(const Ogre::String& arg, ScriptUnitID_t nid);
+
+    /**
+     * Adds a global variable to the script
+     * (Wrapper for ScriptEngine::variableExists)
+     * @param arg A declaration for the variable.
+    */
+    ScriptRetCode_t scriptVariableExists(const Ogre::String& arg, ScriptUnitID_t nid);
 
     /**
      * Deletes a global variable from the script
      * (Wrapper for ScriptEngine::deleteVariable)
      * @param arg A declaration for the variable.
     */
-    int deleteScriptVariable(const Ogre::String& arg);
+    ScriptRetCode_t deleteScriptVariable(const Ogre::String& arg, ScriptUnitID_t nid);
 
     /**
     * Retrieves a memory address of a global variable in any script.
@@ -259,7 +266,7 @@ class GameScript
     * @param refTypeId Type of the reference; To be registered as variable-type parameter `?&out`
     * @return 0 on success, negative number on error.
     */
-    int getScriptVariable(ScriptUnitID_t nid, const Ogre::String& varName, void *ref, int refTypeId);
+    ScriptRetCode_t getScriptVariable(const Ogre::String& varName, void *ref, int refTypeId, ScriptUnitID_t nid);
 
     void clearEventCache();