Bounty Hunter

codex_bounty_hunter adds interactive bounty boards + hunt missions + an optional Bounty Hunter License (ID) flow for RedM.

This documentation is written for server owners and developers. Because the main logic is protected by CFX escrow, you only edit what is intentionally exposed (the Configs/*.lua files and the optional Configs/FunctionsConfig.lua hooks).

What players can do

• Walk up to a bounty board (Valentine / Blackwater / Saint Denis / Rhodes / Strawberry by default)

• Open the Bounty Board UI

• Accept a bounty (a configurable deposit is taken)

• Follow a clue phase, then a hunt phase

• Deliver the target alive or dead (some bounties can require alive)

• Get paid on success

• Officers can issue a Bounty Hunter License (ID), which can be required to open the board

What you (server owner) can configure

• Board locations / objects

• Spawn pools and clue locations per board

• Mission templates (NPC models, guard count, weapons, rewards multipliers)

• Framework type (VORP / RSG / TPZ)

• Deposit percentage and money type

• Time limit per mission

• Law job list & grade needed to issue IDs

• Enable/disable license requirement to open the board

• Optional integration hooks (money handling, open/close UI hooks, etc.)

Use the sidebar pages to configure, install and customize.

---

How it works

This section explains the runtime flow in a way that matches what the resource actually does.

1) Board objects exist in the world

The script spawns (or reuses if already present) bounty board objects at the coordinates defined in Configs/ObjectsConfig.lua.

Each object entry binds a board name (example: Valentine) to a set of world coordinates.

2) Players open the board UI

When a player is close enough to a configured board object, they get a Codex Prompt (hold key) to open the board.

When opened:

1. The client sets NUI focus and shows the UI

2. The client notifies the server the UI is open for that board

3. The client requests the list of bounties for that board via a server callback

4. The UI renders the list and allows Accept / Track / Clear

License gate (optional)

If CodexConfig.EnableCheckBountyIDs = true, the client calls a server callback first to verify the player has a valid issued Bounty Hunter ID (issued by an allowed law job). If the player has no valid license, the board will not open.

3) Accepting a bounty → creates a live bounty row

When a player presses Accept in the UI:

• The server reads the selected bounty template row (from codex_bounty_templates)

• A deposit is charged: deposit = floor(reward * CodexConfig.PercentageMoney)

• A new active bounty row is inserted into codex_bounties

• A mission payload is built from your spawn pool configs (Configs/BountySpawns.lua) and mission templates (Configs/MissionsConfig.lua)

• The server starts the mission for that player by sending the payload to the client

Important: Only one active mission per player is allowed at a time.

4) Mission phases

Phase A — Clues

The mission starts in a clue collection phase:

• The client places blips for each clue location

• A clue object is spawned (prop model is configurable)

• The player must collect requiredClues clues (from your spawn entry)

Phase B — Hunt

Once enough clues are collected:

• The target NPC and guards are spawned at the configured spawn point

• The target gets a blip

• Guards and target attack the player

Some mission templates can allow the target to attempt escape (and in the “Drug Baron” template the target can spawn a horse and flee).

Phase C — Deliver

When the target is detected as either:

• Dead (killed), or

• Captured alive (hogtied / cuffed — best-effort detection)

…the player must go to the drop-off location for that board.

When they enter the drop-off radius, the client reports completion to the server and cleanup runs.

5) Time limit and failure

A mission time limit is enforced server-side using CodexConfig.MissionTimeLimitSeconds:

• If the timer expires, the server fails the mission (time_expired)

• If the player dies during an active mission, the client reports failure (player_died)

When a mission fails, the bounty row is marked inactive so it disappears from boards.

6) Payout

On completion:

• If requiresAlive = true and the target is delivered dead → the mission fails (target_killed) and pays nothing.

• Otherwise, payout is:

finalReward = floor(rewardBase * multiplier)

Where multiplier comes from the mission template:

• rewardAliveMult when delivered alive

• rewardDeadMult when delivered dead

Money is paid using the default Codex Core account functions, unless you enable hooks and override the money functions.

---

Installation

Dependencies

The resource declares these dependencies:

• codex_core

• oxmysql

• ox_lib (initialized via @ox_lib/init.lua)

Make sure all three are started before codex_bounty_hunter.

Basic install steps

1. Put the resource folder in your server resources (example: resources/[codex]/codex_bounty_hunter)

2. Ensure dependencies start first:

   • ensure oxmysql

   • ensure ox_lib

   • ensure codex_core

3. Start this resource:

   • ensure codex_bounty_hunter

4. Import the SQL (see the Database page)

5. Configure board positions and mission settings in Configs/*.lua

Common “first run” checklist

• Verify oxmysql connection string is correct

• Verify codex_core is working and exports are available

• Confirm your framework setting matches your server:

  • CodexConfig.Framework = 'vorp' | 'rsg' | 'tpz'

• Confirm you have at least one bounty template row in codex_bounty_templates for each board you want active

---

Configuration

All user-editable settings for escrow-protected servers are in Configs/*.lua.

Configs/config-main.lua (CodexConfig)

Core

• DeveloperMode Debug printing. Do not enable on live servers.

• Framework 'vorp', 'rsg', or 'tpz'

• EnableCodexPrompts Enables the “hold key” prompts for opening boards and collecting clues.

• UseHooks When true, the resource will call functions you place in Configs/FunctionsConfig.lua.

Bounties & missions

• EnableCheckBountyIDs When true, players must have a valid issued Bounty Hunter license (ID) to open bounty boards.

• MaxBountiesPerPlayer Maximum bounties a player can have (the resource also enforces one active mission at a time).

• PercentageMoney Deposit ratio required to accept a bounty. Example: 0.5 means a bounty with reward $1000 requires $500 deposit.

• MoneyType Account type used by CodexCore money functions:

  • 0 money

  • 1 gold

  • 2 roll

• MissionTimeLimitSeconds Server-enforced time limit. Example default is 1800 (30 minutes).

Law / issuing IDs

• JobGradeAccess Minimum job grade required to issue IDs with /issueid.

• LawJobsAllowed A list of jobs that count as law enforcement (also used to validate ID issuers).

• LicenseItem Item name given when a player completes license info (default: bounty_license).

Keys

CodexConfig.Keys contains key hashes. The script uses CodexConfig.Keys["G"] for prompts by default.

If you change a key value, use only valid key hashes for RedM.

Configs/ObjectsConfig.lua (CodexDataObjects)

Defines bounty board object placements:

• ModelName object model (default mp005_p_mp_bountyboard02x)

• ModelCoords world position

• ModelHeading heading

• DistanceToReact how close the player must be

• BoundBoardName board label shown/used when opening the UI

The board name is later normalized to a lowercase internal name:

• Valentine → valentine

• Blackwater → blackwater

• Saint Denis → saintdenis

• Rhodes → rhodes

• Strawberry → strawberry

Configs/BountySpawns.lua (CodexBountySpawns)

Defines the spawn pool for each board (must match the internal board name used in DB and normalization).

Each entry contains:

• id unique spawn ID

• type mission template key (must exist in MissionsConfig.lua templates)

• spawn coordinates + heading

• searchRadius used for clue area (payload)

• requiredClues number of clues needed to progress

• clues list of clue positions; each clue can include a type (campfire / footprints / witness, etc.) for your own organization.

Configs/MissionsConfig.lua (CodexBountyMissions)

Drop-offs

DropOffs defines the delivery location per board.

Clue prop

CluePropModel defines the prop model used as clue objects.

Templates

Templates define how targets and guards spawn and behave.

Included templates:

• basic_outlaw

• gang_leader

• drug_baron

Each template includes:

• label

• targetModel

• guards and guardModels

• weapons

• spawnRadius

• escape (target can flee)

• baronEscapeOnHorse (Drug Baron only)

• escapeHealthPercent (when to flee)

• reward multipliers:

  • rewardAliveMult

  • rewardDeadMult

---

Bounty boards & locations

Boards are defined in Configs/ObjectsConfig.lua as world objects.

Default locations included:

• Valentine

• Blackwater

• Saint Denis

• Strawberry

• Rhodes

To add or move a board:

1. Add a new entry to CodexDataObjects

2. Choose the world coordinates and heading

3. Set a BoundBoardName (example "Valentine")

4. Ensure your database has bounty templates for the corresponding internal board name

Board name matching (important)

The system normalizes board names by:

• lowercasing

• removing spaces

Then matches known boards like:

• "Saint Denis" → saintdenis

Your codex_bounty_templates.board values must use the internal names (e.g. saintdenis, not Saint Denis).

Your Configs/BountySpawns.lua keys also must use the internal names.

---

Missions

Mission selection

When a bounty is accepted, the mission payload is built from:

• The newly created bounty row (codex_bounties)

• A random spawn entry from Configs/BountySpawns.lua for that board

• The mission template referenced by the spawn entry (type) in Configs/MissionsConfig.lua

Clues phase

• Each spawn entry provides a list of clue positions.

• The player collects clues until requiredClues is reached.

• Clues show as map blips and spawn clue objects (prop model from CodexBountyMissions.CluePropModel).

Hunt phase

After enough clues:

• Target ped spawns using the template targetModel

• Guards spawn using template guardModels and guards count

• Weapons are randomly selected from template weapons

Escape behavior

If a template has escape = true, the target can flee when:

• target health percentage drops below escapeHealthPercent, OR

• most guards are dead (>= 60% dead)

For drug_baron, if baronEscapeOnHorse = true, a horse is spawned and the target mounts and flees.

Delivery

Each board has a drop-off coordinate in CodexBountyMissions.DropOffs.

Delivery is detected when the player comes close enough to the drop-off after the target is:

• dead, or

• captured alive (hogtied/cuffed best-effort)

Success payout

Payout uses the reward multipliers from the template:

• Alive payout: floor(rewardBase * rewardAliveMult)

• Dead payout: floor(rewardBase * rewardDeadMult)

If the bounty requires alive delivery (requiresAlive = true) and the target is dead, the mission fails with no payout.

---

Bounty Hunter License (ID)

This resource includes a Bounty Hunter License system.

What it is

• Law enforcement can issue an ID card to a player.

• The ID is stored in the database table codex_bounty_ids.

• The player can fill out extra license information in the UI and receive the configured license item (CodexConfig.LicenseItem).

Require license to open boards

If CodexConfig.EnableCheckBountyIDs = true, players must have a valid ID row:

• The server checks codex_bounty_ids for the player’s name.

• The issuer job must match one of the jobs in CodexConfig.LawJobsAllowed.

If the player does not have a valid ID, the board UI will not open and they will be notified.

Issuing IDs (law officers)

Client command:

/issueid <serverId>

Rules:

• Your job must be in CodexConfig.LawJobsAllowed

• Your job grade must be >= CodexConfig.JobGradeAccess

When issued:

• The target player is shown an ID overlay (NUI)

• The server stores (or updates) the ID row in codex_bounty_ids

Completing license info

When the ID overlay is shown for an issued ID (not view-only), the player can fill in:

• First name, last name

• Birth year (must be 1700–1899)

• Town of birth

• Father’s first and last names

On successful save:

• the DB row is updated and marked complete

• the player receives CodexConfig.LicenseItem (default bounty_license)

Showing your license item to another player

The configured license item is registered as usable. When used:

• The script finds the nearest player

• It shows the license UI to that nearby player in view-only mode

---

Hooks & integration

Because escrow hides most core logic, this resource exposes an optional hook file:

Configs/FunctionsConfig.lua

Enable hooks by setting:

CodexConfig.UseHooks = true

Available hook functions

Client hooks

• CodexFunctions.Client.OnOpenBoard(boardName) Called when a player tries to open the board UI. Return false to block opening; return true or nil to allow.

• CodexFunctions.Client.OnCloseBoard() Called when the board UI is closed.

Server hooks

• CodexFunctions.Server.OnAcceptBounty(source, bountyId) Called when a bounty is accepted.

• CodexFunctions.Server.OnTrackBounty(source, bountyId) Called when a bounty is tracked.

• CodexFunctions.Server.OnClearBounty(source) Called when a player clears their active bounty.

• CodexFunctions.Server.OnIssueID(issuerSource, targetPlayerId, targetName) Called when an officer issues an ID.

Money integration hooks

If you do not want to use CodexCore’s money functions, implement:

• CodexFunctions.Server.TryTakeMoney(source, amount) -> boolean

Optionally you can also implement:

• CodexFunctions.Server.GiveMoney(source, amount) -> boolean

If a money hook is enabled and returns true, it is considered successful. If it errors or returns false, the resource falls back to its default behavior.

Example: integrating with another money system

CodexFunctions.Server.TryTakeMoney = function(source, amount)
  -- Check and remove money from your framework.
  -- Return true if removed; false if insufficient.
  return false
end

CodexFunctions.Server.GiveMoney = function(source, amount)
  -- Add money using your framework.
  return true
end

Keep hook functions small and safe: the core calls them using protected pcall.

---

Database

This resource uses oxmysql and expects specific tables.

Tables used

codex_bounty_templates

Templates shown on the board UI. The Accept button reads from this table.

Required columns used by the resource:

• id (primary key)

• board (internal board name: valentine, blackwater, saintdenis, rhodes, strawberry, etc.)

• name

• reward

• description

• location

• active (1/0)

Optional column (read safely):

• capture_alive (1/0) If present and set to 1, that bounty requires alive delivery.

codex_bounties

Live bounties created when a player accepts a bounty. The UI “Accepted” state is based on this table.

Columns used:

• id

• name

• reward

• description

• location

• board

• active

• accepted_by

• accepted_at

• tracked_by

When a mission finishes or fails, the row is set inactive (active = 0).

codex_bounty_ids

Stores issued bounty hunter IDs.

Columns used:

• id (format: BH-00000)

• name (player name)

• issuer_job

• issued_by_officer (1/0)

• issued_at (timestamp)

• bh_info_completed (1/0)

• License info fields saved on completion:

  • bh_first_name, bh_last_name

  • bh_birth_year, bh_town_birth

  • bh_father_first, bh_father_last

Importing SQL

Use the SQL files provided with the resource package to create these tables.

If your package contains:

• create_codex_bounties.sql

• create_codex_bounty_ids.sql

…import them with your preferred MySQL tool (phpMyAdmin, HeidiSQL, etc.) into the same database used by oxmysql.

---

Commands, events & callbacks

This page lists what a developer/server owner can rely on.

Commands

/issueid <serverId>

Client command for law officers to issue a Bounty Hunter ID to a player.

• Requires job in CodexConfig.LawJobsAllowed

• Requires grade >= CodexConfig.JobGradeAccess

/codex_bounty_refresh [board]

Server command to force-refresh open bounty board UIs (admin only).

• With a board name: refreshes only that board’s open UIs

• Without args: refreshes all open UIs

Server callbacks (CodexCore)

• codex_bounty:server:GetBounties(boardName) Returns board bounties from codex_bounty_templates.

• codex_bounty:server:CheckPlayerBountyIDs() Checks if the player has a valid issued license in codex_bounty_ids.

• codex_bounty_hunter:CheckCooldown() Queries codex_bounty_ids for the player’s name and returns (true, id) if found, otherwise false.

Server events

• codex_bounty:server:UIOpened(boardName)

• codex_bounty:server:UIClosed()

• codex_bounty:server:AcceptBounty(templateId)

• codex_bounty:server:TrackBounty(bountyId)

• codex_bounty:server:ClearBounty()

• codex_bounty:server:CompleteMission({ bountyId, alive })

• codex_bounty:server:FailMission({ reason })

• codex_bounty:server:FailMissionDirect(targetSrc, reason)

• codex_bounty:server:IssueID(targetPlayerId, targetName)

• codex_bounty:server:SaveBHInfo(data)

• codex_bounty:server:RegisterBH(data) (generates an ID payload and shows it)

Client events

• codex_bounty:client:OpenBountyBoardUI(boardName)

• codex_bounty:client:PushBounties(bounties, playerServerId)

• codex_bounty:client:StartMission(payload)

• codex_bounty:client:MissionFinished({ paid })

• codex_bounty:client:MissionFailed({ reason })

• codex_bounty:client:ShowIssuedID(payload)

• codex_bounty:client:ShowBountyID(payload)

• codex_bounty:client:UseLicenseNearest

• codex_bounty:client:Notify(msg, time)

---

Troubleshooting

The board prompt never appears

Checklist:

• CodexConfig.EnableCodexPrompts = true

• Your board object coords in Configs/ObjectsConfig.lua are correct

• The model name is valid (mp005_p_mp_bountyboard02x by default)

• You are within DistanceToReact

The board UI opens but is empty

• Confirm you have rows in codex_bounty_templates where:

  • board matches the internal name (valentine, blackwater, etc.)

  • active = 1

• Confirm oxmysql is connected and working

• Use /codex_bounty_refresh to refresh open UIs (admin)

Players cannot open boards (license error)

• Set CodexConfig.EnableCheckBountyIDs = false to disable license requirements, OR

• Ensure players have rows in codex_bounty_ids issued by a job in CodexConfig.LawJobsAllowed

Accept button does nothing

• Ensure oxmysql is running

• Ensure the bounty template ID exists and is active

• Check server console for “[Codex Bounty]” logs

Mission fails instantly

Common causes:

• Another active mission exists for that player (only one active mission per player)

• The mission payload failed to build because there are no spawn entries for that board in Configs/BountySpawns.lua

Payout doesn’t work

• If you enabled hooks, ensure your money hooks return true on success

• Otherwise, ensure codex_core account functions are working and CodexConfig.MoneyType matches your economy setup

Developer debugging tips

• Enable CodexConfig.DeveloperMode = true temporarily to print helpful logs.

• Disable it again for production servers.

---