Morrowind Script Extender

https://mwse.github.io/MWSE/
Admin
MWSE provides additional scripting functions and capabilities for modders to create features and...
Tokens:1,544,718
Snippets:19,413
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Translation File Example (French)

Source: https://mwse.github.io/MWSE/guides/mod-translations

Example of a French translation file for the 'Hello world!' string. This demonstrates how to provide translations for different languages.

```lua
return {
    ["Hello world!"] = "Bonjour le monde!",
}

```

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

### Example: Show a Countdown Message

Source: https://mwse.github.io/MWSE/apis/timer

Demonstrates starting a simulation timer to display a countdown message when the player activates an item. The timer ticks down every second and stops when menus are open or the game timescale changes.

```lua
local timeLeft = 0;

local function onTimerExpired() 
    timeLeft = timeLeft - 1
    tes3.messageBox("%d seconds left", timeLeft)
end

local function onActivate(eventData) 
    if (eventData.activator == tes3.player) then
        timeLeft = 10
        timer.start{ duration = 1, iterations = 10, type = timer.simulate, callback = onTimerExpired }
    end
end
event.register(tes3.event.activate, onActivate)


```

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

### Translation File Example (English)

Source: https://mwse.github.io/MWSE/guides/mod-translations

Example of an English translation file for the 'Hello world!' string. This file ensures the default English text is used.

```lua
return {
    ["Hello world!"] = "Hello world!",
}

```

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

### Translation File Example (Polish)

Source: https://mwse.github.io/MWSE/guides/mod-translations

Example of a Polish translation file for the 'Hello world!' string. This shows the structure for adding more language options.

```lua
return {
    ["Hello world!"] = "Witaj świecie!",
}

```

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

### start

Source: https://mwse.github.io/MWSE/types/niKeyframeController?q=

Starts the controller at the specified time. Intended for controllers with `animTimingType` of 1.

```APIDOC
## start

### Description
Starts the controller at the specified time. Intended for controllers with `animTimingType` of 1.

### Method
`myObject:start(time)`

### Parameters
#### Path Parameters
* `time` (number) - Description of the time parameter.
```

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

### Timer Start Function Signature

Source: https://mwse.github.io/MWSE/apis/timer?q=

This snippet shows the basic signature for starting a timer with various optional parameters.

```lua
local timer = timer.start({ type = ..., duration = ..., callback = ..., iterations = ..., persist = ..., data = ... })
```

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

### Translation File Example (Russian)

Source: https://mwse.github.io/MWSE/guides/mod-translations

Example of a Russian translation file for the 'Hello world!' string. Ensure UTF-8 encoding for all language files.

```lua
return {
    ["Hello world!"] = "Привет, мир!",
}

```

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

### Translation File Example (German)

Source: https://mwse.github.io/MWSE/guides/mod-translations

Example of a German translation file for the 'Hello world!' string. Translation files are Lua files returning a table of key-value pairs.

```lua
return {
    ["Hello world!"] = "Hallo Welt!",
}

```

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

### Traverse Scene Graph Example

Source: https://mwse.github.io/MWSE/apis/table

Example demonstrating DFS traversal of a scene graph to log node types and names. Uses `table.traverse` and event registration.

```lua
local function onLoaded()
    mwse.log("Player's scene graph:")
    for node in table.traverse({ tes3.player.sceneNode }) do
        mwse.log("%s : %s", node.RTTI.name, node.name)
    end
end

event.register(tes3.event.loaded, onLoaded)
```

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

### Example: Registering and Using a KeyBinder

Source: https://mwse.github.io/MWSE/types/mwseMCMKeyBinder

Demonstrates setting up a KeyBinder with mouse support and filtering key presses.

```lua
-- An example of a simple configuration setup
local defaultConfig = {
    ---@type mwseKeyMouseCombo
    combo = {
        -- Alt + Left mouse button
        mouseButton = 0,
        isAltDown = true,
        isControlDown = false,
        isShiftDown = false,
    },
}
local config = mwse.loadConfig("myModConfig", defaultConfig)

local function registerModConfig() 
    local template = mwse.mcm.createTemplate({
        name = "Test Mod",
        config = config
    })
    template:register()

    local page = template:createSideBarPage({ label = "Settings" })

    page:createKeyBinder({
        label = "My combo",
        description = "This combo does...",
        allowMouse = true,
        configKey = "combo",
    })
end
event.register(tes3.event.modConfigReady, registerModConfig)


--- @param e keyDownEventData|mouseButtonDownEventData|mouseWheelEventData
local function sayHi(e) 
    if not tes3.isKeyEqual({ expected = config.combo, actual = e }) then
        -- Nothing to do if the pressed combination isn't equal to our expected combination.
        return
    end

    -- Now do our logic
    tes3.messageBox("Hi!")
end

event.register(tes3.event.keyDown, sayHi)
event.register(tes3.event.mouseButtonDown, sayHi)
event.register(tes3.event.mouseWheel, sayHi)

```

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

### Get Item Count Example

Source: https://mwse.github.io/MWSE/references/mwse-mwscript/reference?q=

Retrieves the count of a specific item in a reference's inventory. This example shows how to get the player's gold count.

