startGlobalScript

startglobalscript

This event is triggered when a global script is started. This includes usage of the StartScript command, any scripts that are assigned as a "Start Script" in the editor, and any previously-running global scripts in the save file which get restarted after loading.

The primary use case of this event is to expose lua functionality to dialogue or morrowind script contexts.

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

Tip

This event can be filtered based on the script.id event data.

Tip

This event supports blocking by setting e.block to true or returning false. Blocking the event prevents vanilla behavior from happening. For example, blocking an equip event prevents the item from being equipped.

Tip

An event can be claimed by setting e.claim to true, or by returning false from the callback. Claiming the event prevents any lower priority callbacks from being called.

Event Data

• reference (tes3reference, nil): Read-only. The reference that the script is targeted at, if any.
• script (tes3script): Read-only. The script that is being started.

Examples

Example: Calculating cosine from mwscript

-- This example shows how to perform a cosine calculation inside mwscript. It
-- demonstrates how to execute lua functions from mwscript, and how to pass
-- variables between the languages.

-- TESCS script definition:
-- The script body is intentionally empty, the logic will be implemented in lua.
-- For typical usage we only need to define the variables that we will use.
--
--[[
    begin CalculateCosine
    float input
    float result
    StopScript CalculateCosine ; Not required, but good practice.
    end
]]

-- Using our function:
-- This is what using our script would look like. Typically from another script,
-- or from a dialogue result. This example assumes a `var` variable was defined.
--
--[[
    set CalculateCosine.input to 15
    StartScript CalculateCosine
    set var to CalculateCosine.result
]]

-- The actual lua implementation:

---@param e startGlobalScriptEventData
local function onStartGlobalScript(e)
    if e.script.id == "CalculateCosine" then
        local context = e.script.context
        context.result = math.deg(math.cos(math.rad(context.input)))
        -- Note: We return false here so the actual script never executes.
        -- This is usually what you want! Otherwise the script would begin
        -- running and subsequent `StartScript` calls would not trigger our
        -- event.
        return false
    end
end
event.register(tes3.event.startGlobalScript, onStartGlobalScript)