OpenMW

https://openmw.readthedocs.io
Admin
OpenMW is an open-source implementation of the Morrowind game engine with modding tools, Lua...
Tokens:142,107
Snippets:1,769
Trust Score:9.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install OpenMW on Void Linux

Source: https://openmw.readthedocs.io/en/stable/manuals/installation/install-openmw.html

Install the binary package from the official repository.

```bash
$ xbps-install openmw
```

--------------------------------

### Install OpenMW on Ubuntu via PPA

Source: https://openmw.readthedocs.io/en/stable/manuals/installation/install-openmw.html

Use the official Launchpad PPA to install OpenMW on Ubuntu systems.

```bash
$ sudo add-apt-repository ppa:openmw/openmw
$ sudo apt update
$ sudo apt install openmw
```

--------------------------------

### Install OpenMW via Flatpak

Source: https://openmw.readthedocs.io/en/stable/manuals/installation/install-openmw.html

Install the OpenMW package using the Flatpak command-line utility.

```bash
$ flatpak install openmw
```

--------------------------------

### Install OpenMW on Arch Linux

Source: https://openmw.readthedocs.io/en/stable/manuals/installation/install-openmw.html

Install the binary package from the official community repositories.

```bash
$ pacman -S openmw
```

--------------------------------

### Install OpenMW on Fedora

Source: https://openmw.readthedocs.io/en/stable/manuals/installation/install-openmw.html

Install OpenMW components using the dnf package manager.

```bash
$ dnf install openmw
$ dnf install openmw-cs
$ dnf install openmw-tools
```

--------------------------------

### menu.newGame()

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_menu.html

Starts a new game.

```APIDOC
## menu.newGame()

### Description
Start a new game.
```

--------------------------------

### AI.startPackage

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/index_aipackages.html

Starts an AI package on the local actor using the AI interface.

```APIDOC
## AI.startPackage(options)

### Description
Starts an AI package on the script's owner (self).

### Parameters
- **options** (table) - Required - A table containing the configuration options for the AI package.
```

--------------------------------

### Install innoextract on macOS

Source: https://openmw.readthedocs.io/en/stable/manuals/installation/install-game-files.html

Use Homebrew to install innoextract on macOS systems.

```bash
$ brew install innoextract
```

--------------------------------

### Create and place objects in the world

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_world.html

Examples demonstrating how to create objects and place them in the world or into an inventory.

```lua
-- put 100 gold on the ground at the position of `actor`
money = world.createObject('gold_001', 100)
money:teleport(actor.cell.name, actor.position)
```

```lua
-- put 50 gold into the actor's inventory
money = world.createObject('gold_001', 50)
money:moveInto(types.Actor.inventory(actor))
```

```lua
-- create the an object for the first generated item
potion = world.createObject('Generated:0x0', 1)
```

--------------------------------

### Install innoextract on Debian/Ubuntu

Source: https://openmw.readthedocs.io/en/stable/manuals/installation/install-game-files.html

Use the apt package manager to install innoextract on Debian-based Linux distributions.

```bash
$ sudo apt update
$ sudo apt install innoextract
```

--------------------------------

### StartAIPackage Event

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/index_aipackages.html

Starts an AI package on any actor by sending a 'StartAIPackage' event.

```APIDOC
## actor:sendEvent('StartAIPackage', options)

### Description
Triggers the 'StartAIPackage' event on a specified actor to initiate an AI package.

### Parameters
- **options** (table) - Required - A table containing the configuration options for the AI package.
```

--------------------------------

### Complete shader example

Source: https://openmw.readthedocs.io/en/stable/reference/postprocessing/omwfx.html

A full OMWFX shader file combining uniform definitions, fragment logic, and technique configuration.

```omwfx
uniform_float uDesaturationFactor {
    default = 0.5;
    min = 0.0;
    max = 1.0;
    step = 0.05;
    description = "Desaturation factor. A value of 1.0 is full grayscale.";
}

fragment desaturate {
    omw_In vec2 omw_TexCoord;

    void main()
    {
        // fetch scene texture from last shader
        vec4 scene = omw_GetLastShader(omw_TexCoord);

        // desaturate RGB component
        const vec3 luminance = vec3(0.299, 0.587, 0.144);
        float gray = dot(luminance, scene.rgb);

        omw_FragColor = vec4(mix(scene.rgb, vec3(gray), uDesaturationFactor), scene.a);
    }
}

technique {
    description = "Desaturates scene";
    passes = desaturate;
    version = "1.0";
    author = "Fargoth";
    passes = desaturate;
}
```

--------------------------------

### Start Combat AI Package

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/ai/combat.html

Demonstrates initiating a combat package on an actor using either a local script or an event.

```lua
-- from local script add package to self
local AI = require('openmw.interfaces').AI
AI.startPackage({type='Combat', target=anotherActor})

-- via event to any actor
actor:sendEvent('StartAIPackage', {type='Combat', target=anotherActor})
```

--------------------------------

### Define scripts in .omwscripts

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/overview.html

Example configuration showing how to register global, player, and local scripts using various flags.

```text
# Lines starting with '#' are comments

GLOBAL: scripts/my_mod/some_global_script.lua

# Script that will be automatically attached to the player
PLAYER: scripts/my_mod/player.lua

# Local script that will be automatically attached to every NPC and every creature in the game
NPC, CREATURE: scripts/my_mod/some_other_script.lua

# Local script that can be attached to any object by a global script
CUSTOM: scripts/my_mod/something.lua

# Local script that will be automatically attached to any Container AND can be
# attached to any other object by a global script.
CONTAINER, CUSTOM: scripts/my_mod/container.lua
```

--------------------------------

### Single openmw.cfg configuration for portable install

Source: https://openmw.readthedocs.io/en/stable/reference/modding/paths.html

