Skip to content

mwse⚓︎

The mwse library provides methods for interacting with MWSE itself, rather than direct TES3 objects.

Properties⚓︎

mwse.buildDate⚓︎

A numerical representation of the date that version of MWSE currently being used was built on.

Formatted as YYYYMMDD.

Returns:

  • result (number)
Example: Check if the user has minimal required MWSE build installed.
-- Ensure we have the features we need.
if (mwse.buildDate == nil or mwse.buildDate < 20210817) then
    mwse.log("[Example] Build date of %s does not meet minimum build date of 20210817.", mwse.buildDate)
    return
end

mwse.buildNumber⚓︎

Equal to the APPVEYOR_BUILD_NUMBER in builds by AppVeyor (these builds are installed using the MWSE-Update). Equal to UINT_MAX in regular builds. This number is used for mod metadata files, when a mod depends on MWSE being installed.

Returns:

  • result (integer)

mwse.gameTimers⚓︎

The mwseTimerController responsible for game-type timers.

Returns:


mwse.realTimers⚓︎

The mwseTimerController responsible for real-type timers.

Returns:


mwse.simulateTimers⚓︎

The mwseTimerController responsible for simulate-type timers.

Returns:


mwse.version⚓︎

A numerical representation of the release version of MWSE currently being used.

Formatted as AAABBBCCC, where A is the major version, BBB is the minor version, and CCC is the patch version. BBB and CCC are forward-padded.

It is usually better to use mwse.buildDate instead.

Returns:

  • result (integer)

Functions⚓︎

mwse.clearScriptOverride⚓︎

Configures MWSE to no longer execute a lua function instead when a script would run. This undoes the work of mwse.overrideScript.

local success = mwse.clearScriptOverride(scriptId)

Parameters:

  • scriptId (string)

Returns:

  • success (boolean)

mwse.getCurrentMorrowindScriptState⚓︎

This function returns information on the current mwscript execution state.

local script, reference = mwse.getCurrentMorrowindScriptState()

Returns:

  • script (tes3script, nil): The currently executing mwscript script, or nil if none is presently being executed.
  • reference (tes3reference, nil): The currently executing mwscript script's associated reference. This will be nil for global scripts, or nil if no script is presently being executed.

mwse.getVersion⚓︎

Equivalent to mwse.version.

local result = mwse.getVersion()

Returns:

  • result (integer)

mwse.getVirtualMemoryUsage⚓︎

Returns the amount of memory used, in bytes.

local result = mwse.getVirtualMemoryUsage()

Returns:

  • result (number)

mwse.iconv⚓︎

Converts the provided string in UTF8 encoding to Morrowind's codepage base encoding.

local converted = mwse.iconv(languageCode, utf8string)

Parameters:

  • languageCode (tes3.languageCode): Determines the language (and appropriate encoding) to use. Maps to values in tes3.languageCode table.
  • utf8string (string): The string to convert

Returns:

  • converted (string)

mwse.loadConfig⚓︎

Loads a config table from Data Files\MWSE\config\{fileName}.json.

If the default values table is passed:

  • Empty keys in the config will be filled in using its values.
  • If no file exists, the function will return the default table.
  • In json, tables can be either arrays with integer keys or dictionaries with string keys. If your configuration table is mixed (has both string and integer indices), saving and loading from json will effectively convert all your integer indices to strings. This function will convert your configuration table's integer indices back if defaults table is given.
local result = mwse.loadConfig(fileName, defaults)

Parameters:

  • fileName (string): The non-extensioned name of the config file.
  • defaults (table): Optional. A table of default values.

Returns:

  • result (table)

mwse.loadTranslations⚓︎

Loads translations from the i18n folder for a given mod. This is locale-aware, using the result from tes3.getLanguage(). See the mod translations guide for more information.

local i18n = mwse.loadTranslations(mod)

Parameters:

  • mod (string): Name of the folder that your main.lua mod can be found in.

Returns:

  • i18n (fun(key: string, data: any): string): The callable translation results.

mwse.log⚓︎

This function writes information to the mwse.log file in the user's installation directory.

The message accepts formatting and additional parameters matching string.format's usage.

mwse.log(message, ...)

Parameters:

  • message (string)
  • ... (any): Optional. Formatting arguments. These are passed to string.format.

mwse.longToString⚓︎

Converts a TES3 object type (e.g. from tes3.objectType) into an uppercase, 4-character string.

local result = mwse.longToString(type)

Parameters:

Returns:

  • result (string)

mwse.overrideScript⚓︎

Configures MWSE to execute a given function instead when a script would run.

In most cases its intended to stop the execution of the original mwscript script. You can do so in the callback function by calling mwscript.stopScript().

local success = mwse.overrideScript(scriptId, callback)

Parameters:

Returns:

  • success (boolean)
Example: Here is an example of the most common use case for this function.
-- In this example, the vanilla "RaceCheck" script is overridden
-- with our own raceCheck() function that does the same thing.

local raceCheckScriptID = "RaceCheck"
local raceMap = {
    ["argonian"] = 1,
    ["breton"] = 2,
    ["dark elf"] = 3,
    ["high elf"] = 4,
    ["imperial"] = 5,
    ["khajiit"] = 6,
    ["nord"] = 7,
    ["orc"] = 8,
    ["redguard"] = 9,
    ["wood elf"] = 10,
}

local function raceCheck()
    -- It's almost always the desired behavior to stop the mwscript,
    -- since we are overriding it.
    ---@diagnostic disable-next-line: deprecated
    mwscript.stopScript({ script = raceCheckScriptID })

    local pcRaceID = tes3.player.object.race.id:lower()
    local PCRace = tes3.findGlobal("PCRace")

    PCRace.value = raceMap[pcRaceID]
end

-- Script overrides can be queued when initialited event triggers.
event.register(tes3.event.initialized, function()
    mwse.overrideScript(raceCheckScriptID, raceCheck)
end)

mwse.registerModConfig⚓︎

This is the main function to register a mod's configuration. Only registered configurations appear in the Mod Config menu.

mwse.registerModConfig(name, { onCreate = ..., onSearch = ..., onClose = ... })

Parameters:

  • name (string)
  • package (table)
    • onCreate (fun(modConfigContainer: tes3uiElement)): The function that creates the mod's configuration menu inside given modConfigContainer.
    • onSearch (fun(searchText: string): boolean): Optional. A custom search handler function. This function should return true if this mod should show up in search results for given searchText.
    • onClose (fun(modConfigContainer: tes3uiElement)): Optional. This function is called when the mod's configuration menu is closed. Typically, it's used to save the current config table.

mwse.saveConfig⚓︎

Saves a config table to Data Files\MWSE\config\{fileName}.json. The config is converted to JSON during saving.

mwse.saveConfig(fileName, config, jsonOptions)

Parameters:

  • fileName (string): Usually named after your mod.
  • config (table): The config table to save.
  • jsonOptions (table): Optional. Encoding options. These get passed to the dkjson encoder.

mwse.stringToLong⚓︎

Converts an uppercase, 4-character string into a TES3 object type.

local result = mwse.stringToLong(tag)

Parameters:

  • tag (string)

Returns:

  • result (number)

mwse.virtualKeyPressed⚓︎

Determines whether a key is pressed. A wrapper for GetAsyncKeyState function in Win32 API.

local result = mwse.virtualKeyPressed(VK_key)

Parameters:

  • VK_key (integer)

Returns:

  • result (boolean)