Lua API

Lua API

Function Index

Version 0.3.0 has 79 functions. This table lists the original 20; Gameplay API documents all 59 additions and their exact signatures.

Function	Arguments	Result
htf.on	Supported event name, Lua function	nil; replaces this mod's handler for that event.
htf.command	Command name, Lua function	nil; registers a local-host chat command.
htf.button	Label, Lua function	nil; registers a native action button.
htf.after	Seconds, Lua function	nil; schedules one callback.
htf.every	Seconds, Lua function	nil; schedules repeating callbacks.
htf.chat	Message	nil; broadcasts while hosting.
htf.money	Amount	Boolean indicating host economy availability.
htf.get_data	Key, optional fallback	Stored string; fallback defaults to an empty string.
htf.set_data	Key, value	nil; persists the value as a string.
htf.is_host	None	Boolean.
htf.log	Message	nil; writes to BepInEx output.
htf.players.list	None	Player snapshot array on the host.
htf.players.get	Steam ID string	Player snapshot or nil.
htf.players.heal / htf.players.feed	Steam ID string, amount 0-100	Boolean; restores a living player's stat on the host.
htf.players.teleport	Steam ID string, x, y, z, optional yaw	Boolean; sends a native host teleport.
htf.world.info	None	World status snapshot.
htf.world.spawn_position	None	Position snapshot or nil.
htf.world.boss	None	Boss item snapshot or nil.
htf.economy.balance	None	Shared balance number.

Use dot syntax, for example htf.log("Hello"). Colon syntax adds an implicit argument and is not supported by these callbacks. See Events for handler arguments and Examples for complete scripts.

See Player and World API for original snapshot fields, Steam ID rules, action bounds and readiness results. The original flat functions remain compatible.

Gameplay Namespaces

Namespace	Available operations
htf.items	List/get/nearby, spawn/despawn, cooking, skins, interaction, score bonuses and creature damage.
htf.catalog	Item definitions, bait definitions and attachment descriptions.
htf.inventory	Slots, bait selection/stocks, pocket costs and unlocks.
htf.combat	Weapon/melee stats, bullet upgrades and sharpening.
htf.server	Session rule queries/setters and save requests.
htf.boat	Status, unlocks, radar, motors, skins, driver ejection and return-to-spawn.
htf.npcs	Locations, quests, progression and grill unlock.
htf.bosses	Boss status, immortality and crew-scaled health/damage queries.
htf.players additions	Local-player/held-item queries, damage, poison and fire.
htf.world additions	Island lists/travel/unlock, water height/depth and game-rule queries.
htf.economy additions	Affordability, give and spend.

All new gameplay mutations require the host. IDs and indices are validated; queries return plain snapshots, not raw game objects. Invalid arguments raise errors, while unavailable objects or denied actions normally return nil/false. Read Gameplay API before using grants or spawning: native upgrade grants do not automatically charge money.

Events

htf.on("fish_hooked", function(fish_name)
end)

Register one callback per event per Lua mod. Registering the same event again replaces that mod's previous callback.

There are 50 supported names. Callbacks are queued notifications, not cancellable filters. Each listener gets independent nested snapshot tables. Events produced by a callback wait for a later Update; see Events for ordering, capacity and lifecycle details.

Commands

htf.command("reward", function(args)
  htf.money(50)
end)

Commands are typed by the host as /reward. args is a one-indexed Lua table containing words after the command.

Names accept 1-32 letters, digits, underscores, or hyphens and are normalized to lowercase. Do not include / when registering. Duplicate command names fail registration. Arguments are split at spaces, without quoted-argument parsing. Callbacks do not receive a player object.

Scheduling

htf.after(5, function()
  htf.chat("Five seconds passed.")
end)

htf.every(60, function()
  htf.chat("Minute check.")
end)

Host Actions

htf.chat("Hello crew")
htf.money(100)

htf.chat broadcasts a prefixed game chat message. htf.money awards shared money and only acts while hosting.

Messages are limited to 200 characters including the mod-name prefix. Money must be finite, nonnegative, and at most 1,000,000 per call; amounts are rounded to integers and capped at the balance limit. htf.money returns true when the host economy is available, false otherwise. These are shared funds, not a private player balance.

Persistent Data

local score = tonumber(htf.get_data("score", "0"))
score = score + 1
htf.set_data("score", tostring(score))

Values are strings. Use Lua tonumber and tostring for numeric values.

Keys accept 1-64 letters, digits, underscores, or hyphens. Values are limited to 4096 characters. Data is saved in BepInEx/config/HowToLua.<id>.cfg, shared across that installation's worlds. It is not JSON storage.

Native Buttons

htf.button("Show catch count", function()
  htf.chat("Catches: " .. htf.get_data("catches", "0"))
end)

Buttons appear in Pause > Lua Mods > Mods / Actions. Host-only mod actions are disabled on clients. Labels allow 1-48 characters, with up to 16 actions per mod.

Limits and Errors

Each entry/callback has a 50,000 Lua instruction budget. Runtime failures disable the mod, its timers, commands, and action buttons. Reload after fixing the file. The sandbox exposes math, string and table operations, but not io, os, debug, require, dofile, loadfile, or coroutine.

Timers accept 0.05-86400 seconds, with up to 64 pending timers per mod. They use unscaled game time, including pauses. When a host-only timer becomes eligible after time spent outside a hosted session, it runs once rather than replaying every missed interval. Callbacks cannot yield; split longer work across timers.

Timers do not return handles, and there is no timer cancellation function in this release. Reloading clears all timers. See Troubleshooting for failure messages and recovery.

Utility

if htf.is_host() then
  htf.log("Host is active")
end