Modify the local openmw.cfg to use relative paths for userdata and configuration, allowing for a self-contained installation.

```text
# This is the local openmw.cfg file. Do not modify!
# Modifications should be done on the user openmw.cfg file instead
# (see: https://openmw.readthedocs.io/en/master/reference/modding/paths.html)

data-local="?userdata?data"
user-data="?userdata?"
config="?userconfig?"
resources=./resources
data=./resources/vfs-mw

# lighting
fallback=LightAttenuation_UseConstant,0
fallback=LightAttenuation_ConstantValue,0.0
fallback=LightAttenuation_UseLinear,1
```

```text
data-local=userdata/data
user-data=userdata
resources=./resources
data=./resources/vfs-mw

# lighting
fallback=LightAttenuation_UseConstant,0
fallback=LightAttenuation_ConstantValue,0.0
fallback=LightAttenuation_UseLinear,1
```

--------------------------------

### Separate user openmw.cfg configuration for portable install

Source: https://openmw.readthedocs.io/en/stable/reference/modding/paths.html

Configure a local openmw.cfg to point to a separate user configuration directory, maintaining a structure similar to a standard installation.

```text
# This is the local openmw.cfg file. Do not modify!
# Modifications should be done on the user openmw.cfg file instead
# (see: https://openmw.readthedocs.io/en/master/reference/modding/paths.html)

data-local="?userdata?data"
user-data="?userdata?"
config="?userconfig?"
resources=./resources
data=./resources/vfs-mw

# lighting
fallback=LightAttenuation_UseConstant,0
fallback=LightAttenuation_ConstantValue,0.0
fallback=LightAttenuation_UseLinear,1
```

```text
# This is the local openmw.cfg file. Do not modify!
# Modifications should be done on the user openmw.cfg file instead
# (see: https://openmw.readthedocs.io/en/master/reference/modding/paths.html)

data-local="userdata/data"
user-data="userdata"
config="config"
resources=./resources
data=./resources/vfs-mw

# lighting
fallback=LightAttenuation_UseConstant,0
fallback=LightAttenuation_ConstantValue,0.0
fallback=LightAttenuation_UseLinear,1
```

--------------------------------

### Localization Setup and Usage

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_core.html

Define localization files in the VFS and use core.l10n to retrieve formatting functions for translated strings.

```yaml
# DataFiles/l10n/MyMod/en.yaml
good_morning: 'Good morning.'
you_have_arrows: |-
  {count, plural,
    one {You have one arrow.}
    other {You have {count} arrows.}
  }
```

--------------------------------

### Start Escort AI Package

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/ai/escort.html

Initiates an escort behavior for an actor using the sendEvent method with the 'StartAIPackage' event.

```lua
actor:sendEvent('StartAIPackage', {
    type = 'Escort',
    target = object.self,
    destPosition = util.vector3(x, y, z),
    duration = 3 * time.hour,
    isRepeat = true
})
```

--------------------------------

### AI.forEachPackage

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/interface_ai.html

Iterates over all AI packages and executes a callback function for each, starting from the active one.

```APIDOC
## AI.forEachPackage(callback)

### Description
Iterate over all packages and run `callback` for each starting from the active one.

### Parameters
- **callback** (function) - Required - The function to execute for each package.
```

--------------------------------

### Starting an AI package

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/index_aipackages.html

Use these methods to initiate AI behavior for an actor. The first method is for local scripts, while the second is for triggering packages on any actor via events.

```lua
-- from local script add package to self
local AI = require('openmw.interfaces').AI
AI.startPackage(options)

-- via event to any actor
actor:sendEvent('StartAIPackage', options)
```

--------------------------------

### UI resource files

Source: https://openmw.readthedocs.io/en/stable/reference/modding/openmw-game-template.html

List of UI files from the Template that must be copied to the OpenMW installation resources/mygui folder.

```text
openmw_box.skin.xml
openmw_button.skin.xml
openmw_font.xml
openmw_windows.skin.xml
Pelagiad.ttf
```

--------------------------------

### Accessing Topic Records

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_core.html

Examples for iterating over topic records and accessing specific topic information.

```lua
--print ids of all topic records
for _, topicRecord in pairs(core.dialogue.topic.records) do
    print(topicRecord.id)
end
```

```lua
--print all NPC lines for "vivec"
for idx, topicInfo in pairs(core.dialogue.topic.records["vivec"].infos) do
    print(idx, topicInfo.text)
end
```

--------------------------------

### Configure GUI Tooltip Delay

Source: https://openmw.readthedocs.io/en/stable/reference/modding/settings/index.html

Example of adding a category header and a specific setting to the settings.cfg file to delay tooltips by 1 second.

```text
[GUI]
tooltip delay = 1.0
```

--------------------------------

### Register Script in omwscripts

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/user_interface.html

Example configuration for registering a Lua script in an omwscripts file.

```text
PLAYER: scripts/clock.lua
```

--------------------------------

### Accessing Greeting Records

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_core.html

Examples for iterating over greeting records and accessing specific greeting information.

```lua
--print ids of all greeting records
for _, greetingRecord in pairs(core.dialogue.greeting.records) do
    print(greetingRecord.id)
end
```

```lua
--print all NPC lines for "greeting 0"
for idx, greetingInfo in pairs(core.dialogue.greeting.records["greeting 0"].infos) do
    print(idx, greetingInfo.text)
end
```

--------------------------------

### Play animations with custom settings

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_animation.html

Examples of clearing the animation queue and playing specific animation groups with custom keys or immediate execution.

```lua
-- Play death1 without waiting. Equivalent to playgroup, death1, 1
anim.clearAnimationQueue(self, false)
anim.playQueued(self, 'death1')
```

```lua
-- Play an animation group with custom start/stop keys
anim.clearAnimationQueue(self, false)
anim.playQueued(self, 'spellcast', { startKey = 'self start', stopKey = 'self stop' })
```

