H3lp Yours3lfDocs
guide

Your First H3 Integration

Install H3, run a complete player script, and choose your next helper.

H3 saves you from maintaining the same small utilities in every mod. You can adopt one helper without adopting a framework. Start with a plain module; installed interfaces come later.

Two ways into H3

H3 has two entry points. A plain module is loaded with require and returns a Lua value. An installed interface is published by a registered H3 script, so it must be obtained through openmw.interfaces after H3's plugin is enabled.

-- Plain module
local random = require 'scripts.s3.randomGen'

-- Installed interface
local I = require 'openmw.interfaces'
local s3lf = I.s3.lf

The spelling of the path is part of the contract: randomGen is a module, while s3lf is a member of the I.s3 interface. The interface also carries OpenMW context and lifetime rules; the require call does not grant permissions by itself. Continue with State and Context before combining the two styles in one system.

Install the dependency

Follow the H3 installation instructions: make its data directory available to OpenMW and enable H3lp Yours3lf.esp. Use an OpenMW version supported by the H3 release you installed. These pages describe the source in this repository, not every older release.

Your own mod still needs its own data directory and script declaration. Requiring a helper does not register your script with OpenMW.

Run a complete example

Create scripts/<mod_name>/h3_demo.lua inside your mod's data directory:

local Signal = require 'scripts.s3.signal'
local normalizePath = require 'scripts.s3.normalizePath'

local ready = Signal.new()
ready:connect(function(path)
    print('H3 demo: ' .. path)
end)

local function report()
    ready:fire(normalizePath('Config\\MyMod\\Icon'))
end

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

Create your script list alongside the scripts directory:

PLAYER: scripts/<mod_name>/h3_demo.lua

Enable that script list in OpenMW's content list, with H3 enabled as a dependency. Load a game. The OpenMW log should contain:

H3 demo: config/mymod/icon

The example does not load a texture or change game state. It normalizes a string, passes it to a synchronous listener, and prints the result. onInit covers initialization and onLoad covers loading saved script state; no per-frame polling is needed.

If nothing happens

  • Module not found: check that H3's data directory is active. Paths passed to require are module names, not filesystem paths.
  • No output: check that your script list is enabled and its script path matches your file. Read earlier log errors before debugging the helper.
  • Missing interface: a plain module and an installed interface are different entry points. S3lf is I.s3.lf, not a Signal-style constructor.

Choose the next step