Server

Server exports for kq_drugdeals. Call them from any resource.

Organisations

IsOrganisationUnlocked

Returns whether the player has the organisation unlocked (visible on the map and in the app). A public organisation is always visible without an unlock, and hidden / public organisations are tradeable regardless. This reads the per-player unlock only

-- Example
exports.kq_drugdeals:IsOrganisationUnlocked(
    player, -- integer - Server id
    orgId, -- string - Organisation id
)

-- Returns: boolean - Whether the organisation is unlocked for this character

UnlockOrganisation

Unlocks the organisation for this player's character. Persisted, the blip and app contact appear. This is the intended way to open a Closed organisation from your own quest or job script

-- Example
exports.kq_drugdeals:UnlockOrganisation(
    player, -- integer - Server id
    orgId, -- string - Organisation id
)

-- Returns: boolean - Success (true when unlocked, or already was)

LockOrganisation

Re-locks the organisation for this player's character. Standing survives, only the unlock is removed

-- Example
exports.kq_drugdeals:LockOrganisation(
    player, -- integer - Server id
    orgId, -- string - Organisation id
)

-- Returns: boolean - Success

GetOrganisationIds

Returns the ids of all active organisations

-- Example
exports.kq_drugdeals:GetOrganisationIds()

-- Returns: table - { 'org_a1b2c3', 'org_d4e5f6', ... }

GetAllOrganisations

Returns all active organisations as deep copies, safe to keep or mutate

-- Example
exports.kq_drugdeals:GetAllOrganisations()

-- Returns:
-- {
--     {
--         id = 'org_a1b2c3',
--         name = 'The Lost MC',
--         coords = {x = 0.0, y = 0.0, z = 0.0, h = 90.0}, -- Sell point picked for this server session
--         unlockMode = 'buyin', -- 'public' | 'hidden' | 'buyin' | 'closed'
--         description = 'Bikers out east',
--         enemies = {'org_d4e5f6'},
--         buyPrices = {{drugId = 'drug_a1b2c3', min = 0.8, mid = 1.0, max = 1.2, minQuantity = 10}},
--     },
--     ...
-- }

Organisation standing

Standing is 0-100 per character per organisation, priced in five levels (Bad / Poor / Neutral / Good / Great).

GetOrganisationStanding

Returns the raw standing value

-- Example
exports.kq_drugdeals:GetOrganisationStanding(
    player, -- integer - Server id
    orgId, -- string - Organisation id
)

-- Returns: number - Standing 0-100, or nil on an unknown id

GetOrganisationStandingLevel

Returns the standing level. This is what prices organisation sales

-- Example
exports.kq_drugdeals:GetOrganisationStandingLevel(
    player, -- integer - Server id
    orgId, -- string - Organisation id
)

-- Returns: number - Level 1-5, or nil on an unknown id

AddOrganisationStanding

Applies a standing change immediately (clamped 0-100) and pushes the new value to the player's app. Use for favours, quests, punishments

-- Example
exports.kq_drugdeals:AddOrganisationStanding(
    player, -- integer - Server id
    orgId, -- string - Organisation id
    delta, -- number - Change to apply, negative to lower
)

-- Returns: boolean - Success

SetOrganisationStanding

Sets standing to an absolute value (clamped 0-100) and pushes it to the player's app

-- Example
exports.kq_drugdeals:SetOrganisationStanding(
    player, -- integer - Server id
    orgId, -- string - Organisation id
    value, -- number - Target standing 0-100
)

-- Returns: boolean - Success

Player rating

The app star rating (1.0-5.0) that gates buyer quality.

GetPlayerRating

Returns the player's app rating

-- Example
exports.kq_drugdeals:GetPlayerRating(
    player, -- integer - Server id
)

-- Returns: table - { stars = 3.8, dealsCompleted = 24 }

AddPlayerRating

Moves the star rating by a delta (clamped 1.0-5.0). Does not count a deal

-- Example
exports.kq_drugdeals:AddPlayerRating(
    player, -- integer - Server id
    delta, -- number - Change to apply, negative to lower
)

-- Returns: boolean - Success

Market

GetMarketPrice

Returns the current drifted headline price of a drug (its best grade)

-- Example
exports.kq_drugdeals:GetMarketPrice(
    drugId, -- string - Drug id
)

-- Returns: number - Current price, or nil on an unknown id

GetMarketDrift

Returns the current drift of a drug as a fraction

-- Example
exports.kq_drugdeals:GetMarketDrift(
    drugId, -- string - Drug id
)

-- Returns: number - Drift fraction (0.05 = 5% above base)

GetAllMarketPrices

Returns every active drug's price and drift in one call

-- Example
exports.kq_drugdeals:GetAllMarketPrices()

-- Returns:
-- {
--     drug_a1b2c3 = {price = 120, drift = 0.05}, -- price is the drifted headline (best grade)
--     drug_d4e5f6 = {price = 850, drift = -0.02},
-- }

GetDrugIds

Returns the ids of all active drugs

-- Example
exports.kq_drugdeals:GetDrugIds()

-- Returns: table - { 'drug_a1b2c3', 'drug_d4e5f6', ... }

GetDrugInfo

Returns metadata for one active drug, as a deep copy

-- Example
exports.kq_drugdeals:GetDrugInfo(
    drugId, -- string - Drug id
)

