Player and World API

Player and World API

Added in 0.2.0. Use dot syntax. Returned tables are independent snapshots; changing a table never changes a game object. Actions use the game's normal host networking, so clients do not need Lua for these operations.

For the 0.3.0 additions, including local-player lookup, held items, damage/status effects, economy transactions, island travel and item spawning, see Gameplay API. This page retains the original API contracts.

Players

Function	Result
htf.players.list()	One-indexed array of initialized connected player snapshots on the host; empty on clients/outside hosting. Includes the host.
htf.players.get(steam_id)	Current matching snapshot, or nil if not hosting or the player is absent.
htf.players.heal(steam_id, amount)	Restore health of a living player. Boolean indicating action readiness/acceptance.
htf.players.feed(steam_id, amount)	Restore fullness of a living player. Boolean indicating action readiness/acceptance.
htf.players.teleport(steam_id, x, y, z, yaw)	Send a living player a native teleport. Optional yaw defaults to current rotation. Boolean indicating whether it was sent.

Steam IDs must be nonzero decimal strings, for example "76561198000000001". Never use tonumber on them: Lua numbers cannot represent all Steam IDs exactly. A zero-ID/LAN player can appear in list() but cannot be addressed by these actions. Invalid argument types/ranges raise a Lua error and disable that script, just like other callback errors.

Health/fullness amounts must be numbers from 0 through 100. Fractional amounts are truncated; the game clamps the resulting stat to 100. Dead players are not revived by these APIs. Missing/deinitializing players, inactive hosting or uninitialized vitals return false.

Teleport coordinates must be finite numbers between -100000 and 100000; yaw must be between -360 and 360 degrees. Teleport returns false while an island is loading, for dead/missing players, or without an active owner connection. True means the native teleport was sent, not that the destination is safe or the remote client acknowledged it. There is no collision, water or terrain safety check. Prefer spawn_position() for return-to-spawn commands.

Player Snapshot

Field	Type / meaning
name	Steam display name, or "Unknown".
steam_id	Decimal string; may be "0" before Steam identity is ready or on LAN.
client_id	Connection ID string, or nil. Not a persistent identity.
health	Current integer HP, or 0 if vitals unavailable.
fullness	Current integer fullness, or 0 if vitals unavailable.
poison / fire	Numeric synchronized status values, or 0 if vitals unavailable; added in 0.3.0.
afk	Boolean from the game's AFK state.
position	Table with numeric x, y, z, in world coordinates.

World and Economy

Function	Result
htf.world.info()	World snapshot: is_host, zero-based island (-1 if unavailable), loading, initialized, save_name, difficulty, money. Missing save fields are nil.
htf.world.spawn_position()	{x, y, z} for the current player spawn, or nil unless hosting an initialized, non-loading island.
htf.world.boss()	Current boss item snapshot while hosting, or nil.
htf.economy.balance()	Shared balance; reads the authoritative synchronized value on the host, otherwise the locally observed game balance.

world.info() is a readiness/status query and is callable outside hosting. The other world fields can still be initializing when server_started fires. The existing htf.money(amount) remains a shared-money grant function; it also requires the host's local player. Version 0.3.0 adds htf.economy.give/spend/can_afford and htf.server.save; see Gameplay API for bounds and request semantics. There is no arbitrary balance setter.

Item Snapshot

Used by item, fish and creature events, and world.boss().

Field	Type / meaning
id	Numeric game item definition ID, not a unique instance ID.
name	Game item display name.
worth	Total game-calculated sale worth at capture time.
network_id	Network object ID string, or nil. Session-local and potentially reused; do not persist as an identity.
position	{x, y, z} world position.
is_fish	Boolean.
boss_type	Game boss enum name, usually "None" for ordinary items.

The snapshot is not a live object handle and can outlive its source. In 0.3.0, htf.items.get(network_id) refreshes an instance snapshot and explicit item APIs accept the session-local string ID. htf.catalog.item(id) and htf.items.spawn(id, x, y, z) instead use numeric definition IDs. See Gameplay API for protection rules and detailed fields.