```mwscript
begin Example_xGetItemCount

long ref

long id
long count

setx ref to xGetRef "player"

setx id to xStringBuild "Gold_001"

setx count to ref->xGetItemCount id

MessageBox "Total Gold: %g" count

StopScript Example_xGetItemCount

end
```

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

### Example: Get Animation Timings for Bow Animations

Source: https://mwse.github.io/MWSE/apis/tes3?q=

This example demonstrates how to get animation timings for bow animations. It checks if the upper body animation group is 'bowAndArrow' and then displays the timings.

```lua
local function onSimulate()
    local reference = tes3.is3rdPerson() and tes3.player or tes3.player1stPerson

    local _, upperGroup, _ = tes3.getAnimationGroups({ reference = reference })
    if upperGroup ~= tes3.animationGroup.bowAndArrow then return end

    local _, upperTiming, _ = unpack(
        tes3.getAnimationTiming({ reference = reference })
    )
    tes3.messageBox(upperTiming)
end
event.register(tes3.event.simulate, onSimulate)
```

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

### Create and Run a Simple Test Suite

Source: https://mwse.github.io/MWSE/guides/testing

Demonstrates how to start a test suite, define a test case with an assertion, and finish the suite. Configure to exit the game after tests complete.

```lua
local unitwind = require("unitwind").new{
    enabled = true,
    exitAfter = true,
}
unitwind:start("My Example Test Suite")
unitwind:test("Test 1 + 1 = 2", function()
    unitwind:expect(1 + 1).toBe(2)
end)
unitwind:finish()

```

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

### Get Cumulative Days for Month

Source: https://mwse.github.io/MWSE/apis/tes3?q=

Gets the number of days that have passed leading up to the start of a given month.

```lua
local days = tes3.getCumulativeDaysForMonth(month)
```

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

### weaponSpeed

Source: https://mwse.github.io/MWSE/types/tes3playerAnimationController?q=

Gets or sets the animation speed scaling of the weapon animations, including idle, attack, and ready/unready animations. This value is reset at the starting frame of each weapon strike, normally equal to the weapon speed. It should be changed after every strike and reset afterward. Ready/unready actions do not change speed but are affected by it. Example: `mobile.animationController.weaponSpeed = 0.5`

```APIDOC
## weaponSpeed

### Description
The animation speed scaling of the weapon animations. This includes all weapon related idle, attack, and ready/unready animations. This value is reset at the starting frame of each weapon strike, normally equal to the the weapon speed. Therefore if you use this it should be changed after every strike, and reset after. Ready/unready actions do not change speed, but are affected by speed.
Use by getting the animation controller from the mobile. e.g. `mobile.animationController.weaponSpeed = 0.5`

### Returns
* `result` (number) - The weapon animation speed scaling.
```

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

### Full Fader Example

Source: https://mwse.github.io/MWSE/types/tes3fader

Demonstrates the complete lifecycle of a fader, including creation, color setting, activation, opacity control, and event handling for user interaction.

```lua
local fader = nil

local function createFader() 
    fader = tes3fader.new()
    fader:setColor({
        color = { 0.0, 1.0, 0.0 },
    })

    event.register(tes3.event.enterFrame, function()
        fader:update()
    end)
end

event.register(tes3.event.fadersCreated, createFader)


local opacity = 0.1

local function activateFader()
    fader:activate()
    fader:fadeTo({
        value = opacity,
        duration = 3,
    })
    tes3.messageBox("Welcome to the Fallout mode!")
end

event.register(tes3.event.keyDown, activateFader, { filter = tes3.scanCode.u })

local function increaseOpacity()
    if opacity <= 0.9 then
        opacity = opacity + 0.1
    else
        return
    end
    fader:updateMaterialProperty(opacity)

    tes3.messageBox("Fader opacity increased.\nCurrent opacity: %.1f", opacity)
end
event.register(tes3.event.keyDown, increaseOpacity, { filter = tes3.scanCode.l })

local function decreaseOpacity()
    if opacity >= 0.1 then
        opacity = opacity - 0.1
    else
        return
    end
    fader:updateMaterialProperty(opacity)
    tes3.messageBox("Fader opacity decreased.\nCurrent opacity: %.1f", opacity)
end
event.register(tes3.event.keyDown, decreaseOpacity, { filter = tes3.scanCode.k })

```

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

### Basic MCM Registration Example

Source: https://mwse.github.io/MWSE/events/modConfigReady

Demonstrates how to create and register a simple mod configuration menu (MCM) using MWSE's template system. This includes creating a template, saving configuration, and adding a sidebar page with an on/off button.

```lua
local config = require("MyMod.config")

local function onModConfigReady()
    local template = mwse.mcm.createTemplate({ name = "My Mod" })
    template:saveOnClose("My Mod", config)
    template:register()

    local settings = template:createSideBarPage({ label = "Settings" })
    settings.sidebar:createInfo({
        -- This text will be on the right-hand side block
        text = "My Mod v. 1.0\n\nCreated by me.\n\nHover over a feature for more info."
    })

    settings:createOnOffButton({
        label = "Feature",
        -- The text in the description will replace the text
        -- in sidebar on the right-hand side, when this button
        -- is hovered over.
        description = "This feature does...",
        variable = mwse.mcm.createTableVariable({
            id = "feature",
            table = config,
        })
    })

end

event.register(tes3.event.modConfigReady, onModConfigReady)
```

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

