Skip to content

tes3worldController⚓︎

A core game object used for storing world simulation data.

Properties⚓︎

aiDistanceScale⚓︎

A value in the range [0, 1]. The (relative) maximum distance setting for AI simulation. Corresponds to the AI distance option in the Options menu.

Returns:

  • result (number)

allMobileActors⚓︎

Read-only. The list of all active mobile actors. Mobile actors expire after 72 hours if they have not been in a loaded cell.

Returns:

armCamera⚓︎

Read-only. The access to the first person arms camera.

Returns:

audioController⚓︎

Read-only. The audio controller.

Returns:

blindnessFader⚓︎

Read-only. Screen overlay fader for the blind effect.

Returns:

characterRenderTarget⚓︎

Read-only.

Returns:

charGenState⚓︎

Read-only. The charGenState global variable. Indicates progress through character generation. Has a value of -1 when chargen is complete.

Returns:

countMusicTracksBattle⚓︎

Read-only. The number of available battle music tracks.

Returns:

  • result (number)

countMusicTracksExplore⚓︎

Read-only. The number of available explore music tracks.

Returns:

  • result (number)

criticalDamageSound⚓︎

The sound played when an actor takes damage from a critical hit. It plays instead of the normal health damage sound.

Returns:

cursorOff⚓︎

If the target crosshair is disabled. Corresponds to the "Crosshair" option in the Options menu.

Returns:

  • result (boolean)

day⚓︎

Read-only. The Day global variable, indicating the current day. Day numbering starts at 1 for the first day of a month.

Returns:

daysPassed⚓︎

Read-only. The DaysPassed global variable, indicating the days passed since the game started for this character.

Returns:

deadFloatScale⚓︎

Returns:

  • result (number)

defaultLandSound⚓︎

This it the default sound played when the player lands, after a jump or a fall.

Returns:

defaultLandWaterSound⚓︎

This it the default sound played when the player lands in the water, after a jump or a fall.

Returns:

deltaTime⚓︎

The time interval (in seconds) between this frame and the last frame. Useful for calculations that involve movement or damage over a period of time.

Returns:

  • result (number)

difficulty⚓︎

A number in the range [-1, 1]. Corresponds to the "Difficulty" option in the Options menu.

Returns:

  • result (number)

drowningDamageSound⚓︎

The sound played when an actor takes health damage while drowning. It plays instead of the normal health damage sound.

Returns:

drownSound⚓︎

The sound played when an actor is losing health by drowning.

Returns:

enchantedItemEffect⚓︎

Read-only. The animated texture effect that is applied onto equipped enchanted items.

Returns:

enchantedItemEffectCreated⚓︎

Read-only. If the enchantedItemEffect is available.

Returns:

  • result (boolean)

enchantedItemEffectTextures⚓︎

Read-only. An array of textures used for the enchanted item effect, 32 elements long.

Returns:

flagLevitationDisabled⚓︎

If levitation is disabled.

Returns:

  • result (boolean)

flagTeleportingDisabled⚓︎

If teleporting is disabled.

Returns:

  • result (boolean)

globalScripts⚓︎

Read-only. A list of active global scripts.

Returns:

handToHandHit2Sound⚓︎

A sound played when a hand to hand attack hits. For each attack, handToHandHitSound or handToHandHitSound2 are randomly chosen.

Returns:

handToHandHitSound⚓︎

A sound played when a hand to hand attack hits. For each attack, handToHandHitSound or handToHandHitSound2 are randomly chosen.

Returns:

healthDamageSound⚓︎

The sound played when health damage is taken.

Returns:

heavyArmorHitSound⚓︎

The sound played when a heavy armor piece is hit.

Returns:

helpDelay⚓︎

A number in the range [0, 2]. The delay in seconds before a tooltip appears. Corresponds to the "Menu help delay" option in the Options menu.

Returns:

  • result (number)

hitFader⚓︎

Read-only. Screen overlay fader that pulses when damage is taken.

Returns:

hour⚓︎

Read-only. The GameHour global variable, indicating the time of day.

Returns:

Example: Day - night calculation 
--- The strings returned by getDayTime function.
--- Using an alias as a collection for these strings
--- gives better autocomplete suggestions.
---@alias myModDaySegment
---| "sunrise"
---| "day"
---| "sunset"
---| "night"

--- This function returns a string that represents the current part of day.
--- The day segments are based on the sunset and sunrise durations.
---@return myModDaySegment
local function getDayTime()
    local hour = tes3.worldController.hour.value
    local wc = tes3.worldController.weatherController

    local sunriseBegin = wc.sunriseHour
    local sunriseDuration = wc.sunsetDuration
    local sunriseEnd = sunriseBegin + sunriseDuration

    local sunsetBegin = wc.sunsetHour
    local sunsetDuration = wc.sunsetDuration
    local sunsetEnd = sunsetBegin + sunsetDuration

    if (hour >= sunriseBegin and hour < sunriseEnd) then
        return "sunrise"
    elseif (hour >= sunriseEnd and hour < sunsetBegin) then
        return "day"
    elseif (hour >= sunsetBegin and hour < sunsetEnd) then
        return "sunset"
    else
        return "night"
    end
end

local function onLoaded()
    tes3.messageBox("Currently it's " .. getDayTime())
end
event.register(tes3.event.loaded, onLoaded)

hudStyle⚓︎

No known effect.

Returns:

  • result (number)

inputController⚓︎

Read-only. The controller responsible for player input.

Returns:

instance⚓︎

Read-only.

Returns:

  • result (HINSTANCE)

itemRepairSound⚓︎

The sound played when an item is repaired.

Bug

Due to a bug in the game engine, the initialization code for this field never sets it to any tes3sound object. Instead, use sound IDs "repair" or "repair fail."

Returns:

lastFrameTime⚓︎

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)

lightArmorHitSound⚓︎

The sound played when a light armor piece is hit.

Returns:

mapController⚓︎

Read-only. The controller responsible for the world and local maps.

Returns:

  • result (tes3mapController)

maxFPS⚓︎

Maximum framerate target for the engine's FPS limiter.

Returns:

  • result (number)

mediumArmorHitSound⚓︎

The sound played when a medium armor piece is hit.

Returns:

A value in the range [0, 1]. The alpha value of the black background of menus. Corresponds to the "Menu transparency" option in the Options menu.

Returns:

  • result (number)

Read-only. The access to the camera used to render menus.

Returns:

The sound played when a UI button or other control is clicked.

Returns:

Read-only. The controller responsible for the menu system.

Returns:

Unused sound. Not used when a menu is resized.

Returns:

missSound⚓︎

The sound played when a weapon fails its to-hit check.

Returns:

mobManager⚓︎

Read-only. The manager responsible for mobile objects and collision.

Returns:

month⚓︎

Read-only. The Month global variable, indicating the current month. Month numbering starts at 0 for the first month, Morning Star.

Returns:

monthsToRespawn⚓︎

Read-only. The monthsToRespawn global variable, used by the game to count the time left until containers are respawned. This is decremented at the end of a month (or end of a day with the appropriate MCP option). When it reaches 0, containers are respawned.

Returns:

mouseSensitivityX⚓︎

The horizontal camera rotation sensitivity. Corresponds to the "Horizontal sensitivity" option in the Options menu.

Returns:

  • result (number)

mouseSensitivityY⚓︎

The vertical camera rotation sensitivity. Corresponds to the "Vertical sensitivity" option in the Options menu.

Returns:

  • result (number)

musicSituation⚓︎

The kind of music being played. Only updates when music is not muted.

  • 0 Explore music
  • 1 Combat music
  • 2 Main menu music

Tip

These values are available via the tes3.musicSituation constants.

Returns:

nodeCursor⚓︎

Read-only. The scenegraph node for the target crosshair.

Returns:

parentWindowHandle⚓︎

Read-only. Handle to the parent window.

