summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/sol2/docs/source/api
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/sol2/docs/source/api')
-rw-r--r--3rdparty/sol2/docs/source/api/api-top.rst46
-rw-r--r--3rdparty/sol2/docs/source/api/as_function.rst67
-rw-r--r--3rdparty/sol2/docs/source/api/as_table.rst24
-rw-r--r--3rdparty/sol2/docs/source/api/c_call.rst71
-rw-r--r--3rdparty/sol2/docs/source/api/compatibility.rst16
-rw-r--r--3rdparty/sol2/docs/source/api/coroutine.rst109
-rw-r--r--3rdparty/sol2/docs/source/api/error.rst15
-rw-r--r--3rdparty/sol2/docs/source/api/function.rst89
-rw-r--r--3rdparty/sol2/docs/source/api/make_reference.rst26
-rw-r--r--3rdparty/sol2/docs/source/api/metatable_key.rst154
-rw-r--r--3rdparty/sol2/docs/source/api/object.rst70
-rw-r--r--3rdparty/sol2/docs/source/api/optional.rst6
-rw-r--r--3rdparty/sol2/docs/source/api/overload.rst89
-rw-r--r--3rdparty/sol2/docs/source/api/property.rst64
-rw-r--r--3rdparty/sol2/docs/source/api/protect.rst33
-rw-r--r--3rdparty/sol2/docs/source/api/protected_function.rst185
-rw-r--r--3rdparty/sol2/docs/source/api/proxy.rst201
-rw-r--r--3rdparty/sol2/docs/source/api/readonly.rst11
-rw-r--r--3rdparty/sol2/docs/source/api/reference.rst75
-rw-r--r--3rdparty/sol2/docs/source/api/resolve.rst39
-rw-r--r--3rdparty/sol2/docs/source/api/simple_usertype.rst16
-rw-r--r--3rdparty/sol2/docs/source/api/stack.rst199
-rw-r--r--3rdparty/sol2/docs/source/api/stack_reference.rst8
-rw-r--r--3rdparty/sol2/docs/source/api/state.rst121
-rw-r--r--3rdparty/sol2/docs/source/api/table.rst208
-rw-r--r--3rdparty/sol2/docs/source/api/this_state.rst31
-rw-r--r--3rdparty/sol2/docs/source/api/thread.rst52
-rw-r--r--3rdparty/sol2/docs/source/api/tie.rst26
-rw-r--r--3rdparty/sol2/docs/source/api/types.rst207
-rw-r--r--3rdparty/sol2/docs/source/api/unique_usertype_traits.rst44
-rw-r--r--3rdparty/sol2/docs/source/api/user.rst19
-rw-r--r--3rdparty/sol2/docs/source/api/userdata.rst13
-rw-r--r--3rdparty/sol2/docs/source/api/usertype.rst329
-rw-r--r--3rdparty/sol2/docs/source/api/usertype_memory.rst47
-rw-r--r--3rdparty/sol2/docs/source/api/var.rst49
-rw-r--r--3rdparty/sol2/docs/source/api/variadic_args.rst49
36 files changed, 2808 insertions, 0 deletions
diff --git a/3rdparty/sol2/docs/source/api/api-top.rst b/3rdparty/sol2/docs/source/api/api-top.rst
new file mode 100644
index 00000000000..f9b0378b30e
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/api-top.rst
@@ -0,0 +1,46 @@
+api reference manual
+====================
+
+Browse the various function and classes :doc:`Sol<../index>` utilizes to make your life easier when working with Lua.
+
+
+.. toctree::
+ :caption: Sol API
+ :name: apitoc
+ :maxdepth: 2
+
+ state
+ table
+ proxy
+ as_table
+ usertype
+ simple_usertype
+ usertype_memory
+ unique_usertype_traits
+ tie
+ function
+ protected_function
+ coroutine
+ error
+ object
+ userdata
+ reference
+ thread
+ stack_reference
+ make_reference
+ optional
+ this_state
+ variadic_args
+ overload
+ property
+ var
+ protect
+ readonly
+ as_function
+ c_call
+ resolve
+ stack
+ user
+ compatibility
+ types
+ metatable_key
diff --git a/3rdparty/sol2/docs/source/api/as_function.rst b/3rdparty/sol2/docs/source/api/as_function.rst
new file mode 100644
index 00000000000..bb058ba52c7
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/as_function.rst
@@ -0,0 +1,67 @@
+as_function
+===========
+make sure an object is pushed as a function
+-------------------------------------------
+
+.. code-block:: cpp
+
+ template <typename Sig = sol::function_sig<>, typename... Args>
+ function_argumants<Sig, Args...> as_function ( Args&& ... );
+
+This function serves the purpose of ensuring that a callable struct (like a lambda) can be passed to the ``set( key, value )`` calls on :ref:`sol::table<set-value>` and be treated like a function binding instead of a userdata. It is recommended that one uses the :ref:`sol::table::set_function<set-function>` call instead, but if for some reason one must use ``set``, then ``as_function`` can help ensure a callable struct is handled like a lambda / callable, and not as just a userdata structure.
+
+This class can also make it so usertypes bind variable types as functions to for usertype bindings.
+
+.. code-block:: cpp
+
+ #include <sol.hpp>
+
+ int main () {
+ struct callable {
+ int operator()( int a, bool b ) {
+ return a + b ? 10 : 20;
+ }
+ };
+
+
+ sol::state lua;
+ // Binds struct as userdata
+ lua.set( "not_func", callable() );
+ // Binds struct as function
+ lua.set( "func", sol::as_function( callable() ) );
+ // equivalent: lua.set_function( "func", callable() );
+ // equivalent: lua["func"] = callable();
+ }
+
+Note that if you actually want a userdata, but you want it to be callable, you simply need to create a :ref:`sol::table::new_usertype<new-usertype>` and then bind the ``"__call"`` metamethod (or just use ``sol::meta_function::call`` :ref:`enumeration<meta_function_enum>`).
+
+Here's an example of binding a variable as a function to a usertype:
+
+.. code-block:: cpp
+
+ #include <sol.hpp>
+
+ int main () {
+ class B {
+ public:
+ int bvar = 24;
+ };
+
+ sol::state lua;
+ lua.open_libraries();
+ lua.new_usertype<B>("B",
+ // bind as variable
+ "b", &B::bvar,
+ // bind as function
+ "f", sol::as_function(&B::bvar)
+ );
+
+ B b;
+ lua.set("b", &b);
+ lua.script("x = b:f()");
+ lua.script("y = b.b");
+ int x = lua["x"];
+ int y = lua["y"];
+ assert(x == 24);
+ assert(y == 24);
+ }
diff --git a/3rdparty/sol2/docs/source/api/as_table.rst b/3rdparty/sol2/docs/source/api/as_table.rst
new file mode 100644
index 00000000000..58870fa770f
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/as_table.rst
@@ -0,0 +1,24 @@
+as_table
+===========
+make sure an object is pushed as a table
+----------------------------------------
+
+.. code-block:: cpp
+
+ template <typename T>
+ as_table_t { ... };
+
+ template <typename T>
+ as_table_t<T> as_function ( T&& container );
+
+This function serves the purpose of ensuring that an object is pushed -- if possible -- like a table into Lua. The container passed here can be a pointer, a reference, a ``std::reference_wrapper`` around a container, or just a plain container value. It must have a begin/end function, and if it has a ``std::pair<Key, Value>`` as its ``value_type``, it will be pushed as a dictionary. Otherwise, it's pushed as a sequence.
+
+.. code-block:: cpp
+
+ sol::state lua;
+ lua.open_libraries();
+ lua.set("my_table", sol::as_table(std::vector<int>{ 1, 2, 3, 4, 5 }));
+ lua.script("for k, v in ipairs(my_table) do print(k, v) assert(k == v) end");
+
+
+Note that any caveats with Lua tables apply the moment it is serialized, and the data cannot be gotten out back out in C++ as a vector without explicitly using the ``as_table_t`` marker for your get and conversion operations using Sol. \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/c_call.rst b/3rdparty/sol2/docs/source/api/c_call.rst
new file mode 100644
index 00000000000..36395eea549
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/c_call.rst
@@ -0,0 +1,71 @@
+c_call
+======
+Templated type to transport functions through templates
+-------------------------------------------------------
+
+.. code-block:: cpp
+
+ template <typename Function, Function f>
+ int c_call (lua_State* L);
+
+ template <typename... Functions>
+ int c_call (lua_State* L);
+
+The goal of ``sol::c_call<...>`` is to provide a way to wrap a function and transport it through a compile-time context. This enables faster speed at the cost of a much harder to read / poorer interface. ``sol::c_call`` expects a type for its first template argument, and a value of the previously provided type for the second template argument. To make a compile-time transported overloaded function, specify multiple functions in the same ``type, value`` pairing, but put it inside of a ``sol::wrap``. Note that is can also be placed into the argument list for a :doc:`usertype<usertype>` as well.
+
+It is advisable for the user to consider making a macro to do the necessary ``decltype( &function_name, ), function_name``. Sol does not provide one because many codebases already have `one similar to this`_.
+
+Here's an example below of various ways to use ``sol::c_call``:
+
+.. code-block:: cpp
+ :linenos:
+ :caption: Compile-time transported function calls
+
+ #include "sol.hpp"
+
+ int f1(int) { return 32; }
+ int f2(int, int) { return 1; }
+ struct fer {
+ double f3(int, int) {
+ return 2.5;
+ }
+ };
+
+
+ int main() {
+
+ sol::state lua;
+ // overloaded function f
+ lua.set("f", sol::c_call<sol::wrap<decltype(&f1), &f1>, sol::wrap<decltype(&f2), &f2>, sol::wrap<decltype(&fer::f3), &fer::f3>>);
+ // singly-wrapped function
+ lua.set("g", sol::c_call<sol::wrap<decltype(&f1), &f1>>);
+ // without the 'sol::wrap' boilerplate
+ lua.set("h", sol::c_call<decltype(&f2), &f2>);
+ // object used for the 'fer' member function call
+ lua.set("obj", fer());
+
+ // call them like any other bound function
+ lua.script("r1 = f(1)");
+ lua.script("r2 = f(1, 2)");
+ lua.script("r3 = f(obj, 1, 2)");
+ lua.script("r4 = g(1)");
+ lua.script("r5 = h(1, 2)");
+
+ // get the results and see
+ // if it worked out
+ int r1 = lua["r1"];
+ // r1 == 32
+ int r2 = lua["r2"];
+ // r2 == 1
+ double r3 = lua["r3"];
+ // r3 == 2.5
+ int r4 = lua["r4"];
+ // r4 == 32
+ int r5 = lua["r5"];
+ // r5 == 1
+
+ return 0;
+ }
+
+
+.. _one similar to this: http://stackoverflow.com/a/5628222/5280922
diff --git a/3rdparty/sol2/docs/source/api/compatibility.rst b/3rdparty/sol2/docs/source/api/compatibility.rst
new file mode 100644
index 00000000000..3299bff931b
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/compatibility.rst
@@ -0,0 +1,16 @@
+compatibility.hpp
+=================
+Lua 5.3/5.2 compatibility for Lua 5.1/LuaJIT
+--------------------------------------------
+
+This is a detail header used to maintain compatability with the 5.2 and 5.3 APIs. It contains code from the MIT-Licensed `Lua code`_ in some places and also from the `lua-compat`_ repository by KeplerProject.
+
+It is not fully documented as this header's only purpose is for internal use to make sure Sol compiles across all platforms / distributions with no errors or missing Lua functionality. If you think there's some compatibility features we are missing or if you are running into redefinition errors, please make an `issue in the issue tracker`_.
+
+If you have this already in your project or you have your own compatibility layer, then please ``#define SOL_NO_COMPAT 1`` before including ``sol.hpp`` or pass this flag on the command line to turn off the compatibility wrapper.
+
+For the licenses, see :doc:`here<../licenses>`
+
+.. _issue in the issue tracker: https://github.com/ThePhD/sol2/issues/
+.. _Lua code: http://www.Lua.org/
+.. _lua-compat: https://github.com/keplerproject/lua-compat-5.3 \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/coroutine.rst b/3rdparty/sol2/docs/source/api/coroutine.rst
new file mode 100644
index 00000000000..3d03da31f5c
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/coroutine.rst
@@ -0,0 +1,109 @@
+coroutine
+=========
+resumable/yielding functions from Lua
+-------------------------------------
+
+A ``coroutine`` is a :doc:`reference<reference>` to a function in Lua that can be called multiple times to yield a specific result. It is run on the :doc:`lua_State<state>` that was used to create it (see :doc:`thread<thread>` for an example on how to get a coroutine that runs on a thread separate from your usual "main" :doc:`lua_State<state>`).
+
+The ``coroutine`` object is entirely similar to the :doc:`protected_function<protected_function>` object, with additional member functions to check if a coroutine has yielded (:doc:`call_status::yielded<types>`) and is thus runnable again, whether it has completed (:ref:`call_status::ok<call-status>`) and thus cannot yield anymore values, or whether it has suffered an error (see :ref:`status()<status>` and :ref:`call_status<call-status>`'s error codes).
+
+For example, you can work with a coroutine like this:
+
+.. code-block:: lua
+ :caption: co.lua
+
+ function loop()
+ while counter ~= 30
+ do
+ coroutine.yield(counter);
+ counter = counter + 1;
+ end
+ return counter
+ end
+
+This is a function that yields:
+
+.. code-block:: cpp
+ :caption: main.cpp
+
+ sol::state lua;
+ lua.open_libraries(sol::lib::base, sol::lib::coroutine);
+ lua.script_file("co.lua");
+ sol::coroutine cr = lua["loop"];
+
+ for (int counter = 0; // start from 0
+ counter < 10 && cr; // we want 10 values, and we only want to run if the coroutine "cr" is valid
+ // Alternative: counter < 10 && cr.valid()
+ ++counter) {
+ // Call the coroutine, does the computation and then suspends
+ int value = cr();
+ }
+
+Note that this code doesn't check for errors: to do so, you can call the function and assign it as ``auto result = cr();``, then check ``result.valid()`` as is the case with :doc:`protected_function<protected_function>`. Finally, you can run this coroutine on another thread by doing the following:
+
+.. code-block:: cpp
+ :caption: main_with_thread.cpp
+
+ sol::state lua;
+ lua.open_libraries(sol::lib::base, sol::lib::coroutine);
+ lua.script_file("co.lua");
+ sol::thread runner = sol::thread::create(lua.lua_state());
+ sol::state_view runnerstate = runner.state();
+ sol::coroutine cr = runnerstate["loop"];
+
+ for (int counter = 0; counter < 10 && cr; ++counter) {
+ // Call the coroutine, does the computation and then suspends
+ int value = cr();
+ }
+
+The following are the members of ``sol::coroutine``:
+
+members
+-------
+
+.. code-block:: cpp
+ :caption: function: constructor
+
+ coroutine(lua_State* L, int index = -1);
+
+Grabs the coroutine at the specified index given a ``lua_State*``.
+
+.. code-block:: cpp
+ :caption: returning the coroutine's status
+ :name: status
+
+ call_status status() const noexcept;
+
+Returns the status of a coroutine.
+
+
+.. code-block:: cpp
+ :caption: checks for an error
+
+ bool error() const noexcept;
+
+Checks if an error occured when the coroutine was run.
+
+.. _runnable:
+
+.. code-block:: cpp
+ :caption: runnable and explicit operator bool
+
+ bool runnable () const noexcept;
+ explicit operator bool() const noexcept;
+
+These functions allow you to check if a coroutine can still be called (has more values to yield and has not errored). If you have a coroutine object ``coroutine my_co = /*...*/``, you can either check ``runnable()`` or do ``if ( my_co ) { /* use coroutine */ }``.
+
+.. code-block:: cpp
+ :caption: calling a coroutine
+
+ template<typename... Args>
+ protected_function_result operator()( Args&&... args );
+
+ template<typename... Ret, typename... Args>
+ decltype(auto) call( Args&&... args );
+
+ template<typename... Ret, typename... Args>
+ decltype(auto) operator()( types<Ret...>, Args&&... args );
+
+Calls the coroutine. The second ``operator()`` lets you specify the templated return types using the ``my_co(sol::types<int, std::string>, ...)`` syntax. Check ``status()`` afterwards for more information about the success of the run or just check the coroutine object in an ifs tatement, as shown :ref:`above<runnable>`. \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/error.rst b/3rdparty/sol2/docs/source/api/error.rst
new file mode 100644
index 00000000000..4bfe21e91a4
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/error.rst
@@ -0,0 +1,15 @@
+error
+=====
+the single error/exception type
+-------------------------------
+
+.. code-block:: cpp
+
+ class error : public std::runtime_error {
+ public:
+ error(const std::string& str): std::runtime_error("Lua: error: " + str) {}
+ };
+
+If an eror is thrown by Sol, it is going to be of this type. We use this in a single place: the default ``at_panic`` function we bind on construction of a :ref:`sol::state<set-panic>`. If you turn :doc:`off exceptions<../exceptions>`, the chances of you seeing this error are nil unless you specifically use it to pull errors out of things such as :doc:`sol::protected_function<protected_function>`.
+
+As it derives from ``std::runtime_error``, which derives from ``std::exception``, you can catch it with a ``catch (const std::exception& )`` clause in your try/catch blocks. You can retrieve a string error from Lua (Lua pushes all its errors as string returns) by using this type with any of the get or lookup functions in Sol. \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/function.rst b/3rdparty/sol2/docs/source/api/function.rst
new file mode 100644
index 00000000000..27946117a8c
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/function.rst
@@ -0,0 +1,89 @@
+function
+========
+calling functions bound to Lua
+------------------------------
+
+.. code-block:: cpp
+
+ class function : public reference;
+
+Function is a correct-assuming version of :doc:`protected_function<protected_function>`, omitting the need for typechecks and error handling. It is the default function type of Sol. Grab a function directly off the stack using the constructor:
+
+.. code-block:: cpp
+ :caption: constructor: function
+
+ function(lua_State* L, int index = -1);
+
+
+When called without the return types being specified by either a ``sol::types<...>`` list or a ``call<Ret...>( ... )`` template type list, it generates a :ref:`function_result<function-result>` class that gets implicitly converted to the requested return type. For example:
+
+.. code-block:: lua
+ :caption: func_barks.lua
+ :linenos:
+
+ bark_power = 11;
+
+ function woof ( bark_energy )
+ return (bark_energy * (bark_power / 4))
+ end
+
+The following C++ code will call this function from this file and retrieve the return value:
+
+.. code-block:: cpp
+ :linenos:
+
+ sol::state lua;
+
+ lua.script_file( "func_barks.lua" );
+
+ sol::function woof = lua["woof"];
+ double numwoof = woof(20);
+
+The call ``woof(20)`` generates a :ref:`function_result<function-result>`, which is then implicitly converted to an ``double`` after being called. The intermediate temporary ``function_result`` is then destructed, popping the Lua function call results off the Lua stack.
+
+You can also return multiple values by using ``std::tuple``, or if you need to bind them to pre-existing variables use ``sol::tie``:
+
+.. code-block:: cpp
+ :linenos:
+
+ sol::state lua;
+
+ lua.script( "function f () return 10, 11, 12 end" );
+
+ sol::function f = lua["f"];
+ std::tuple<int, int, int> abc = f(); // 10, 11, 12 from Lua
+ // or
+ int a, b, c;
+ sol::tie(a, b, c) = f(); // a = 10, b = 11, c = 12 from Lua
+
+This makes it much easier to work with multiple return values. Using ``std::tie`` from the C++ standard will result in dangling references or bad behavior because of the very poor way in which C++ tuples/``std::tie`` were specified and implemented: please use ``sol::tie( ... )`` instead to satisfy any multi-return needs.
+
+.. _function-result-warning:
+
+.. warning::
+
+ Do NOT save the return type of a :ref:`function_result<function-result>` with ``auto``, as in ``auto numwoof = woof(20);``, and do NOT store it anywhere. Unlike its counterpart :ref:`protected_function_result<protected-function-result>`, ``function_result`` is NOT safe to store as it assumes that its return types are still at the top of the stack and when its destructor is called will pop the number of results the function was supposed to return off the top of the stack. If you mess with the Lua stack between saving ``function_result`` and it being destructed, you will be subject to an incredible number of surprising and hard-to-track bugs. Don't do it.
+
+.. code-block:: cpp
+ :caption: function: call operator / function call
+
+ template<typename... Args>
+ protected_function_result operator()( Args&&... args );
+
+ template<typename... Ret, typename... Args>
+ decltype(auto) call( Args&&... args );
+
+ template<typename... Ret, typename... Args>
+ decltype(auto) operator()( types<Ret...>, Args&&... args );
+
+Calls the function. The second ``operator()`` lets you specify the templated return types using the ``my_func(sol::types<int, std::string>, ...)`` syntax. Function assumes there are no runtime errors, and thusly will call the ``atpanic`` function if an error does occur.
+
+.. note::
+
+ All arguments are forwarded. Unlike :doc:`get/set/operator[] on sol::state<state>` or :doc:`sol::table<table>`, value semantics are not used here. It is forwarding reference semantics, which do not copy/move unless it is specifically done by the receiving functions / specifically done by the user.
+
+
+function call safety
+--------------------
+
+You can have functions here and on usertypes check to definitely make sure that the types passed to C++ functions are what they're supposed to be by adding a ``#define SOL_CHECK_ARGUMENTS`` before including Sol, or passing it on the command line. Otherwise, for speed reasons, these checks are only used where absolutely necessary (like discriminating between :doc:`overloads<overload>`). See :doc:`safety<../safety>` for more information. \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/make_reference.rst b/3rdparty/sol2/docs/source/api/make_reference.rst
new file mode 100644
index 00000000000..cd39b5a31d9
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/make_reference.rst
@@ -0,0 +1,26 @@
+make_object/make_reference
+==========================
+Create a value on the Lua stack and return it
+---------------------------------------------
+
+.. code-block:: cpp
+ :caption: function: make_reference
+ :name: make-reference
+
+ template <typename R = reference, bool should_pop = (R is not base of sol::stack_index), typename T>
+ R make_reference(lua_State* L, T&& value);
+ template <typename T, typename R = reference, bool should_pop = (R is base of sol::stack_index), typename... Args>
+ R make_reference(lua_State* L, Args&&... args);
+
+Makes an ``R`` out of the value. The first overload deduces the type from the passed in argument, the second allows you to specify a template parameter and forward any relevant arguments to ``sol::stack::push``. The type figured out for ``R`` is what is referenced from the stack. This allows you to request arbitrary pop-able types from Sol and have it constructed from ``R(lua_State* L, int stack_index)``. If the template boolean ``should_pop`` is ``true``, the value that was pushed will be popped off the stack. It defaults to popping, but if it encounters a type such as :doc:`sol::stack_reference<stack_reference>` (or any of its typically derived types in Sol), it will leave the pushed values on the stack.
+
+.. code-block:: cpp
+ :caption: function: make_object
+ :name: make-object
+
+ template <typename T>
+ object make_object(lua_State* L, T&& value);
+ template <typename T, typename... Args>
+ object make_object(lua_State* L, Args&&... args);
+
+Makes an object out of the value. It pushes it onto the stack, then pops it into the returned ``sol::object``. The first overload deduces the type from the passed in argument, the second allows you to specify a template parameter and forward any relevant arguments to ``sol::stack::push``. The implementation essentially defers to :ref:`sol::make_reference<make-reference>` with the specified arguments, ``R == object`` and ``should_pop == true``. It is preferred that one uses the :ref:`in_place object constructor instead<overloaded-object-constructor>`, since it's probably easier to deal with, but both versions will be supported for forever, since there's really no reason not to and people already have dependencies on ``sol::make_object``.
diff --git a/3rdparty/sol2/docs/source/api/metatable_key.rst b/3rdparty/sol2/docs/source/api/metatable_key.rst
new file mode 100644
index 00000000000..718eb2b2ffc
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/metatable_key.rst
@@ -0,0 +1,154 @@
+metatable_key
+=============
+A key for setting and getting an object's metatable
+---------------------------------------------------
+
+.. code-block:: cpp
+
+ struct metatable_key_t {};
+ const metatable_key_t metatable_key;
+
+You can use this in conjunction with :doc:`sol::table<table>` to set/get a metatable. Lua metatables are powerful ways to override default behavior of objects for various kinds of operators, among other things. Here is an entirely complete example, showing getting and working with a :doc:`usertype<usertype>`'s metatable defined by Sol:
+
+.. code-block:: cpp
+ :caption: messing with metatables
+ :linenos:
+
+ #include <sol.hpp>
+
+ int main () {
+
+ struct bark {
+ int operator()(int x) {
+ return x;
+ }
+ };
+
+ sol::state lua;
+ lua.open_libraries(sol::lib::base);
+
+ lua.new_usertype<bark>("bark",
+ sol::meta_function::call_function, &bark::operator()
+ );
+
+ bark b;
+ lua.set("b", &b);
+
+ sol::table b_as_table = lua["b"];
+ sol::table b_metatable = b_as_table[sol::metatable_key];
+ sol::function b_call = b_metatable["__call"];
+ sol::function b_as_function = lua["b"];
+
+ int result1 = b_as_function(1);
+ int result2 = b_call(b, 1);
+ // result1 == result2 == 1
+ }
+
+It's further possible to have a "Dynamic Getter" (`thanks to billw2012 and Nava2 for this example`_!):
+
+.. code-block:: cpp
+ :caption: One way to make dynamic properties (there are others!)
+ :linenos:
+
+ #include <sol.hpp>
+ #include <unordered_map>
+
+ struct PropertySet {
+ sol::object get_property_lua(const char* name, sol::this_state s)
+ {
+ auto& var = props[name];
+ return sol::make_object(s, var);
+ }
+
+ void set_property_lua(const char* name, sol::stack_object object)
+ {
+ props[name] = object.as<std::string>();
+ }
+
+ std::unordered_map<std::string, std::string> props;
+ };
+
+ struct DynamicObject {
+ PropertySet& get_dynamic_props() {
+ return dynamic_props;
+ }
+
+ PropertySet dynamic_props;
+ };
+
+
+ int main () {
+ sol::state lua;
+ lua.open_libraries(sol::lib::base);
+
+ lua.new_usertype<PropertySet>("PropertySet",
+ sol::meta_function::new_index, &PropertySet::set_property_lua,
+ sol::meta_function::index, &PropertySet::get_property_lua
+ );
+
+ lua.new_usertype<DynamicObject>("DynamicObject",
+ "props", sol::property(&DynamicObject::get_dynamic_props)
+ );
+
+ lua.script(R"(
+ obj = DynamicObject:new()
+ obj.props.name = 'test name'
+ print('name = ' .. obj.props.name)
+ )");
+
+ std::string name = lua["obj"]["props"]["name"];
+ // name == "test name";
+ }
+
+
+You can even manipulate the ability to set and get items using metatable objects on a usertype or similar:
+
+.. code-block:: cpp
+ :caption: messing with metatables - vector type
+ :linenos:
+
+ #include <sol.hpp>
+
+ class vector {
+ public:
+ double data[3];
+
+ vector() : data{ 0,0,0 } {}
+
+ double& operator[](int i)
+ {
+ return data[i];
+ }
+
+
+ static double my_index(vector& v, int i)
+ {
+ return v[i];
+ }
+
+ static void my_new_index(vector& v, int i, double x)
+ {
+ v[i] = x;
+ }
+ };
+
+ int main () {
+ sol::state lua;
+ lua.open_libraries(sol::lib::base);
+ lua.new_usertype<vector>("vector", sol::constructors<sol::types<>>(),
+ sol::meta_function::index, &vector::my_index,
+ sol::meta_function::new_index, &vector::my_new_index);
+ lua.script("v = vector.new()\n"
+ "print(v[1])\n"
+ "v[2] = 3\n"
+ "print(v[2])\n"
+ );
+
+ vector& v = lua["v"];
+ // v[0] == 0.0;
+ // v[1] == 0.0;
+ // v[2] == 3.0;
+ }
+
+
+.. _thanks to billw2012 and Nava2 for this example: https://github.com/ThePhD/sol2/issues/71#issuecomment-225402055 \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/object.rst b/3rdparty/sol2/docs/source/api/object.rst
new file mode 100644
index 00000000000..f38f089cc4d
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/object.rst
@@ -0,0 +1,70 @@
+object
+======
+general-purpose safety reference to an existing object
+------------------------------------------------------
+
+.. code-block:: cpp
+
+ class object : reference;
+
+
+``object``'s goal is to allow someone to pass around the most generic form of a reference to something in Lua (or propogate a ``nil``). It is the logical extension of :doc:`sol::reference<reference>`, and is used in :ref:`sol::table's iterators<table-iterators>`.
+
+
+members
+-------
+
+.. code-block:: cpp
+ :caption: overloaded constructor: object
+ :name: overloaded-object-constructor
+
+ template <typename T>
+ object(T&&);
+ object(lua_State* L, int index = -1);
+ template <typename T, typename... Args>
+ object(lua_State* L, in_place_t, T&& arg, Args&&... args);
+ template <typename T, typename... Args>
+ object(lua_State* L, in_place_type_t<T>, Args&&... args);
+
+There are 4 kinds of constructors here. One allows construction of an object from other reference types such as :doc:`sol::table<table>` and :doc:`sol::stack_reference<stack_reference>`. The second creates an object which references the specific element at the given index in the specified ``lua_State*``. The more advanced ``in_place...`` constructors create a single object by pushing the specified type ``T`` onto the stack and then setting it as the object. It gets popped from the stack afterwards (unless this is an instance of ``sol::stack_object``, in which case it is left on the stack). An example of using this and :doc:`sol::make_object<make_reference>` can be found in the `any_return example`_.
+
+.. code-block:: cpp
+ :caption: function: type conversion
+
+ template<typename T>
+ decltype(auto) as() const;
+
+Performs a cast of the item this reference refers to into the type ``T`` and returns it. It obeys the same rules as :ref:`sol::stack::get\<T><getter>`.
+
+.. code-block:: cpp
+ :caption: function: type check
+
+ template<typename T>
+ bool is() const;
+
+Performs a type check using the :ref:`sol::stack::check<checker>` api, after checking if the reference is valid.
+
+
+non-members
+-----------
+
+.. code-block:: cpp
+ :caption: functions: nil comparators
+
+ bool operator==(const object& lhs, const nil_t&);
+ bool operator==(const nil_t&, const object& rhs);
+ bool operator!=(const object& lhs, const nil_t&);
+ bool operator!=(const nil_t&, const object& rhs);
+
+These allow a person to compare an ``sol::object`` against :ref:`nil<nil>`, which essentially checks if an object references a non-nil value, like so:
+
+.. code-block:: cpp
+
+ if (myobj == sol::nil) {
+ // doesn't have anything...
+ }
+
+Use this to check objects.
+
+
+.. _any_return example: https://github.com/ThePhD/sol2/blob/develop/examples/any_return.cpp \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/optional.rst b/3rdparty/sol2/docs/source/api/optional.rst
new file mode 100644
index 00000000000..f999849bcd9
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/optional.rst
@@ -0,0 +1,6 @@
+optional<T>
+===========
+
+This is an implemention of `optional from the standard library`_. If it detects that a proper optional exists, it will attempt to use it. This is mostly an implementation detail, used in the :ref:`sol::stack::check_get<stack-check-get>` and :ref:`sol::stack::get\<optional\<T>><stack-get>` and ``optional<T> maybe_value = table["arf"];`` implementations for additional safety reasons.
+
+.. _optional from the standard library: http://en.cppreference.com/w/cpp/utility/optional \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/overload.rst b/3rdparty/sol2/docs/source/api/overload.rst
new file mode 100644
index 00000000000..399b409d1af
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/overload.rst
@@ -0,0 +1,89 @@
+overload
+========
+calling different functions based on argument number/type
+---------------------------------------------------------
+
+this function helps users make overloaded functions that can be called from Lua using 1 name but multiple arguments. It is meant to replace the spaghetti of code whre users mock this up by doing strange if statemetns and switches on what version of a function to call based on `luaL_check{number/udata/string}`_. Its use is simple: whereever you can pass a function type to Lua, whether its on a :doc:`usertype<usertype>` or if you are just setting any kind of function with ``set`` or ``set_function`` (for :doc:`table<table>` or :doc:`state(_view)<state>`), simply wrap up the functions you wish to be considered for overload resolution on one function like so:
+
+.. code-block:: cpp
+
+ sol::overload( func1, func2, ... funcN );
+
+
+The functions can be any kind of function / function object (lambda). Given these functions and struct:
+
+.. code-block:: cpp
+ :linenos:
+
+ struct pup {
+ int barks = 0;
+
+ void bark () {
+ ++barks; // bark!
+ }
+
+ bool is_cute () const {
+ return true;
+ }
+ };
+
+ void ultra_bark( pup& p, int barks) {
+ for (; barks --> 0;) p.bark();
+ }
+
+ void picky_bark( pup& p, std::string s) {
+ if ( s == "bark" )
+ p.bark();
+ }
+
+You then use it just like you would for any other part of the api:
+
+.. code-block:: cpp
+ :linenos:
+
+ sol::state lua;
+
+ lua.set_function( "bark", sol::overload(
+ ultra_bark,
+ []() { return "the bark from nowhere"; }
+ ) );
+
+ lua.new_usertype<pup>( "pup",
+ // regular function
+ "is_cute", &pup::is_cute,
+ // overloaded function
+ "bark", sol::overload( &pup::bark, &picky_bark )
+ );
+
+Thusly, doing the following in Lua:
+
+.. code-block:: Lua
+ :caption: pup.lua
+ :linenos:
+
+ local barker = pup.new()
+ pup:bark() -- calls member function pup::bark
+ pup:bark(20) -- calls ultra_bark
+ pup:bark("meow") -- picky_bark, no bark
+ pup:bark("bark") -- picky_bark, bark
+
+ bark(pup, 20) -- calls ultra_bark
+ local nowherebark = bark() -- calls lambda which returns that string
+
+The actual class produced by ``sol::overload`` is essentially a type-wrapper around ``std::tuple`` that signals to the library that an overload is being created:
+
+.. code-block:: cpp
+ :caption: function: create overloaded set
+ :linenos:
+
+ template <typename... Args>
+ struct overloaded_set : std::tuple<Args...> { /* ... */ };
+
+ template <typename... Args>
+ overloaded_set<Args...> overload( Args&&... args );
+
+.. note::
+
+ Please keep in mind that doing this bears a runtime cost to find the proper overload. The cost scales directly not exactly with the number of overloads, but the number of functions that have the same argument count as each other (Sol will early-eliminate any functions that do not match the argument count).
+
+.. _luaL_check{number/udata/string}: http://www.Lua.org/manual/5.3/manual.html#luaL_checkinteger
diff --git a/3rdparty/sol2/docs/source/api/property.rst b/3rdparty/sol2/docs/source/api/property.rst
new file mode 100644
index 00000000000..e3ee02e2353
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/property.rst
@@ -0,0 +1,64 @@
+property
+========
+
+.. code-block:: cpp
+
+ template <typename Read, typename Write>
+ decltype(auto) property ( Read&& read_function, Write&& write_function );
+ template <typename Read>
+ decltype(auto) property ( Read&& read_function );
+ template <typename Write>
+ decltype(auto) property ( Write&& write_function );
+
+These set of functions create a type which allows a setter and getter pair (or a single getter, or a single setter) to be used to create a variable that is either read-write, read-only, or write-only. When used during :doc:`usertype<usertype>` construction, it will create a variable that uses the setter/getter member function specified.
+
+.. code-block:: cpp
+ :caption: player.hpp
+ :linenos:
+
+ class Player {
+ public:
+ int get_hp() const {
+ return hp;
+ }
+
+ void set_hp( int value ) {
+ hp = value;
+ }
+
+ int get_max_hp() const {
+ return hp;
+ }
+
+ void set_max_hp( int value ) {
+ maxhp = value;
+ }
+
+ private:
+ int hp = 50;
+ int maxHp = 50;
+ }
+
+.. code-block:: cpp
+ :caption: game.cpp
+ :linenos:
+
+ sol::state lua;
+ lua.open_libraries(sol::lib::base);
+
+ lua.set("theplayer", Player());
+
+ // Yes, you can register after you set a value and it will
+ // connect up the usertype automatically
+ lua.new_usertype<Player>( "Player",
+ "hp", sol::property(&Player::get_hp, &Player::set_hp),
+ "maxHp", sol::property(&Player::get_max_hp, &Player::set_max_hp)
+ );
+
+
+.. code-block:: lua
+ :caption: game-snippet.lua
+
+ -- variable syntax, calls functions
+ theplayer.hp = 20
+ print(theplayer.hp) \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/protect.rst b/3rdparty/sol2/docs/source/api/protect.rst
new file mode 100644
index 00000000000..4f14cb0db2a
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/protect.rst
@@ -0,0 +1,33 @@
+protect
+=======
+Routine to mark a function / variable as requiring safety
+---------------------------------------------------------
+
+.. code-block:: cpp
+
+ template <typename T>
+ auto protect( T&& value );
+
+``sol::protect( my_func )`` allows you to protect a function call or member variable call when it is being set to Lua. It can be used with usertypes or when just setting a function into Sol. Below is an example that demonstrates that a call that would normally not error without :doc:`Safety features turned on<../safety>` that instead errors and makes the Lua safety-call wrapper ``pcall`` fail:
+
+.. code-block:: cpp
+
+ struct protect_me {
+ int gen(int x) {
+ return x;
+ }
+ };
+
+ sol::state lua;
+ lua.open_libraries(sol::lib::base);
+ lua.new_usertype<protect_me>("protect_me",
+ "gen", sol::protect( &protect_me::gen )
+ );
+
+ lua.script(R"__(
+ pm = protect_me.new()
+ value = pcall(pm.gen,pm)
+ )__");
+ );
+ bool value = lua["value"];
+ // value == false
diff --git a/3rdparty/sol2/docs/source/api/protected_function.rst b/3rdparty/sol2/docs/source/api/protected_function.rst
new file mode 100644
index 00000000000..97d4e09f14f
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/protected_function.rst
@@ -0,0 +1,185 @@
+protected_function
+==================
+Lua function calls that trap errors and provide error handling
+--------------------------------------------------------------
+
+.. code-block:: cpp
+
+ class protected_function : public reference;
+
+Inspired by a request from `starwing<https://github.com/starwing>` in the old repository, this class provides the same interface as :doc:`function<function>` but with heavy protection and a potential error handler for any Lua errors and C++ exceptions. You can grab a function directly off the stack using the constructor, or pass to it 2 valid functions, which we'll demonstrate a little later.
+
+When called without the return types being specified by either a ``sol::types<...>`` list or a ``call<Ret...>( ... )`` template type list, it generates a :doc:`protected_function_result<proxy>` class that gets implicitly converted to the requested return type. For example:
+
+.. code-block:: lua
+ :caption: pfunc_barks.lua
+ :linenos:
+
+ bark_power = 11;
+
+ function got_problems( error_msg )
+ return "got_problems handler: " .. error_msg
+ end
+
+ function woof ( bark_energy )
+ if bark_energy < 20
+ error("*whine*")
+ end
+ return (bark_energy * (bark_power / 4))
+ end
+
+ function woofers ( bark_energy )
+ if bark_energy < 10
+ error("*whine*")
+ end
+ return (bark_energy * (bark_power / 4))
+ end
+
+The following C++ code will call this function from this file and retrieve the return value, unless an error occurs, in which case you can bind an error handling function like so:
+
+.. code-block:: cpp
+ :linenos:
+
+ sol::state lua;
+
+ lua.open_file( "pfunc_barks.lua" );
+
+ sol::protected_function problematicwoof = lua["woof"];
+ problematicwoof.error_handler = lua["got_problems"];
+
+ auto firstwoof = problematic_woof(20);
+ if ( firstwoof.valid() ) {
+ // Can work with contents
+ double numwoof = first_woof;
+ }
+ else{
+ // An error has occured
+ sol::error err = first_woof;
+ }
+
+ // errors, calls handler and then returns a string error from Lua at the top of the stack
+ auto secondwoof = problematic_woof(19);
+ if (secondwoof.valid()) {
+ // Call succeeded
+ double numwoof = secondwoof;
+ }
+ else {
+ // Call failed
+ // Note that if the handler was successfully called, this will include
+ // the additional appended error message information of
+ // "got_problems handler: " ...
+ sol::error err = secondwoof;
+ std::string what = err.what();
+ }
+
+This code is much more long-winded than its :doc:`function<function>` counterpart but allows a person to check for errors. The type here for ``auto`` are ``sol::protected_function_result``. They are implicitly convertible to result types, like all :doc:`proxy-style<proxy>` types are.
+
+Alternatively, with a bad or good function call, you can use ``sol::optional`` to check if the call succeeded or failed:
+
+.. code-block:: cpp
+ :linenos:
+
+ sol::state lua;
+
+ lua.open_file( "pfunc_barks.lua" );
+
+ sol::protected_function problematicwoof = lua["woof"];
+ problematicwoof.error_handler = lua["got_problems"];
+
+ sol::optional<double> maybevalue = problematicwoof(19);
+ if (maybevalue) {
+ // Have a value, use it
+ double numwoof = maybevalue.value();
+ }
+ else {
+ // No value!
+ }
+
+That makes the code a bit more concise and easy to reason about if you don't want to bother with reading the error. Thankfully, unlike ``sol::function_result``, you can save ``sol::protected_function_result`` in a variable and push/pop things above it on the stack where its returned values are. This makes it a bit more flexible than the rigid, performant ``sol::function_result`` type that comes from calling :doc:`sol::function<function>`.
+
+If you're confident the result succeeded, you can also just put the type you want (like ``double`` or ``std::string`` right there and it will get it. But, if it doesn't work out, sol can throw and/or panic if you have the :doc:`safety<../safety>` features turned on:
+
+.. code-block:: cpp
+ :linenos:
+
+ sol::state lua;
+
+ lua.open_file( "pfunc_barks.lua" );
+
+ // construct with function + error handler
+ // shorter than old syntax
+ sol::protected_function problematicwoof(lua["woof"], lua["got_problems"]);
+
+ // dangerous if things go wrong!
+ double value = problematicwoof(19);
+
+
+Finally, it is *important* to note you can set a default handler. The function is described below: please use it to avoid having to constantly set error handlers:
+
+.. code-block:: cpp
+ :linenos:
+
+ sol::state lua;
+
+ lua.open_file( "pfunc_barks.lua" );
+ // sets got_problems as the default
+ // handler for all protected_function errors
+ sol::protected_function::set_default_handler(lua["got_problems"]);
+
+ sol::protected_function problematicwoof = lua["woof"];
+ sol::protected_function problematicwoofers = lua["woofers"];
+
+ double value = problematicwoof(19);
+ double value2 = problematicwoof(9);
+
+
+members
+-------
+
+.. code-block:: cpp
+ :caption: constructor: protected_function
+
+ template <typename T>
+ protected_function( T&& func, reference handler = sol::protected_function::get_default_handler() );
+ protected_function( lua_State* L, int index = -1, reference handler = sol::protected_function::get_default_handler() );
+
+Constructs a ``protected_function``. Use the 2-argument version to pass a custom error handling function more easily. You can also set the :ref:`member variable error_handler<protected-function-error-handler>` after construction later. ``protected_function`` will always use the latest error handler set on the variable, which is either what you passed to it or the default *at the time of construction*.
+
+.. code-block:: cpp
+ :caption: function: call operator / protected function call
+
+ template<typename... Args>
+ protected_function_result operator()( Args&&... args );
+
+ template<typename... Ret, typename... Args>
+ decltype(auto) call( Args&&... args );
+
+ template<typename... Ret, typename... Args>
+ decltype(auto) operator()( types<Ret...>, Args&&... args );
+
+Calls the function. The second ``operator()`` lets you specify the templated return types using the ``my_func(sol::types<int, std::string>, ...)`` syntax. If you specify no return type in any way, it produces s ``protected_function_result``.
+
+.. note::
+
+ All arguments are forwarded. Unlike :doc:`get/set/operator[] on sol::state<state>` or :doc:`sol::table<table>`, value semantics are not used here. It is forwarding reference semantics, which do not copy/move unless it is specifically done by the receiving functions / specifically done by the user.
+
+
+.. code-block:: cpp
+ :caption: default handlers
+
+ static const reference& get_default_handler ();
+ static void set_default_handler( reference& ref );
+
+Get and set the Lua entity that is used as the default error handler. The default is a no-ref error handler. You can change that by calling ``protected_function::set_default_handler( lua["my_handler"] );`` or similar: anything that produces a reference should be fine.
+
+.. code-block:: cpp
+ :caption: variable: handler
+ :name: protected-function-error-handler
+
+ reference error_handler;
+
+The error-handler that is called should a runtime error that Lua can detect occurs. The error handler function needs to take a single string argument (use type std::string if you want to use a C++ function bound to lua as the error handler) and return a single string argument (again, return a std::string or string-alike argument from the C++ function if you're using one as the error handler). If :doc:`exceptions<../exceptions>` are enabled, Sol will attempt to convert the ``.what()`` argument of the exception into a string and then call the error handling function. It is a :doc:`reference<reference>`, as it must refer to something that exists in the lua registry or on the Lua stack. This is automatically set to the default error handler when ``protected_function`` is constructed.
+
+.. note::
+
+ ``protected_function_result`` safely pops its values off the stack when its destructor is called, keeping track of the index and number of arguments that were supposed to be returned. If you remove items below it using ``lua_remove``, for example, it will not behave as expected. Please do not perform fundamentally stack-rearranging operations until the destructor is called (pushing/popping above it is just fine).
diff --git a/3rdparty/sol2/docs/source/api/proxy.rst b/3rdparty/sol2/docs/source/api/proxy.rst
new file mode 100644
index 00000000000..897dbbaf7dd
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/proxy.rst
@@ -0,0 +1,201 @@
+proxy, (protected\_)function_result - proxy_base derivatives
+============================================================
+``table[x]`` and ``function(...)`` conversion struct
+----------------------------------------------------
+
+.. code-block:: c++
+
+ template <typename Recurring>
+ struct proxy_base;
+
+ template <typename Table, typename Key>
+ struct proxy : proxy_base<...>;
+
+ struct stack_proxy: proxy_base<...>;
+
+ struct function_result : proxy_base<...>;
+
+ struct protected_function_result: proxy_base<...>;
+
+
+These classes provide implicit assignment operator ``operator=`` (for ``set``) and an implicit conversion operator ``operator T`` (for ``get``) to support items retrieved from the underlying Lua implementation, specifically :doc:`sol::table<table>` and the results of function calls on :doc:`sol::function<function>` and :doc:`sol::protected_function<protected_function>`.
+
+.. _proxy:
+
+proxy
+-----
+
+``proxy`` is returned by lookups into :doc:`sol::table<table>` and table-like entities. Because it is templated on key and table type, it would be hard to spell: you can capture it using the word ``auto`` if you feel like you need to carry it around for some reason before using it. ``proxy`` evaluates its arguments lazily, when you finally call ``get`` or ``set`` on it. Here are some examples given the following lua script.
+
+.. code-block:: lua
+ :linenos:
+ :caption: lua nested table script
+
+ bark = {
+ woof = {
+ [2] = "arf!"
+ }
+ }
+
+
+After loading that file in or putting it in a string and reading the string directly in lua (see :doc:`state`), you can start kicking around with it in C++ like so:
+
+.. code-block:: c++
+ :linenos:
+
+ sol::state lua;
+
+ // produces proxy, implicitly converts to std::string, quietly destroys proxy
+ std::string x = lua["bark"]["woof"][2];
+
+
+``proxy`` lazy evaluation:
+
+.. code-block:: c++
+ :linenos:
+ :caption: multi-get
+
+ auto x = lua["bark"];
+ auto y = x["woof"];
+ auto z = x[2];
+ // retrivies value inside of lua table above
+ std::string value = z; // "arf!"
+ // Can change the value later...
+ z = 20;
+ // Yay, lazy-evaluation!
+ int changed_value = z; // now it's 20!
+
+
+We don't recommend the above to be used across classes or between function: it's more of something you can do to save a reference to a value you like, call a script or run a lua function, and then get it afterwards. You can also set functions (and function objects :ref:`*<note 1>`) this way, and retrieve them as well.
+
+.. code-block:: c++
+ :linenos:
+
+ lua["bark_value"] = 24;
+ lua["chase_tail"] = floof::chase_tail; // chase_tail is a free function
+
+
+members
+-------
+
+.. code-block:: c++
+ :caption: functions: [overloaded] implicit conversion get
+ :name: implicit-get
+
+ requires( sol::is_primitive_type<T>::value == true )
+ template <typename T>
+ operator T() const;
+
+ requires( sol::is_primitive_type<T>::value == false )
+ template <typename T>
+ operator T&() const;
+
+Gets the value associated with the keys the proxy was generated and convers it to the type ``T``. Note that this function will always return ``T&``, a non-const reference, to types which are not based on :doc:`sol::reference<reference>` and not a :doc:`primitive lua type<types>`
+
+.. code-block:: c++
+ :caption: function: get a value
+ :name: regular-get
+
+ template <typename T>
+ decltype(auto) get( ) const;
+
+Gets the value associated with the keys and converts it to the type ``T``.
+
+.. code-block:: c++
+ :caption: function: optionally get a value
+ :name: regular-get-or
+
+ template <typename T, typename Otherwise>
+ optional<T> get_or( Otherwise&& otherise ) const;
+
+Gets the value associated with the keys and converts it to the type ``T``. If it is not of the proper type, it will return a ``sol::nullopt`` instead.
+
+``operator[]`` proxy-only members
+---------------------------------
+
+.. code-block:: c++
+ :caption: function: valid
+ :name: proxy-valid
+
+ bool valid () const;
+
+Returns whether this proxy actually refers to a valid object. It uses :ref:`sol::stack::probe_get_field<stack-probe-get-field>` to determine whether or not its valid.
+
+.. code-block:: c++
+ :caption: functions: [overloaded] implicit set
+ :name: implicit-set
+
+ requires( sol::detail::Function<Fx> == false )
+ template <typename T>
+ proxy& operator=( T&& value );
+
+ requires( sol::detail::Function<Fx> == true )
+ template <typename Fx>
+ proxy& operator=( Fx&& function );
+
+Sets the value associated with the keys the proxy was generated with to ``value``. If this is a function, calls ``set_function``. If it is not, just calls ``set``. Does not exist on :ref:`function_result<function-result>` or :ref:`protected_function_result<protected-function-result>`. See :ref:`note<note 1>` for caveats.
+
+.. code-block:: c++
+ :caption: function: set a callable
+ :name: regular-set-function
+
+ template <typename Fx>
+ proxy& set_function( Fx&& fx );
+
+Sets the value associated with the keys the proxy was generated with to a function ``fx``. Does not exist on :ref:`function_result<function-result>` or :ref:`protected_function_result<protected-function-result>`.
+
+
+.. code-block:: c++
+ :caption: function: set a value
+ :name: regular-set
+
+ template <typename T>
+ proxy& set( T&& value );
+
+Sets the value associated with the keys the proxy was generated with to ``value``. Does not exist on :ref:`function_result<function-result>` or :ref:`protected_function_result<protected-function-result>`.
+
+stack_proxy
+-----------
+
+``sol::stack_proxy`` is what gets returned by :doc:`sol::variadic_args<variadic_args>` and other parts of the framework. It is similar to proxy, but is meant to alias a stack index and not a named variable.
+
+.. _function-result:
+
+function_result
+---------------
+
+``function_result`` is a temporary-only, intermediate-only implicit conversion worker for when :doc:`function<function>` is called. It is *NOT* meant to be stored or captured with ``auto``. It provides fast access to the desired underlying value. It does not implement ``set`` / ``set_function`` / templated ``operator=``, as is present on :ref:`proxy<proxy>`.
+
+
+.. _protected-function-result:
+
+protected_function_result
+-------------------------
+
+``protected_function_result`` is a nicer version of ``function_result`` that can be used to detect errors. Its gives safe access to the desired underlying value. It does not implement ``set`` / ``set_function`` / templated ``operator=`` as is present on :ref:`proxy<proxy>`.
+
+
+.. _note 1:
+
+on function objects and proxies
+-------------------------------
+
+Consider the following:
+
+.. code-block:: cpp
+ :linenos:
+ :caption: Note 1 Case
+
+ struct doge {
+ int bark;
+
+ void operator()() {
+ bark += 1;
+ }
+ };
+
+ sol::state lua;
+ lua["object"] = doge{}; // bind constructed doge to "object"
+ // but it binds as a function
+
+When you use the ``lua["object"] = doge{};`` from above, keep in mind that Sol detects if this is a function *callable with any kind of arguments*. Since ``doge`` has overriden ``return_type operator()( argument_types... )`` on itself, it results in satisfying the ``requires`` constraint from above. This means that if you have a user-defined type you want to bind as a :doc:`userdata with usertype semantics<usertype>` with this syntax, it might get bound as a function and not as a user-defined type (d'oh!). use ``lua["object"].set(doge)`` directly to avoid this, or ``lua["object"].set_function(doge{})`` to perform this explicitly. \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/readonly.rst b/3rdparty/sol2/docs/source/api/readonly.rst
new file mode 100644
index 00000000000..3a9517f1058
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/readonly.rst
@@ -0,0 +1,11 @@
+readonly
+========
+Routine to mark a member variable as read-only
+----------------------------------------------
+
+.. code-block:: cpp
+
+ template <typename T>
+ auto readonly( T&& value );
+
+The goal of read-only is to protect a variable set on a usertype or a function. Simply wrap it around a member variable, e.g. ``sol::readonly( &my_class::my_member_variable )`` in the appropriate place to use it. If someone tries to set it, it will throw an error.
diff --git a/3rdparty/sol2/docs/source/api/reference.rst b/3rdparty/sol2/docs/source/api/reference.rst
new file mode 100644
index 00000000000..37886dc2300
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/reference.rst
@@ -0,0 +1,75 @@
+reference
+=========
+general purpose reference to Lua object in registry
+---------------------------------------------------
+
+.. code-block:: cpp
+ :caption: reference
+
+ class reference;
+
+This type keeps around a reference to something that was on the stack and places it in the Lua registry. It is the backbone for all things that reference items on the stack and needs to keep them around beyond their appearance and lifetime on said Lua stack. Its progeny include :doc:`sol::coroutine<coroutine>`, :doc:`sol::function<function>`, :doc:`sol::protected_function<protected_function>`, :doc:`sol::object<object>`, :doc:`sol::table<table>`/:doc:`sol::global_table<table>`, :doc:`sol::thread<thread>`, and :doc:`sol::userdata<userdata>`.
+
+For all of these types, there's also a ``stack_{x}`` version of them, such as ``stack_table``
+
+
+members
+-------
+
+.. code-block:: cpp
+ :caption: constructor: reference
+
+ reference(lua_State* L, int index = -1);
+
+Creates a reference from the Lua stack at the specified index, saving it into the metatable registry. This constructor is exposed on all types that derive from ``sol::reference``.
+
+.. code-block:: cpp
+ :caption: function: push referred-to element from the stack
+
+ int push() const noexcept;
+
+This function pushes the referred-to data onto the stack and returns how many things were pushed. Typically, it returns 1.
+
+.. code-block:: cpp
+ :caption: function: reference value
+
+ int registry_index() const noexcept;
+
+The value of the reference in the registry.
+
+.. code-block:: cpp
+ :caption: functions: non-nil, non-null check
+
+ bool valid () const noexcept;
+ explicit operator bool () const noexcept;
+
+These functions check if the reference at ``T`` is valid: that is, if it is not :ref:`nil<nil>` and if it is not non-existing (doesn't refer to anything, including nil) reference. The explicit operator bool allows you to use it in the context of an ``if ( my_obj )`` context.
+
+.. code-block:: cpp
+ :caption: function: retrieves the type
+
+ type get_type() const noexcept;
+
+Gets the :doc:`sol::type<types>` of the reference; that is, the Lua reference.
+
+.. code-block:: cpp
+ :caption: function: lua_State* of the reference
+
+ lua_State* lua_state() const noexcept;
+
+Gets the ``lua_State*`` this reference exists in.
+
+
+non-members
+-----------
+
+.. code-block:: cpp
+ :caption: functions: reference comparators
+
+ bool operator==(const reference&, const reference&);
+ bool operator!=(const reference&, const reference&);
+
+Compares two references using the Lua API's `lua_compare`_ for equality.
+
+
+.. _lua_compare: https://www.lua.org/manual/5.3/manual.html#lua_compare
diff --git a/3rdparty/sol2/docs/source/api/resolve.rst b/3rdparty/sol2/docs/source/api/resolve.rst
new file mode 100644
index 00000000000..d8811d43f5c
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/resolve.rst
@@ -0,0 +1,39 @@
+resolve
+=======
+utility to pick overloaded C++ function calls
+---------------------------------------------
+
+.. code-block:: cpp
+ :caption: function: resolve C++ overload
+
+ template <typename... Args, typename F>
+ auto resolve( F f );
+
+``resolve`` is a function that is meant to help users pick a single function out of a group of overloaded functions in C++. You can use it to pick overloads by specifying the signature as the first template argument. Given a collection of overloaded functions:
+
+.. code-block:: cpp
+ :linenos:
+
+ int overloaded(int x);
+ int overloaded(int x, int y);
+ int overloaded(int x, int y, int z);
+
+You can disambiguate them using ``resolve``:
+
+.. code-block:: cpp
+ :linenos:
+
+ auto one_argument_func = resolve<int(int)>( overloaded );
+ auto two_argument_func = resolve<int(int, int)>( overloaded );
+ auto three_argument_func = resolve<int(int, int, int)>( overloaded );
+
+This resolution becomes useful when setting functions on a :doc:`table<table>` or :doc:`state_view<state>`:
+
+.. code-block:: cpp
+ :linenos:
+
+ sol::state lua;
+
+ lua.set_function("a", resolve<int(int)>( overloaded ) );
+ lua.set_function("b", resolve<int(int, int)>( overloaded ));
+ lua.set_function("c", resolve<int(int, int, int)>( overloaded ));
diff --git a/3rdparty/sol2/docs/source/api/simple_usertype.rst b/3rdparty/sol2/docs/source/api/simple_usertype.rst
new file mode 100644
index 00000000000..e030ed92985
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/simple_usertype.rst
@@ -0,0 +1,16 @@
+simple_usertype
+==================
+structures and classes from C++ made available to Lua code (simpler)
+--------------------------------------------------------------------
+
+
+This type is no different from :doc:`regular usertype<usertype>`, but allows much of its work to be done at runtime instead of compile-time. You can reduce compilation times from a plain `usertype` when you have an exceedingly bulky registration listing.
+
+You can set functions incrementally to reduce compile-time burden with ``simple_usertype`` as well, as shown in `this example`_.
+
+Some developers used ``simple_usertype`` to have variables automatically be functions. To achieve this behavior, wrap the desired variable into :doc:`sol::as_function<as_function>`.
+
+The performance `seems to be good enough`_ to not warn about any implications of having to serialize things at runtime. You do run the risk of using (slightly?) more memory, however, since variables and functions need to be stored differently and separately from the metatable data itself like with a regular ``usertype``. The goal here was to avoid compiler complaints about too-large usertypes (some individuals needed to register 190+ functions, and the compiler choked from the templated implementation of ``usertype``). As of Sol 2.14, this implementation has been heavily refactored to allow for all the same syntax and uses of usertype to apply here, with no caveats/exceptions.
+
+.. _seems to be good enough: https://github.com/ThePhD/sol2/issues/202#issuecomment-246767629
+.. _this example: https://github.com/ThePhD/sol2/blob/develop/examples/usertype_simple.cpp \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/stack.rst b/3rdparty/sol2/docs/source/api/stack.rst
new file mode 100644
index 00000000000..0ebb2d2e40b
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/stack.rst
@@ -0,0 +1,199 @@
+stack namespace
+===============
+the nitty-gritty core abstraction layer over Lua
+------------------------------------------------
+
+.. code-block:: cpp
+
+ namespace stack
+
+If you find that the higher level abstractions are not meeting your needs, you may want to delve into the ``stack`` namespace to try and get more out of Sol. ``stack.hpp`` and the ``stack`` namespace define several utilities to work with Lua, including pushing / popping utilities, getters, type checkers, Lua call helpers and more. This namespace is not thoroughly documented as the majority of its interface is mercurial and subject to change between releases to either heavily boost performance or improve the Sol :doc:`api<api-top>`.
+
+There are, however, a few :ref:`template customization points<extension_points>` that you may use for your purposes and a handful of potentially handy functions. These may help if you're trying to slim down the code you have to write, or if you want to make your types behave differently throughout the Sol stack. Note that overriding the defaults **can** throw out many of the safety guarantees Sol provides: therefore, modify the :ref:`extension points<extension_points>` at your own discretion.
+
+structures
+----------
+
+.. code-block:: cpp
+ :caption: struct: record
+ :name: stack-record
+
+ struct record {
+ int last;
+ int used;
+
+ void use(int count);
+ };
+
+This structure is for advanced usage with :ref:`stack::get<stack-get>` and :ref:`stack::check_get<stack-get>`. When overriding the customization points, it is important to call the ``use`` member function on this class with the amount of things you are pulling from the stack. ``used`` contains the total accumulation of items produced. ``last`` is the number of items gotten from the stack with the last operation (not necessarily popped from the stack). In all trivial cases for types, ``last == 1`` and ``used == 1`` after an operation; structures such as ``std::pair`` and ``std::tuple`` may pull more depending on the classes it contains.
+
+When overriding the :doc:`customization points<../tutorial/customization>`, please note that this structure should enable you to push multiple return values and get multiple return values to the stack, and thus be able to seamlessly pack/unpack return values from Lua into a single C++ struct, and vice-versa. This functionality is only recommended for people who need to customize the library further than the basics. It is also a good way to add support for the type and propose it back to the original library so that others may benefit from your work.
+
+Note that customizations can also be put up on a separate page here, if individuals decide to make in-depth custom ones for their framework or other places.
+
+members
+-------
+
+.. code-block:: cpp
+ :caption: function: get
+ :name: stack-get
+
+ template <typename T>
+ auto get( lua_State* L, int index = -1 )
+ template <typename T>
+ auto get( lua_State* L, int index, record& tracking )
+
+Retrieves the value of the object at ``index`` in the stack. The return type varies based on ``T``: with primitive types, it is usually ``T``: for all unrecognized ``T``, it is generally a ``T&`` or whatever the extension point :ref:`stack::getter\<T><getter>` implementation returns. The type ``T`` has top-level ``const`` qualifiers and reference modifiers removed before being forwarded to the extension point :ref:`stack::getter\<T><getter>` struct. ``stack::get`` will default to forwarding all arguments to the :ref:`stack::check_get<stack-check-get>` function with a handler of ``type_panic`` to strongly alert for errors, if you ask for the :doc:`safety<../safety>`.
+
+`record`
+
+You may also retrieve an :doc:`sol::optional\<T><optional>` from this as well, to have it attempt to not throw errors when performing the get and the type is not correct.
+
+.. code-block:: cpp
+ :caption: function: check
+ :name: stack-check
+
+ template <typename T>
+ bool check( lua_State* L, int index = -1 )
+
+ template <typename T, typename Handler>
+ bool check( lua_State* L, int index, Handler&& handler )
+
+Checks if the object at ``index`` is of type ``T``. If it is not, it will call the ``handler`` function with ``lua_State*``, ``int index``, ``type`` expected, and ``type`` actual as arguments.
+
+.. code-block:: cpp
+ :caption: function: check_get
+ :name: stack-check-get
+
+ template <typename T>
+ auto check_get( lua_State* L, int index = -1 )
+ template <typename T, typename Handler>
+ auto check_get( lua_State* L, int index, Handler&& handler, record& tracking )
+
+Retrieves the value of the object at ``index`` in the stack, but does so safely. It returns an ``optional<U>``, where ``U`` in this case is the return type deduced from ``stack::get<T>``. This allows a person to properly check if the type they're getting is what they actually want, and gracefully handle errors when working with the stack if they so choose to. You can define ``SOL_CHECK_ARGUMENTS`` to turn on additional :doc:`safety<../safety>`, in which ``stack::get`` will default to calling this version of the function with a handler of ``type_panic`` to strongly alert for errors and help you track bugs if you suspect something might be going wrong in your system.
+
+.. code-block:: cpp
+ :caption: function: push
+ :name: stack-push
+
+ // push T inferred from call site, pass args... through to extension point
+ template <typename T, typename... Args>
+ int push( lua_State* L, T&& item, Args&&... args )
+
+ // push T that is explicitly specified, pass args... through to extension point
+ template <typename T, typename Arg, typename... Args>
+ int push( lua_State* L, Arg&& arg, Args&&... args )
+
+ // recursively call the the above "push" with T inferred, one for each argument
+ template <typename... Args>
+ int multi_push( lua_State* L, Args&&... args )
+
+Based on how it is called, pushes a variable amount of objects onto the stack. in 99% of cases, returns for 1 object pushed onto the stack. For the case of a ``std::tuple<...>``, it recursively pushes each object contained inside the tuple, from left to right, resulting in a variable number of things pushed onto the stack (this enables multi-valued returns when binding a C++ function to a Lua). Can be called with ``sol::stack::push<T>( L, args... )`` to have arguments different from the type that wants to be pushed, or ``sol::stack::push( L, arg, args... )`` where ``T`` will be inferred from ``arg``. The final form of this function is ``sol::stack::multi_push``, which will call one ``sol::stack::push`` for each argument. The ``T`` that describes what to push is first sanitized by removing top-level ``const`` qualifiers and reference qualifiers before being forwarded to the extension point :ref:`stack::pusher\<T><pusher>` struct.
+
+.. code-block:: cpp
+ :caption: function: set_field
+
+ template <bool global = false, typename Key, typename Value>
+ void set_field( lua_State* L, Key&& k, Value&& v );
+
+ template <bool global = false, typename Key, typename Value>
+ void set_field( lua_State* L, Key&& k, Value&& v, int objectindex);
+
+Sets the field referenced by the key ``k`` to the given value ``v``, by pushing the key onto the stack, pushing the value onto the stack, and then doing the equivalent of ``lua_setfield`` for the object at the given ``objectindex``. Performs optimizations and calls faster verions of the function if the type of ``Key`` is considered a c-style string and/or if its also marked by the templated ``global`` argument to be a global.
+
+.. code-block:: cpp
+ :caption: function: get_field
+
+ template <bool global = false, typename Key>
+ void get_field( lua_State* L, Key&& k [, int objectindex] );
+
+Gets the field referenced by the key ``k``, by pushing the key onto the stack, and then doing the equivalent of ``lua_getfield``. Performs optimizations and calls faster verions of the function if the type of ``Key`` is considered a c-style string and/or if its also marked by the templated ``global`` argument to be a global.
+
+This function leaves the retrieved value on the stack.
+
+.. code-block:: cpp
+ :caption: function: probe_get_field
+ :name: stack-probe-get-field
+
+ template <bool global = false, typename Key>
+ probe probe_get_field( lua_State* L, Key&& k [, int objectindex] );
+
+Gets the field referenced by the key ``k``, by pushing the key onto the stack, and then doing the equivalent of ``lua_getfield``. Performs optimizations and calls faster verions of the function if the type of ``Key`` is considered a c-style string and/or if its also marked by the templated ``global`` argument to be a global. Furthermore, it does this safely by only going in as many levels deep as is possible: if the returned value is not something that can be indexed into, then traversal queries with ``std::tuple``/``std::pair`` will stop early and return probing information with the :ref:`probe struct<stack-probe-struct>`.
+
+This function leaves the retrieved value on the stack.
+
+.. code-block:: cpp
+ :caption: struct: probe
+ :name: stack-probe-struct
+
+ struct probe {
+ bool success;
+ int levels;
+
+ probe(bool s, int l);
+ operator bool() const;
+ };
+
+This struct is used for showing whether or not a :ref:`probing get_field<stack-probe-get-field>` was successful or not.
+
+.. _extension_points:
+
+objects (extension points)
+--------------------------
+
+You can customize the way Sol handles different structures and classes by following the information provided in the :doc:`adding your own types<../tutorial/customization>`.
+
+Below is more extensive information for the curious.
+
+The structs below are already overriden for a handful of types. If you try to mess with them for the types ``sol`` has already overriden them for, you're in for a world of thick template error traces and headaches. Overriding them for your own user defined types should be just fine, however.
+
+.. code-block:: cpp
+ :caption: struct: getter
+ :name: getter
+
+ template <typename T, typename = void>
+ struct getter {
+ static T get (lua_State* L, int index, record& tracking) {
+ // ...
+ return // T, or something related to T.
+ }
+ };
+
+This is an SFINAE-friendly struct that is meant to expose static function ``get`` that returns a ``T``, or something convertible to it. The default implementation assumes ``T`` is a usertype and pulls out a userdata from Lua before attempting to cast it to the desired ``T``. There are implementations for getting numbers (``std::is_floating``, ``std::is_integral``-matching types), getting ``std::string`` and ``const char*``, getting raw userdata with :doc:`userdata_value<types>` and anything as upvalues with :doc:`upvalue_index<types>`, getting raw `lua_CFunction`_ s, and finally pulling out Lua functions into ``std::function<R(Args...)>``. It is also defined for anything that derives from :doc:`sol::reference<reference>`. It also has a special implementation for the 2 standard library smart pointers (see :doc:`usertype memory<usertype_memory>`).
+
+.. code-block:: cpp
+ :caption: struct: pusher
+ :name: pusher
+
+ template <typename X, typename = void>
+ struct pusher {
+ template <typename T>
+ static int push ( lua_State* L, T&&, ... ) {
+ // can optionally take more than just 1 argument
+ // ...
+ return // number of things pushed onto the stack
+ }
+ };
+
+This is an SFINAE-friendly struct that is meant to expose static function ``push`` that returns the number of things pushed onto the stack. The default implementation assumes ``T`` is a usertype and pushes a userdata into Lua with a :ref:`usertype_traits\<T><usertype-traits>` metatable associated with it. There are implementations for pushing numbers (``std::is_floating``, ``std::is_integral``-matching types), getting ``std::string`` and ``const char*``, getting raw userdata with :doc:`userdata<types>` and raw upvalues with :doc:`upvalue<types>`, getting raw `lua_CFunction`_ s, and finally pulling out Lua functions into ``sol::function``. It is also defined for anything that derives from :doc:`sol::reference<reference>`. It also has a special implementation for the 2 standard library smart pointers (see :doc:`usertype memory<usertype_memory>`).
+
+.. code-block:: cpp
+ :caption: struct: checker
+ :name: checker
+
+ template <typename T, type expected = lua_type_of<T>, typename = void>
+ struct checker {
+ template <typename Handler>
+ static bool check ( lua_State* L, int index, Handler&& handler, record& tracking ) {
+ // if the object in the Lua stack at index is a T, return true
+ if ( ... ) return true;
+ // otherwise, call the handler function,
+ // with the required 4 arguments, then return false
+ handler(L, index, expected, indextype);
+ return false;
+ }
+ };
+
+This is an SFINAE-friendly struct that is meant to expose static function ``check`` that returns the number of things pushed onto the stack. The default implementation simply checks whether the expected type passed in through the template is equal to the type of the object at the specified index in the Lua stack. The default implementation for types which are considered ``userdata`` go through a myriad of checks to support checking if a type is *actually* of type ``T`` or if its the base class of what it actually stored as a userdata in that index. Down-casting from a base class to a more derived type is, unfortunately, impossible to do.
+
+.. _lua_CFunction: http://www.Lua.org/manual/5.3/manual.html#lua_CFunction \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/stack_reference.rst b/3rdparty/sol2/docs/source/api/stack_reference.rst
new file mode 100644
index 00000000000..db5359d11aa
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/stack_reference.rst
@@ -0,0 +1,8 @@
+stack_reference
+===============
+zero-overhead object on the stack
+---------------------------------
+
+When you work with a :doc:`sol::reference<reference>`, the object gotten from the stack has a reference to it made in the registry, keeping it alive. If you want to work with the Lua stack directly without having any additional references made, ``sol::stack_reference`` is for you. Its API is identical to ``sol::reference`` in every way, except it contains a ``int stack_index()`` member function that allows you to retrieve the stack index.
+
+All of the base types have ``stack`` versions of themselves, and the APIs are identical to their non-stack forms. This includes :doc:`sol::stack_table<table>`, :doc:`sol::stack_function<function>`, :doc:`sol::stack_protected_function<protected_function>`, :doc:`sol::stack_(light\_)userdata<userdata>` and :doc:`sol::stack_object<object>`. \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/state.rst b/3rdparty/sol2/docs/source/api/state.rst
new file mode 100644
index 00000000000..b593d5cc810
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/state.rst
@@ -0,0 +1,121 @@
+state
+=====
+owning and non-owning state holders for registry and globals
+------------------------------------------------------------
+
+.. code-block:: cpp
+
+ class state_view;
+
+ class state : state_view, std::unique_ptr<lua_State*, deleter>;
+
+The most important class here is ``state_view``. This structure takes a ``lua_State*`` that was already created and gives you simple, easy access to Lua's interfaces without taking ownership. ``state`` derives from ``state_view``, inheriting all of this functionality, but has the additional purpose of creating a fresh ``lua_State*`` and managing its lifetime for you in the default constructor.
+
+The majority of the members between ``state_view`` and :doc:`sol::table<table>` are identical, with added for this higher-level type. Therefore, all of the examples and notes in :doc:`sol::table<table>` apply here as well.
+
+enumerations
+------------
+
+.. code-block:: cpp
+ :caption: in-lua libraries
+ :name: lib-enum
+
+ enum class lib : char {
+ base,
+ package,
+ coroutine,
+ string,
+ os,
+ math,
+ table,
+ debug,
+ bit32,
+ io,
+ ffi,
+ jit,
+ count // do not use
+ };
+
+This enumeration details the various base libraries that come with Lua. See the `standard lua libraries`_ for details about the various standard libraries.
+
+
+members
+-------
+
+.. code-block:: cpp
+ :caption: function: open standard libraries/modules
+ :name: open-libraries
+
+ template<typename... Args>
+ void open_libraries(Args&&... args);
+
+This function takes a number of :ref:`sol::lib<lib-enum>` as arguments and opens up the associated Lua core libraries.
+
+.. code-block:: cpp
+ :caption: function: script / script_file
+
+ sol::function_result script(const std::string& code);
+ sol::function_result script_file(const std::string& filename);
+
+These functions run the desired blob of either code that is in a string, or code that comes from a filename, on the ``lua_State*``. It will not run isolated: any scripts or code run will affect code in the ``lua_State*`` the object uses as well (unless ``local`` is applied to a variable declaration, as specified by the Lua language). Code ran in this fashion is not isolated. If you need isolation, consider creating a new state or traditional Lua sandboxing techniques.
+
+If your script returns a value, you can capture it from the returned :ref:`function_result<function-result>`.
+
+.. code-block:: cpp
+ :caption: function: require / require_file
+ :name: state-require-function
+
+ sol::object require(const std::string& key, lua_CFunction open_function, bool create_global = true);
+ sol::object require_script(const std::string& key, const std::string& code, bool create_global = true);
+ sol::object require_file(const std::string& key, const std::string& file, bool create_global = true);
+
+These functions play a role similar to `luaL_requiref`_ except that they make this functionality available for loading a one-time script or a single file. The code here checks if a module has already been loaded, and if it has not, will either load / execute the file or execute the string of code passed in. If ``create_global`` is set to true, it will also link the name ``key`` to the result returned from the open function, the code or the file. Regardless or whether a fresh load happens or not, the returned module is given as a single :doc:`sol::object<object>` for you to use as you see fit.
+
+Thanks to `Eric (EToreo) for the suggestion on this one`_!
+
+.. code-block:: cpp
+ :caption: function: load / load_file
+ :name: state-load-code
+
+ sol::load_result load(const std::string& code);
+ sol::load_result load_file(const std::string& filename);
+
+These functions *load* the desired blob of either code that is in a string, or code that comes from a filename, on the ``lua_State*``. It will not run: it returns a ``load_result`` proxy that can be called to actually run the code, turned into a ``sol::function``, a ``sol::protected_function``, or some other abstraction. If it is called, it will run on the object's current ``lua_State*``: it is not isolated. If you need isolation, consider creating a new state or traditional Lua sandboxing techniques.
+
+.. code-block:: cpp
+ :caption: function: global table / registry table
+
+ sol::global_table globals() const;
+ sol::table registry() const;
+
+Get either the global table or the Lua registry as a :doc:`sol::table<table>`, which allows you to modify either of them directly. Note that getting the global table from a ``state``/``state_view`` is usually unnecessary as it has all the exact same functions as a :doc:`sol::table<table>` anyhow.
+
+
+.. code-block:: cpp
+ :caption: function: Lua set_panic
+ :name: set-panic
+
+ void set_panic(lua_CFunction panic);
+
+Overrides the panic function Lua calls when something unrecoverable or unexpected happens in the Lua VM. Must be a function of the that matches the ``int(*)(lua_State*)`` function signature.
+
+.. code-block:: cpp
+ :caption: function: make a table
+
+ sol::table create_table(int narr = 0, int nrec = 0);
+ template <typename Key, typename Value, typename... Args>
+ sol::table create_table(int narr, int nrec, Key&& key, Value&& value, Args&&... args);
+
+
+ template <typename... Args>
+ sol::table create_table_with(Args&&... args);
+
+ static sol::table create_table(lua_State* L, int narr = 0, int nrec = 0);
+ template <typename Key, typename Value, typename... Args>
+ static sol::table create_table(lua_State* L, int narr, int nrec, Key&& key, Value&& value, Args&&... args);
+
+Creates a table. Forwards its arguments to :ref:`table::create<table-create>`.
+
+.. _standard lua libraries: http://www.lua.org/manual/5.3/manual.html#6
+.. _luaL_requiref: https://www.lua.org/manual/5.3/manual.html#luaL_requiref
+.. _Eric (EToreo) for the suggestion on this one: https://github.com/ThePhD/sol2/issues/90 \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/table.rst b/3rdparty/sol2/docs/source/api/table.rst
new file mode 100644
index 00000000000..b5a946487de
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/table.rst
@@ -0,0 +1,208 @@
+table
+=====
+a representation of a Lua (meta)table
+-------------------------------------
+
+.. code-block:: cpp
+
+ template <bool global>
+ class table_core;
+
+ typedef table_core<false> table;
+ typedef table_core<true> global_table;
+
+``sol::table`` is an extremely efficient manipulator of state that brings most of the magic of the Sol abstraction. Capable of doing multiple sets at once, multiple gets into a ``std::tuple``, being indexed into using ``[key]`` syntax and setting keys with a similar syntax (see: :doc:`here<proxy>`), ``sol::table`` is the corner of the interaction between Lua and C++.
+
+There are two kinds of tables: the global table and non-global tables: however, both have the exact same interface and all ``sol::global_table`` s are convertible to regular ``sol::table`` s.
+
+Tables are the core of Lua, and they are very much the core of Sol.
+
+
+members
+-------
+
+.. code-block:: cpp
+ :caption: constructor: table
+
+ table(lua_State* L, int index = -1);
+
+Takes a table from the Lua stack at the specified index and allows a person to use all of the abstractions therein.
+
+.. code-block:: cpp
+ :caption: function: get / traversing get
+
+ template<typename... Args, typename... Keys>
+ decltype(auto) get(Keys&&... keys) const;
+
+ template<typename T, typename... Keys>
+ decltype(auto) traverse_get(Keys&&... keys) const;
+
+ template<typename T, typename Key>
+ decltype(auto) get_or(Key&& key, T&& otherwise) const;
+
+ template<typename T, typename Key, typename D>
+ decltype(auto) get_or(Key&& key, D&& otherwise) const;
+
+
+These functions retrieve items from the table. The first one (``get``) can pull out *multiple* values, 1 for each key value passed into the function. In the case of multiple return values, it is returned in a ``std::tuple<Args...>``. It is similar to doing ``return table["a"], table["b"], table["c"]``. Because it returns a ``std::tuple``, you can use ``std::tie``/``std::make_tuple`` on a multi-get to retrieve all of the necessary variables. The second one (``traverse_get``) pulls out a *single* value, using each successive key provided to do another lookup into the last. It is similar to doing ``x = table["a"]["b"]["c"][...]``.
+
+If the keys within nested queries try to traverse into a table that doesn't exist, the second lookup into the nil-returned variable and belong will cause a panic to be fired by the lua C API. If you need to check for keys, check with ``auto x = table.get<sol::optional<int>>( std::tie("a", "b", "c" ) );``, and then use the :doc:`optional<optional>` interface to check for errors. As a short-hand, easy method for returning a default if a value doesn't exist, you can use ``get_or`` instead.
+
+.. code-block:: cpp
+ :caption: function: set / traversing set
+ :name: set-value
+
+ template<typename... Args>
+ table& set(Args&&... args);
+
+ template<typename... Args>
+ table& traverse_set(Args&&... args);
+
+These functions set items into the table. The first one (``set``) can set *multiple* values, in the form ``key_a, value_a, key_b, value_b, ...``. It is similar to ``table[key_a] = value_a; table[key_b] = value_b, ...``. The second one (``traverse_set``) sets a *single* value, using all but the last argument as keys to do another lookup into the value retrieved prior to it. It is equivalent to ``table[key_a][key_b][...] = value;``.
+
+.. note::
+
+ Value semantics are applied to all set operations. If you do not ``std::ref( obj )`` or specifically make a pointer with ``std::addressof( obj )`` or ``&obj``, it will copy / move. This is different from how :doc:`sol::function<function>` behaves with its call operator.
+
+.. code-block:: cpp
+ :caption: function: set a function with the specified key into lua
+ :name: set-function
+
+ template<typename Key, typename Fx>
+ state_view& set_function(Key&& key, Fx&& fx, [...]);
+
+Sets the desired function to the specified key value. Note that it also allows for passing a member function plus a member object or just a single member function: however, using a lambda is almost always better when you want to bind a member function + class instance to a single function call in Lua.
+
+.. code-block:: cpp
+ :caption: function: add
+
+ template<typename... Args>
+ table& add(Args&&... args);
+
+This function appends a value to a table. The definition of appends here is only well-defined for a table which has a perfectly sequential (and integral) ordering of numeric keys with associated non-null values (the same requirement for the :ref:`size<size-function>` function). Otherwise, this falls to the implementation-defined behavior of your Lua VM, whereupon is may add keys into empty 'holes' in the array (e.g., the first empty non-sequential integer key it gets to from ``size``) or perhaps at the very "end" of the "array". Do yourself the favor of making sure your keys are sequential.
+
+Each argument is appended to the list one at a time.
+
+.. code-block:: cpp
+ :caption: function: size
+ :name: size-function
+
+ std::size_t size() const;
+
+This function returns the size of a table. It is only well-defined in the case of a Lua table which has a perfectly sequential (and integral) ordering of numeric keys with associated non-null values.
+
+.. code-block:: cpp
+ :caption: function: setting a usertype
+ :name: new-usertype
+
+ template<typename Class, typename... Args>
+ table& new_usertype(const std::string& name, Args&&... args);
+ template<typename Class, typename CTor0, typename... CTor, typename... Args>
+ table& new_usertype(const std::string& name, Args&&... args);
+ template<typename Class, typename... CArgs, typename... Args>
+ table& new_usertype(const std::string& name, constructors<CArgs...> ctor, Args&&... args);
+
+This class of functions creates a new :doc:`usertype<usertype>` with the specified arguments, providing a few extra details for constructors. After creating a usertype with the specified argument, it passes it to :ref:`set_usertype<set_usertype>`.
+
+.. code-block:: cpp
+ :caption: function: setting a simple usertype
+ :name: new-simple-usertype
+
+ template<typename Class, typename... Args>
+ table& new_simple_usertype(const std::string& name, Args&&... args);
+ template<typename Class, typename CTor0, typename... CTor, typename... Args>
+ table& new_simple_usertype(const std::string& name, Args&&... args);
+ template<typename Class, typename... CArgs, typename... Args>
+ table& new_simple_usertype(const std::string& name, constructors<CArgs...> ctor, Args&&... args);
+
+This class of functions creates a new :doc:`simple usertype<simple_usertype>` with the specified arguments, providing a few extra details for constructors and passing the ``sol::simple`` tag as well. After creating a usertype with the specified argument, it passes it to :ref:`set_usertype<set_usertype>`.
+
+.. code-block:: cpp
+ :caption: function: creating an enum
+ :name: new-enum
+
+ template<bool read_only = true, typename... Args>
+ basic_table_core& new_enum(const std::string& name, Args&&... args);
+
+Use this function to create an enumeration type in Lua. By default, the enum will be made read-only, which creates a tiny performance hit to make the values stored in this table behave exactly like a read-only enumeration in C++. If you plan on changing the enum values in Lua, set the ``read_only`` template parameter in your ``new_enum`` call to false. The arguments are expected to come in ``key, value, key, value, ...`` list.
+
+.. _set_usertype:
+
+.. code-block:: cpp
+ :caption: function: setting a pre-created usertype
+ :name: set-usertype
+
+ template<typename T>
+ table& set_usertype(usertype<T>& user);
+ template<typename Key, typename T>
+ table& set_usertype(Key&& key, usertype<T>& user);
+
+Sets a previously created usertype with the specified ``key`` into the table. Note that if you do not specify a key, the implementation falls back to setting the usertype with a ``key`` of ``usertype_traits<T>::name``, which is an implementation-defined name that tends to be of the form ``{namespace_name 1}_[{namespace_name 2 ...}_{class name}``.
+
+.. code-block:: cpp
+ :caption: function: begin / end for iteration
+ :name: table-iterators
+
+ table_iterator begin () const;
+ table_iterator end() const;
+ table_iterator cbegin() const;
+ table_iterator cend() const;
+
+Provides `input iterators`_ for a table. This allows tables to work with single-pass, input-only algorithms (like ``std::for_each``).
+
+.. code-block:: cpp
+ :caption: function: iteration with a function
+ :name: table-for-each
+
+ template <typename Fx>
+ void for_each(Fx&& fx);
+
+A functional ``for_each`` loop that calls the desired function. The passed in function must take either ``sol::object key, sol::object value`` or take a ``std::pair<sol::object, sol::object> key_value_pair``. This version can be a bit safer as allows the implementation to definitively pop the key/value off the Lua stack after each call of the function.
+
+.. code-block:: cpp
+ :caption: function: operator[] access
+
+ template<typename T>
+ proxy<table&, T> operator[](T&& key);
+ template<typename T>
+ proxy<const table&, T> operator[](T&& key) const;
+
+Generates a :doc:`proxy<proxy>` that is templated on the table type and the key type. Enables lookup of items and their implicit conversion to a desired type.
+
+.. code-block:: cpp
+ :caption: function: create a table with defaults
+ :name: table-create
+
+ table create(int narr = 0, int nrec = 0);
+ template <typename Key, typename Value, typename... Args>
+ table create(int narr, int nrec, Key&& key, Value&& value, Args&&... args);
+
+ static table create(lua_State* L, int narr = 0, int nrec = 0);
+ template <typename Key, typename Value, typename... Args>
+ static table create(lua_State* L, int narr, int nrec, Key&& key, Value&& value, Args&&... args);
+
+Creates a table, optionally with the specified values pre-set into the table. If ``narr`` or ``nrec`` are 0, then compile-time shenanigans are used to guess the amount of array entries (e.g., integer keys) and the amount of hashable entries (e.g., all other entries).
+
+.. code-block:: cpp
+ :caption: function: create a table with compile-time defaults assumed
+ :name: table-create-with
+
+ template <typename... Args>
+ table create_with(Args&&... args);
+ template <typename... Args>
+ static table create_with(lua_State* L, Args&&... args);
+
+
+Creates a table, optionally with the specified values pre-set into the table. It checks every 2nd argument (the keys) and generates hints for how many array or map-style entries will be placed into the table.
+
+.. code-block:: cpp
+ :caption: function: create a named table with compile-time defaults assumed
+ :name: table-create-named
+
+ template <typename Name, typename... Args>
+ table create_named(Name&& name, Args&&... args);
+
+
+Creates a table, optionally with the specified values pre-set into the table, and sets it as the key ``name`` in the table.
+
+.. _input iterators: http://en.cppreference.com/w/cpp/concept/InputIterator \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/this_state.rst b/3rdparty/sol2/docs/source/api/this_state.rst
new file mode 100644
index 00000000000..c4c6b3b7f75
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/this_state.rst
@@ -0,0 +1,31 @@
+this_state
+==========
+transparent state argument for the current state
+------------------------------------------------
+
+.. code-block:: cpp
+
+ struct this_state;
+
+This class is a transparent type that is meant to be gotten in functions to get the current lua state a bound function or usertype method is being called from. It does not actually retrieve anything from lua nor does it increment the argument count, making it "invisible" to function calls in lua and calls through ``std::function<...>`` and :doc:`sol::function<function>` on this type. It can be put in any position in the argument list of a function:
+
+.. code-block:: cpp
+ :linenos:
+
+ sol::state lua;
+
+ lua.set_function("bark", []( sol::this_state s, int a, int b ){
+ lua_State* L = s; // current state
+ return a + b + lua_gettop(L);
+ });
+
+ lua.script("first = bark(2, 2)"); // only takes 2 arguments, NOT 3
+
+ // Can be at the end, too, or in the middle: doesn't matter
+ lua.set_function("bark", []( int a, int b, sol::this_state s ){
+ lua_State* L = s; // current state
+ return a + b + lua_gettop(L);
+ });
+
+ lua.script("second = bark(2, 2)"); // only takes 2 arguments
+ \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/thread.rst b/3rdparty/sol2/docs/source/api/thread.rst
new file mode 100644
index 00000000000..1a713f973b4
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/thread.rst
@@ -0,0 +1,52 @@
+thread
+======
+a separate state that can contain and run functions
+---------------------------------------------------
+
+.. code-block:: cpp
+
+ class thread : public reference { /* ... */ };
+
+``sol::thread`` is a separate runnable part of the Lua VM that can be used to execute work separately from the main thread, such as with :doc:`coroutines<coroutine>`. To take a table or a coroutine and run it specifically on the ``sol::thread`` you either pulled out of lua or created, just get that function through the :ref:`state of the thread<thread_state>`
+
+members
+-------
+
+.. code-block:: cpp
+ :caption: constructor: thread
+
+ thread(lua_State* L, int index = -1);
+
+Takes a thread from the Lua stack at the specified index and allows a person to use all of the abstractions therein.
+
+.. code-block:: cpp
+ :caption: function: view into thread_state()'s state
+
+ state_view state() const;
+
+This retrieves the current state of the thread, producing a :doc:`state_view<state>` that can be manipulated like any other. :doc:`Coroutines<coroutine>` pulled from Lua using the thread's state will be run on that thread specifically.
+
+.. _thread_state:
+
+.. code-block:: cpp
+ :caption: function: retrieve thread state object
+
+ lua_State* thread_state () const;
+
+This function retrieves the ``lua_State*`` that represents the thread.
+
+.. code-block:: cpp
+ :caption: current thread status
+
+ thread_status status () const;
+
+Retrieves the :doc:`thread status<types>` that describes the current state of the thread.
+
+.. code-block:: cpp
+ :caption: function: thread creation
+ :name: thread-create
+
+ thread create();
+ static thread create (lua_State* L);
+
+Creates a new thread from the given a ``lua_State*``. \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/tie.rst b/3rdparty/sol2/docs/source/api/tie.rst
new file mode 100644
index 00000000000..080c8a1cc4f
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/tie.rst
@@ -0,0 +1,26 @@
+tie
+===
+An improved version of ``std::tie``
+-----------------------------------
+
+`std::tie()`_ does not work well with :doc:`sol::function<function>`'s ``sol::function_result`` returns. Use ``sol::tie`` instead. Because they're both named `tie`, you'll need to be explicit when you use Sol's by naming it with the namespace (``sol::tie``), even with a ``using namespace sol;``. Here's an example:
+
+.. code-block:: cpp
+
+ sol::state lua;
+ lua.open_libraries(sol::lib::base);
+
+ const auto& code = R"(
+ function test()
+ return 1, 2, 3
+ end
+ )";
+ lua.script(code);
+
+ int a, b, c;
+ //std::tie(a, b, c) = lua["test"]();
+ // will error: use the line below
+ sol::tie(a, b, c) = lua["test"]();
+
+
+.. _std::tie(): http://en.cppreference.com/w/cpp/utility/tuple/tie
diff --git a/3rdparty/sol2/docs/source/api/types.rst b/3rdparty/sol2/docs/source/api/types.rst
new file mode 100644
index 00000000000..9f761ee25b9
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/types.rst
@@ -0,0 +1,207 @@
+types
+=====
+nil, lua_primitive type traits, and other fundamentals
+------------------------------------------------------
+
+The ``types.hpp`` header contains various fundamentals and utilities of Sol.
+
+
+enumerations
+------------
+
+.. code-block:: cpp
+ :caption: syntax of a function called by Lua
+ :name: call-syntax
+
+ enum class call_syntax {
+ dot = 0,
+ colon = 1
+ };
+
+This enumeration indicates the syntax a function was called with in a specific scenario. There are two ways to call a function: with ``obj:func_name( ... )`` or ``obj.func_name( ... );`` The first one passes "obj" as the first argument: the second one does not. In the case of usertypes, this is used to determine whether the call to a :doc:`constructor/initializer<usertype>` was called with a ``:`` or a ``.``, and not misalign the arguments.
+
+.. code-block:: cpp
+ :caption: status of a Lua function call
+ :name: call-status
+
+ enum class call_status : int {
+ ok = LUA_OK,
+ yielded = LUA_YIELD,
+ runtime = LUA_ERRRUN,
+ memory = LUA_ERRMEM,
+ handler = LUA_ERRERR,
+ gc = LUA_ERRGCMM
+ };
+
+This strongly-typed enumeration contains the errors potentially generated by a call to a :doc:`protected function<protected_function>` or a :doc:`coroutine<coroutine>`.
+
+.. code-block:: cpp
+ :caption: status of a Lua thread
+ :name: thread-status
+
+ enum class thread_status : int {
+ ok = LUA_OK,
+ yielded = LUA_YIELD,
+ runtime = LUA_ERRRUN,
+ memory = LUA_ERRMEM,
+ gc = LUA_ERRGCMM,
+ handler = LUA_ERRERR,
+ dead,
+ };
+
+This enumeration contains the status of a thread. The ``thread_status::dead`` state is generated when the thread has nothing on its stack and it is not running anything.
+
+.. code-block:: cpp
+ :caption: status of a Lua load operation
+ :name: load-status
+
+ enum class load_status : int {
+ ok = LUA_OK,
+ runtime = LUA_ERRSYNTAX,
+ memory = LUA_ERRMEM,
+ gc = LUA_ERRGCMM,
+ file = LUA_ERRFILE,
+ };
+
+This enumeration contains the status of a load operation from :ref:`state::load(_file)<state-load-code>`.
+
+.. code-block:: cpp
+ :caption: type enumeration
+ :name: type-enum
+
+ enum class type : int {
+ none = LUA_TNONE,
+ nil = LUA_TNIL,
+ string = LUA_TSTRING,
+ number = LUA_TNUMBER,
+ thread = LUA_TTHREAD,
+ boolean = LUA_TBOOLEAN,
+ function = LUA_TFUNCTION,
+ userdata = LUA_TUSERDATA,
+ lightuserdata = LUA_TLIGHTUSERDATA,
+ table = LUA_TTABLE,
+ poly = none | nil | string | number | thread |
+ table | boolean | function | userdata | lightuserdata
+ };
+
+The base types that Lua natively communicates in and understands. Note that "poly" isn't really a true type, it's just a symbol used in Sol for something whose type hasn't been checked (and you should almost never see it).
+
+
+type traits
+-----------
+
+.. code-block:: cpp
+ :caption: lua_type_of trait
+ :name: lua-type-of
+
+ template <typename T>
+ struct lua_type_of;
+
+This type trait maps a C++ type to a :ref:`type enumeration<type-enum>` value. The default value is ``type::userdata``.
+
+.. code-block:: cpp
+ :caption: primitive checking traits
+ :name: is-primitive
+
+ template <typename T>
+ struct is_lua_primitive;
+
+ template <typename T>
+ struct is_proxy_primitive;
+
+
+This trait is used by :doc:`proxy<proxy>` to know which types should be returned as references to internal Lua memory (e.g., ``userdata`` types) and which ones to return as values (strings, numbers, :doc:`references<reference>`). ``std::reference_wrapper``, ``std::tuple<...>`` are returned as values, but their contents can be references. The default value is false.
+
+special types
+-------------
+
+.. code-block:: cpp
+ :caption: nil
+ :name: nil
+
+ strunil_t {};
+ const nil_t nil {};
+ bool operator==(nil_t, nil_t);
+ bool operator!=(nil_t, nil_t);
+
+``nil`` is a constant used to signify Lua's ``nil``, which is a type and object that something does not exist. It is comparable to itself, :doc:`sol::object<object>` and :doc:`proxy values<proxy>`.
+
+
+.. code-block:: cpp
+ :caption: non_null
+
+ template <typename T>
+ struct non_null {};
+
+A tag type that, when used with :doc:`stack::get\<non_null\<T*>><stack>`, does not perform a ``nil`` check when attempting to retrieve the userdata pointer.
+
+
+.. code-block:: cpp
+ :caption: type list
+ :name: type-list
+
+ template <typename... Args>
+ struct types;
+
+A type list that, unlike ``std::tuple<Args...>``, does not actually contain anything. Used to indicate types and groups of types all over Sol.
+
+
+functions
+---------
+
+.. code-block:: cpp
+ :caption: type_of
+
+ template<typename T>
+ type type_of();
+
+ type type_of(lua_State* L, int index);
+
+
+These functions get the type of a C++ type ``T``; or the type at the specified index on the Lua stack.
+
+.. code-block:: cpp
+ :caption: type checking convenience functions
+
+ int type_panic(lua_State* L, int index, type expected, type actual);
+
+ int no_panic(lua_State*, int, type, type) noexcept;
+
+ void type_error(lua_State* L, int expected, int actual);
+
+ void type_error(lua_State* L, type expected, type actual);
+
+ void type_assert(lua_State* L, int index, type expected, type actual);
+
+ void type_assert(lua_State* L, int index, type expected);
+
+The purpose of these functions is to assert / throw / crash / error (or do nothing, as is the case with ``no_panic``). They're mostly used internally in the framework, but they're provided here if you should need them.
+
+.. code-block:: cpp
+ :caption: type name retrieval
+
+ std::string type_name(lua_State*L, type t);
+
+Gets the Lua-specified name of the :ref:`type<type-enum>`.
+
+structs
+-------
+
+.. code-block:: cpp
+
+ struct userdata_value {
+ void* value;
+ };
+
+ struct light_userdata_value {
+ void* value;
+ };
+
+ struct up_value_index {
+ int index;
+ };
+
+
+Types that differentiate between the two kinds of ``void*`` Lua hands back from its API: full userdata and light userdata, as well as a type that modifies the index passed to ``get`` to refer to `up values`_ These types can be used to trigger different underlying API calls to Lua when working with :doc:`stack<stack>` namespace and the ``push``/``get``/``pop``/``check`` functions.
+
+.. _up values: http://www.Lua.org/manual/5.3/manual.html#4.4 \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/unique_usertype_traits.rst b/3rdparty/sol2/docs/source/api/unique_usertype_traits.rst
new file mode 100644
index 00000000000..4568b11349c
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/unique_usertype_traits.rst
@@ -0,0 +1,44 @@
+unique_usertype_traits<T>
+=========================
+A trait for hooking special handles / pointers
+----------------------------------------------
+
+.. code-block:: cpp
+ :caption: unique_usertype
+ :name: unique-usertype
+
+ template <typename T>
+ struct unique_usertype_traits {
+ typedef T type;
+ typedef T actual_type;
+ static const bool value = false;
+
+ static bool is_null(const actual_type&) {...}
+
+ static type* get (const actual_type&) {...}
+ };
+
+This is a customization point for users who need to *work with special kinds of pointers/handles*. For generic customization, please review the :doc:`customization tutorial<../tutorial/customization>` A traits type for alerting the library that a certain type is to be pushed as a special userdata with special deletion / destruction semantics. It is already defined for ``std::unique_ptr<T, D>`` and ``std::shared_ptr<T>``. You can specialize this to get ``unique_usertype_traits`` semantics with your code, for example with ``boost::shared_ptr<T>`` like so:
+
+.. code-block:: cpp
+
+ namespace sol {
+ template <typename T>
+ struct unique_usertype_traits<boost::shared_ptr<T>> {
+ typedef T type;
+ typedef boost::shared_ptr<T> actual_type;
+ static const bool value = true;
+
+ static bool is_null(const actual_type& value) {
+ return value == nullptr;
+ }
+
+ static type* get (const actual_type& p) {
+ return p.get();
+ }
+ }
+ }
+
+This will allow the framework to properly handle ``boost::shared_ptr<T>``, with ref-counting and all. The `type` is the type that lua and sol will interact with, and will allow you to pull out a non-owning reference / pointer to the data when you just ask for a plain `T*` or `T&` or `T` using the getter functions and properties of Sol.
+
+Note that if ``is_null`` triggers, a ``nil`` value will be pushed into Sol. \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/user.rst b/3rdparty/sol2/docs/source/api/user.rst
new file mode 100644
index 00000000000..9a0905d76bd
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/user.rst
@@ -0,0 +1,19 @@
+light<T>/user<T>
+================
+Utility class for the cheapest form of (light) userdata
+-------------------------------------------------------
+
+.. code-block:: cpp
+
+ template <typename T>
+ struct user;
+
+ template <typename T>
+ struct light;
+
+
+``sol::user<T>`` and ``sol::light<T>`` are two utility classes that do not participate in the full :doc:`sol::usertype\<T><usertype>` system. The goal of these classes is to provide the most minimal memory footprint and overhead for putting a single item and getting a single item out of Lua. ``sol::user<T>``, when pushed into Lua, will create a thin, unnamed metatable for that instance specifically which will be for calling its destructor. ``sol::light<T>`` specifically pushes a reference / pointer into Lua as a ``sol::type::lightuserdata``.
+
+If you feel that you do not need to have something participate in the full :doc:`usertype\<T><usertype>` system, use the utility functions ``sol::make_user( ... )`` and ``sol::make_light( ... )`` to create these types and store them into Lua. You can get them off the Lua stack / out of the Lua system by using the same retrieval techniques on ``get`` and ``operator[]`` on tables and with stack operations.
+
+Both have implicit conversion operators to ``T*`` and ``T&``, so you can set them immediately to their respective pointer and reference types if you need them. \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/userdata.rst b/3rdparty/sol2/docs/source/api/userdata.rst
new file mode 100644
index 00000000000..6bc64791552
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/userdata.rst
@@ -0,0 +1,13 @@
+userdata
+========
+reference to a userdata
+-----------------------
+
+.. code-block:: cpp
+ :caption: (light\_)userdata reference
+
+ class userdata : public reference;
+
+ class light_userdata : public reference;
+
+These type is meant to hold a reference to a (light) userdata from Lua and make it easy to push an existing userdata onto the stack. It is essentially identical to :doc:`reference<reference>` in every way, just with a definitive C++ type.
diff --git a/3rdparty/sol2/docs/source/api/usertype.rst b/3rdparty/sol2/docs/source/api/usertype.rst
new file mode 100644
index 00000000000..d3282cd5c64
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/usertype.rst
@@ -0,0 +1,329 @@
+usertype<T>
+===========
+structures and classes from C++ made available to Lua code
+----------------------------------------------------------
+
+*Note: ``T`` refers to the type being turned into a usertype.*
+
+While other frameworks extend lua's syntax or create Data Structure Languages (DSLs) to create classes in lua, :doc:`sol<../index>` instead offers the ability to generate easy bindings. These use metatables and userdata in lua for their implementation. Given this C++ class:
+
+.. code-block:: cpp
+ :linenos:
+
+ struct ship {
+ int bullets = 20;
+ int life = 100;
+
+ bool shoot () {
+ if (bullets > 0) {
+ --bullets;
+ // successfully shot
+ return true;
+ }
+ // cannot shoot
+ return false;
+ }
+
+ bool hurt (int by) {
+ life -= by;
+ // have we died?
+ return life < 1;
+ }
+ };
+
+You can bind the it to Lua using the following C++ code:
+
+.. code-block:: cpp
+ :linenos:
+
+ sol::state lua;
+
+ lua.new_usertype<ship>( "ship", // the name of the class, as you want it to be used in lua
+ // List the member functions you wish to bind:
+ // "name_of_item", &class_name::function_or_variable
+ "shoot", &ship::shoot,
+ "hurt", &ship::hurt,
+ // bind variable types, too
+ "life", &ship::bullets
+ // names in lua don't have to be the same as C++,
+ // but it probably helps if they're kept the same,
+ // here we change it just to show its possible
+ "bullet_count", &ship::bullets
+ );
+
+
+Equivalently, you can also write:
+
+.. code-block:: cpp
+ :linenos:
+ :emphasize-lines: 4,12
+
+ sol::state lua;
+
+ // Use constructor directly
+ usertype<ship> shiptype(
+ "shoot", &ship::shoot,
+ "hurt", &ship::hurt,
+ "life", &ship::bullets
+ "bullet_count", &ship::bullets
+ );
+
+ // set usertype explicitly, with the given name
+ lua.set_usertype<ship>( "ship", shiptype );
+
+ // shiptype is now a useless skeleton type, just let it destruct naturally and don't use it again.
+
+
+Note that here, because the C++ class is default-constructible, it will automatically generate a creation function that can be called in lua called "new" that takes no arguments. You can use it like this in lua code:
+
+.. code-block:: lua
+ :linenos:
+
+ fwoosh = ship.new()
+ -- note the ":" that is there: this is mandatory for member function calls
+ -- ":" means "pass self" in Lua
+ local success = fwoosh:shoot()
+ local is_dead = fwoosh:hurt(20)
+ -- check if it works
+ print(is_dead) -- the ship is not dead at this point
+ print(fwoosh.life .. "life left") -- 80 life left
+ print(fwoosh.bullet_count) -- 19
+
+
+There are more advanced use cases for how to create and use a usertype, which are all based on how to use its constructor (see below).
+
+enumerations
+------------
+
+.. _meta_function_enum:
+
+.. code-block:: cpp
+ :caption: meta_function enumeration for names
+ :linenos:
+
+ enum class meta_function {
+ construct,
+ index,
+ new_index,
+ mode,
+ call,
+ metatable,
+ to_string,
+ length,
+ unary_minus,
+ addition,
+ subtraction,
+ multiplication,
+ division,
+ modulus,
+ power_of,
+ involution = power_of,
+ concatenation,
+ equal_to,
+ less_than,
+ less_than_or_equal_to,
+ garbage_collect,
+ call_function,
+ };
+
+
+Use this enumeration to specify names in a manner friendlier than memorizing the special lua metamethod names for each of these. Each binds to a specific operation indicated by the descriptive name of the enum.
+
+members
+-------
+
+.. code-block:: cpp
+ :caption: function: usertype<T> constructor
+ :name: usertype-constructor
+
+ template<typename... Args>
+ usertype<T>(Args&&... args);
+
+
+The constructor of usertype takes a variable number of arguments. It takes an even number of arguments (except in the case where the very first argument is passed as the :ref:`constructor list type<constructor>`). Names can either be strings, :ref:`special meta_function enumerations<meta_function_enum>`, or one of the special indicators for initializers.
+
+
+usertype constructor options
+++++++++++++++++++++++++++++
+
+If you don't specify any constructor options at all and the type is `default_constructible`_, Sol will generate a ``new`` for you. Otherwise, the following are special ways to handle the construction of a usertype:
+
+.. _constructor:
+
+* ``"{name}", constructors<Type-List-0, Type-List-1, ...>``
+ - ``Type-List-N`` must be a ``sol::types<Args...>``, where ``Args...`` is a list of types that a constructor takes. Supports overloading by default
+ - If you pass the ``constructors<...>`` argument first when constructing the usertype, then it will automatically be given a ``"{name}"`` of ``"new"``
+* ``"{name}", sol::initializers( func1, func2, ... )``
+ - Used to handle *initializer functions* that need to initialize the memory itself (but not actually allocate the memory, since that comes as a userdata block from Lua)
+ - Given one or more functions, provides an overloaded Lua function for creating a the specified type
+ + The function must have the argument signature ``func( T*, Arguments... )`` or ``func( T&, Arguments... )``, where the pointer or reference will point to a place of allocated memory that has an uninitialized ``T``. Note that Lua controls the memory, so performing a ``new`` and setting it to the ``T*`` or ``T&`` is a bad idea: instead, use ``placement new`` to invoke a constructor, or deal with the memory exactly as you see fit
+* ``{anything}, sol::factories( func1, func2, ... )``
+ - Used to indicate that a factory function (e.g., something that produces a ``std::unique_ptr<T, ...>``, ``std::shared_ptr<T>``, ``T``, or similar) will be creating the object type
+ - Given one or more functions, provides an overloaded function for invoking
+ + The functions can take any form and return anything, since they're just considered to be some plain function and no placement new or otherwise needs to be done. Results from this function will be pushed into Lua according to the same rules as everything else.
+ + Can be used to stop the generation of a ``.new()`` default constructor since a ``sol::factories`` entry will be recognized as a constructor for the usertype
+ + If this is not sufficient, see next 2 entries on how to specifically block a constructor
+* ``{anything}, sol::no_constructor``
+ - Specifically tells Sol not to create a ``.new()`` if one is not specified and the type is default-constructible
+ - ``{anything}`` should probably be ``"new"``, which will specifically block its creation and give a proper warning if someone calls ``new`` (otherwise it will just give a nil value error)
+ - *Combine with the next one to only allow a factory function for your function type*
+* ``{anything}, {some_factory_function}``
+ - Essentially binds whatever the function is to name ``{anything}``
+ - When used WITH the ``sol::no_constructor`` option above (e.g. ``"new", sol::no_constructor`` and after that having ``"create", &my_creation_func``), one can remove typical constructor avenues and then only provide specific factory functions. Note that this combination is similar to using the ``sol::factories`` method mentioned earlier in this list. To control the destructor as well, see further below
+* ``sol::call_constructor, {valid function / constructor / initializer / factory}``
+ - The purpose of this is to enable the syntax ``local v = my_class( 24 )`` and have that call a constructor; it has no other purpose
+ - This is compatible with luabind, kaguya and other Lua library syntaxes and looks similar to C++ syntax, but the general consensus in Programming with Lua and other places is to use a function named ``new``
+
+usertype destructor options
++++++++++++++++++++++++++++
+
+If you don't specify anything at all and the type is `destructible`_, then a destructor will be bound to the garbage collection metamethod. Otherwise, the following are special ways to handle the destruction of a usertype:
+
+* ``"__gc", sol::destructor( func )`` or ``sol::meta_function::garbage_collect, sol::destructor( func )``
+ - Creates a custom destructor that takes an argument ``T*`` or ``T&`` and expects it to be destructed/destroyed. Note that lua controls the memory and thusly will deallocate the necessary space AFTER this function returns (e.g., do not call ``delete`` as that will attempt to deallocate memory you did not ``new``)
+ - If you just want the default constructor, you can replace the second argument with ``sol::default_destructor``
+ - The usertype will error / throw if you specify a destructor specifically but do not map it to ``sol::meta_function::gc`` or a string equivalent to ``"__gc"``
+
+usertype regular function options
++++++++++++++++++++++++++++++++++
+
+If you don't specify anything at all and the type ``T`` supports ``operator <``, ``operator <=``, or ``operator==`` (``const`` or non-``const`` qualified):
+
+* for ``operator <`` and ``operator <=``
+ - These two ``sol::meta_function::less_than(_or_equal_to)`` are generated for you and overriden in Lua.
+* for ``operator==``
+ - An equality operator will always be generated, doing pointer comparison if ``operator==`` on the two value types is not supported or doing a reference comparison and a value comparison if ``operator==`` is supported
+* heterogenous operators cannot be supported for equality, as Lua specifically checks if they use the same function to do the comparison: if they do not, then the equality method is not invoked; one way around this would be to write one ``int super_equality_function(lua_State* L) { ... }``, pull out arguments 1 and 2 from the stack for your type, and check all the types and then invoke ``operator==`` yourself after getting the types out of Lua (possibly using :ref:`sol::stack::get<stack-get>` and :ref:`sol::stack::check_get<stack-check-get>`)
+
+Otherwise, the following is used to specify functions to bind on the specific usertype for ``T``.
+
+* ``"{name}", &free_function``
+ - Binds a free function / static class function / function object (lambda) to ``"{name}"``. If the first argument is ``T*`` or ``T&``, then it will bind it as a member function. If it is not, it will be bound as a "static" function on the lua table
+* ``"{name}", &type::function_name`` or ``"{name}", &type::member_variable``
+ - Binds a typical member function or variable to ``"{name}"``. In the case of a member variable or member function, ``type`` must be ``T`` or a base of ``T``
+* ``"{name}", sol::readonly( &type::member_variable )``
+ - Binds a typical variable to ``"{name}"``. Similar to the above, but the variable will be read-only, meaning an error will be generated if anything attemps to write to this variable
+* ``"{name}", sol::as_function( &type::member_variable )``
+ - Binds a typical variable to ``"{name}"`` *but forces the syntax to be callable like a function*. This produces a getter and a setter accessible by ``obj:name()`` to get and ``obj::name(value)`` to set.
+* ``"{name}", sol::property( getter_func, setter_func )``
+ - Binds a typical variable to ``"{name}"``, but gets and sets using the specified setter and getter functions. Not that if you do not pass a setter function, the variable will be read-only. Also not that if you do not pass a getter function, it will be write-only
+* ``"{name}", sol::var( some_value )`` or ``"{name}", sol::var( std::ref( some_value ) )``
+ - Binds a typical variable to ``"{name}"``, optionally by reference (e.g., refers to the same memory in C++). This is useful for global variables / static class variables and the like
+* ``"{name}", sol::overloaded( Func1, Func2, ... )``
+ - Creates an oveloaded member function that discriminates on number of arguments and types.
+* ``sol::base_classes, sol::bases<Bases...>``
+ - Tells a usertype what its base classes are. You need this to have derived-to-base conversions work properly. See :ref:`inheritance<usertype-inheritance>`
+
+
+usertype arguments - simple usertype
+++++++++++++++++++++++++++++++++++++
+
+* ``sol::simple``
+ - Only allowed as the first argument to the usertype constructor, must be accompanied by a ``lua_State*``
+ - This tag triggers the :doc:`simple usertype<simple_usertype>` changes / optimizations
+ - Only supported when directly invoking the constructor (e.g. not when calling ``sol::table::new_usertype`` or ``sol::table::new_simple_usertype``)
+ - Should probably not be used directly. Use ``sol::table::new_usertype`` or ``sol::table::new_simple_usertype`` instead
+
+
+
+overloading
+-----------
+
+Functions set on a usertype support overloading. See :doc:`here<overload>` for an example.
+
+
+.. _usertype-inheritance:
+
+inheritance
+-----------
+
+Sol can adjust pointers from derived classes to base classes at runtime, but it has some caveats based on what you compile with:
+
+If your class has no complicated™ virtual inheritance or multiple inheritance, than you can try to sneak away with a performance boost from not specifying any base classes and doing any casting checks. (What does "complicated™" mean? Ask your compiler's documentation, if you're in that deep.)
+
+For the rest of us safe individuals out there: You must specify the ``sol::base_classes`` tag with the ``sol::bases<Types...>()`` argument, where ``Types...`` are all the base classes of the single type ``T`` that you are making a usertype out of.
+
+.. note::
+
+ Always specify your bases if you plan to retrieve a base class using the Sol abstraction directly and not casting yourself.
+
+.. code-block:: cpp
+ :linenos:
+
+ struct A {
+ int a = 10;
+ virtual int call() { return 0; }
+ };
+ struct B : A {
+ int b = 11;
+ virtual int call() override { return 20; }
+ };
+
+Then, to register the base classes explicitly:
+
+.. code-block:: cpp
+ :linenos:
+ :emphasize-lines: 5
+
+ sol::state lua;
+
+ lua.new_usertype<B>( "B",
+ "call", &B::call,
+ sol::base_classes, sol::bases<A>()
+ );
+
+.. note::
+
+ You must list ALL base classes, including (if there were any) the base classes of A, and the base classes of those base classes, etc. if you want Sol/Lua to handle them automagically.
+
+.. note::
+
+ Sol does not support down-casting from a base class to a derived class at runtime.
+
+.. warning::
+
+ Specify all base class member variables and member functions to avoid current implementation caveats regarding automatic base member lookup. Sol currently attempts to link base class methods and variables with their derived classes with an undocumented, unsupported feature, provided you specify ``sol::base_classes<...>``. Unfortunately, this can come at the cost of performance, depending on how "far" the base is from the derived class in the bases lookup list. If you do not want to suffer the performance degradation while we iron out the kinks in the implementation (and want it to stay performant forever), please specify all the base methods on the derived class in the method listing you write. In the future, we hope that with reflection we will not have to worry about this.
+
+
+inheritance + overloading
+-------------------------
+
+While overloading is supported regardless of inheritance caveats or not, the current version of Sol has a first-match, first-call style of overloading when it comes to inheritance. Put the functions with the most derived arguments first to get the kind of matching you expect or cast inside of an intermediary C++ function and call the function you desire.
+
+traits
+------
+
+.. code-block:: cpp
+ :caption: usertype_traits<T>
+ :name: usertype-traits
+
+ template<typename T>
+ struct usertype_traits {
+ static const std::string name;
+ static const std::string metatable;
+ static const std::string variable_metatable;
+ static const std::string gc_table;
+ };
+
+
+This trait is used to provide names for the various metatables and global tables used to perform cleanup and lookup. They are automagically generated at runtime. Sol attempts to parse the output of ``__PRETTY_FUCNTION__`` (``g++``/``clang++``) or ``_FUNCDSIG`` (``vc++``) to get the proper type name. If you have a special need you can override the names for your specific type. If you notice a bug in a class name when you don't manually specify it during setting a usertype, feel free to open an issue request or send an e-mail!
+
+
+compilation speed
+-----------------
+
+.. note::
+
+ If you find that compilation times are too long and you're only binding member functions, consider perhaps using :doc:`simple usertypes<simple_usertype>`. This can reduce compile times (but may cost memory size and speed). See the simple usertypes documentation for more details.
+
+
+performance note
+----------------
+
+.. note::
+
+ Note that performance for member function calls goes down by a fixed overhead if you also bind variables as well as member functions. This is purely a limitation of the Lua implementation and there is, unfortunately, nothing that can be done about it. If you bind only functions and no variables, however, Sol will automatically optimize the Lua runtime and give you the maximum performance possible. *Please consider ease of use and maintenance of code before you make everything into functions.*
+
+
+.. _destructible: http://en.cppreference.com/w/cpp/types/is_destructible
+.. _default_constructible: http://en.cppreference.com/w/cpp/types/is_constructible \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/usertype_memory.rst b/3rdparty/sol2/docs/source/api/usertype_memory.rst
new file mode 100644
index 00000000000..55734f7e543
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/usertype_memory.rst
@@ -0,0 +1,47 @@
+usertype memory
+===============
+
+.. note::
+
+ Sol does not take ownership of raw pointers, returned from functions or set through the ``set`` functions. Return a value, a ``std::unique_ptr``, a ``std::shared_ptr`` of some kind, or hook up the :doc:`unique usertypes traits<unique_usertype_traits>` to work for some specific handle structure you use (AKA, for ``boost::shared_ptr``).
+
+The userdata generated by Sol has a specific layout, depending on how Sol recognizes userdata passed into it. All of the referred to metatable names are generated from :ref:`usertype_traits\<T><usertype-traits>`
+
+In general, we always insert a T* in the first `sizeof(T*)` bytes, so the any framework that pulls out those first bytes expecting a pointer will work. The rest of the data has some different alignments and contents based on what it's used for and how it's used.
+
+For ``T``
+---------
+
+These are classified with the metatable name from :ref:`usertype_traits\<T><usertype-traits>`.
+
+The data layout for references is as follows::
+
+ | T* | T |
+ ^-sizeof(T*) bytes-^-sizeof(T) bytes, actual data-^
+
+Lua will clean up the memory itself but does not know about any destruction semantics T may have imposed, so when we destroy this data we simply call the destructor to destroy the object and leave the memory changes to for lua to handle after the "__gc" method exits.
+
+
+For ``T*``
+----------
+
+These are classified as a separate ``T*`` metatable, essentially the "reference" table. Things passed to Sol as a pointer or as a ``std::reference<T>`` are considered to be references, and thusly do not have a ``__gc`` (garbage collection) method by default. All raw pointers are non-owning pointers in C++. If you're working with a C API, provide a wrapper around pointers that are supposed to own data and use the constructor/destructor idioms (e.g., with an internal ``std::unique_ptr``) to keep things clean.
+
+The data layout for data that only refers is as follows::
+
+ | T* |
+ ^-sizeof(T*) bytes-^
+
+That is it. No destruction semantics need to be called.
+
+For ``std::unique_ptr<T, D>`` and ``std::shared_ptr<T>``
+--------------------------------------------------------
+
+These are classified as :ref:`"unique usertypes"<unique-usertype>`, and have a special metatable for them as well. The special metatable is either generated when you add the usertype to Lua using :ref:`set_usertype<set-usertype>` or when you first push one of these special types. In addition to the data, a deleter function that understands the following layout is injected into the usertype.
+
+The data layout for these kinds of types is as follows::
+
+ | T* | void(*)(void*) function_pointer | T |
+ ^-sizeof(T*) bytes-^-sizeof(void(*)(void*)) bytes, deleter-^- sizeof(T) bytes, actal data -^
+
+Note that we put a special deleter function before the actual data. This is because the custom deleter must know where the offset to the data is, not the rest of the library. Sol just needs to know about ``T*`` and the userdata (and userdata metatable) to work, everything else is for preserving construction / destruction semantics. \ No newline at end of file
diff --git a/3rdparty/sol2/docs/source/api/var.rst b/3rdparty/sol2/docs/source/api/var.rst
new file mode 100644
index 00000000000..9e9bcec57d9
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/var.rst
@@ -0,0 +1,49 @@
+var
+===
+For hooking up static / global variables to Lua usertypes
+---------------------------------------------------------
+
+The sole purpose of this tagging type is to work with :doc:`usertypes<usertype>` to provide ``my_class.my_static_var`` access, and to also provide reference-based access as well.
+
+.. code-block:: cpp
+
+ #include <sol.hpp>
+
+ struct test {
+ static int muh_variable;
+ };
+ int test::muh_variable = 25;
+
+
+ int main () {
+ sol::state lua;
+ lua.open_libraries();
+ lua.new_usertype<test>("test",
+ "direct", sol::var(2),
+ "global", sol::var(test::muh_variable),
+ "ref_global", sol::var(std::ref(test::muh_variable))
+ );
+
+ int direct_value = lua["test"]["direct"];
+ // direct_value == 2
+
+ int global = lua["test"]["global"];
+ // global == 25
+ int global2 = lua["test"]["ref_global"];
+ // global2 == 25
+
+ test::muh_variable = 542;
+
+ global = lua["test"]["global"];
+ // global == 25
+ // global is its own memory: was passed by value
+
+ global2 = lua["test"]["ref_global"];
+ // global2 == 542
+ // global2 was passed through std::ref
+ // global2 holds a reference to muh_variable
+ // if muh_variable goes out of scope or is deleted
+ // problems could arise, so be careful!
+
+ return 0;
+ }
diff --git a/3rdparty/sol2/docs/source/api/variadic_args.rst b/3rdparty/sol2/docs/source/api/variadic_args.rst
new file mode 100644
index 00000000000..5d3e0c10282
--- /dev/null
+++ b/3rdparty/sol2/docs/source/api/variadic_args.rst
@@ -0,0 +1,49 @@
+variadic_args
+=============
+transparent argument to deal with multiple parameters to a function
+-------------------------------------------------------------------
+
+
+.. code-block:: cpp
+
+ struct variadic_args;
+
+This class is meant to represent every single argument at its current index and beyond in a function list. It does not increment the argument count and is thus transparent. You can place it anywhere in the argument list, and it will represent all of the objects in a function call that come after it, whether they are listed explicitly or not.
+
+``variadic_args`` also has ``begin()`` and ``end()`` functions that return (almost) random-acess iterators. These return a proxy type that can be implicitly converted, much like the :doc:`table proxy type<proxy>`.
+
+.. code-block:: cpp
+ :linenos:
+
+ #include <sol.hpp>
+
+ int main () {
+
+ sol::state lua;
+
+ // Function requires 2 arguments
+ // rest can be variadic, but:
+ // va will include everything after "a" argument,
+ // which means "b" will be part of the varaidic_args list too
+ // at position 0
+ lua.set_function("v", [](int a, sol::variadic_args va, int b) {
+ int r = 0;
+ for (auto v : va) {
+ int value = v; // get argument out (implicit conversion)
+ // can also do int v = va.get<int>(i); with index i
+ r += value;
+ }
+ // Only have to add a, b was included
+ return r + a;
+ });
+
+ lua.script("x = v(25, 25)");
+ lua.script("x2 = v(25, 25, 100, 50, 250, 150)");
+ lua.script("x3 = v(1, 2, 3, 4, 5, 6)");
+ // will error: not enough arguments
+ //lua.script("x4 = v(1)");
+
+ lua.script("print(x)"); // 50
+ lua.script("print(x2)"); // 600
+ lua.script("print(x3)"); // 21
+ }