S3lf

S3lf is a lazily cached facade over the attached OpenMW object. It resolves type methods, stats, records, object fields, and related helpers on demand, caching values where the configured key behavior allows it so repeated engine-backed lookups become ordinary table access. Bound type methods automatically use the attached object.

For the design reasoning and internal evolution behind this boundary, see Cod3x's I.s3.lf Design Genealogy.

What it actually does

These two forms ask the same OpenMW question:

local types = require 'openmw.types'
local health = types.Actor.stats.dynamic.health(self)
local stance = types.Actor.getStance(self)

local I = require 'openmw.interfaces'

local health = I.s3.lf.health
local stance = I.s3.lf.getStance()

The first S3lf access resolves the engine-backed value and stores cacheable results on the facade. Later reads use ordinary table lookup. The bound method supplies the attached object, so callers do not repeatedly pass self; type methods are wrapped once with the attached object and cached, removing repeated self plumbing and repeated facade resolution.

S3lf caches the engine-backed stat object, not a numeric snapshot of the stat. Caching s3lf.health does not freeze health.current; it retains the DynamicStat view instead of reconstructing that wrapper on every access.

Read the attached actor's health

local core = require 'openmw.core'
local I = require 'openmw.interfaces'

if not core.contentFiles.has 'H3lp Yours3lf.esp' then
    error 'H3 S3lf dependency is missing; enable the H3lp Yours3lf plugin before this script'
end

local function reportHealth()
    local s3lf = I.s3.lf
    local actor = s3lf.asActor()
    if actor then
        print(actor.recordId .. ': ' .. tostring(actor.health.current))
    end
end

return {
    engineHandlers = {
        onInit = reportHealth,
        onLoad = reportHealth,
    },
}

Use the bootstrap's player-script registration. Put H3lp Yours3lf.esp before your content in the load order. The content-file check diagnoses a missing or misconfigured dependency; the lookup still happens when the handler runs rather than assuming the interface is ready during another script's top-level evaluation.

Common members

Values marked uncacheable are read again; ignored values return nil. The lists below describe the complete H3-provided and inherited facade surface. record may be a creature, NPC, armor, book, clothing, ingredient, light, miscellaneous, potion, weapon, apparatus, lockpick, probe, repair, activator, container, door, static, or levelled-creature record when the attached object has that record type.

Inherited object members

S3lf retains the fields and methods of OpenMW's attached-object (SelfObject) surface. Their availability and mutation rules remain the OpenMW rules; the facade does not make read-only local object fields writable.

Forwarded dynamic members

The attached object's type module, record, and OpenMW animation module may expose additional members. S3lf forwards those members using the same key lookup, binding functions to the attached object and caching values according to the configured key behavior. Their names and availability therefore depend on the attached object's type and record; they are not a fixed H3 field list. Use type, record, and the relevant OpenMW API contract to determine what a particular object provides.

Actor methods

These methods exist on actor views. They omit the object argument because S3lf supplies the attached object.

Actor stats

These fields are engine stat objects, not copied plain tables. Dynamic stats, AI stats, attributes, and level apply to actor views as supported by the underlying type. Skills are available on NPC and player views.

NPC methods

These methods exist on NPC views. OpenMW's NPC type includes the player, so asNPC() also exposes them for a player view.

Player methods

These methods exist only on a player view.

Record-derived fields

When the attached record provides them, S3lf resolves these fields from the record:

Bound type methods omit the object argument. For example, actor.getStance() and actor.getEquipment(slot) operate on the attached actor. Use dot calls: adding a colon would supply an extra argument. Availability still depends on the object type and underlying OpenMW API.

Diagnostics and player-specific tracking

Combat tracking consumes OMWMusicCombatTargetsChanged; it is not an independent scan of every fight in the world. Incoming reports produce S3CombatTargetAdded or S3CombatTargetRemoved, with the reporting actor as payload. Do not interpret repeated reports as a unique kill count or guaranteed deduplicated transition history.

S3LFCellChanged carries the previous cell ID when the player moves between known cells. The player provider saves its tracked target data and visited cells. Consumers should use the interface, not reach into that provider's save payload.

Caching and lifetime

Most resolved members are cached; selected openmw.self keys are explicitly ignored or left uncached through H3's key-behavior table. Type values, type methods, stats, record values, object values, and animation values then follow their own lazy-cache paths. This is not a deep snapshot: cached engine stat objects can still expose current values. Do not infer that every cached scalar is refreshed each frame or that every field exists on every object. Retain the interface only for its valid script/object lifetime and read changing data when needed.

See State and Context for the distinction between wrappers, permissions, and persistent data.