Script updates and fixes

doc/angelscript/Script2Game/AngelOgre/AngelOgre_Overlay.h

@@ -0,0 +1,52 @@
+
+namespace AngelOgre { // Dummy namespace, just to distinguish AngelScript from C++
+
+/** \addtogroup ScriptSideAPIs
+ *  @{
+ */    
+
+/** \addtogroup Script2Game
+ *  @{
+ */  
+
+    /** 
+    */
+    class  Overlay
+    {
+    public:
+        // (order roughly matches OgreOverlay.h)
+
+        const string& getName() const;
+        // > z-order
+        uint16 getZOrder();
+        // > visibility
+        bool isVisible() const;
+        void show();
+        void hide();
+        // > 2D elements
+        void add2D(OverlayElement@);
+        void remove2D(OverlayElement@);
+        // > scrolling
+        void setScroll(float, float);
+        float getScrollX() const;
+        float getScrollY() const;
+        void scroll(float, float);
+        // > rotating
+        void setRotate(const radian&in);
+        const radian& getRotate() const;
+        void rotate(const radian&in);
+        // > scaling
+        void setScale(float, float);
+        float getScaleX() const;
+        float getScaleY() const;
+        // > 2D elements
+        array<OverlayElement@>@ get2DElements();
+
+    };
+
+/// @}    //addtogroup Script2Game
+/// @}    //addtogroup ScriptSideAPIs
+
+} // namespace AngelOgre (dummy, just to distinguish AngelScript from C++)
+
+

doc/angelscript/Script2Game/AngelOgre/AngelOgre_OverlayElement.h

@@ -0,0 +1,73 @@
+
+namespace AngelOgre { // Dummy namespace, just to distinguish AngelScript from C++
+
+/** \addtogroup ScriptSideAPIs
+ *  @{
+ */    
+
+/** \addtogroup Script2Game
+ *  @{
+ */  
+
+    // Register the GuiMetricsMode enum
+    enum GuiMetricsMode
+    {
+        GMM_PIXELS,
+        GMM_RELATIVE,
+        GMM_RELATIVE_ASPECT_ADJUSTED
+    }
+
+    // Register the GuiHorizontalAlignment enum
+    enum GuiHorizontalAlignment
+    {
+        GHA_LEFT,
+        GHA_CENTER,
+        GHA_RIGHT
+    }
+
+
+    class  OverlayElement
+    {
+    public:
+        // (order roughly matches OgreOverlayElement.h)
+        const string& getName() const;
+        // > visibility
+        void show();
+        void hide();
+        bool isVisible() const;
+        // > positioning
+        void setPosition(float, float);
+        void setDimensions(float, float);
+        float getLeft() const;
+        float getTop() const;
+        float getWidth() const;
+        float getHeight() const;
+        void setLeft(float);
+        void setTop(float);
+        void setWidth(float);
+        void setHeight(float);
+        // > material
+        const string& getMaterialName() const;
+        void setMaterialName(const string&in, const string&in);
+        // > caption
+        void setCaption(const string&in);
+        const string& getCaption() const;
+        // > color
+        void setColour(const color&in);
+        const color& getColour() const;
+        // > GuiMetricsMode
+        GuiMetricsMode getMetricsMode() const;
+        void setMetricsMode(GuiMetricsMode);
+        // > GuiHorizontalAlignment
+        GuiHorizontalAlignment getHorizontalAlignment() const;
+        void setHorizontalAlignment(GuiHorizontalAlignment);
+
+
+    };
+
+/// @}    //addtogroup Script2Game
+/// @}    //addtogroup ScriptSideAPIs
+
+} // namespace AngelOgre (dummy, just to distinguish AngelScript from C++)
+
+

doc/angelscript/Script2Game/AngelOgre/AngelOgre_OverlayManager.h

@@ -0,0 +1,46 @@
+
+namespace AngelOgre { // Dummy namespace, just to distinguish AngelScript from C++
+
+/** \addtogroup ScriptSideAPIs
+ *  @{
+ */    
+
+/** \addtogroup Script2Game
+ *  @{
+ */  
+
+    /** a singleton - use `Ogre::OverlayManager::getSingleton()` to retrieve instance.
+    */
+    class  OverlayManager
+    {
+    public:
+        // Overlay (container) objects
+        Overlay@ create(const string&in name);
+        Overlay@ getByName(const string&in name);
+        void destroy(const string&in name);
+        void destroy(Overlay@ overlay);
+        void destroyAll();
+        array<Overlay@>@ getOverlays();
+        // Utils
+        float getViewportHeight() const;
+        float getViewportWidth() const;
+        // OverlayElement objects
+        OverlayElement@ createOverlayElement(const string&in type, const string&in name, bool isTemplate=false);
+        OverlayElement@ getOverlayElement(const string&in name) const;
+        bool hasOverlayElement(const string&in) const;
+        void destroyOverlayElement(const string&in, bool isTemplate=false) const;
+        void destroyOverlayElement(OverlayElement@, bool isTemplate=false) const;
+        void destroyAllOverlayElements(bool isTemplate=false) const;
+        // Templates
+        OverlayElement@ createOverlayElementFromTemplate(const string&in, const string&in, const string&in, bool=false);
+        OverlayElement@ cloneOverlayElementFromTemplate(const string&in, const string&in);
+        array<OverlayElement@>@ getTemplates();
+        bool isTemplate(const string&in);
+    };
+
+/// @}    //addtogroup Script2Game
+/// @}    //addtogroup ScriptSideAPIs
+
+} // namespace AngelOgre (dummy, just to distinguish AngelScript from C++)
+
+