Returns:

  • result (HWND)

projectionDistance⚓︎

Returns:

  • result (number)

quests⚓︎

Read-only. A list of all available quest objects.

Returns:

quickSaveWhenResting⚓︎

Controls if auto-save on resting or waiting is enabled. Corresponds to the "Auto-save when rest" option in the Options menu.

Returns:

  • result (boolean)

rechargingItems⚓︎

Read-only. A list of enchanted items that are recharging. Items in the list may not all belong to the player.

Returns:

shaderWaterReflectTerrain⚓︎

If pixel shader water reflection includes terrain. Not functional with MGE enabled.

Returns:

  • result (boolean)

shaderWaterReflectUpdate⚓︎

Period between reflection updates for pixel shader water. Not functional with MGE enabled.

Returns:

  • result (number)

shadowCamera⚓︎

Read-only. The access to the camera used for shadows rendering.

Returns:

shadows⚓︎

An integer in the range of 0 to 6. Controls the amount of actor shadows drawn. The maximum value of 6 is loose; it is determined by the "Number of Shadows" INI setting. Corresponds to the "Real-time shadows" option in the Options menu.

Returns:

  • result (integer)

showSubtitles⚓︎

If subtitles are shown. Corresponds to the "Subtitles" option in the Options menu.

Returns:

  • result (boolean)

simulationTimeScalar⚓︎

A scalar used for simulation time. At the start of every frame, the deltaTime is multiplied by this value. Doing this here is safer than doing it in another event. This value doesn't need to be modified every frame. You need to restore it to its original value to cancel the time scaling.

Returns:

  • result (number)

splashController⚓︎

Read-only. Access to the splash controller.

Returns:

splashscreenCamera⚓︎

Read-only. The access to the camera used to render splashscreens.

Returns:

stopGameLoop⚓︎

When true, the game simulation loop will stop. Not normally used, and may have other unknown effects.

Returns:

  • result (boolean)

sunglareFader⚓︎

Read-only. Screen overlay fader for sunglare.

Returns:

systemTime⚓︎

Read-only. Time in milliseconds since the program was started.

Returns:

  • result (number)

timescale⚓︎

Read-only. The timescale global variable. Used to convert real time to in-game time.

Returns:

transitionFader⚓︎

Read-only. Screen overlay fader for cell transitions.

Returns:

useBestAttack⚓︎

Automatically choose the best attack direction for attacks. Corresponds to the "Always use best attack" option in the Options menu.

Returns:

  • result (boolean)

vfxManager⚓︎

Read-only. Access to the VFX manager.

Returns:

viewHeight⚓︎

Read-only. The height of the UI viewport in pixels (also returned by tes3ui.getViewportSize()). Affected by UI scaling. For screen resolution, use tes3.getViewportSize().

Returns:

  • result (number)

viewWidth⚓︎

Read-only. The width of the UI viewport in pixels (also used by tes3ui.getViewportSize()). Affected by UI scaling. For screen resolution, use tes3.getViewportSize().

Returns:

  • result (number)

weaponSwishSound⚓︎

The sound played when an attack with a melee weapon is performed. It always plays when a melee attack is released, irrespective of hit or miss.

Returns:

weatherController⚓︎

Read-only. The weather controller.

Returns:

werewolfFader⚓︎

Read-only. Screen overlay fader for werewolf vision.

Returns:

werewolfFOV⚓︎

The camera FOV when the player is a werewolf.

Returns:

  • result (number)

worldCamera⚓︎

Read-only. The access to the world camera.

Returns:

year⚓︎

Read-only. The Year global variable, indicating the current year.

Returns:

Methods⚓︎

applyEnchantEffect⚓︎

This method applies an enchantment's effects to a scene node.

local result = myObject:applyEnchantEffect(node, enchantment)

Parameters:

  • node (niNode): A scene node to which to apply the enchantment's effects.
  • enchantment (tes3enchantment): The enchantment's effects to apply.

Returns:

  • result (boolean)