--------------------------------

### Extract Morrowind files with innoextract

Source: https://openmw.readthedocs.io/en/stable/manuals/installation/install-game-files.html

Extract game files from the GOG installer executable to a specified directory.

```bash
$ innoextract ./setup_tes_morrowind_goty_2.0.0.7.exe -d ~/Documents/Games/Morrowind/
```

--------------------------------

### Define technique block

Source: https://openmw.readthedocs.io/en/stable/reference/postprocessing/omwfx.html

Example of a technique block requiring GLSL 330, HDR, and specific flags.

```glsl
fragment dummy {
    void main()
    {
        omw_FragColor = vec4(0.0);
    }
}

technique {
    passes = dummy;
    glsl_version = 330;
    hdr = true;
    flags = disable_interiors, disable_abovewater;
}
```

--------------------------------

### Basic Localisation YAML

Source: https://openmw.readthedocs.io/en/stable/reference/modding/localisation.html

Example of simple string translations and pluralization rules in a YAML localisation file.

```yaml
good_morning: 'Good morning.'

you_have_arrows: |-
  {count, plural,
    one {You have one arrow.}
    other {You have {count} arrows.}
  }
```

```yaml
good_morning: "Guten Morgen."
you_have_arrows: |-
  {count, plural,
    one {Du hast ein Pfeil.}
    other {Du hast {count} Pfeile.}
  }
"Hello {name}!": "Hallo {name}!"
```

--------------------------------

### Launch OpenMW directly to a cell

Source: https://openmw.readthedocs.io/en/stable/manuals/openmw-cs/tour.html

Use these command line arguments to bypass the menu and start directly in a specific game cell for testing.

```bash
--start="Ancient Shipwreck, Cabin" --skip-menu
```

--------------------------------

### Vector2 Usage Examples

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_util.html

Demonstrates common operations for the immutable Vector2 type, including initialization, arithmetic, and swizzling.

```lua
v = util.vector2(3, 4)
v.x, v.y       -- 3.0, 4.0
str(v)         -- "(3.0, 4.0)"
v:length()     -- 5.0    length
v:length2()    -- 25.0   square of the length
v:normalize()  -- vector2(3/5, 4/5)
v:rotate(radians)    -- rotate counterclockwise (returns rotated vector)
v1:dot(v2)     -- dot product (returns a number)
v1 * v2        -- dot product
v1 + v2        -- vector addition
v1 - v2        -- vector subtraction
v1 * x         -- multiplication by a number
v1 / x         -- division by a number
v1.xx, v1.xyx  -- swizzle with standard fields
v1.y1y, v1.x00 -- swizzle with 0/1 constant
v1['0xy']      -- swizzle with 0/1 constant starting with 0 or 1
```

--------------------------------

### Accessing Weather Records

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_core.html

Examples of retrieving weather records from the global weather list by ID or index, and iterating through them.

```lua
local weather = core.weather.records['Cloudy']  -- get by id
```

```lua
local weather = core.weather.records[1]  -- get by index
```

```lua
-- Print all storms
for _, weather in pairs(core.weather.records) do
    if weather.isStorm then
        print(weather.name)
    end
end
```

--------------------------------

### Registering and Accessing Settings

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/interface_settings.html

Demonstrates how to register a settings page and group, and how to retrieve values from storage.

```lua
-- In a player script
local storage = require('openmw.storage')
local I = require('openmw.interfaces')
I.Settings.registerPage {
    key = 'MyModPage',
    l10n = 'MyMod',
    name = 'My Mod Name',
    description = 'My Mod Description',
}
I.Settings.registerGroup {
    key = 'SettingsPlayerMyMod',
    page = 'MyModPage',
    l10n = 'MyMod',
    name = 'My Group Name',
    description = 'My Group Description',
    permanentStorage = false,
    settings = {
        {
            key = 'Greeting',
            renderer = 'textLine',
            name = 'Greeting',
            description = 'Text to display when the game starts',
            default = 'Hello, world!',
        },
    },
}
local playerSettings = storage.playerSection('SettingsPlayerMyMod')
...
ui.showMessage(playerSettings:get('Greeting'))
-- ...
-- access a setting page registered by a global script
local globalSettings = storage.globalSection('SettingsGlobalMyMod')
```

--------------------------------

### Access Player Journal Topic Entries

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_types.html

Examples for interacting with conversation lines within specific journal topics.

```lua
-- First NPC topic line entry in the "Background" topic
local firstBackgroundLine = types.Player.journal(player).topics["Background"].entries[1]
```

```lua
-- The number of topic entries accumulated in the player journal for "Vivec"
local num = #types.Player.journal(player).topics["vivec"].entries
```

```lua
-- Print all conversation lines accumulated in the player journal for "Balmora"
for idx, topicEntry in pairs(types.Player.journal(player).topics["balmora"].entries) do
    print(idx, topicEntry.text)
end
```

--------------------------------

### Import openmw_aux.util

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_aux_util.html

Load the utility module to access its functions.

```lua
local aux_util = require('openmw_aux.util')
```

--------------------------------

### Start Wander AI Package

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/ai/wander.html

Initiates a Wander AI package for an actor using a table of idle chances and specific movement parameters.

```lua
local idleTable = {
    idle2 = 60,
    idle3 = 50,
    idle4 = 40,
    idle5 = 30,
    idle6 = 20,
    idle7 = 10,
    idle8 = 0,
    idle9 = 25
}
actor:sendEvent('StartAIPackage', {
    type = 'Wander',
    distance = 5000,
    duration = 5 * time.hour,
    idle = idleTable,
    isRepeat = true
})
```

--------------------------------

### Create a .desktop file for Linux

