Ashlar checks / tooling (push) Successful in 5s
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>
282 lines
7.9 KiB
ReStructuredText
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 })
|