### Example: Getting Animation Timings for Bow Animations

Source: https://mwse.github.io/MWSE/apis/tes3?q=

This snippet demonstrates how to get and display the upper body animation timing when the player is using a bow.

```Lua
local function onSimulate()
    local reference = tes3.is3rdPerson() and tes3.player or tes3.player1stPerson

    local _, upperGroup, _ = tes3.getAnimationGroups({ reference = reference })
    if upperGroup ~= tes3.animationGroup.bowAndArrow then return end

    local _, upperTiming, _ = unpack(
        tes3.getAnimationTiming({ reference = reference })
    )
    tes3.messageBox(upperTiming)
end
event.register(tes3.event.simulate, onSimulate)

```

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

### startTime

Source: https://mwse.github.io/MWSE/types/niParticleSystemController?q=

Gets or sets the time at which the animation controller starts playing its animation.

```APIDOC
## startTime

### Description
Gets or sets the time at which the animation controller starts playing its animation.

### Returns
* `result` (number) - The start time of the animation.
```

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

### tes3.getCumulativeDaysForMonth

Source: https://mwse.github.io/MWSE/apis/tes3?q=

Gets the number of days that have passed leading up to the start of a given month.

```APIDOC
## tes3.getCumulativeDaysForMonth

### Description
Gets the number of days that have passed leading up to the start of a given month.

### Method
`tes3.getCumulativeDaysForMonth(month)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* `month` (number) - Required. The 0-based month index.

### Request Example
```lua
local days = tes3.getCumulativeDaysForMonth(month)
```

### Response
#### Success Response
* `days` (number) - The cumulative number of days up to the start of the specified month.

#### Response Example
```lua
-- Example response structure (actual value depends on game state)
-- local days = 31
```
```

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

### Create and Preview Palette Menu

Source: https://mwse.github.io/MWSE/apis/tes3ui?q=

This example demonstrates how to create a menu to preview all available color palettes in Morrowind. It registers a key listener to trigger the menu creation and display.

```lua
local function onKey() 
    local menu = tes3ui.findHelpLayerMenu("testing:Menu")

    if not menu then
        menu = tes3ui.createHelpLayerMenu({ id = "testing:Menu" })
        menu:destroyChildren()
        menu.absolutePosAlignX = 0.1
        menu.absolutePosAlignY = 0.05
        menu.autoWidth = false
        menu.autoHeight = false
        menu.paddingLeft = 8
        menu.paddingRight = 8
        menu.paddingTop = 8
        menu.paddingBottom = 8
        menu.alpha = 1
        menu.visible = true
        menu.flowDirection = tes3.flowDirection.leftToRight
        menu.autoWidth = true
        menu.autoHeight = true
        menu.childAlignX = 0.5
    end

    local left = menu:createBlock()
    left.flowDirection = tes3.flowDirection.topToBottom
    left.autoHeight = true
    left.autoWidth = true
    left.childAlignX = 0.5

    local right = menu:createBlock()
    right.flowDirection = tes3.flowDirection.topToBottom
    right.autoWidth = true
    right.autoHeight = true
    right.childAlignX = 0.5

    local palettes = {}
    local i = 1
    for name, palette in pairs(tes3.palette) do
        palettes[i] = {
            name = name,
            palette = palette
        }
        i = i + 1
    end
    table.sort(palettes, function(a, b) 
        return a.name < b.name
    end)

    for i, entry in ipairs(palettes) do
        local label
        if i < 27 then
            label = left:createLabel({ text = entry.name })
        else
            label = right:createLabel({ text = entry.name })
        end
        label.color = tes3ui.getPalette(entry.palette)
    end
    menu:updateLayout()
end

event.register(tes3.event.keyDown, onKey, { filter = tes3.scanCode.o })


```

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

### Creating and Managing a Fader

Source: https://mwse.github.io/MWSE/events/fadersCreated

Demonstrates creating a new fader, setting its color, and updating it every frame. This example also shows how to activate the fader, fade it to a specific opacity, and adjust opacity using key presses.

```lua
-- This is a working example. You are encouraged to create a new file
-- main.lua, paste this code and see the results in-game!
-- Use `u` key to activate the fader.
-- Use `l` and `k` keys to increase or decrease the fader's opacity.

-- This variable is used to store our fader.
local fader = nil

local function createFader()
    fader = tes3fader.new()
    fader:setColor({
        -- This changes the color of our fader to green.
        -- The RGB values are in range [0.0, 1.0].
        color = { 0.0, 1.0, 0.0 },
    })

    -- The fader needs to be updated every frame to be rendered correctly.
    -- You may notice that for this event we have registered a function with
    -- no name. That is an anonymous function. It works exactly the same as
    -- any other function. We have a need to register this function inside
    -- our createFader() function, since our `fader` variable is `nil` at start
    -- (look up). We can't call fader:update() if fader is `nil`.
    event.register(tes3.event.enterFrame, function()
        fader:update()
    end)
