Gameengine-Classes
##########################################

class ``ground_model``
***********************

.. cpp:class:: ground_model

  .. cpp:function:: ground_model()

    .. todo:: What is it

    **Example**: creates a new ground_model and prints the roughness Coefficient into the console.

    .. code-block:: lua

            local gmodel = ground_model()
            print(tostring(gmodel:as_table().roughnessCoefficient)) -- prints 0

  .. cpp:function:: TABLE as_table()

     .. code-block:: lua

          local gmodel = ground_model()
          print(tostring(gmodel:as_table().roughnessCoefficient)) -- prints 0

  .. cpp:function:: from_table( table )

    .. todo:: Not included yet

  **Members of the ground_model**:

+-------+----------------------------+---------------------------------------------------------------------------------------+
| Value | Name                       | Description                                                                           |
+-------+----------------------------+---------------------------------------------------------------------------------------+
| float | roughnessCoefficient       | an indicator of how rough a surface is. Range: [0-1]                                  |
+-------+----------------------------+---------------------------------------------------------------------------------------+
| float | defaultDepth               | the depth of the model if not overriden by the terrain                                |
+-------+----------------------------+---------------------------------------------------------------------------------------+
| float | staticFrictionCoefficient  | static friction coefficient                                                           |
+-------+----------------------------+---------------------------------------------------------------------------------------+
| float | slidingFrictionCoefficient | sliding friction coefficient                                                          |
+-------+----------------------------+---------------------------------------------------------------------------------------+
| float | hydrodynamicFriction       | hydrodynamic friction (s/m)                                                           |
+-------+----------------------------+---------------------------------------------------------------------------------------+
| float | stribeckVelocity           | stribeck velocity (m/s)                                                               |
+-------+----------------------------+---------------------------------------------------------------------------------------+
| float | strength                   | ground strength                                                                       |
+-------+----------------------------+---------------------------------------------------------------------------------------+
| int   | collisiontype              | material id for particles and sounds                                                  |
+-------+----------------------------+---------------------------------------------------------------------------------------+
| float | fluidDensity               | Density of liquid                                                                     |
+-------+----------------------------+---------------------------------------------------------------------------------------+
| float | flowConsistencyIndex       | general drag coefficient                                                              |
+-------+----------------------------+---------------------------------------------------------------------------------------+
| float | flowBehaviorIndex          |                                                                                       |
+-------+----------------------------+---------------------------------------------------------------------------------------+
| float | shearStrength              | if flow_behavior_index<1 then liquid is Pseudoplastic (ketchup, whipped cream, paint) |
|       |                            |                                                                                       |
|       |                            | if =1 then liquid is Newtonian fluid                                                  |
|       |                            |                                                                                       |
|       |                            | if >1 then liquid is Dilatant fluid (less common)                                     |
+-------+----------------------------+---------------------------------------------------------------------------------------+
| float | dragAnisotropy             | Upwards/Downwards drag anisotropy                                                     |
+-------+----------------------------+---------------------------------------------------------------------------------------+
| float | skidMarks                  | spawn particles yes/no                                                                |
+-------+----------------------------+---------------------------------------------------------------------------------------+
| float | name                       |                                                                                       |
+-------+----------------------------+---------------------------------------------------------------------------------------+

    You can get them by this:

    .. code-block:: lua

	        local gmodel = ground_model()
	        print(tostring(gmodel:as_table().roughnessCoefficient))


