Exports

Call server exports from a server script and client exports from a client script. Keep the resource folder named sky_treasurehunt and add dependency "sky_treasurehunt" to the integrating resource's manifest. Install the resource version containing these exports before using them.

Server Exports

Use server locks when a minijob, mission or another activity must prevent Treasure Hunt bin searching. The server rejects new searches and collection attempts while blocked and synchronizes the restriction to the player's HUD, search key and target interaction. Locks affect searching bins; metal detecting, magnet fishing and diving keep their existing behavior.

SetTrashSearchBlocked(playerId, blocked, reason?)

• Purpose: Prevents bin searches and cancels any current bin search, including inventory-full retries. Setting a block also invalidates requests waiting for progression or bin storage.
• Arguments: playerId is a loaded online player's numeric server ID. Pass -1 to block searching server-wide, including players who join later. blocked must be a boolean. reason is an optional string of 1–96 bytes; its default is "default".
• Returns: The effective blocked state after the change. For -1, the result describes the global restriction only. Invalid setter arguments raise an error.

-- Run after your server has accepted the player's job start.
exports["sky_treasurehunt"]:SetTrashSearchBlocked(player_source, true, "garbage_route")

-- Run on completion, cancellation and any other job exit path.
local still_blocked = exports["sky_treasurehunt"]:SetTrashSearchBlocked(
    player_source,
    false,
    "garbage_route"
)

Each lock belongs to the actual calling resource and reason. Repeating true for the same resource, player and reason is idempotent. Passing false releases only that caller's matching reason; other reasons, other resources, a global lock or disabled configuration can keep the player blocked. Use the same reason when releasing a lock.

-- Reserve all bins for another activity:
exports["sky_treasurehunt"]:SetTrashSearchBlocked(-1, true, "city_cleanup")

-- Release this resource's global restriction:
exports["sky_treasurehunt"]:SetTrashSearchBlocked(-1, false, "city_cleanup")

Blocking immediately releases the active bin reservation. It does not reroll the bin, reset its refill timer, clear progression or remove rewards already delivered. If a completed claim has already consumed the bin before cancellation, that bin stays depleted. Releasing a block allows a fresh search; it never resumes the cancelled claim.

Player locks are removed on disconnect; stopping an integrating resource removes that resource's locks. Locks are temporary and are cleared when Treasure Hunt restarts. Reapply them for ongoing jobs after a restart and release them when a character leaves a job or switches characters on the same connection. Global locks remain effective across player disconnects until released or their owning resource stops.

IsTrashSearchBlocked(playerId)

Returns true when bin searching is disabled by configuration, a global lock or a lock for this player. Pass -1 to query only the global/configuration restriction. This query does not evaluate distance, health, inventory capacity or whether another method is equipped.

local blocked = exports["sky_treasurehunt"]:IsTrashSearchBlocked(player_source)

GetTrashSearchState(playerId)

Returns a fresh status table for one player's established bin search. It contains no claim token, selected loot or mutable internal state.

local state = exports["sky_treasurehunt"]:GetTrashSearchState(player_source)
if state.active then
    print(("Bin search has %d ms remaining"):format(state.remainingMs))
end

Inventory-full claims can remain active with remainingMs = 0. Requests still loading progression before establishing a session are not reported as active.

CancelTrashSearch(playerId)

Cancels this player's current bin search and releases its reservation without setting a persistent block. It also invalidates a pending begin request and tells the client to clear its search/animation/HUD. playerId must be a positive integer server ID; -1 is not supported.

Returns true when an established server session existed, otherwise false. A pending begin request can be cancelled while the return value is false. Cancelling does not remove existing locks, reset a depleted bin or undo completed rewards.

local cancelled = exports["sky_treasurehunt"]:CancelTrashSearch(player_source)

GetActiveMethod(playerId)

Returns the method currently reserved by the player's character: "detector", "magnet", "diving" or "trash"; otherwise nil. Detector and shovel equipment share the "detector" method. Equipped magnet/diving sessions can reserve a method between individual actions, so this is not a progress-bar check.

local method = exports["sky_treasurehunt"]:GetActiveMethod(player_source)
if method then
    print(("Player has active Treasure Hunt equipment/activity: %s"):format(method))
end

Client Exports

Client exports apply to the local player. Client locks hide and cancel Treasure Hunt's bin interaction locally. Use the server setter above when the restriction must also prevent reward requests on the server. Server locks synchronize automatically; calling both setters for the same job is optional and creates two independently managed locks.

SetTrashSearchBlocked(blocked, reason?)

Sets or releases this client resource's reason, using the same boolean and 1–96-byte reason rules as the server setter. Setting true immediately clears the local search animation/HUD, hides the E prompt and prevents the Treasure Hunt target option from being selected. Pending responses cannot restore a cancelled search.

exports["sky_treasurehunt"]:SetTrashSearchBlocked(true, "local_activity")

-- Release only this client resource's matching reason:
local still_blocked = exports["sky_treasurehunt"]:SetTrashSearchBlocked(false, "local_activity")

Returns the effective local blocked state, including server restrictions and disabled configuration. Locks from other client resources/reasons remain active. Stopping the caller removes its local locks.

IsTrashSearchBlocked()

Returns true for a local lock, a synchronized server restriction, disabled configuration or a stopped resource. The client also starts blocked until its initial server access response arrives. If that sync fails, searching stays blocked until another server access update or a resource restart.

local blocked = exports["sky_treasurehunt"]:IsTrashSearchBlocked()

This checks restrictions; use CanSearchTrash to include the local gameplay conditions.

GetTrashSearchState()

Returns a fresh local status table:

local state = exports["sky_treasurehunt"]:GetTrashSearchState()

CancelTrashSearch()

Immediately cancels the local animation, HUD and pending request; an established claim is also closed on the server. Returns true if a local search or request existed, otherwise false. It does not release locks. Use the server cancellation export when server-side job logic must cancel a request before a client claim is established.

local cancelled = exports["sky_treasurehunt"]:CancelTrashSearch()

CanSearchTrash(entity?)

Returns whether a fresh local bin search can start now: no active/pending search or block, suitable player state, no conflicting NUI focus, a supported non-depleted bin within range and clear line of sight. Pass a local entity handle; omitting it uses Treasure Hunt's last detected nearby bin. With E discovery disabled, pass the entity explicitly.

local can_search = exports["sky_treasurehunt"]:CanSearchTrash(bin_entity)

The query starts no animation or reward request. It is a local availability hint; the server still validates the actual search. Other minijob interactions on that bin remain owned by their own resources.