Source: https://openmw.readthedocs.io/en/stable/reference/modding/paths.html

Define a desktop entry to launch OpenMW with custom configuration profiles on Linux systems.

```ini
[Desktop Entry]
Type=Application
Name=OpenMW - Total Overhaul
GenericName=Role Playing Game
Comment=OpenMW with the Total Overhaul profile
Keywords=Morrowind;Reimplementation Mods;esm;bsa;
TryExec=openmw
Exec=openmw --replace config --config ?userconfig?/Morrowind --config "?userconfig?/Morrowind/Total Overhaul"
Icon=openmw
Categories=Game;RolePlaying;
```

--------------------------------

### Door.getDoorState(object)

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_types.html

Gets the current state of the door.

```APIDOC
### Door.getDoorState(object)

**Description:** Returns the current state of the door.

**Parameters:**
- **object** (openmw.core#GameObject) - The door object to query.

**Returns:**
- #DoorSTATE - The current state of the door.
```

--------------------------------

### input.getAxisValue

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_input.html

Get the value of an axis of a game controller.

```APIDOC
## input.getAxisValue(axisId)

### Description
Get value of an axis of a game controller.

### Parameters
- **axisId** (number) - Required - Index of a controller axis.

### Return Value
- **number** - Value in range [-1, 1].
```

--------------------------------

### world.pause

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_world.html

Pauses the game world starting from the next frame.

```APIDOC
## world.pause(tag)

### Description
Pauses the game. The game will remain paused until unpause is called with the same tag.

### Parameters
- **tag** (string) - Optional - The identifier for the pause request. Defaults to an empty string.
```

--------------------------------

### animation.getCurrentTime

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_animation.html

Gets the current absolute time of an animation group.

```APIDOC
## animation.getCurrentTime(actor, groupName)

### Description
Get the current absolute time of the given animation group if it is playing, or -1 if it is not playing.

### Parameters
- **actor** (openmw.core#GameObject) - Required - The actor.
- **groupName** (string) - Required - The name of the animation group.
```

--------------------------------

### StorageSection:get(key)

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_storage.html

Retrieves a value associated with a specific key.

```APIDOC
## StorageSection:get(key)

### Description
Retrieves a value by a string key. If the retrieved value is a table, it is returned as read-only.

### Parameters
- **key** (string): The key to look up.

### Return Value
- **any**: The value associated with the key.
```

--------------------------------

### Registering and using input actions and triggers

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_input.html

Demonstrates how to register a custom action and a trigger, and how to handle them within the script.

```lua
local input = require('openmw.input')
-- Example of Action usage
input.registerAction {
    key = 'MyAction',
    type = input.ACTION_TYPE.Boolean,
    l10n = 'MyLocalizationContext',
    name = 'MyAction_name',
    description = 'MyAction_full_description',
    defaultValue = false,
}
return {
    onFrame = function()
        local myAction = input.getBooleanActionValue('MyAction')
        if (myAction) then print('My action is active!') end
    end,
}
-- Example of Trigger usage
input.registerTrigger {
    key = 'MyTrigger',
    l10n = 'MyLocalizationContext',
    name = 'MyTrigger_name',
    description = 'MyTrigger_full_description',
}
input.registerTriggerHandler('MyTrigger', async:callback(function() print('MyTrigger') end))
```

--------------------------------

### Iterate over world cells

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_world.html

Example of iterating through all available cells in the world.

```lua
for i, cell in ipairs(world.cells) do print(cell) end
```

--------------------------------

### Importing openmw.vfs

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_vfs.html

Initialize the module to access VFS functionality.

```lua
local vfs = require('openmw.vfs')
```

--------------------------------

### Import openmw.content

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_content.html

Load the content module to access record manipulation functionality.

```lua
local content = require('openmw.content')
```

--------------------------------

### Launch OpenMW with specific profiles via command line

Source: https://openmw.readthedocs.io/en/stable/reference/modding/paths.html

Use this command to override default configuration directories and load specific profile paths.

```bash
$ openmw --replace config --config ?userconfig?/Morrowind --config "?userconfig?/Morrowind/Total Overhaul"
```

--------------------------------

### Modify Actor Spells

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_types.html

Examples for adding all available spells or a specific spell to an actor.

```lua
-- add ALL spells that exist in the world
local mySpells = types.Actor.spells(self)
for _, spell in pairs(core.magic.spells.records) do
    if spell.type == core.magic.SPELL_TYPE.Spell then
        mySpells:add(spell)
    end
end
```

```lua
-- add specific spell
types.Actor.spells(self):add('thunder fist')
```

--------------------------------

### Importing openmw.util

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_util.html

Load the utility module to access its functions and classes.

```lua
local util = require('openmw.util')
```

--------------------------------

### Logical OR Expression

Source: https://openmw.readthedocs.io/en/stable/manuals/openmw-cs/record-filters.html

Example of filtering for multiple record types using the OR logical operator.

```text
or(string("record type", "npc"), string("record type", "creature"))
```

--------------------------------

### Load and use an auxiliary library

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/overview.html

Demonstrates loading the openmw_aux.time library and using it to schedule a recurring task.

```lua
local time = require('openmw_aux.time')
time.runRepeatedly(doSomething, 15 * time.second)  -- run `doSomething()` every 15 seconds
```

--------------------------------

### Importing openmw_aux.ui

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_aux_ui.html

Load the utility module to access UI helper functions.

```lua
local auxUi = require('openmw_aux.ui')
```

--------------------------------

### Get NPC Faction Reputation

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_types.html

Retrieves the reputation level of an NPC within a specific faction.

```lua
local NPC = require('openmw.types').NPC;
print(NPC.getFactionReputation(player, "mages guild"));
```

--------------------------------

### Get NPC Faction Rank

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_types.html

Retrieves the rank index of an NPC within a specific faction.

