Events

Events

Event	Arguments	When it fires
fish_hooked	fish_name, item	A fish first attaches to a rod during this host session.
creature_killed	creature_name, item	A creature's health crosses from positive to zero or below.
boss_killed	boss_name, item	The killed creature is a mini-boss or boss.
server_command	command_name, args	A registered How to Lua command runs.
player_joined	name, steam_id, player	Host roster polling first observes a player with a nonzero Steam ID.
player_left	name, steam_id	A previously observed player leaves the host roster.
server_started	world	The framework first observes active hosting, once per host session.
server_stopped	None	The framework observes hosting end. Pending game events are discarded.
server_save_requested	save_name, auto_save	The host enters SaveManager.SaveServer with a current save. Not proof that the disk write succeeded.
island_changing	previous_index, next_index	The authoritative island selection changes.
island_loaded	island_index	The host's island load coroutine completes, including its final setup/teleport steps.
boss_spawned	boss_name, item	A new boss fight is initialized.
boss_despawned	boss_name, item	A boss is removed; the snapshot was captured before removal.
creature_health_changed	item, previous, current	Server-side creature health changes.
money_changed	previous, current, delta	Server balance changes for any reason, including rewards and spending.
item_picked_up	item, player	An item's synchronized holder becomes a player.
item_dropped	item, player	An item's synchronized holder stops being that player.
item_sold	item, seller	The host's MoneyManager.SellItem method returns; seller is the last holder, possibly nil.
fish_sold	item, seller	The sold item is a fish. Also triggers item_sold.
item_cooked	item, previous, current	Server cookness changes, not necessarily completion of cooking.
item_skin_changed	item, previous_skin, current_skin	Server-side equipped item skin index changes. Not a skin unlock event.
player_health_changed	player, previous, current	Server-side player health changes.
player_died	player	Health crosses from positive to zero or below.
player_revived	player	Health crosses from zero or below to positive; can include initial spawn health setup.
player_fullness_changed	player, previous, current	Server-side fullness changes.
player_poison_changed	player, previous, current	Server poison counter changes.
player_fire_changed	player, previous, current	Server fire counter changes.

Added in 0.3.0

Event	Arguments	When it fires
item_spawned	item	Native Item.OnStartServer runs, including ordinary game spawns that call the base lifecycle method. Derived initialization may still be pending.
item_despawned	item	Native Item.OnStopServer begins, including island unload removals.
fish_released	fish_name, item	A fish detaches from its rod; it may attach again later.
inventory_changed	player, operation, slot, item	The server inventory dictionary changes. Operation is the game's enum name; item can be nil.
inventory_slot_changed	player, previous, current	Selected zero-based slot changes; -1 means no slot.
inventory_pockets_changed	player, previous, current	Number of extra inventory pockets changes.
inventory_bait_changed	player, previous, current	Selected bait ID changes.
inventory_bait_stock_changed	player, operation, bait_id, previous, current	Owned bait list changes. Completion/clear operations are not individual bait purchases; inspect operation first.
boat_driver_changed	previous_player, current_player	Driver changes; either player snapshot can be nil.
boat_motor_changed	previous, current	Motor index changes.
boat_skin_changed	previous, current	Boat skin index changes.
boat_radar_changed	previous, current	Radar unlock state changes.
difficulty_changed	previous_name, current_name	Server difficulty changes, using game enum names.
boss_max_health_changed	previous, current	Boss maximum HP changes, including player-count scaling.
boss_immortality_changed	previous, current	Boss invulnerability state changes.
npc_talk_requested	npc_id	The server handles an NPC talk request; no requesting-player identity is available.
npc_quest_progressed	npc_id, quest_index, progress, line_type	Native quest dialogue is sent for ItemReceived or OnCompleted. Not every line of ordinary dialogue.
grill_unlocked	None	Server grill state changes from locked to unlocked.
weapon_sight_changed	item, previous, current	Weapon sight index changes.
weapon_barrel_changed	item, previous, current	Weapon barrel index changes.
weapon_ammo_type_changed	item, previous, current	Bullet upgrade/ammo-type index changes. Not ammunition count.
weapon_magazine_changed	item, previous, current	Extended-magazine boolean changes.
weapon_laser_changed	item, previous, current	Laser-sight boolean changes.

These are the 50 supported events in 0.3.0. Game events run only on the host; server_stopped is the one notification delivered after hosting ends. See Player and World API and Gameplay API for snapshot fields. Optional destroyed/unavailable object snapshots are nil. Island indices are zero-based.

fish_hooked means attachment to a rod, not landing or selling the fish. It fires at most once per fish instance during a host session. Creature death notifications are deduplicated per instance per session. They do not identify the killer and may include environmental deaths. A boss also triggers creature_killed; removing its body can later trigger boss_despawned.

Roster checks run once per second and include the host. Existing players are observed as joins on the first poll. Very short connections between polls can be missed. Steam IDs are strings; zero-ID/LAN players are not reported by these two events.

Commands are local-host chat commands only. Client chat does not invoke them. Each listener receives its own argument table for server_command.

Delivery and Compatibility

The six events from 0.1.1 keep their leading arguments. Existing function(name) handlers continue working and may ignore the new snapshot argument.

Callbacks run from the framework's Update after the native hook has captured its values. A callback cannot cancel damage, item sales, drops, or another game operation. Returning false has no cancellation effect. Do not treat these events as pre-action filters.

Each listener gets a fresh copy of every nested snapshot table. Editing it does not affect the game or another mod. Snapshots reflect capture time; query htf.players.get(id) for current state.

The queue holds up to 1024 events and drains at most 128 per Update. Events created by an event callback wait for a later Update. Overflow drops new events and logs a warning. Reload clears queued events and registrations; ending a host session discards pending game events before server_stopped. Old events are not replayed to reloaded mods. server_started is not a scene-ready notification; use island_loaded and readiness queries.

Avoid granting money from every money_changed callback or healing unconditionally from player_health_changed: those actions can generate more events. Callbacks remain instruction-limited, but feedback loops can continue across frames.

Semantics to Know

• Pickup/drop events describe holder changes, which can include transfers or inventory operations, not just throwing an item onto the ground.
• Sale hooks target SellItem, not the misleading vanilla OnItemSold event, which fires on any balance change. money_changed may arrive before item_sold.
• Save requests may fail validation or disk I/O inside vanilla code. Check the game's logs for success/failure; there is deliberately no server_saved guarantee.
• Initial synchronized-value setup can produce health, fullness, skin or money events. Do not assume every change was caused by a player.
• Fire, poison and cookness values are raw game counters/values, not normalized percentages.
• island_loaded observes the host's completion, not an acknowledgement from every remote client. A cancelled or failed coroutine does not generate it.