Class ``GameEngineLua``
*************************
.. cpp:class:: GameEngineLua

  .. cpp:function:: log(string level, string origin, string msg)

    Logs a text into the console.

    **Parameters:**

    - ``string level``: {``E`` = Error , ``I`` = Info, ``W`` = Warning, ``D`` = Debug}
    - ``string origin``: name of the lua module and the function ( GELua. is prepended when in GE VM)
    - ``string msg``: Message/data to print

    **Example**:

    .. code-block:: lua

        Lua:log("E", "test", "This is a crazy test")
        -- prints |E|GELua.test|This is a crazy test

  .. cpp:function:: blacklistLogLevel(string str)

  .. todo:: Whats this?

    Hide a specific level of logs

  .. cpp:function:: exec(string str)

    Executes a LUA file

    **Parameters:**

    - ``string str``: The path to the lua-File (f.e. testing.lua, if its in Documents/BeamNG.drive/)

    Info: Its allways the relative path from "Documents/BeamNG.drive/"

    **Example** Prints a text from another file (testing.lua)

    lua code:


    .. code-block:: lua

        Lua:exec("testing.lua")

    testing.lua:

    .. code-block:: lua

        print("This is a cool test") -- prints |A|GELua.print|This is a cool test



  .. cpp:function:: requestReload()

    Request a Lua reload

    **Example**: Reloads the complete Lua

    .. code-block:: lua

        Lua:requestReload()

  .. cpp:function:: queueLuaCommand(string str)

    queue the command given by argument

    **Parameters:**

    - ``string str``: The Lua Command as String

    **Example**

    .. code-block:: lua

        Lua:queueLuaCommand("print(\"Hi\")") --prints "Hi"

  .. cpp:function:: dumpStack(string logLevel)

    dump the current stack

  .. cpp:function:: int getMemoryUsageKB()

    .. todo:: Does it exist?

  .. cpp:function:: enableStackTraceFile(string filename, bool full)

    dump the stack in a specific file

    **Parameters:**

    - ``string filename``: The path where it should be stored
    - ``bool full``: Do you want to save the whole stack?

    **Example**

    .. code-block:: lua

        Lua:enableStackTraceFile("levels.log", true)

  .. cpp:function:: table findObjectByNameAsTable(string name)

    Finds an Object By its name and returns a table

    **Parameters**:

    - ``string name``: The name of the Object

    :returns: the object or false if not found

    **Example** //TODO: Game crashes if I try

    .. code-block:: lua

        print(tostring(Lua:findObjectByNameAsTable("SimObject")))

  .. cpp:function:: bool findObjectByIdAsTable(int id)

    try to find the :cpp:class:`SimObject` with this name

    :returns: the object or false if not found

    .. todo:: Game Crashes if I try

  .. cpp:function:: int getAllObjects(table)

    **Parameters:**

    - ``table``: A table

    :returns: (int) Number of all objects in the level

    .. todo:: Whats the meaning of "table"?



  .. cpp:function:: int findObjectsByClassAsTable(string className, table)

    Get all object which have the class ``className`` :cpp:class:`SimObject` in a table

    **Example**:

    .. code-block:: lua

        local table = {}
        print(Lua:findObjectsByClassAsTable("SimObject", table))

  .. cpp:function:: bool castSimObject(ConsoleObject obj, table)

  .. cpp:function:: bool saveFunctionOpcode(string filename, v)

  .. cpp:function:: string getSelectedLanguage()

    Gets the selected Language of the Player

    :returns: (string) the language

    **Example**

    .. code-block:: lua

        local language = Lua:getSelectedLanguage()
        print(language) --prints f.e. en-US

  .. cpp:function:: string getSteamLanguage()

    Gets the language, that is used at Steam interface

    :returns: (string) the language used for the steam interface

    **Example**

    .. code-block:: lua

        print(Lua:getSteamLanguage()) --prints f.e: en-US

  .. cpp:function:: string getOSLanguage()

    :returns: (string) the language used by the OS

    **Example**:

    .. code-block:: lua

        local lang = Lua:getOSLanguage()
        print(lang) --prints f.e. en-US

  .. cpp:function:: reloadLanguages()

    Reloads the languages

    **Example**:

    .. code-block:: lua

        Lua:reloadLanguages()

  .. cpp:member:: Point3F lastDebugFocusPos

    .. code-block:: lua

        print(Lua.lastDebugFocusPos) --prints f.e. 0.00326664, -1.52147, 0


Class ``BeamEngine``
*************************

