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