end

-- The fader needs to be created during `fadersCreated` event,
-- so our createFader() function is registered for that event.
event.register(tes3.event.fadersCreated, createFader)


local opacity = 0.1

local function activateFader()
    -- The fader needs to be activated first to be visible.
    fader:activate()
    -- Now we change its visibility.
    fader:fadeTo({
        value = opacity,
        duration = 3,
    })
    tes3.messageBox("Welcome to the Fallout mode!")
end

-- We registered our activateFader() function on keyDown event, filtered for `u` key.
-- That makes our activateFader() function called only when `u` is pressed.
event.register(tes3.event.keyDown, activateFader, { filter = tes3.scanCode.u })

local function increaseOpacity()
    -- The fader's opacity is in [0.0, 1.0] range.
    -- Make sure we don't exceed it.
    if opacity <= 0.9 then
        opacity = opacity + 0.1
    else
        return
    end
    -- This method sets the current opacity of our fader
    -- to the value of `opacity` variable
    fader:updateMaterialProperty(opacity)

    -- The "\n" sign means insert a new line here.
    -- The "%.1f" code means insert the opacity's value in this text.
    -- The ".1" part means show 1 decimal after the decimal point.
    tes3.messageBox("Fader opacity increased.\nCurrent opacity: %.1f", opacity)
end
event.register(tes3.event.keyDown, increaseOpacity, { filter = tes3.scanCode.l })

local function decreaseOpacity()
    if opacity >= 0.1 then
        opacity = opacity - 0.1
    else
        return
    end
    fader:updateMaterialProperty(opacity)
    tes3.messageBox("Fader opacity decreased.\nCurrent opacity: %.1f", opacity)
end
event.register(tes3.event.keyDown, decreaseOpacity, { filter = tes3.scanCode.k })

```

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

### Get String Data Starting With from NiSourceTexture

Source: https://mwse.github.io/MWSE/types/niSourceTexture?q=

Searches for an niStringExtraData on this object whose string field starts with the provided 'value'. Returns the first matching extra data object.

```lua
local extra = myObject:getStringDataStartingWith(value)


```

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

### new

Source: https://mwse.github.io/MWSE/types/mwseMCMSetting

Creates a new Setting instance with specified data and configuration options.

```APIDOC
## new

### Description
Creates a new Setting.

### Parameters
* `data` (table): _Optional_.
    * `label` (string): _Optional_. The Setting's label.
    * `text` (string): _Optional_. The Setting's text.
    * `variable` (mwseMCMVariable, mwseMCMSettingNewVariable): _Optional_. A variable for this setting.
    * `config` (table): _Default_ : `parentComponent.config`. The config to use when creating a `mwseMCMTableVariable` for this `Setting`. If provided, it will override the config stored in `parentComponent`. Otherwise, the value in `parentComponent` will be used.
    * `defaultConfig` (table): _Default_ : `parentComponent.defaultConfig`. The `defaultConfig` to use when creating a `mwseMCMTableVariable` for this `Setting`. If provided, it will override the `defaultConfig` stored in `parentComponent`. Otherwise, the value in `parentComponent` will be used.
    * `configKey` (string, number): _Optional_. The `configKey` used to create a new `mwseMCMTableVariable`. If this is provided, along with a `config` (which may be inherited from the `parentComponent`), then a new `mwseMCMTableVariable` variable will be created for this setting.
    * `converter` (fun(newValue: unknown): unknown): _Optional_. A converter to use for this component's `variable`.
    * `defaultSetting` (unknown): _Optional_. If `defaultSetting` wasn't passed in the `variable` table, can be passed here. The new variable will be initialized to this value. If not provided, then the value in `defaultConfig` will be used, if possible.
    * `showDefaultSetting` (boolean): _Default_ : `parentComponent.showDefaultSetting`. If `true`, and in a Sidebar Page, then the `defaultSetting` of this setting's `variable` will be shown below its `description`. The `defaultSetting` will be formatted in accordance with the `convertToLabelValue` function. **Note:** This parameter does not update the `description` field.
    * `description` (string): _Optional_. If in a Sidebar Page, the description will be shown on mouseover.
    * `callback` (fun(self: mwseMCMSetting)): _Optional_. The custom function called when the player interacts with this Setting.
    * `inGameOnly` (boolean): _Default_ : `false`. If true, the setting is disabled while the game is on main menu.
    * `restartRequired` (boolean): _Default_ : `false`. If true, updating this Setting will notify the player to restart the game.
    * `restartRequiredMessage` (string): _Optional_. The message shown if restartRequired is triggered. The default text is a localized version of: "The game must be restarted before this change will come into effect."
    * `indent` (integer): _Default_ : `12`. The left padding size in pixels. Only used if the `childIndent` isn't set on the parent component.
    * `childIndent` (integer): _Optional_. The left padding size in pixels. Used on all the child components.
    * `paddingBottom` (integer): _Default_ : `4`. The bottom border size in pixels. Only used if the `childSpacing` is unset on the parent component.
    * `childSpacing` (integer): _Optional_. The bottom border size in pixels. Used on all the child components.
    * `postCreate` (fun(self: mwseMCMSetting)): _Optional_. Can define a custom formatting function to make adjustments to any element saved in `self.elements`.
    * `class` (string): _Optional_.
    * `componentType` (string): _Optional_.
    * `parentComponent` (mwseMCMComponent): _Optional_.