```lua
local NPC = require('openmw.types').NPC;
print(NPC.getFactionRank(player, "mages guild");
```

--------------------------------

### Get List size

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/iterables.html

Retrieve the total number of elements in a list using the length operator.

```lua
-- can get total size with the size # operator
local length = #list
```

--------------------------------

### Create a basic Player script

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/overview.html

A simple script that listens for the 'X' key press and displays a UI message.

```lua
-- Save to my_lua_mod/scripts/example/player.lua

local ui = require('openmw.ui')

return {
    engineHandlers = {
        onKeyPress = function(key)
            if key.symbol == 'x' then
                ui.showMessage('You have pressed "X"')
            end
        end
    }
}
```

--------------------------------

### Set Actor Equipment

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_types.html

Example of clearing all equipment for the current actor using the Actor.setEquipment method.

```lua
local self = require('openmw.self')
local Actor = require('openmw.types').Actor
Actor.setEquipment(self, {}) -- unequip all
```

--------------------------------

### AI.startPackage({type='Combat', ...})

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/ai/combat.html

Initiates a combat AI package to make an actor attack a target.

```APIDOC
## AI.startPackage({type='Combat', ...})

### Description
Commands an actor to attack a specified target using the Combat AI package.

### Arguments
- **type** (string) - Required - The name of the package, must be 'Combat'.
- **cancelOther** (boolean) - Optional - Whether to cancel all other AI packages. Defaults to true.
- **target** (GameObject) - Required - The actor to attack.

### Usage Example
```lua
local AI = require('openmw.interfaces').AI
AI.startPackage({type='Combat', target=anotherActor})
```
```

--------------------------------

### Accessing Persuasion Records

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_core.html

Examples for iterating over persuasion records and accessing specific persuasion information.

```lua
--print ids of all persuasion records
for _, persuasionRecord in pairs(core.dialogue.persuasion.records) do
    print(persuasionRecord.id)
end
```

```lua
--print all NPC lines for "admire success"
for idx, persuasionInfo in pairs(core.dialogue.persuasion.records["admire success"].infos) do
    print(idx, persuasionInfo.text)
end
```

--------------------------------

### Creating a Container Record Draft

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_types.html

Demonstrates creating a new container record using a template and adding it to the world.

```lua
local chestTemplate = types.Container.records['chest_small_01']
local containerTable = {name = "Respawning Treasure Chest", template = chestTemplate, isRespawning = true, weight = 150.0}
local recordDraft = types.Container.createRecordDraft(containerTable)
local newRecord = world.createRecord(recordDraft)
world.createObject(newRecord.id):teleport(playerCell, playerPosition)
```

--------------------------------

### Retrieve object by Form ID

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_world.html

Example of fetching a game object using its Form ID.

```lua
local obj = world.getObjectByFormId(core.getFormId('Morrowind.esm', 128964))
```

--------------------------------

### Manage UI Layers

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_ui.html

Demonstrates how to insert, access, and iterate over UI layers in OpenMW.

```lua
ui.layers.insertAfter('HUD', 'NewLayer', { interactive = true })
local fourthLayer = ui.layers[4]
local windowsIndex = ui.layers.indexOf('Windows')
for i, layer in ipairs(ui.layers) do
  print('layer', i, layer.name, layer.size)
end
```

--------------------------------

### Select Profile in Base Configuration

Source: https://openmw.readthedocs.io/en/stable/reference/modding/paths.html

Point the base configuration file to a specific profile directory.

```text
# select the profile
config=Original
```

--------------------------------

### AI.filterPackages

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/interface_ai.html

Iterates over all AI packages starting from the active one and removes those where the provided filterCallback returns false.

```APIDOC
## AI.filterPackages(filterCallback)

### Description
Iterate over all packages starting from the active one and remove those where `filterCallback` returns false.

### Parameters
- **filterCallback** (function) - Required - A function that returns a boolean to determine if a package should be kept.
```

--------------------------------

### animation.getTextKeyTime(actor, text)

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_animation.html

Gets the absolute position within the animation track for a specific text key.

```APIDOC
### animation.getTextKeyTime(actor, text)

Get the absolute position within the animation track of the given text key.

#### Parameters
- **actor** (openmw.core#GameObject) - The actor object.
- **text** (string) - The text key.

#### Returns
- **number** - The time position.
```

--------------------------------

### ui.create

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_ui.html

Creates a UI element from the provided layout table and options.

```APIDOC
## ui.create(layout, options)

### Description
Creates a new UI element based on the provided layout definition and configuration options.

### Parameters
- **layout** (table) - The layout definition for the UI element.
- **options** (table) - Configuration options for the UI element creation.
```

--------------------------------

### Accessing Probe Records

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_types.html

Examples of accessing probe records by ID or index from the global records list.

```lua
local record = types.Probe.records['example_recordid']
```

```lua
local record = types.Probe.records[1]
```

--------------------------------

### Localization Usage in Lua

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_core.html

Demonstrates how to initialize a localization object and retrieve translated strings with optional parameters.

```lua
local myMsg = core.l10n('MyMod', 'en')
print( myMsg('good_morning') )
print( myMsg('you_have_arrows', {count=5}) )
print( myMsg('Hello {name}!', {name='World'}) )
```

--------------------------------

### ui.registerSettingsPage(page)

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_ui.html

Adds a settings page to the main menu's Scripts tab.

```APIDOC
## ui.registerSettingsPage(page)

### Description
Adds a settings page to the main menu setting's Scripts tab.

### Parameters
- **page** (SettingsPageOptions) - Required - The configuration options for the settings page.
```

--------------------------------

### Access Player Journal Entries

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_types.html

Examples for retrieving information from the player's journal text entries.

```lua
-- The `firstQuestName` variable below is likely to be "a1_1_findspymaster" in vanilla MW
local firstQuestName = types.Player.journal(player).journalTextEntries[1].questId
```