.. cpp:class:: BeamEngine

  .. cpp:function:: BeamNGVehicle getObject(int objectId)

  .. todo::

    - Example

    Gets the Object with the index of the ObjectID.

    :returns: the :cpp:class:`BeamNGVehicle` which have the index ``objectId``

    **Example**: This example gets the Vehicle with objectid 0 and prints its position to the console.

    .. code-block:: lua

        local car = be:getObject(0)
        print(car:getPosition())

  .. cpp:function:: BeamNGVehicle getObjectByID(int id)

    **Parameters:**

    - ``int id``: the id of the Object you want to get

    :returns: the :cpp:class:`BeamNGVehicle` which have the id

    **Example**: Gets the number of existing BeamNGVehicle and prints it to console.

    .. code-block:: lua

       local number = be:getObjectCount()
       print(tostring(number))

  .. cpp:function:: int getObjectCount()

    Gets the Count of all BeamNGVehicle's

    :returns: (int) the number of :cpp:class:`BeamNGVehicle`

    **Example**: Gets the number of existing BeamNGVehicle and prints it to console.

    .. code-block:: lua

       local number = be:getObjectCount()
       print(tostring(number))

  .. cpp:function:: BeamNGVehicle getPlayerVehicle(int id)

    **Parameters:**

    - ``int id``: the Player ID: mostly it is 0

    :returns: the :cpp:class:`BeamNGVehicle` which have the player id

    **Example**: Gets the Vehicle and prints its Position

    .. code-block:: lua

       local veh = be:getPlayerVehicle(0)
       print(tostring(veh:getPosition()))

  .. cpp:function:: int getPlayerVehicleID(int player)

    Gets the ID of the Vehicle Model of the Player

    **Parameters:**

    - ``int id``: the Player you want to get the VehicleID from ( 0 = normal player)

    :returns: (int) the id of the Vehicle driver by the player

    .. code-block:: lua

       local number = be:getPlayerVehicleID(0) -- prints f.e. 5616
       print(tostring(veh:number()))

  .. cpp:function:: string getFFBConfig(int ffid)

    .. todo:: What is FFB and ffid?

  .. cpp:function:: queueAllObjectLua( string str)

    Add a command to the queue of every objects

    **Parameters:**

    - ``string str``: Command to execute

  .. cpp:function:: queueAllObjectLuaExcept( string str, int exceptId)

    Add a command to the queue of every objects except the object that have the id ``exceptId``

    **Parameters:**

    - ``string str``: Command to execute
    - ``int exceptId``: The Object id where the command won't be executed

  .. cpp:function:: executeJS(string js)

    Executes a Javascript-Script.

    **Parameters:**

    - ``string js``: The Javascript-Code, you want to execute

    **Example**: This example opens via Javascript an alert-window.

    .. code-block:: lua

        local js = "alert(\"ok\")"
        be:executeJS(js);

  .. cpp:function:: queueJS(string ref, string js)

    Same as :cpp:func:`executeJS` , backward compatibility

  .. cpp:function:: executeStreamJS(string ref, string js)

  .. cpp:function:: queueStreamJS(string ref, string js)

    Same as :cpp:func:`executeStreamJS` , backward compatibility

  .. cpp:function:: setEnabled(bool v)

    **Parameters:**

    - ``bool v``: true to enable, false to disable

    **Example**: Disbles be and prints it to the console

    .. code-block:: lua

        be:setEnabled(false);
        print(tostring(be:getEnabled()))

  .. cpp:function:: bool getEnabled()

    :returns: true if its enabled, false otherwise

    Example See: :cpp:func:`BeamEngine::setEnabled`

  .. cpp:function:: reloadVehicle(int player)

    Reloads the Vehicle and sets Reload-Position to curent position

    **Parameters:**

    - ``int player``: The player ID (normal player = 0)

    **Example**: Reloads the Vehicle

    .. code-block:: lua

        be:reloadVehicle(0)
        print("Vehicle reload success")

  .. cpp:function:: resetVehicle(int player)

    Resets the Car to his Reload-Position.

    **Parameters:**

    - ``int player``: The player ID (normal player = 0)

    **Example**: Resets the car

    .. code-block:: lua

        be:resetVehicle(0)
        print("Vehicle reset success")

  .. cpp:function:: toggleEnabled()

    .. deprecated:: 0.9

    Deprecated API call :cpp:func:`toggleEnabled()`. Please use lua :cpp:func:`bullettime::togglePause` from now on

  .. cpp:function:: exitVehicle(int player)

    .. todo:: Not included yet?

    Function to leave the car

    **Parameters:**

    - ``int player``: The player ID (normal player = 0)

    **Example**: Exits the Car

    .. code-block:: lua

        be:exitVehicle(0)

  .. cpp:function:: enterNextVehicle(int player, int nextStep)

    **Parameters:**

    - ``int player``: The player ID (normal player = 0)
    - ``int nextStep``: Up to which car is to be skipped

    **Example**: Changes to the next car

    .. code-block:: lua

        be:enterNextVehicle(0, 1)

  .. cpp:function:: enterVehicle(int player, BeamNGVehicle vehicle)

    The function places the player in the vehicle with ID 2.

    **Parameters:**

    - ``int player``: The player ID (normal player = 0)
    - ``BeamNGVehicle vehicle``: The vehicle in which the player is to be placed.

    **Example**: Gets the Car with ID 2 and places the player in it.

    .. code-block:: lua

        local car = be:getObject(2)
        be:enterVehicle(0, car)

  .. cpp:function:: reloadStaticCollision(bool debug = false)

    .. todo::
       Whats the difference if it starts in Debug-mode?

    Reloads the collision of static objects

    **Parameters:**

    - ``bool debug``: true if it should be started in debug-mode, false otherwise

    **Example**: Reloads the static collision.

    .. code-block:: lua

        be:reloadStaticCollision(true)

  .. cpp:function:: bool isBlockedByFirewall()

    Gets if the BeamEngine is blocked by the firewall.

    :returns: true if its blocked, false otherwise

    **Example**: Gets if the firewall is blocked and prints the result to console.

    .. code-block:: lua

        local isblocked = be:isBlockedByFirewall()
        print(tostring(isblocked))

  .. cpp:function:: addFirewallException()

    Adds a Firewall Exception to the BeamEngine

    **Example**: adds Firewall Exception and prints the state to console

    .. code-block:: lua

        be:addFirewallException()
        local isblocked = be:isBlockedByFirewall()
        print(tostring(isblocked))

  .. cpp:function:: resetGroundModels()

    Resets all Ground models

    **Example**

    .. code-block:: lua

       be:resetGroundModels()
       print("Ground models resetted")

  .. cpp:function:: table getGroundModel(string name)

    .. todo:: Where do I get the names from?

  .. cpp:function:: int getGroundModelCount()

    Gets the number of ground models in the Level.

    :returns: (int) number of ground models

    **Example**: Prints the number of ground models into the console

    .. code-block:: lua

       print(be:getGroundModelCount()) -- prints f.e 46

  .. cpp:function:: int getGroundModelIDByName(string name)

    .. todo:: Where do I get the name from?

  .. cpp:function:: table getGroundModelByID(int id)

    .. todo:: Where do I get the ID from?

  .. cpp:function:: float castRay(Point3F origin, Point3F target)

    .. todo:: Not sure, what this function does

  .. cpp:function:: notifyMissionLoaded()

  .. cpp:function:: notifyMissionUnloaded()

  .. cpp:function:: bool physicsInitWorld()

  .. cpp:function:: physicsDestroyWorld()

  .. cpp:function:: physicsStartSimulation()

  .. cpp:function:: physicsStopSimulation()

  .. cpp:function:: setGroundModel(string name, BeamNG::ground_model_t g)

  .. cpp:function:: setSeaLevelTemperatureK(float seaLevelTemperatureKelvin)

    Sets the Sea-level-temperatur to a float.

    **Parameters:**

    - ``float seaLevelTemperatureKelvin``: the new temperature

    **Example**:

    .. code-block:: lua

        be:setSeaLevelTemperatureK(298.15)


  .. cpp:function:: setSimulationTimeScale(float v)

    Sets the Speed of the Game

    **Parameters:**

    - ``float v``: The new Speed

    **Example**: Changes the Speed of the game to the double and prints it to console

    .. code-block:: lua

       be:setSimulationTimeScale(2)
       print(be:getSimulationTimeScale())

  .. cpp:function:: float getSimulationTimeScale()

    Gets the Speed-Scale of the Game

    :returns: (float) Speed of the Game

    **Example** See: :cpp:func:`BeamEngine::setSimulationTimeScale`

  .. cpp:function:: string sfxGetAvailableDevices()

    Gets all compitable Audidevices

    :returns: (string) all audio devices

    **Example**

    .. code-block:: lua

        print(be:sfxGetAvailableDevices())

    .. todo:: Refresh path

    Prints for example:

    .. image:: example_sfxDevices.png
      :width: 200pt

  .. cpp:function:: reloadCollision(bool withDebug = false)

    Function to reload the Collision

    **Parameters:**

    - ``bool withDebug``: if its called in Debug-Mode (Standard: false)

    **Example**: Reloads Collision

    .. code-block:: lua

        be:reloadCollision()

  .. cpp:function:: string makeRelativePath(string path, string to)

    **Parameters:**

    - ``string path``: The curent path
    - ``string to``: where does it goes to?

    :returns: (string) the relative path

    **Example**:

    .. code-block:: lua

      local path = be:makeRelativePath("levels/derby/info.json", "/C/")
      print(path)
      -- prints f.e.: C:/Users/erik/Desktop/BeamNG/levels/derby/info.json


  .. cpp:function:: string getWorkingDirectory()

    Gets the Working Directory path

    :returns: (string) the path

    **Example:**

    .. code-block:: lua

        local path = be:getWorkingDirectory()
        print(path)
        --prints C:/Users/supercooluser/Desktop/BeamNG

  .. cpp:function:: bool decalManagerLoad(string fileName)

  .. cpp:function:: deleteDataBlocks()

  .. cpp:member:: string persistenceLuaData

  //TODO All almost all member are nil?

  .. cpp:member:: BeamNGNodeStreamPhysFS nodeStream

  .. cpp:member:: bool interpolateCenter

  .. cpp:member:: bool interpolateNodes

  .. cpp:member:: bool interpolateCircles

  .. cpp:member:: bool interpolateLua

  .. cpp:member:: BeamNGNodeGrabber nodeGrabber

  .. cpp:member:: bool physicsMaxSpeed

  .. cpp:member:: float physicsSimSpeedUp

  .. cpp:member:: float camY

  .. cpp:member:: float camX

  .. cpp:member:: float zoomInSpeed

  .. cpp:member:: float zoomOutSpeed