New [Game] mantling setting, on by default, with mantle max height (1.1 times the actor's height above its feet) and mantle duration (0.4 s). When the player jumps or falls into a wall while moving towards it (within 60 degrees), the movement solver casts the player's collision shape up, across the edge and down. If it finds a surface flat enough to stand on, above the feet and within reach, with headroom and room on top, the player moves up, across and onto it along that checked path. Movement and jump input are ignored meanwhile, and the climb ends any fall without fall damage. No animation is needed. A script move or teleport, noclip or paralysis cancels a climb. Lua: self.controls.mantle (true by default) vetoes climbs while false, and the actor's scripts get an AshlarMantle event with the ledge height when one starts. The engine logs "Ashlar mantle:" lines at verbose level. Player only; with the setting off nothing changes. The geometry rules (reach, headroom, room on top, slope, too high, too low) and the climb path are in mwphysics/mantle.cpp, apart from the physics calls, with unit tests. The new mantle scenario uses a CC0 box mesh written for it: the player climbs an 80 unit ledge, doesn't climb it with the Lua veto, and doesn't climb a 240 unit wall. Closes #28 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MWLua
This folder contains the C++ implementation of the Lua scripting system.
For user-facing documentation, see Lua scripting. The documentation is generated from /docs/source/reference/lua-scripting. You can find instructions for generating the documentation at the root of the docs folder.
The Lua API reference is generated from the specifications in /files/lua_api. They are written in the Lua Development Tool Documentation Language, and also enable autocompletion for (LDT) users. Please update them to reflect any changes you make.
MWLua::LuaManager
The Lua manager is the central interface through which information flows from the engine to the scripts and back.
Lua is executed in a separate thread by
default.
This thread executes update() in parallel with rendering logic (specifically with OSG Cull traversal).
Because of this, Lua must not synchronously mutate anything that can directly or indirectly affect the scene graph.
Instead such changes are queued to mActionQueue. They are then processed by
synchronizedUpdate(), which is executed by the main thread.
The Lua thread is paused while other updates of the game state take place,
which means that state that doesn't affect the scene graph
can be mutated immediately. There is no easy way to characterize
which things affect the graph, you'll need to inspect the code.
Bindings
The bulk of the code in this folder consists of bindings that expose C++ data to Lua.
As explained in the scripting overview,
there are Global and Local scripts, and they have different capabilities.
A Local script has read-only access to objects other the one it is attached to.
The bindings use the types MWLua::GObject, MWLua::LObject, MWLua::SelfObject to enforce this behaviour.
MWLua::GObjectis used in global scriptsMWLua::LObjectis used in local scripts (readonly),MWLua::SelfObjectis the object the local script is attached to.MWLua::Objectis the common base of all 3.
Functions that don't change objects are usually available in both local and global scripts so they accept MWLua::Object.
Some (for example setEquipment in actor.cpp)
should work only on self and because of this have argument of type SelfObject.
There are also cases where a function is available in both local and global scripts, but has different effects in different cases.
For example see the binding actor["inventory"] in 'MWLua::addActorBindings` in actor.cpp:
actor["inventory"] = sol::overload([](const LObject& o) { return Inventory<LObject>{ o }; },
[](const GObject& o) { return Inventory<GObject>{ o }; });
The difference is that Inventory<LObject> is readonly and Inventory<GObject> is mutable.
The read-only bindings are defined for both, but some functions are exclusive for Inventory<GObject>.
Mutations that affect the scene graph
Because of the threading issues mentioned under MWLua::LuaManager,
bindings that mutate things that affect the scene graph
must be implemented by queuing an action with LuaManager::addAction.
Here is an example that illustrates action queuing,
along with the differences between GObject and LObject:
// We can always read the value because OSG Cull doesn't modify `RefData`.
auto isEnabled = [](const Object& o) { return o.ptr().getRefData().isEnabled(); };
// Changing the value must be queued because `World::enable`/`World::disable` aside of
// changing `RefData` also adds/removes the object to the scene graph.
auto setEnabled = [context](const Object& object, bool enable) {
// It is important that the lambda state stores `object` and not the result of
// `object.ptr()` because when delayed will be executed the old Ptr can potentially
// be already invalidated.
context.mLuaManager->addAction([object, enable] {
if (enable)
MWBase::Environment::get().getWorld()->enable(object.ptr());
else
MWBase::Environment::get().getWorld()->disable(object.ptr());
});
};
// Local scripts can only view the value (because in multiplayer local scripts
// will be client-side and we want to avoid synchronization issues).
LObjectMetatable["enabled"] = sol::readonly_property(isEnabled);
// Global scripts can both read and modify the value.
GObjectMetatable["enabled"] = sol::property(isEnabled, setEnabled);
Please note that queueing means changes scripts make won't be visible to other scripts before the next frame. If you want to avoid that, you can implement a cache in the bindings. The first write will create the cache and queue the value to be synchronized from the cache to the engine in the next synchronization. Later writes will update the cache. Reads will read the cache if it exists. See LocalScripts::SelfObject::mStatsCache for an example.