### Returns
* `setting` (mwseMCMSetting)
```

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

### Get String Data Starting With

Source: https://mwse.github.io/MWSE/types/niAlphaProperty

Retrieves the first niStringExtraData whose string field starts with the specified value. Useful for finding specific string data associated with an object.

```lua
local extra = myObject:getStringDataStartingWith(value)
```

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

### Get and Display Weapon Skill Name

Source: https://mwse.github.io/MWSE/types/tes3weapon

This snippet demonstrates how to retrieve the skill ID of a weapon and then use it to get and display the skill's name using tes3.getSkillName. It registers an event listener for when an attack starts.

```lua
local function showMessage(e)
    if not e.mobile.readiedWeapon then return end
    local id = e.mobile.readiedWeapon.object.skillId
    local name = tes3.getSkillName(id)

    tes3.messageBox(name)
end

event.register(tes3.event.attackStart, showMessage)

```

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

### Get Key Name from Scan Code with tes3.getKeyName

Source: https://mwse.github.io/MWSE/apis/tes3?q=

Gets the display name of a key based on its scan code, similar to the in-game Controls menu. For example, tes3.getKeyName(tes3.scanCode.b) returns "B".

```lua
local keyName = tes3.getKeyName(keyCode)
```

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

### Package Section Example

Source: https://mwse.github.io/MWSE/guides/metadata

Defines essential information about your mod, including its name, description, homepage, repository, authors, and version.

```toml
[package]
name = "My Mod"
description = "A description of the mod"
homepage = "https://www.nexusmods.com/morrowind/mods/49658"
repository = "https://github.com/jhaakma/skoomaesthesia"
authors = ["Merlord", "Greatness7"]
version = "7.8.9"

```

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

### Registering a startGlobalScript Callback

Source: https://mwse.github.io/MWSE/events/startGlobalScript?q=

Registers a Lua function to be called when a global script starts. This is the basic setup for handling the event.

```lua
--- @param e startGlobalScriptEventData
local function startGlobalScriptCallback(e)
end
event.register(tes3.event.startGlobalScript, startGlobalScriptCallback)
```

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

### Initialize UnitWind Instance

Source: https://mwse.github.io/MWSE/guides/testing

Create a new UnitWind instance with basic configuration. This is the first step to setting up the testing framework.

```lua
local unitWind = require("unitwind").new{
    enabled = true,
    --- ... other settings ...
}

```

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

### startTime

Source: https://mwse.github.io/MWSE/types/tes3playerAnimationController

Gets the starting time of the actor's attack animation in their .kf file. This value is updated for attacks from different directions.

```APIDOC
### `startTime`⚓︎
starttime
This it the starting time of the actor's attack animation in their `.kf` file. It's updated for the attacks from different directions.
**Returns** :
  * `result` (number)
```

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

### Create Info using create Method

Source: https://mwse.github.io/MWSE/apis/mwse

This demonstrates an alternative way to create an Info element by first instantiating it with data and then explicitly calling its create method with a parent. This approach is useful when more control over the creation process is needed.

```lua
local myInfo = mwse.mcm.createInfo({ ... })
myInfo:create(parent)

```

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

### startTime

Source: https://mwse.github.io/MWSE/types/tes3playerAnimationController?q=

Gets the starting time of the actor's attack animation in their .kf file. This value is updated for attacks from different directions.

```APIDOC
## startTime

### Description
Gets the starting time of the actor's attack animation in their .kf file. This value is updated for attacks from different directions.

### Returns
* `result` (number) - The starting time of the attack animation.
```

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

### Simplest Mod Config Menu

Source: https://mwse.github.io/MWSE/guides/mod-config

This example demonstrates the minimal code required to create a functional mod configuration menu. It sets up default configurations, registers the mod, saves settings on close, and creates a simple page with a Yes/No button.

```lua
-- Default settings for your mod.
local myDefaultConfig = {
    enabled = true
}

-- The name of the config json file of your mod.
-- This is used to save/load your config, so that changes persist
-- between game launches.
local configPath = "My Awesome Mod"

-- Loaded config, taking into account any setting changes made by the user.
local myConfig = mwse.loadConfig(configPath, defaultConfig)

-- When the mod config menu is ready to start accepting registrations,
-- register this mod.
local function registerModConfig()
    -- Create the top level component Template.
    -- This is basically a box that holds all the other parts of the menu.
    local template = mwse.mcm.createTemplate({
        -- This will be displayed in the mod list on the lefthand pane.
        name = "My Awesome Mod",
        -- This makes all settings update the values stored in this table.
        config = myConfig
    })

    -- This tells MWSE to add this config menu to the list.
    template:register()

    -- Saves the config to a file whenever the menu is closed.
    template:saveOnClose(configPath, myConfig)

    -- Create a simple container Page under Template.
    local page = template:createPage({ label = "Settings" })

    -- Create a button under that controls the "enabled"
    -- setting in `myConfig`.
    -- Clicking on this button will change "enabled" from `true`
    -- to `false, and vice-versa.
    page:createYesNoButton({
        -- The `label` is the text that will be shown in your config menu.
        -- It lets users know what the button does.
        label = "Enable Mod",
        configKey = "enabled"
    })
end
event.register(tes3.event.modConfigReady, registerModConfig)

```

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