```lua
-- The number of journal entries accumulated in the player journal
local num = #types.Player.journal(player).journalTextEntries
```

```lua
-- Print all journal entries accumulated in the player journal
for idx, journalEntry in pairs(types.Player.journal(player).journalTextEntries) do
    print(idx, journalEntry.text)
end
```

--------------------------------

### Iterate and check ActorActiveEffects

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_types.html

Examples for iterating through active effects and querying specific effects by type or attribute.

```lua
-- print active effects
for _, effect in pairs(Actor.activeEffects(self)) do
    print('Active Effect: '..effect.id..', attribute='..tostring(effect.affectedAttribute)..', skill='..tostring(effect.affectedSkill)..', magnitude='..tostring(effect.magnitude))
end
```

```lua
-- Check for a specific effect
local effect = Actor.activeEffects(self):getEffect(core.magic.EFFECT_TYPE.Telekinesis)
if effect.magnitude ~= 0 then
    print(effect.id..', attribute='..tostring(effect.affectedAttribute)..', skill='..tostring(effect.affectedSkill)..', magnitude='..tostring(effect.magnitude))
else
    print('No Telekinesis effect')
end
```

```lua
-- Check for a specific effect targeting a specific attribute.
local effect = Actor.activeEffects(self):getEffect(core.magic.EFFECT_TYPE.FortifyAttribute, 'luck')
if effect.magnitude ~= 0 then
    print(effect.id..', attribute='..tostring(effect.affectedAttribute)..', skill='..tostring(effect.affectedSkill)..', magnitude='..tostring(effect.magnitude))
else
    print('No Fortify Luck effect')
end
```

--------------------------------

### Use and Modify UI Templates

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/interface_mwui.html

Demonstrates creating a UI element using a template and modifying a template's properties.

```lua
local I = require('openmw.interfaces')
local ui = require('openmw.ui')
local auxUi = require('openmw_aux.ui')
ui.create {
    template = I.MWUI.templates.textNormal,
    layer = 'Windows',
    type = ui.TYPE.Text,
    props = {
        text = 'Hello, world!',
    },
}
-- important to copy here
local myText = auxUi.deepLayoutCopy(I.MWUI.templates.textNormal)
myText.props.textSize = 20
I.MWUI.templates.textNormal = myText
ui.updateAll()
```

--------------------------------

### Import UI Interface

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/interface_ui.html

Initializes the UI interface module for use in scripts.

```lua
require('openmw.interfaces').UI
```

--------------------------------

### Accessing Voice Records

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_core.html

Examples for iterating over voice records and accessing specific voice line information.

```lua
--print ids of all voice records
for _, voiceRecord in pairs(core.dialogue.voice.records) do
    print(voiceRecord.id)
end
```

```lua
--print all NPC lines & sounds for "flee"
for idx, voiceInfo in pairs(core.dialogue.voice.records["flee"].infos) do
    print(idx, voiceInfo.text, voiceInfo.sound)
end
```

--------------------------------

### Equivalent openmw.cfg option formatting

Source: https://openmw.readthedocs.io/en/stable/reference/modding/paths.html

Demonstrates that leading/trailing whitespace is trimmed for option names and values.

```text
data=some/dir
    data=some/dir
data = some/dir
```

--------------------------------

### Define custom vertex shader

Source: https://openmw.readthedocs.io/en/stable/reference/postprocessing/omwfx.html

Example of passing custom data from a vertex shader to a fragment shader.

```glsl
vertex pass {
    #if OMW_USE_BINDINGS
        omw_In vec2 omw_Vertex;
    #endif

    uniform sampler2D noiseSampler;

    omw_Out vec2 omw_TexCoord;

    // custom output from vertex shader
    omw_Out float noise;

    void main()
    {
        omw_Position = vec4(omw_Vertex.xy, 0.0, 1.0);
        omw_TexCoord = omw_Position.xy * 0.5 + 0.5;

        noise = sqrt(omw_Texture2D(noiseSampler, vec2(0.5, 0.5)).r);
    }
}

fragment pass {
    omw_In vec2 omw_TexCoord;

    // our custom output from the vertex shader is available
    omw_In float noise;

    void main()
    {
        omw_FragColor = vec4(1.0);
    }
}
```

--------------------------------

### Define fragment passes

Source: https://openmw.readthedocs.io/en/stable/reference/postprocessing/omwfx.html

Example of defining two distinct fragment passes within an .omwfx file.

```glsl
fragment pass {
    void main()
    {
        omw_FragColor = vec4(1.0);
    }
}

fragment otherPass {

    omw_In vec2 omw_TexCoord;

    void main()
    {
        omw_FragColor = omw_GetLastPass(omw_TexCoord);
    }
}
```

--------------------------------

### Implementing onSave and onLoad for state persistence

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/overview.html

Demonstrates how to use onSave and onLoad handlers to serialize and restore script variables, including versioning logic.

```lua
local scriptVersion = 3  -- increase it every time when `onSave` is changed

local function onSave()
    return {
        version = scriptVersion
        some = someVariable,
        someOther = someOtherVariable
    }
end

local function onLoad(data)
    if not data or not data.version or data.version < 2 then
        print('Was saved with an old version of the script, initializing to default')
        someVariable = 'some value'
        someOtherVariable = 42
        return
    end
    if data.version > scriptVersion then
        error('Required update to a new version of the script')
    end
    someVariable = data.some
    if data.version == scriptVersion then
        someOtherVariable = data.someOther
    else
        print(string.format('Updating from version %d to %d', data.version, scriptVersion))
        someOtherVariable = 42
    end
end

return {
    engineHandlers = {
        onUpdate = update,
        onSave = onSave,
        onLoad = onLoad,
    }
}
```

