API reference¶

The complete Lua API of H7ModEngine. For an introduction with worked examples, read the modding guide first.

Every mod runs in a Lua 5.4 state shared by all mods, with the standard libraries (string, table, math, io, os, utf8, coroutine, debug, package) and these additions:

Name	What it is	Reference
`h7`	The engine library: finding objects, hooks, events, timers, mods, creating objects, logging	h7 library
`mod`	The current mod: its name, folder, settings, saved data and `require`	Mods
`print(...)`	Same as `h7.log(...)`	h7.log
`require(name)`	Standard `require`, searching `<Game>\H7ModEngine\lib\?.lua`	Mods
`on_unload()`	A global function a mod may define; called before the mod unloads	Mods

Values coming from the engine are one of three reference types, plus plain Lua values:

Type	What it is	Reference
Object reference	A live engine object (actor, hero, class, function, ...)	Engine objects
Struct reference	A live view of a struct inside an object, a struct or hook arguments	Structs
Array reference	A live view of an UnrealScript `array<T>`	Arrays

How every UnrealScript type is converted is in Values and types. The game's own classes, whose properties and functions mods use through these references, are listed in Game classes.

Index¶

h7 library¶

Function	Summary
`h7.version`	Engine version string
Logging
`h7.log(...)`	Write a line to `engine.log`
`h7.warn(...)`	Write a `WARNING` line
`h7.error(...)`	Write an `ERROR` line (does not raise)
`h7.log_lines([after])`	Recent log lines (the last 2000), e.g. to show the log in game
Finding objects
`h7.first(class)`	First live instance of a class
`h7.find_all(class [, include_templates])`	All live instances of a class
`h7.find(path)`	An object by path
`h7.find_class(name)`	A class by name
`h7.enum(name)`	An enum's values by name
Reflection
`h7.properties(x)`	Properties of a class, struct or function
`h7.functions(x)`	Functions of a class
`h7.signature(func)`	A function's declaration as text
`h7.to_table(value)`	Plain Lua copy of a struct, array or object
Hooks
`h7.hook(func, fn [, when])`	Run `fn` before (or after) a game function
`h7.hook_post(func, fn)`	Run `fn` after a game function
`h7.unhook(id)`	Remove a hook
Events and timers
`h7.on(event, fn)`	Handle an event
`h7.off(id)`	Remove an event handler
`h7.after(seconds, fn)`	Run `fn` once after a delay
`h7.every(seconds, fn)`	Run `fn` repeatedly
`h7.cancel(id)`	Cancel a timer
Creating objects
`h7.clone(source, name [, outer [, flags]])`	Copy an object or archetype
`h7.new_object(class [, options])`	Create a new object
`h7.package(name)`	Find or create a top-level package
`h7.name(str)`	Add a name to the engine's name table
`h7.can_create()`	Whether object creation is available
`h7.flags`	Object flag constants
Mods
`h7.mods()`	Every installed mod
`h7.set_mod_enabled(name, on)`	Turn a mod on or off
`h7.mod_settings(name)`	A mod's settings and their values
`h7.set_mod_setting(name, key, value)`	Change a mod's setting
`h7.reload()`	Reload every mod
Console
`h7.exec(command)`	Run a console command
`h7.config(section, key [, default])`	Read a value from `H7ModEngine.ini`
`h7.clipboard([text])`	Read or set the Windows clipboard's text

Object methods¶

Method	Summary
`obj.Property`, `obj.Property = v`	Read or write a property
`obj:Function(...)`	Call an UnrealScript function
`obj:call(name, ...)`	Call a function by name
`obj:get_name()`	Object name
`obj:get_full_name()`	Class and path
`obj:get_path_name()`	Path
`obj:get_class()`	Class object
`obj:get_outer()`	Containing object
`obj:get_default()`	A class's default object
`obj:get_super()`	Parent class, struct or function
`obj:get_address()`	Memory address
`obj:is_valid()`	Whether the object still exists
`obj:is_a(class)`	Class check
`arr:add([value])`	Append to an array
`arr:remove(i)`	Remove an array element

Per mod¶

Name	Summary
`mod.name`, `mod.version`, `mod.author`, `mod.dir`	Mod information
`mod.require(name)`	Load a Lua file from the mod's folder
`mod.save(table)` / `mod.load()`	Persistent data
`mod.settings`	The mod's settings
`on_unload()`	Cleanup before unloading
Manifest (`mod.lua`)	Name, version, load order, settings, ...

Events¶

Event	Arguments
`tick`	`dt`
`map_loaded`	`map`
`mods_loaded`	`count`
`mod_toggled`	`name`, `enabled`
`setting_changed`	`name`, `key`, `value`

Conventions in this reference¶

Signatures are written h7.find_all(class [, include_templates]) → table: square brackets mark optional parameters, → what the function returns, | alternatives.
class parameters take a class name ("H7AdventureHero" or "MMH7Game.H7AdventureHero") or a class object.
func parameters take a function path ("MMH7Game.H7Calendar.NextDay", optionally prefixed with "Function ") or a function object.
Errors are raised with Lua's error, so a mistake stops the current chunk, hook, handler or timer and is logged with a stack trace (see Errors); use pcall to handle one yourself.
Every hook, event handler and timer belongs to the mod whose code created it and is removed when that mod unloads. Ones created from an exec script belong to no mod: nothing removes them automatically.