### Example: Find First Numeral

Source: https://mwse.github.io/MWSE/apis/re

Demonstrates using re.find to locate the starting and ending positions of the first sequence of digits in a string.

```lua
local re = require("re")

local function onLoaded(e)

    -- find the position of the first numeral in a string
    mwse.log("%d %d", re.find("the number 423 is odd", "[0-9]+"))  --> 12 14

end

event.register(tes3.event.loaded, onLoaded)
```

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

### Create Mod Configuration with Keybinder

Source: https://mwse.github.io/MWSE/guides/mod-config

Extends the previous example by adding a keybinder to control the hotkey that opens the mod's UI element. This allows users to define custom key combinations for mod activation.

```lua
-- Default settings for your mod.
local myDefaultConfig = {
    enabled = true,
    -- These values should be between 0 and 1.
    xPosition = 0.5, -- 0 means "left-most", and 1 means "right-most".
    yPosition = 0.5, -- 0 means "top-most", and 1 means "bottom-most".

    -- This stores the key combination that opens your mods UI element.
    -- This value corresponds to holding `Alt + H`.
    menuKeyCombo = {
        keyCode = tes3.scanCode.h,
        isAltDown = true,
        isControlDown = false,
        isShiftDown = false
    },
}

local configPath = "My Awesome Mod"
local myConfig = mwse.loadConfig(configPath, defaultConfig)

-- When the mod config menu is ready to start accepting registrations,
-- register this mod.
local function registerModConfig()
    -- Create the top level component Template. This is basically a box that holds all the other parts of the menu.

    local template = mwse.mcm.createTemplate({ name = "My Awesome Mod", config = myConfig })
    template:register()
    template:saveOnClose(configPath, myConfig)

    -- Create a simple container Page under Template.
    local page = template:createPage({ label = "Settings" })

    -- Create a button under Page that toggles a variable between true and false
    page:createYesNoButton({ label = "Enable Mod", configKey = "enabled" })

    -- Controls the position of the menu.
    page:createPercentageSlider({
        label = "Menu X Position",
        configKey = "xPosition"
    })
    page:createPercentageSlider({
        label = "Menu Y Position",
        configKey = "yPosition"
    })

    -- Controls the key that opens the menu.
    page:createKeyBinder({ label = "Menu key", configKey = "menuKeyCombo" })
end
event.register(tes3.event.modConfigReady, registerModConfig)


```

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

### Get Days in Month

Source: https://mwse.github.io/MWSE/apis/tes3?q=

Returns the number of days in a given month. This may be altered if a Morrowind Code Patch feature was installed.

```lua
local dayCount = tes3.getDaysInMonth(month)
```

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

### Get Weapon Skill Name

Source: https://mwse.github.io/MWSE/types/tes3weapon?q=

Retrieves the name of the skill used by a weapon when an attack starts. Registers an event listener for the attackStart event.

```lua
local function showMessage(e)
    if not e.mobile.readiedWeapon then return end
    local id = e.mobile.readiedWeapon.object.skillId
    local name = tes3.getSkillName(id)

    tes3.messageBox(name)
end

event.register(tes3.event.attackStart, showMessage)
```

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

### Create MCM Template with Default Settings Display

Source: https://mwse.github.io/MWSE/guides/mod-config

Shows how to initialize an MCM template, including providing default configurations and enabling the display of default setting values.

```lua
local template = mwse.mcm.createTemplate({
    name = "My Awesome Mod",
    config = myConfig,
    defaultConfig = myDefaultConfig,
    showDefaultSetting = true,
})
```

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

### skillId

Source: https://mwse.github.io/MWSE/types/tes3weapon?q=

Gets the skill ID for the attack skill used by the weapon, mapping to values in the `tes3.skill` namespace. An example is provided for printing the skill name.

```APIDOC
## skillId

### Description
Gets the skill ID for the attack skill used by the weapon. Maps to values in `tes3.skill` namespace.

### Returns
* `result` (tes3.skill)

### Example
```lua
local function showMessage(e)
    if not e.mobile.readiedWeapon then return end
    local id = e.mobile.readiedWeapon.object.skillId
    local name = tes3.getSkillName(id)

    tes3.messageBox(name)
end

event.register(tes3.event.attackStart, showMessage)
```
```

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

### new

Source: https://mwse.github.io/MWSE/types/mwseMCMKeyBinder

Creates a new KeyBinder instance with specified configuration options. Allows customization of labels, behavior, and associated variables.