doc/angelscript/Script2Game/GameScriptClass.h

@@ -274,32 +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 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
@@ -435,6 +462,11 @@ class GameScriptClass
     */
     bool getMousePositionOnTerrain(vector3 &out);
 
+    /**
+    * Returns `array<Ogre::MovableObjects@>` in no particular order; works using bounding boxes so large/generated meshes like roads get matched all the time.
+    */
+    array<Ogre::MovableObjects@> getMousePointedMovableObjects();
+
     /// @}
 
     /// @name Character

doc/angelscript/Script2Game/GenericDocContextClass.h

@@ -14,7 +14,8 @@ enum TokenType
     TOKEN_TYPE_LINEBREAK,
     TOKEN_TYPE_COMMENT,
     TOKEN_TYPE_STRING,
-    TOKEN_TYPE_NUMBER,
+    TOKEN_TYPE_FLOAT,
+	TOKEN_TYPE_INT,
     TOKEN_TYPE_BOOL,
     TOKEN_TYPE_KEYWORD
 };
@@ -37,23 +38,36 @@ class GenericDocContextClass
 
     string getTokString(int offset = 0);
     float getTokFloat(int offset = 0);
+    float getTokInt(int offset = 0);
     bool gettokBool(int offset = 0);
     string getTokKeyword(int offset = 0);
     string getTokComment(int offset = 0);
 
     bool isTokString(int offset = 0);
     bool isTokFloat(int offset = 0);
+    bool isTokInt(int offset = 0);
     bool isTokBool(int offset = 0);
     bool isTokKeyword(int offset = 0);
     bool isTokComment(int offset = 0);
+    bool isTokLineBreak(int offset = 0);
 
     // Editing functions:
 
+    void appendTokens(int count); //!< Appends a series of `TokenType::NONE` and sets Pos at the first one added; use `setTok*` functions to fill them.
     bool insertToken(int offset = 0); //!< Inserts `TokenType::NONE`; @return false if offset is beyond EOF
     bool eraseToken(int offset = 0); //!< @return false if offset is beyond EOF
+
+    void appendTokString(const string&in str);
+    void appendTokFloat(float val);
+    void appendTokInt(float val);
+    void appendTokBool(bool val);
+    void appendTokKeyword(const string&in str);
+    void appendTokComment(const string&in str);
+    void appendTokLineBreak();    
 
     bool setTokString(int offset, const string&in str);
     bool setTokFloat(int offset, float val);
+    bool setTokInt(int offset, int val);
     bool setTokBool(int offset, bool val);
     bool setTokKeyword(int offset, const string&in str);
     bool setTokComment(int offset, const string&in str);

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

resources/scripts/AI.as

@@ -11,9 +11,14 @@ void main()
 
     for (int x = 0; x < game.getAIVehicleCount(); x++)
     {
+        string spawn_vehiclename = game.getAIVehicleName(x);
         array<vector3> waypoints = game.getWaypoints(x);
+        if (waypoints.length() == 0)
+        {
+            game.log("Vehicle AI: No waypoints defined for vehicle '"+spawn_vehiclename+"' ("+(x+1)+"/"+game.getAIVehicleCount()+"), skipping it...");
+            continue; // Skip this vehicle
+        }        
 
-        string spawn_vehiclename = game.getAIVehicleName(x);
         vector3 spawn_pos = vector3(waypoints[0].x + translation_x, waypoints[0].y, waypoints[0].z + translation_z);
         string spawn_sectionconfig = game.getAIVehicleSectionConfig(x);
         string spawn_skin = game.getAIVehicleSkin(x);

resources/scripts/README.txt

@@ -8,7 +8,7 @@ FOR DEVELOPERS: Visit https://developer.rigsofrods.org/ and click "Script-side A
 Conventions:
 * Scripts named 'example_*.as' are short introductory scripts that perform one thing, usually showing UI with tips and controls. You can run them using 'loadscript'.
 * Scripts named '*_editor.as' are complete tools. You can run them using 'loadscript'.
-* Scripts named '*_utils.as' are includes - running them directly is not possible, 'loadscript' would result in error "there is no main() function".
+* Scripts named '*_utils.as' are includes - running them via 'loadscript' does nothing, they are to be `#include`-d into other scripts.
 
 Special scripts:
 * 'default.as' - fallback terrain script, loaded if modder didn't provide custom script.