--------------------------------

### Import openmw.async

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_async.html

Required to access the async API functionality.

```lua
local async = require('openmw.async')
```

--------------------------------

### Advanced Number Formatting

Source: https://openmw.readthedocs.io/en/stable/reference/modding/localisation.html

Examples of formatting numbers as percentages, ordinals, spellouts, and custom rounding patterns.

```yaml
quest_completion: "The quest is {done, number, percent} complete."
# E.g. "You came in 4th place"
ordinal: "You came in {num, ordinal} place."
# E.g. "There is one thing", "There are one hundred things"
spellout: "There {num, plural, one{is {num, spellout} thing} other{are {num, spellout} things}}."
numbers: "{int} and {double, number, integer} are integers, but {double} is a double"
rounding: "{value, number, :: .00}"
```

--------------------------------

### Apply Distortion Effect via NiStringExtraData

Source: https://openmw.readthedocs.io/en/stable/reference/modding/custom-shader-effects.html

Example JSON structure for applying the distortion effect to a node.

```json
omw:data {
    "shader" : {
        "distortion" : {
            "strength": 0.12,
        }
    }
}
```

--------------------------------

### Creating a custom Armor record

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_types.html

Demonstrates creating a new armor record using an existing record as a template and adding it to the player's inventory.

```lua
local armorTemplate = types.Armor.record('orcish_cuirass')
local armorTable = {name = "Better Orcish Cuirass",template = armorTemplate,baseArmor = armorTemplate.baseArmor + 10}
 --This is the new record we want to create, with a record provided as a template.
local recordDraft = types.Armor.createRecordDraft(armorTable)--Need to convert the table into the record draft
local newRecord = world.createRecord(recordDraft)--This creates the actual record
world.createObject(newRecord.id):moveInto(playerActor)--Create an instance of this object, and move it into the player's inventory
```

--------------------------------

### Vector3 Usage and Operations

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_util.html

Demonstrates instantiation, arithmetic operations, swizzling, and vector math methods for the Vector3 type.

```lua
v = util.vector3(3, 4, 5)
v.x, v.y, v.z  -- 3.0, 4.0, 5.0
str(v)         -- "(3.0, 4.0, 4.5)"
v:length()     -- length
v:length2()    -- square of the length
v:normalize()  -- normalized vector
v1:dot(v2)     -- dot product (returns a number)
v1 * v2        -- dot product (returns a number)
v1:cross(v2)   -- cross product (returns a vector)
v1 ^ v2        -- cross product (returns a vector)
v1 + v2        -- vector addition
v1 - v2        -- vector subtraction
v1 * x         -- multiplication by a number
v1 / x         -- division by a number
v1.zyz, v1.yx  -- swizzle with standard fields
v1.w1y, v1.z0z -- swizzle with 0/1 constant
v1['0xy']      -- swizzle with 0/1 constant starting with 0 or 1
```

--------------------------------

### Apply Soft Effect via NiStringExtraData

Source: https://openmw.readthedocs.io/en/stable/reference/modding/custom-shader-effects.html

Example JSON structure for applying the soft effect to a node.

```json
omw:data {
    "shader" : {
        "soft_effect" : {
            "size": 250,
            "falloff" : false,
            "falloffDepth": 5,
        }
    }
}
```

--------------------------------

### Logical AND Expression

Source: https://openmw.readthedocs.io/en/stable/manuals/openmw-cs/record-filters.html

Example of combining record type and weight range filters using the AND logical operator.

```text
and(string("record type", "weapon"), value("weight", (0, 100)))
```

--------------------------------

### Manage storage sections and subscriptions in Lua

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_storage.html

Demonstrates how to access a global storage section, set values, and subscribe to changes using an asynchronous callback.

```lua
local storage = require('openmw.storage')
local myModData = storage.globalSection('MyModExample')
myModData:set("someVariable", 1.0)
myModData:set("anotherVariable", { exampleStr='abc', exampleBool=true })
local async = require('openmw.async')
myModData:subscribe(async:callback(function(section, key)
    if key then
        print('Value is changed:', key, '=', myModData:get(key))
    else
        print('All values are changed')
    end
end))
```

--------------------------------

### ui.create(layout, options)

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_ui.html

Creates a UI element from the given layout table.

```APIDOC
## ui.create(layout, options)

### Description
Creates a UI element from the given layout table.

### Parameters
- **layout** (Layout) - Required - The layout definition.
- **options** (table) - Optional - Configuration options, such as `noWarnUnused` (boolean) to suppress warnings about unused properties.

### Return Value
- **Element** - The created UI element.
```

--------------------------------

### Importing the time module

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_aux_time.html

Load the time utility module to access timer functions.

```lua
local time = require('openmw_aux.time')
```

--------------------------------

### Accessing Potion Records

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_types.html

Examples of retrieving a PotionRecord from the global records list using either an ID or an index.

```lua
local record = types.Potion.records['example_recordid']
```

```lua
local record = types.Potion.records[1]
```

--------------------------------

### StartAIPackage: Escort

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/ai/escort.html

Initiates an Escort AI package for an actor using the sendEvent method.

```APIDOC
## StartAIPackage: Escort

### Description
Instructs an actor to escort another actor to a specified location.

### Arguments
- **type** (string) - Required - The name of the package ('Escort').
- **cancelOther** (boolean) - Optional - Whether to cancel all other AI packages (default: true).
- **target** (GameObject) - Required - The actor to follow.
- **destPosition** (3d vector) - Required - The destination point.
- **destCell** (Cell) - Optional - The destination cell.
- **duration** (number) - Optional - Duration in game time (rounded up to the next hour).
- **isRepeat** (boolean) - Optional - Whether the package will repeat.

### Example
```lua
actor:sendEvent('StartAIPackage', {
    type = 'Escort',
    target = object.self,
    destPosition = util.vector3(x, y, z),
    duration = 3 * time.hour,
    isRepeat = true
})
```
```