```APIDOC
## new

### Description
Creates a new KeyBinder.

### Method
`new(data)`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
* `data` (table): _Optional_. Configuration options for the new KeyBinder.
  * `label` (string): _Optional_. Text shown next to the button.
  * `description` (string): _Optional_. If in a Sidebar Page, the description will be shown on mouseover.
  * `allowCombinations` (boolean): _Default_ : `true`. If true, the KeyBinder will let the user use modification keys: Shift, Ctrl, and Alt when rebinding.
  * `allowMouse` (boolean): _Default_ : `false`. If true, the KeyBinder will let the user use mouse buttons and scroll wheel in this keybinder. In that case the variable will have mwseKeyMouseCombo layout, mwseKeyCombo otherwise.
  * `keybindName` (string): _Optional_. The keybind name. Shown in the popup menu header. This string is formatted into a localized version of "SET %s KEYBIND.". If none is provided the popup has "SET NEW KEYBIND." as header text.
  * `leftSide` (boolean): _Default_ : `true`. If true, the button will be created on the left and label on the right.
  * `variable` (mwseMCMVariable, mwseMCMSettingNewVariable): _Optional_. A variable for this KeyBinder.
  * `defaultSetting` (mwseKeyCombo, mwseKeyMouseCombo): _Optional_. If `defaultSetting` wasn't passed in the `variable` table, can be passed here. The new variable will be initialized to this value.
  * `callback` (fun(self: mwseMCMKeyBinder)): _Optional_. The custom function called when the player interacts with this KeyBinder.
  * `inGameOnly` (boolean): _Default_ : `false`. If true, the setting is disabled while the game is on main menu.
  * `restartRequired` (boolean): _Default_ : `false`. If true, updating this Setting will notify the player to restart the game.
  * `restartRequiredMessage` (string): _Optional_. The message shown if restartRequired is triggered. The default text is a localized version of: "The game must be restarted before this change will come into effect."
  * `indent` (integer): _Default_ : `12`. The left padding size in pixels. Only used if the `childIndent` isn't set on the parent component.
  * `childIndent` (integer): _Optional_. The left padding size in pixels. Used on all the child components.
  * `paddingBottom` (integer): _Default_ : `4`. The bottom border size in pixels. Only used if the `childSpacing` is unset on the parent component.
  * `childSpacing` (integer): _Optional_. The bottom border size in pixels. Used on all the child components.
  * `postCreate` (fun(self: mwseMCMKeyBinder)): _Optional_. Can define a custom formatting function to make adjustments to any element saved in `self.elements`.
  * `class` (string): _Optional_.
  * `componentType` (string): _Optional_.
  * `parentComponent` (mwseMCMComponent): _Optional_. 

### Returns
* `button` (mwseMCMKeyBinder) - The newly created KeyBinder instance.
```

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

### Get Music File Duration

Source: https://mwse.github.io/MWSE/types/tes3audioController?q=

Loads a music file and calculates its duration in seconds. The provided path should be relative to the game's installation directory.

```lua
local duration = myObject:getMusicFileDuration(path)

```

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

### Get Weapon Speed

Source: https://mwse.github.io/MWSE/types/tes3playerAnimationController

Retrieves the animation speed scaling for weapon animations. This value is typically reset at the start of each strike and can be modified to affect animation speed.

```lua
local currentWeaponSpeed = mobile.animationController.weaponSpeed
```

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

### Start New Game

Source: https://mwse.github.io/MWSE/apis/tes3?q=

Initiates a new game session.

```lua
tes3.newGame()
```

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

### Get High-Precision CPU Time with os.getHighPrecisionClock

Source: https://mwse.github.io/MWSE/apis/os

Returns a high-precision CPU time measurement in seconds since Lua started. This is intended for detailed performance profiling.

```lua
local result = os.getHighPrecisionClock()

```

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

### Start a Timer with a Callback

Source: https://mwse.github.io/MWSE/guides/introduction

Demonstrates using the timer library to schedule a function call after a specified delay. Useful for time-based actions.

```lua
-- Define the function we want to call when our timer completes.
local function myTimerCallback()
    tes3.messageBox({ message = "My timer completed!" })
end

-- Start a timer that finishes after 5 seconds.
-- When it does finish it will call the above function.
timer.start(5, myTimerCallback)

```

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

### create

Source: https://mwse.github.io/MWSE/types/mwseMCMColorPickerButton?q=

Initializes and renders the UI elements that constitute this Setting component within a given parent block.

```APIDOC
## create

### Description
This method creates the UI elements that comprise this Setting.

### Method
`create(parentBlock)`

### Parameters
* `parentBlock` (tes3uiElement) - The parent UI element to which this setting's elements will be attached.

### Example
```lua
myObject:create(parentBlock)
```
```

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

### Get CPU Time with os.clock

Source: https://mwse.github.io/MWSE/apis/os

Retrieves the CPU time elapsed since the Lua script started in seconds. This is a basic clock for general timing purposes.

```lua
local result = os.clock()

```

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

### Get MGE XE Version

Source: https://mwse.github.io/MWSE/types/mgeVersionTable

Retrieve the semantic version of the installed MGE XE. This function returns an object containing the major, minor, and patch versions.

```javascript
mge.getVersion()
```

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

### Example: Log Skill Information

Source: https://mwse.github.io/MWSE/apis/tes3ui?q=

Logs the name and type of each player skill to the console when the 'u' key is pressed. Demonstrates advanced logging with formatting.

