pebble_looting · v0.1.0
Exports, hooks & events
All exports are server-side: exports.pebble_looting:Name(...). Expected failures return nil (or false) plus { code, message }, where code is one of invalid_payload, not_found, duplicate, database or unauthorized.
Waiting for pebble_looting
Exports wait for the resource to finish loading before they answer. To register things at startup, listen for pebble_looting:server:ready, or check IsReady() first:
local looting = exports.pebble_looting
local function onLootingReady()
looting:RegisterLootTemplate(MY_TEMPLATE)
end
if GetResourceState("pebble_looting") == "started" and looting:IsReady() then
onLootingReady()
end
AddEventHandler("pebble_looting:server:ready", onLootingReady)
Templates
See Templates for the fields.
| Export | Returns | Notes |
|---|---|---|
RegisterLootTemplate(data) |
template?, err? |
Creates the template, or updates it when data.version is newer than both the last version you registered and the last staff edit in /lootadmin. |
GetOrCreateLootTemplate(data) |
template?, wasCreated, err? |
Never overwrites an existing template. |
UpdateLootTemplate(ref, data) |
template?, err? |
ref is the numeric id or your script id. |
GetLootTemplate(ref) |
template? |
Returns a copy; changing it has no effect. |
RemoveLootTemplate(ref) |
removed, err? |
Containers using it fall back to their zone template. |
GenerateLoot(ref, options?) |
items?, slots, weight, err? |
Rolls without opening anything. options: source, coords, tags, multiplier, extraItems. |
Items are { name, count, metadata? }. weight uses your inventory's unit (grams on every supported inventory).
World loot owned by your resource
These only exist while your resource runs. They're removed when it stops and never touch the database.
| Export | Notes |
|---|---|
RegisterLootPoint({ id, label, model, coords, template? }) |
Spawns a searchable prop. coords is a vector4; leave template out to use the zone's. Returns the point key. |
RemoveLootPoint(id) |
|
RegisterLootBox({ id, label, coords, length, width, heading, minZ, maxZ, interactionLabel?, template? }) |
An invisible searchable box. |
RemoveLootBox(id) |
|
RegisterModelOverride(model, template) |
Every prop or ped of this model becomes searchable. |
RemoveModelOverride(model) |
|
SpawnGroundLoot({ item, model, coords, count?, metadata? }) |
One pickup that goes straight into the inventory. Returns its id. |
RemoveGroundLoot(id) |
|
AddNoLootZone(id, zone) |
{ type = "sphere", coords, radius }, { type = "box", coords, size, rotation } or { type = "poly", points, minZ?, maxZ? }. |
RemoveNoLootZone(id) |
Zones
| Export | Returns |
|---|---|
GetZoneForCoords(coords) |
{ id, name } of the smallest zone around the coords, or the nearest fallback zone. |
GetZoneMetadata(coords, key) |
The first value for key, walking from the smallest zone outwards. Staff edit these in /lootadmin. |
GetLootTemplateForCoords(coords, category?) |
The template id the zones give that spot, optionally for a ped category. |
GetZoneMetadata is how zone-specific settings reach other resources. A zombie script can read zombieDifficulty per area without pebble_looting knowing about zombies.
Hooks
Every add returns an id for RemoveLootHook(id). Hooks are also removed when the resource that added them stops.
Each handler gets a context: { source?, template, tags (set), coords?, sourceType, sourceId }. sourceType is "point", "box", "model", "ped", "script" or "simulation" (the admin roll simulator).
| Export | Handler returns |
|---|---|
AddLootModifier(modifier, handler) |
A multiplier for "rolls", "searchTime" or "cooldown", or nil to leave it. Results multiply together. |
AddExtraDropProvider(handler) |
Extra items added to every roll. |
AddLootCondition(handler) |
true, or false, reason to block the search. The reason is shown to the player. |
AddPedCategoryResolver(handler) |
A category name for a dead ped; zones map categories to templates. |
local function scavengerBonus(ctx)
if ctx.source and ctx.tags.scrap then
return 1 + exports.my_skills:GetLevel(ctx.source, "scavenging") * 0.1
end
end
local function bossKeyDrop(ctx)
if ctx.sourceType == "ped" and ctx.sourceId == "zombie_boss" then
return { { name = "boss_key", count = 1 } }
end
end
local function militaryOnly(ctx)
if ctx.tags.military and not exports.my_jobs:IsMilitary(ctx.source) then
return false, "Only the military can open these"
end
return true
end
local function zombieCategory(ped)
local zombie = exports.my_zombies:GetZombie(ped.entity)
return zombie and ("zombie_%s"):format(zombie.type)
end
looting:AddLootModifier("rolls", scavengerBonus)
looting:AddExtraDropProvider(bossKeyDrop)
looting:AddLootCondition(militaryOnly)
looting:AddPedCategoryResolver(zombieCategory)
Events
| Event | Payload |
|---|---|
pebble_looting:server:ready |
None. Fires once the caches are loaded, at the same moment IsReady() turns true. |
pebble_looting:server:stashOpened |
source, templateId, scriptId, stashId, key, newStash, firstTouch, tags, sourceType, sourceId |
pebble_looting:server:stashRemoved |
key, stashId. Fires when loot refreshes or a container is removed. |
firstTouch is true the first time a player opens a stash during its cooldown. That makes it the right trigger for XP or quest progress.
Example resource
docs/example.lua in the resource is a complete example: it registers its own template, rolls loot with GenerateLoot and gives it to a player, and adds a night-time bonus to the rolls.
local TEMPLATE = {
id = "airdrop_crate_blue",
version = 1731456000,
label = "Airdrop Crate (Blue)",
cooldown = 90,
minRolls = 3,
maxRolls = 5,
tags = { "airdrop" },
pools = {
COMMON = { { item = "bread", min = 1, max = 3 } },
RARE = { { item = "ammo-rifle", min = 10, max = 30 } },
},
}
local function nightBonus(ctx)
if not ctx.tags.airdrop then return nil end
local hour = GetClockHours()
return (hour >= 22 or hour < 6) and 1.5 or nil
end
local function onLootingReady()
local template, err = looting:RegisterLootTemplate(TEMPLATE)
if not template then return lib.print.error(err.message) end
looting:AddLootModifier("rolls", nightBonus)
end