Files
ashlar/docs/source/reference/lua-scripting/events.rst
T
claudeandClaude Opus 5.5 9e28969629
Ashlar checks / tooling (push) Successful in 5s
Add ledge mantling
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>
2026-11-15 15:44:40 -05:00

282 lines
7.9 KiB
ReStructuredText

Events
======
.. include:: version.rst
Actor events
------------
**DialogueResponse**
This event is sent to the player's local script when an actor triggers a greeting, topic response, service refusal, or plays a voice line.
It returns a lua table with the following fields:
- ``actor``: The actor that responded.
- ``type``: The type of ``DialogueRecord`` that triggered the event, can be ``"greeting"``, ``"journal"``, ``"persuasion"``, ``"topic"``, or ``"voice"``.
- ``recordId``: The ID of the ``DialogueRecord``.
- ``infoId``: The ID of the ``DialogueRecordInfo`` in question.
.. code-block:: Lua
eventHandlers = {
DialogueResponse = function(e)
local topic = core.dialogue[e.type].records[e.recordId];
for _, info in pairs(topic.infos) do
if info.id == e.infoId then
print(e.actor, 'said', info.text)
return
end
end
end
}
**Died**
This event is sent to an actor's local script when that actor dies.
.. code-block:: Lua
eventHandlers = {
Died = function()
print('Alas, ye hardly knew me!')
end
}
**AshlarMantle**
Ashlar. Sent to an actor's local scripts when the actor starts climbing onto a ledge (``[Game] mantling``). ``height``
is how far the ledge is above the actor's feet. To stop climbs, set ``self.controls.mantle = false``.
.. code-block:: Lua
eventHandlers = {
AshlarMantle = function(e)
print('Climbing a ledge', e.height, 'units up')
end
}
**StartAIPackage, RemoveAIPackages**
Any script can send to any actor (except player, for player will be ignored) events ``StartAIPackage`` and ``RemoveAIPackages``.
The effect is equivalent to calling ``interfaces.AI.startPackage`` or ``interfaces.AI.removePackages`` in a local script on this actor.
Examples:
.. code-block:: Lua
actor:sendEvent('StartAIPackage', {type='Combat', target=self.object})
actor:sendEvent('RemoveAIPackages', 'Pursue')
**UseItem**
Any script can send global event ``UseItem`` with arguments ``object``, ``actor``, and optional boolean ``force``.
The actor will use (e.g. equip or consume) the object. The object should be in the actor's inventory.
Example:
.. code-block:: Lua
core.sendGlobalEvent('UseItem', {object = potion, actor = player, force = true})
**ModifyStat**
Modify the corresponding stat.
.. code-block:: Lua
-- Consume 10 magicka
actor:sendEvent('ModifyStat', {stat = 'magicka', amount = -10})
**AddVfx**
Calls the corresponding method in openmw.animation
.. code-block:: Lua
local eventParams = {
model = 'vfx_default',
options = {
textureOverride = effect.particle,
},
}
actor:sendEvent('AddVfx', eventParams)
**PlaySound3d**
Calls the corresponding function in openw.core on the target. Will use core.sound.playSoundFile3d instead of core.sound.playSound3d if you put `file` instead of `sound` in the event data.
.. code-block:: Lua
actor:sendEvent('PlaySound3d', {sound = 'Open Lock'})
**BreakInvisibility**
Forces the actor to lose all active invisibility effects.
**Unequip**
Any script can send ``Unequip`` events with the argument ``item`` or ``slot`` to any actor, to make that actor unequip an item.
The following two examples are equivalent, except the ``item`` variant is guaranteed to only unequip the specified item and won't unequip a different item if the actor's equipment changed during the same frame:
.. code-block:: Lua
local item = Actor.getEquipment(actor, Actor.EQUIPMENT_SLOT.CarriedLeft)
if item then
actor:sendEvent('Unequip', {item = item})
end
.. code-block:: Lua
actor:sendEvent('Unequip', {slot = Actor.EQUIPMENT_SLOT.CarriedLeft})
Combat events
-------------
**Hit**
Any script can send ``Hit`` events with arguments described in the Combat interface to cause a hit to an actor
Example:
.. code-block:: Lua
-- See Combat#AttackInfo
local attack = {
attacker = self,
weapon = Actor.getEquipment(self, Actor.EQUIPMENT_SLOT.CarriedRight),
sourceType = I.Combat.ATTACK_SOURCE_TYPES.Melee,
strength = 1,
type = self.ATTACK_TYPE.Chop,
damage = {
health = 20,
fatigue = 10,
},
successful = true,
}
victim:sendEvent('Hit', attack)
Item events
-----------
**ModifyItemCondition**
Any script can send ``ModifyItemCondition`` events to global to adjust the condition of an item.
Example:
.. code-block:: Lua
local item = Actor.getEquipment(actor, Actor.EQUIPMENT_SLOT.CarriedLeft)
if item then
-- Reduce condition by 1
-- Note that actor should be included, if applicable, to allow forcibly unequipping items whose condition is reduced to 0
core.sendGlobalEvent('ModifyItemCondition', {actor = self, item = item, amount = -1})
end
Spellcast events
----------------
**ApplyMagicEffects**
Used by built-in scripts to apply effects on Lockables and other actors during spellcasting.
UI events
---------
**ShowMessage**
If sent to a player, shows a message as if a call to ui.showMessage was made.
.. code-block:: Lua
player:sendEvent('ShowMessage', {message = 'Lorem ipsum', showInDialogue = false})
**UiModeChanged**
Every time UI mode is changed built-in scripts send to player the event ``UiModeChanged`` with arguments ``oldMode, ``newMode`` (same as ``I.UI.getMode()``)
and ``arg`` (for example in the mode ``Book`` the argument is the book the player is reading).
.. code-block:: Lua
eventHandlers = {
UiModeChanged = function(data)
print('UiModeChanged from', data.oldMode , 'to', data.newMode, '('..tostring(data.arg)..')')
end
}
**AddUiMode**
Equivalent to ``I.UI.addMode``, but can be sent from another object or global script.
.. code-block:: Lua
player:sendEvent('AddUiMode', {mode = 'Book', target = book})
**SetUiMode**
Equivalent to ``I.UI.setMode``, but can be sent from another object or global script.
.. code-block:: Lua
player:sendEvent('SetUiMode', {mode = 'Book', target = book})
World events
------------
Global events that just call the corresponding function in `openmw.world`.
.. code-block:: Lua
-- world.pause(tag)
core.sendGlobalEvent('Pause', tag)
-- world.unpause(tag)
core.sendGlobalEvent('Unpause', tag)
-- world.setGameTimeScale(scale)
core.sendGlobalEvent('SetGameTimeScale', scale)
-- world.setSimulationTimeScale(scale)
core.sendGlobalEvent('SetSimulationTimeScale', scale)
**SpawnVfx, PlaySound3d**
Calls the corresponding function in openw.core. Note that PlaySound3d will call core.sound.playSoundFile3d instead of core.sound.playSound3d if you put `file` instead of `sound` in the event data.
.. code-block:: Lua
core.sendGlobalEvent('SpawnVfx', {position = hitPos, model = 'vfx_destructarea', options = {scale = 10}})
core.sendGlobalEvent('PlaySound3d', {sound = 'Open Lock', position = container.position})
**ConsumeItem**
Reduces stack size of an item by a given amount, removing the item completely if stack size is reduced to 0 or less.
.. code-block:: Lua
core.sendGlobalEvent('ConsumeItem', {item = foobar, amount = 1})
**Lock**
Lock a container or door
.. code-block:: Lua
core.sendGlobalEvent('Lock', {target = selected, magnitude = 50})
**Unlock**
Unlock a container or door
.. code-block:: Lua
core.sendGlobalEvent('Unlock', {target = selected})
**SetSaveState**
Sets whether or not an object will be written into the save. For script-spawned objects, setting this to false effectively means they are deleted after the game loads. For objects from content files, setting this to false restores them to their original state upon loading.
Use this as a means to easily reset **individual** objects. To reset all objects in a given cell instead, use `cell:getAll` and call `object:setSaveState(false)` on each object.
.. code-block:: Lua
core.sendGlobalEvent('SetSaveState', { nearby.actors[#nearby.actors] = false })