```lua
local function printNames(e)
    local skillTypeNames = {
        [0] = "Major",
        [1] = "Minor",
        [2] = "Miscellaneous"
    }

    for _, skillId in pairs(tes3.skill) do
        local skillStat = tes3.mobilePlayer:getSkillStatistic(skillId)
        local name = tes3.getSkillName(skillId)
        local typeName = skillTypeNames[skillStat.type]

        tes3ui.log("%s, type: %s skill", name, typeName)
    end

    tes3.messageBox("Done! Open the console to see the result.")
end

event.register(tes3.event.keyDown, printNames, { filter = tes3.scanCode.u })


```

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

### Retrieve and Change GMST Value

Source: https://mwse.github.io/MWSE/apis/tes3?q=

This example demonstrates how to read the current value of a GMST and then how to modify it. It uses `findGMST` to get the GMST object and accesses its `value` property.

```lua
local oldGMST = tes3.findGMST("sServiceTrainingTitle").value

-- oldGMST is now "Training"

-- Now let's change the message to something more appropriate.
tes3.findGMST("sServiceTrainingTitle").value = "Cheat"

```

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

### xStartScript

Source: https://mwse.github.io/MWSE/references/mwse-mwscript/utility?q=

Starts a specified script. This function is a wrapper around `StartScript` allowing variable input.

```APIDOC
## `xStartScript`⚓︎

### Description
Starts a specified script. This function is a wrapper around `StartScript` allowing variable input.

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Parameters
* `string` **scriptName**: The name of the script to start.

### Returned:
* _None_
```

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

### Prevent Specific Actors from Initiating Combat

Source: https://mwse.github.io/MWSE/events/combatStart?q=

This example demonstrates how to prevent certain actors from initiating combat with the player by returning false from the callback. It uses a helper function `isPacifistTarget` to determine if an actor should be prevented from starting combat.

```lua
---@param actor tes3mobileActor
local function isPacifistTarget(actor)
    -- Here you can filter if the actor should initiate combat with the player.
    -- ...
end

--- @param e combatStartEventData
local function forcedPacifism(e)
    if (e.target == tes3.player and isPacifistTarget(e.actor)) then
        return false
    end
end
event.register(tes3.event.combatStart, forcedPacifism)
```

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

### Minimal Formatter Example (String Formatting)

Source: https://mwse.github.io/MWSE/guides/logging

This example shows how to create a custom formatter that mimics `string.format` behavior for log messages. It ensures the first argument is a string and applies `string.format` if additional arguments are provided.

```lua
local log = mwse.Logger.new{
    --@param self mwseLogger
    --@param record mwseLogger.Record
    --@param msg string|any
    --@param ... any
    formatter = function(self, record, msg, ...) 
        -- Use the default header.
        local header = self:makeHeader(record)

        -- Make sure the first parameter is a string.
        local outputMessage = tostring(msg)

        -- If there were multiple arguments passed, call `string.format`.
        if select("#", ...) > 0 then
            outputMessage = string.format(msg, ...)
        end

        -- Prefix the message with the default header.
        return header .. outputMessage
    end
}

```

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

### Start Dialogue

Source: https://mwse.github.io/MWSE/types/tes3mobileActor?q=

Starts dialogue with this actor for the player.

```lua
myObject:startDialogue()
```

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

### Start NiKeyframeController

Source: https://mwse.github.io/MWSE/types/niKeyframeController?q=

Starts the controller at a specified time. This method is intended for controllers with an animTimingType of 1.

```lua
myObject:start(time)

```

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

### new

Source: https://mwse.github.io/MWSE/types/niVertexColorProperty

Creates a new niVertexColorProperty object. Initializes `lighting` to `ni.lightingMode.emiAmbDif` and `source` to `ni.sourceVertexMode.ignore` by default.

```APIDOC
## new

### Description
Creates a new niVertexColorProperty with `lighting` set to `ni.lightingMode.emiAmbDif` and `source` set to `ni.sourceVertexMode.ignore`.

### Method
`local property = niVertexColorProperty.new()`

### Returns
#### Success Response
* `property` (niVertexColorProperty) - The newly created niVertexColorProperty object.
```

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

### Get Current Weather

Source: https://mwse.github.io/MWSE/apis/tes3?q=

Gets the currently active weather from the player's current region.

```lua
local weather = tes3.getCurrentWeather()
```

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

### new

Source: https://mwse.github.io/MWSE/types/niCollisionSwitch

Creates a new instance of `niCollisionSwitch`.

```APIDOC
## `new`⚓︎

### Description
Creates a new niCollisionSwitch.

### Method
`local new = niCollisionSwitch.new()`

### Returns
- `new` (niCollisionSwitch) - The newly created niCollisionSwitch object.
```

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

### lastFrameTime

Source: https://mwse.github.io/MWSE/types/tes3worldController?q=

_Read-only_. The value of `tes3.worldController.systemTime` at the start of the previous frame. Measured in milliseconds since the program was started.

```APIDOC
## lastFrameTime

### Description
_Read-only_. The value of `tes3.worldController.systemTime` at the start of the previous frame. Measured in milliseconds since the program was started.

### Returns
* `result` (number)
```
Tokens:
Raw