-- Returns:
-- {
--     id = 'drug_a1b2c3',
--     item = 'weed_packaged', -- Inventory item name
--     label = 'Weed',
--     street = true, -- Enabled sell channels
--     app = true,
--     useMetaPricing = true,
--     metaKey = 'quality',
--     metaSteps = {...}, -- Grade list, empty when the drug isn't metadata priced
--     appMinRating = 0,
--     streetQuantity = {min = 1, max = 3},
--     appQuantity = {min = 5, max = 20},
--     price = 120, -- Current headline market
--     drift = 0.05,
-- }

App

ForceBuyerRequest

Forces a buyer inquiry to the player's phone, same as the drugdeals:forcemsg admin command. Fails when the player has no advertised stock and no app-enabled drug exists

-- Example
exports.kq_drugdeals:ForceBuyerRequest(
    player, -- integer - Server id
)

-- Returns: boolean - Success

Saved contacts

Repeat customers saved in the player's app (Contacts tab). Per character, stored in kq_drugdeals_contacts. Standing uses the same 0-100 / five-level model as organisations. Statuses: active, blocked (standing hit 0), deleted (profile expired).

GetPlayerContacts

Returns every saved contact as deep copies, dead ones included

-- Example
exports.kq_drugdeals:GetPlayerContacts(
    player, -- integer - Server id
)

-- Returns:
-- {
--     {
--         id = 'ct_a1b2c3',
--         name = 'Fat Tony',
--         status = 'active', -- 'active' | 'blocked' | 'deleted'
--         standing = 46,
--         standingLevel = 3,
--         deals = 4, -- Completed deals with this contact
--         persona = 'rich',
--         deliveryMethod = 'npc', -- 'npc' | 'deaddrop'
--         pedModel = 'a_m_m_hillbilly_01', -- Their guy at npc handovers
--         neverBuys = false,
--         drugs = {'drug_a1b2c3'}, -- Preferred drugs
--     },
--     ...
-- }

GetContactSlots

Returns the active contact count against the rating-based cap (Config.contacts.maxByRating)

-- Example
exports.kq_drugdeals:GetContactSlots(
    player, -- integer - Server id
)

-- Returns: table - { active = 2, max = 4 }

AddPlayerContact

Creates an active contact and pushes it to the player's app. Ignores the slot cap, the caller decides. Every field of data is optional and rolled like a natural add when unset

-- Example
exports.kq_drugdeals:AddPlayerContact(
    player, -- integer - Server id
    data, -- table - Optional contact fields, see below
)

-- data:
-- {
--     name = 'Fat Tony',
--     persona = 'rich', -- 'broke' | 'cheap' | 'rushed' | 'regular' | 'rich' (drives budget and haggle patience)
--     deliveryMethod = 'npc', -- 'npc' | 'deaddrop'
--     drugs = {'drug_a1b2c3'}, -- Preferred drugs
--     standing = 40, -- 0-100
--     neverBuys = false,
--     pedModel = 'a_m_m_hillbilly_01',
--     home = {x = 215.7, y = -810.1}, -- Deliveries meet at the nearest free spot to this, random when unset
-- }

-- Returns: string - Contact id (ct_...), or false when no valid drug exists

RemovePlayerContact

Deletes the contact outright, whatever its status. Players can do the same from the contact's profile page

-- Example
exports.kq_drugdeals:RemovePlayerContact(
    player, -- integer - Server id
    contactId, -- string - Contact id
)

-- Returns: boolean - Success

GetContactStanding

Returns the raw standing value of a contact

-- Example
exports.kq_drugdeals:GetContactStanding(
    player, -- integer - Server id
    contactId, -- string - Contact id
)

-- Returns: number - Standing 0-100, or nil on an unknown id

AddContactStanding

Applies a standing change immediately (clamped 0-100) on an active contact. Dropping it to 0 blocks the contact exactly like a natural fallout, message included

-- Example
exports.kq_drugdeals:AddContactStanding(
    player, -- integer - Server id
    contactId, -- string - Contact id
    delta, -- number - Change to apply, negative to lower
)

-- Returns: boolean - Success

ForceContactRequest

Makes a contact message the player with a buy request now, skipping the message interval, decline snooze and police gate. Fails without a free delivery spot or thread slot

-- Example
exports.kq_drugdeals:ForceContactRequest(
    player, -- integer - Server id
    contactId, -- string - Optional, picks a random active contact when nil
)

-- Returns: boolean - Success

ForceContactReferral

Spawns a referred stranger vouched for by a random active contact, skipping the standing gate and the hourly roll. Still needs a free contact slot, a phone item and a free delivery spot

-- Example
exports.kq_drugdeals:ForceContactReferral(
    player, -- integer - Server id
)

-- Returns: boolean - Success

ExpireContact

Ends a contact's lifetime now. The profile flips to "Profile Deleted" and the farewell message is sent

-- Example
exports.kq_drugdeals:ExpireContact(
    player, -- integer - Server id
    contactId, -- string - Optional, picks a random active contact when nil
)

-- Returns: boolean - Success

Debug commands

ACE-gated in game (command.drugdeals:admin), or from the server console with the player id as first argument:

• drugdeals:forcemsg [playerId] - force a random buyer inquiry

• drugdeals:givecontact [playerId] - add a rolled contact (skips the cap)

• drugdeals:forcecontactmsg [playerId] - force a contact buy request

• drugdeals:forcereferral [playerId] - force a referral stranger

• drugdeals:expirecontact [playerId] - expire a random active contact

• drugdeals:contactstanding [playerId] <delta> - move a random active contact's standing (e.g. -45 to test blocking)

Owner hooks

Beyond exports, server/editable/editable.lua carries the Dummy.* hooks. Edit that file directly to react to events without another resource