--------------------------------

### Configure sunrise and sunset times in openmw.cfg

Source: https://openmw.readthedocs.io/en/stable/reference/modding/extended.html

Define the timing for day/night transitions in the configuration file.

```ini
fallback=Weather_Sunrise_Time,6
fallback=Weather_Sunset_Time,18
fallback=Weather_Sunrise_Duration,2
fallback=Weather_Sunset_Duration,2
```

--------------------------------

### Access Player Journal Topics

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_types.html

Examples for retrieving specific records from the player's journal topics map.

```lua
local record = types.Player.journal(player).topics["my trade"]
```

```lua
local record = types.Player.journal(player).topics["Vivec"]
```

--------------------------------

### ui.registerSettingsPage

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_ui.html

Adds a custom settings page to the main menu's Scripts tab.

```APIDOC
## ui.registerSettingsPage(page)

### Description
Registers a new settings page, making it available under the Scripts tab in the main menu settings.

### Parameters
- **page** (table) - The settings page definition.
```

--------------------------------

### Import openmw.camera module

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_camera.html

Required to access camera control functions in Lua scripts.

```lua
local camera = require('openmw.camera')
```

--------------------------------

### Accessing Spell Records

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_core.html

Examples of retrieving spell records from the global spells list by ID or index, and iterating through them.

```lua
local spell = core.magic.spells.records['thunder fist']  -- get by id
```

```lua
local spell = core.magic.spells.records[1]  -- get by index
```

```lua
-- Print all powers
for _, spell in pairs(core.magic.spells.records) do
    if spell.type == core.magic.SPELL_TYPE.Power then
        print(spell.name)
    end
end
```

--------------------------------

### Import MWUI Interface

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/interface_mwui.html

Load the MWUI interface module to access UI templates.

```lua
require('openmw.interfaces').MWUI
```

--------------------------------

### Accessing Dialogue Information

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_core.html

Examples of how to access text and sound properties from dialogue records using the core.dialogue API.

```APIDOC
## Accessing Dialogue Information

### Description
Access read-only data from dialogue records such as topics or voice lines using the `core.dialogue` interface.

### Usage Examples

```lua
-- Accessing text from a topic record
local text = core.dialogue.topic.records['advancement'].infos[100].text

-- Accessing sound path from a voice record
local sound = core.dialogue.voice.records['flee'].infos[149].sound
```
```

--------------------------------

### Import the UI module

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_ui.html

Required to access the openmw.ui functionality in a script.

```lua
local ui = require('openmw.ui')
```

--------------------------------

### Define Custom Bone Hierarchy

Source: https://openmw.readthedocs.io/en/stable/reference/modding/extended.html

Example NIF record hierarchy for attaching a custom weapon bone to the skeleton.

```text
NiNode "root"
    NiNode "Bip01 L Hand"
        NiNode "Weapon Bone Left"
            NiStringExtraData "BONE"
```

--------------------------------

### Creating a New Creature Record

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_types.html

Demonstrates creating a creature record draft from a template and adding it to the world.

```lua
local creatureTemplate = types.Creature.records['mudcrab']
local creatureTable = {name = "Epic Mudcrab", template = creatureTemplate, soulValue = 500, isEssential = true}
local recordDraft = types.Creature.createRecordDraft(creatureTable)
local newRecord = world.createRecord(recordDraft)
world.createObject(newRecord.id):teleport(playerCell, playerPosition)
```

--------------------------------

### Define animation blending rules

Source: https://openmw.readthedocs.io/en/stable/reference/modding/animation-blending.html

Example of a YAML configuration file defining blending rules between animation states.

```yaml
blending_rules:
 - from: "*"
   to: "*"
   easing: "sineOut"
   duration: 0.25
 - from: "*"
   to: "idlesneak*"
   easing: "springOutWeak"
   duration: 0.4
```

--------------------------------

### vfs.open(fileName)

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_vfs.html

Opens a file and returns a FileHandle.

```APIDOC
## vfs.open(fileName)

### Description
Opens a file for reading.

### Parameters
- **fileName** (string) - Path to the file in VFS.

### Return Values
- **FileHandle** - Opened file handle if successful.
- **nil, string** - Returns nil and an error message if the operation fails.
```

--------------------------------

### Value Range Comparison

Source: https://openmw.readthedocs.io/en/stable/manuals/openmw-cs/record-filters.html

Example of matching a numerical value within a specific range using brackets and parentheses.

```text
value("Weight", [20, 50))
```

--------------------------------

### Importing the ambient package

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_ambient.html

Required to access the ambient sound control functions.

```lua
local ambient = require('openmw.ambient')
```

--------------------------------

### Play a blended animation

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/interface_animation.html

Triggers a specific animation group with defined start and stop keys and bone group priorities.

```lua
local anim = require('openmw.animation')
local I = require('openmw.interfaces')

-- play spellcast animation 
I.AnimationController.playBlendedAnimation('spellcast', { startkey = 'self start', stopkey = 'self stop', priority = {
     [anim.BONE_GROUP.RightArm] = anim.PRIORITY.Weapon,
     [anim.BONE_GROUP.LeftArm] = anim.PRIORITY.Weapon,
     [anim.BONE_GROUP.Torso] = anim.PRIORITY.Weapon,
     [anim.BONE_GROUP.LowerBody] = anim.PRIORITY.WeaponLowerBody
     } })
```

--------------------------------

### Importing the calendar module

Source: https://openmw.readthedocs.io/en/stable/reference/lua-scripting/openmw_aux_calendar.html

Load the calendar utility module to access its functions and fields.

```lua
local calendar = require('openmw_aux.calendar')
```
Tokens:
Raw