Guides

Unique phones

Config.UniquePhone.Enabled = true gives each physical item its own identity. The resource writes these metadata keys by default:

Metadata	Purpose
`trapPhoneId`	Persistent internal identity for that physical phone
`phoneNumber`	Generated public number shown in the phone

Keep the item unique or non-stackable. If two phones are allowed to merge into one inventory stack, their metadata and phone history cannot remain separate.

Set Config.UniquePhone.Enabled = false if every character should have one trap-phone profile regardless of which item they use.

Phone numbers use Config.Number.Prefix followed by Config.Number.Digits random digits. Existing phone numbers are stored in the database and are not regenerated by later config changes.

Buyer contracts

config/buyers.lua defines the buyers initially available to the server. Config.DrugItems maps each buyer drug ID to its inventory item:

Config.DrugItems = {
    weed = "weed",
    coke = "coke",
}

Each buyer can contain:

Field	Purpose
`id`, `name`, `enabled`	Stable buyer identity, display name and availability
`minReputation`	Reputation required before the buyer can unlock
`introducedBy`	Another buyer that introduces this contact
`drugs`	Drug IDs, per-item price ranges and requested amount ranges
`neededBeforeMinutes`	Delivery deadline
`reputationReward`	Reputation awarded for a completed contract
`failedReputationPenalty`	Reputation removed after a failed deal
`policeRisk`	Buyer-specific dispatch chance
`replyDelaySeconds`	Delay before the buyer responds
`buyIntervalHours`	Range used when scheduling the buyer's next request
`buyerPedModel`, `buyerVehicleModel`	Models used for the arriving buyer
`angryChance`	Base chance that the handoff turns hostile

Introduction chains must reference an existing buyer and cannot contain loops.

Buyer manager

Run /trapphoneadmin as an admin to create, edit, enable, disable or remove buyers. Changes are stored in electus_trap_phone_buyers.

On first start, buyers from config/buyers.lua are inserted into the database. Existing database rows take priority on later starts, so editing an already-imported buyer in the Lua file does not overwrite the admin-managed version.

To re-import one configured buyer, remove that buyer's row from electus_trap_phone_buyers and restart the resource. Back up the table before changing production data.

Reputation and buyer trust

Global reputation unlocks contacts through each buyer's minReputation.

Buyer trust is tracked separately for every contact. Configure its range, rewards, penalties and levels in Config.Buyer.Trust. Trust levels can increase price, add requested items and reduce the buyer's angry chance.

Calls, messages and voicemail

Trap-to-trap calls use the voice resource configured in Config.Calls.VoiceResource, which defaults to pma-voice.

Call history and voicemail are controlled by Config.Calls.History:

MaxEntries limits saved history returned to the phone.
RetentionDays removes old call records.
VoicemailEnabled enables voicemail.
MaxVoicemailLength limits voicemail text length.

When Config.Calls.LBPhone.Enabled is true and lb-phone is started, trap phones can exchange calls and direct messages with LB Phone numbers. Set RequirePhone = true if the LB Phone side must have an equipped phone.

Police dispatch and witnesses

Buyer policeRisk can send a dispatch during a deal. Nearby witnesses add a separate risk configured in Config.DealWitness.

The bundled bridge auto-detects lb-tablet, ps-dispatch, cd_dispatch, origen_police and qs-dispatch. To select one explicitly, add this near the integration settings in config/config.lua:

Config.DispatchSystem = "ps-dispatch"

Set a risk value to 0 when that source should never dispatch police.

Electus Gangs

Set Config.Gangs.Enabled = true and start electus_gangs before electus_trap_phone.

Successful sales inside a gang zone can:

Award gang XP through Config.Gangs.SaleXp
Change gang reputation through Config.Gangs.SaleRep
Add capture progress using Config.Gangs.Capture

Make sure drugCapture exists in electus_gangs under Config.capturing.captureProgressTypes, and allow that progress type on the relevant zones. If you change Config.Gangs.Capture.Type, add the same name to Electus Gangs.

Set Config.Gangs.OnlySellInDrugZones = true when sales should require the player to be inside an Electus Gangs zone.