☠ BountyBoard — Plugin Documentation

Version: 2.0.0 | Framework: Oxide / uMod | Game: Rust

A modern, performance-optimized player bounty system with a live CUI board, automatic kill-claim payouts, and full RP/Economics support.

---

Table of Contents

1. Overview
2. Features
3. Requirements & Dependencies
4. Installation
5. Configuration Reference
6. Permissions
7. Command Reference
8. Player Guide
9. Admin Guide
10. UI & UX Layout
11. Performance & Architecture
12. Data Storage
13. Troubleshooting
14. FAQ
15. Changelog

---

1. Overview

BountyBoard transforms the competitive dynamic of any Rust server by letting players put a price on each other's heads using in-game currency. Bounties are posted on a live leaderboard and paid out instantly and automatically when a target is killed — no admin intervention, no commands, no delay.

The board itself is a sleek, paginated CUI overlay with real-time online status, gold/silver/bronze rank indicators for top bounties, and full pagination for servers with large active bounty pools. Players also receive on-screen toast notifications for key events (bounty placed on them, bounty claimed, etc.).

---

2. Features

Feature	Description
☠ Bounty Placement	Spend RP or coins to post a bounty on any online player
⚡ Auto Kill-Claim	Killer is paid instantly on death — zero commands required
📋 Live Bounty Board	Paginated CUI sorted by reward value descending
🔴 Online Status Dots	Green dot = target is online, grey = offline
🏆 Top-3 Rank Badges	Gold, silver, and bronze rank decorations
🔔 Toast Notifications	Non-intrusive HUD popups for claims, placements, and targets
✅ Two-Step Confirmation	Modal confirm dialog prevents accidental fund deductions
📢 Server Broadcasts	Configurable chat announcements for placements and claims
🎯 Reward Pooling	Multiple bounties on one player stack — killer claims all
⚙️ Full Config Control	Min/max amounts, per-player limits, currency backend, and more
🛡️ Admin Override	Force-remove any bounty and auto-refund the placer
💾 Persistent Data	Bounties survive server restarts via Oxide data file

---

3. Requirements & Dependencies

Required

• Oxide / uMod — latest version recommended
• One economy plugin (choose one):

Plugin	Config Setting	Notes
ServerRewards	"Use Economics instead of ServerRewards": false	Default. Uses RP (Reward Points)
Economics	"Use Economics instead of ServerRewards": true	Uses coin/dollar balance

⚠️ Both plugins can coexist on your server — BountyBoard will only use whichever one is specified in the config. However, at least one must be installed or all fund operations will silently fail.

---

4. Installation

Step 1 — Upload the plugin

Copy BountyBoard.cs into your Oxide plugins folder:

/oxide/plugins/BountyBoard.cs

Oxide will automatically detect, compile, and load the plugin. Confirm in your server console:

[Oxide] Loaded plugin BountyBoard v2.0.0 by OhShit100x

Step 2 — Verify auto-generated files

On first load, BountyBoard creates:

/oxide/config/BountyBoard.json     ← Configuration file
/oxide/data/BountyBoard/bounties.json  ← Active bounty data

Step 3 — Configure

Edit /oxide/config/BountyBoard.json to match your server's economy setup and preferences (see Configuration Reference), then reload:

oxide.reload BountyBoard

Step 4 — Grant Permissions

At minimum, grant players the ability to place bounties:

oxide.grant group default bountyboard.place

Updating

Replace the .cs file with the new version. Oxide detects the change and hot-reloads automatically. All bounty data is preserved.

Uninstalling

oxide.unload BountyBoard

Then delete BountyBoard.cs. Data files are retained in /oxide/data/BountyBoard/ and can be safely deleted manually.

---

5. Configuration Reference

Location: /oxide/config/BountyBoard.json

{
  "Minimum bounty amount": 50,
  "Maximum bounty amount": 10000,
  "Max active bounties per player (0 = unlimited)": 3,
  "Allow bounty on yourself": false,
  "Broadcast claim to server": true,
  "Broadcast new bounty to server": true,
  "Use Economics instead of ServerRewards": false,
  "Currency label (RP / $)": "RP",
  "Notify target when bounty is placed on them": true,
  "UI: entries per page": 8,
  "Chat prefix": "<color=#E8472A>[ BOUNTY ]</color> "
}

Full Parameter Reference

Key	Type	Default	Description
Minimum bounty amount	int	50	Lowest amount a player may place as a bounty
Maximum bounty amount	int	10000	Highest single bounty amount allowed
Max active bounties per player (0 = unlimited)	int	3	Caps simultaneous active bounties per placer. Set to 0 to disable the limit
Allow bounty on yourself	bool	false	Whether players can place a bounty on their own Steam ID. Useful for event servers
Broadcast claim to server	bool	true	Posts a server-wide chat message when a bounty is claimed via kill
Broadcast new bounty to server	bool	true	Posts a server-wide chat message when a new bounty is placed
Use Economics instead of ServerRewards	bool	false	Switches the currency backend to the Economics plugin
Currency label (RP / $)	string	"RP"	Label shown in all UI and chat. Change to "$", "coins", "GP", etc.
Notify target when bounty is placed on them	bool	true	Sends a HUD toast notification to the player a bounty is placed on
UI: entries per page	int	8	Bounty rows shown per board page. Recommended range: 4–12
Chat prefix	string	"[ BOUNTY ]"	Prefix before all BountyBoard chat messages. Supports Rust rich-text color tags

Configuration Tips

• Low-pop servers: Set Max active bounties per player to 1 to keep the board clean and competitive.
• High-pop servers (100x+): Set UI: entries per page to 10–12 to reduce pagination flipping.
• Wipe-day economy: Set Minimum bounty amount low (e.g., 10) early wipe, then raise it mid-wipe as RP pools grow.
• VIP rewards: Use Minimum bounty amount as a soft gate — VIPs with larger RP pools naturally dominate the board.

---

6. Permissions

Permission Node	Description
bountyboard.place	Allows the player to use /bounty to place bounties
bountyboard.admin	Allows use of /bountycancel to force-remove bounties and refund placers

ℹ️ /bounties (viewing the board) requires no permission — it is open to all players by default.

Granting Permissions

# Allow all players to place bounties
oxide.grant group default bountyboard.place

# Allow a specific player to place bounties
oxide.grant user STEAMID64 bountyboard.place

# Grant admin rights to your admin group
oxide.grant group admin bountyboard.admin

# Grant admin rights to a specific moderator
oxide.grant user STEAMID64 bountyboard.admin

# Revoke placement rights from a player
oxide.revoke user STEAMID64 bountyboard.place

---

7. Command Reference

Player Commands

Command	Permission	Description
/bounties	None	Toggles the Bounty Board UI open/closed
/bounty <name> <amount>	bountyboard.place	Places a bounty on the named player for the specified amount. Opens a confirmation dialog before deducting funds

/bounty Usage Examples

/bounty Shadowfox 500
/bounty John 1000
/bounty xXSniper 250

Partial name matching is supported. If multiple players match the input, BountyBoard lists them and asks you to be more specific.

Admin Commands

Command	Permission	Description
/bountycancel <name>	bountyboard.admin	Removes all active bounties targeting the named player and refunds the RP/coins to any placers who are currently online

/bountycancel Usage Examples

/bountycancel Shadowfox
/bountycancel toxic

Partial name matching applies. All matching bounties are removed in one command.

Console / RCON Commands

BountyBoard registers several internal console commands used by the CUI buttons. These can also be run directly from RCON or server console for testing:

Console Command	Description
bountyboard.confirm	Confirms a pending bounty placement (triggered by confirm button)
bountyboard.cancel	Cancels a pending bounty placement (triggered by cancel button)
bountyboard.page <n>	Navigates the board to page n (triggered by pagination buttons)
bountyboard.close	Closes the board UI (triggered by ✕ button)

---

8. Player Guide

Placing a Bounty

1. Type /bounty <playername> <amount> in chat.
   • Example: /bounty Shadowfox 500
2. A confirmation modal appears showing the target name and amount.
3. Click CONFIRM to deduct the funds and post the bounty, or CANCEL to abort.
4. The bounty is immediately visible to everyone on the /bounties board.

Rules that apply:

• You must have sufficient RP/coins in your balance before confirming.
• The amount must be within the server's configured min/max range.
• You cannot exceed the server's per-player active bounty limit (if configured).
• You cannot place a bounty on yourself (unless the server allows it).

Viewing the Bounty Board

Type /bounties in chat at any time to open or close the board. The board shows:

• Target name with an online status indicator (green = online, grey = offline)
• Placed by — who posted the bounty
• Reward — amount in RP/coins, highlighted in red
• Age — how long ago the bounty was placed
• Rank badges — top 3 bounties get gold, silver, and bronze rank decorations

Use the PREV and NEXT buttons at the bottom to page through results. Type /bounties again or click the ✕ button to close.

Claiming a Bounty

No command is needed. Simply kill the player who has an active bounty on them. The payout is automatic:

1. You kill a player with one or more active bounties.
2. All bounties on that player are claimed simultaneously.
3. The total pooled reward is deposited into your balance.
4. You receive a chat message and a HUD notification confirming your reward.
5. A server-wide broadcast announces your claim (if enabled by the server).

Receiving a Bounty Notification

If another player places a bounty on you, you will receive a HUD toast notification (if the server has this enabled):

⚡  A 500 RP bounty has been placed on your head!

This notification auto-dismisses after 8 seconds.

---

9. Admin Guide

Force-Removing a Bounty

Use /bountycancel <name> to remove all bounties targeting a specific player. This is useful when:

• A player is being griefed with targeted bounties
• A banned player had bounties posted against them
• Wipe cleanup is needed before the server resets

/bountycancel Shadowfox

Refund behavior: Placers who are online at the time of cancellation are automatically refunded. Placers who are offline are not refunded — this is by design to prevent exploitation via logging off after placing and then requesting removal.

Monitoring Bounty Activity

The bounty data file at /oxide/data/BountyBoard/bounties.json is human-readable JSON. You can inspect it any time to audit active bounties, amounts, timestamps, and Steam IDs.

Adjusting Limits Mid-Wipe

You can change config values mid-wipe without losing existing bounty data:

1. Edit /oxide/config/BountyBoard.json
2. Run oxide.reload BountyBoard in console
3. Changes apply immediately — existing bounties are unaffected

Recommended Admin Permissions Setup

# Standard player access
oxide.grant group default bountyboard.place

# Moderator access
oxide.grant group moderator bountyboard.admin

# VIP group (if you want to give higher limits via other plugins)
oxide.grant group vip bountyboard.place

---

10. UI & UX Layout

Main Bounty Board (/bounties)

┌─────────────────────────────────────────────────────┬──────────┐
│  ☠  BOUNTY BOARD                          ● LIVE   │    ✕    │
├──────────────────────────────────────────────────────┴──────────┤
│  Use /bounty <n> <amount> to place a new bounty  │  12 active · pool: 24,500 RP │
├────────────────────────────────────────────────────────────────┤
│  TARGET            PLACED BY           REWARD       AGE        │
├───┬────────────────────────────────────────────────────────────┤
│ 🥇│ ● Shadowfox     xXSniper_420        [3000 RP]   2h ago    │
│ 🥈│ ● JohnWick99    AdminDave           [2500 RP]   45m ago   │
│ 🥉│ ◌ NightRaider   Toxic_Tim           [2000 RP]   1d ago    │
│  4│ ● CraftKing     Shadowfox           [1500 RP]   3h ago    │
│  5│ ● PVPGod        Griefer99           [1200 RP]   30m ago   │
│  6│ ◌ LootGoblin    RandomPlayer        [800 RP]    5h ago    │
│  7│ ● FarmBot_Real  NewPlayer           [500 RP]    12m ago   │
│  8│ ● QuietSniper   VIPMember           [250 RP]    1d ago    │
├────────────────────────────────────────────────────────────────┤
│  ◀ PREV              Page 1 / 2              NEXT ▶            │
└────────────────────────────────────────────────────────────────┘

• Header bar — red accent with plugin name and live badge
• Stats row — active count and total RP pool at a glance
• Column headers — target, placer, reward, age
• Rank column — gold/silver/bronze for top 3, numbered for the rest
• Online dot — filled green circle for online, hollow grey for offline
• Reward pill — red-tinted pill badge showing RP amount
• Pagination footer — only shown when there are multiple pages

Confirmation Modal

┌──────────────────────────┐
│   CONFIRM BOUNTY          │
│                           │
│  Place a bounty on        │
│    Shadowfox              │
│  for  500 RP ?            │
│                           │
│  [CONFIRM]   [CANCEL]     │
└──────────────────────────┘

HUD Toast Notification

┌────────────────────────────────────┐
│ ⚡  Bounty claimed! +1,500 RP earned│
└────────────────────────────────────┘

• Appears top-center of the screen
• Red left accent bar for visual hierarchy
• Auto-dismisses after 8 seconds
• Safely replaced if a new notification fires before the old one clears

---

11. Performance & Architecture

BountyBoard was engineered from the ground up for high-population servers (50–200+ concurrent players). Here is a complete breakdown of every design decision made for performance:

Hook Usage

Hook	Frequency	Cost
OnPlayerDeath	Once per death	O(n) scan of bounty list — negligible
OnPlayerDisconnected	Once per disconnect	Dictionary removals — microseconds

There are no tick hooks, no OnEntitySpawned, and no frame-level polling. The plugin is entirely event-driven.

Timer Architecture

• The only timers in the plugin are HUD toast dismissal timers — one per player, fired once, then immediately cleaned up.
• All timers are stored in _notifyTimers (a Dictionary<ulong, Timer>).
• Timers are explicitly .Destroy()'d on player disconnect, plugin unload, and whenever a new notification replaces an old one.
• There are zero InvokeRepeating calls anywhere in the codebase.

Memory Management

• Active bounty list is a plain List<BountyEntry> — ~5 fields per entry, kilobytes at any realistic scale.
• CUI containers (CuiElementContainer) are built on demand and released after CuiHelper.AddUi() — no persistent references.
• All player-keyed collections (HashSet<ulong>, Dictionary<ulong, ...>) are cleaned up on disconnect and unload.

Kill Processing Safety

• A _processingKill HashSet<ulong> prevents double-payout if OnPlayerDeath fires multiple times for one death event (an edge case in some Rust versions).
• The debounce flag is removed on NextTick to ensure it doesn't persist across separate death events.

CUI Board Refresh Strategy

• The board is built only when a player opens it or navigates a page.
• On a kill event, if players have the board open, their UIs refresh — but this is bounded by _openUIs.Count (realistically never more than a handful of players at once).

Estimated Server Impact

Category	Impact
Hook overhead	Negligible — 2 hooks, event-driven only
Timer load	Near-zero — short-lived, auto-cleaned
Memory footprint	< 1 MB under any realistic load
CUI server cost	Minimal — rendering is client-side
Risk of FPS drops	Very low — will not appear in profiler output

---

12. Data Storage

File Location

/oxide/data/BountyBoard/bounties.json

Data Structure

{
  "Bounties": [
    {
      "PlacerId": 76561198000000000,
      "PlacerName": "xXSniper_420",
      "TargetId": 76561198111111111,
      "TargetName": "Shadowfox",
      "Amount": 3000,
      "PlacedAt": 1700000000
    }
  ]
}

Field	Type	Description
PlacerId	ulong	Steam64 ID of the player who placed the bounty
PlacerName	string	Display name of the placer at time of placement
TargetId	ulong	Steam64 ID of the bounty target
TargetName	string	Display name of the target at time of placement
Amount	int	RP/coin amount of the bounty
PlacedAt	long	Unix timestamp (UTC) when the bounty was created

Persistence Behavior

• Data is written to disk on every bounty placement, claim, and admin removal.
• Data is also written cleanly on plugin unload.
• Bounties survive server restarts, map wipes (if data folder is preserved), and plugin reloads.
• If you want to clear all bounties on wipe, simply delete bounties.json — the file will be recreated empty on next load.

---

13. Troubleshooting

Plugin fails to load

Symptoms: No load message in console, or a compile error.

Solutions:

• Verify you are running the latest version of Oxide/uMod.
• Check the server console for a specific C# compile error and ensure the .cs file was not corrupted during upload.
• Confirm the file is in /oxide/plugins/ (not a subdirectory).

---

Players can't place bounties

Symptoms: /bounty returns "You don't have permission."

Solution:

oxide.grant group default bountyboard.place

---

Bounty placement fails with "Failed to deduct funds"

Symptoms: Confirmation dialog appears but clicking Confirm does nothing or returns an error.

Solutions:

• Confirm either ServerRewards or Economics is installed and loaded.
• Verify the "Use Economics instead of ServerRewards" config value matches which plugin is installed.
• Check that the economy plugin itself is functioning (test with its native commands).

---

Bounty Board shows as empty even though bounties exist

Symptoms: /bounties opens but shows "No active bounties."

Solution: Check /oxide/data/BountyBoard/bounties.json directly to confirm the data file exists and has entries. If the file is empty or missing, data may have failed to save during a hard server crash. This is a rare edge case — normal restarts and reloads save cleanly.

---

Kill does not pay out the bounty

Symptoms: Player kills the target but receives no reward.

Possible causes:

1. The economy plugin is not loaded or is malfunctioning — test AddPoints/Deposit manually.
2. The kill was processed before the plugin fully loaded (very rare on startup).
3. The bounty was already claimed by another player a split second earlier (first kill wins).

---

Notification toasts are not appearing

Symptoms: No HUD popup on bounty claim or placement.

Solutions:

• Confirm "Notify target when bounty is placed on them": true is set in config.
• Toast notifications do not appear if the player has the board open — this is intentional to avoid layering.

---

/bountycancel does not refund the placer

Expected behavior: Placers are only refunded if they are online at the time of cancellation. Offline players are not refunded. This is intentional anti-exploit behavior.

---

14. FAQ

Q: Do bounties expire over time? A: No. Bounties persist indefinitely until claimed via a kill or removed by an admin. If you want time-limited bounties, consider wipe-day data resets.

---

Q: What happens if the target disconnects after a bounty is placed on them? A: The bounty remains active. If the target reconnects and is killed, the claim processes normally. The board shows an offline indicator (grey dot) for disconnected targets.

---

Q: Can multiple players place bounties on the same target? A: Yes. All bounties on a target stack. The player who kills the target claims the combined total of all active bounties on that player in a single payout.

---

Q: What happens to the bounty money if the target is never killed? A: The funds remain locked in the bounty pool until the target is killed or an admin runs /bountycancel. Placers do not get refunds unless an admin intervenes.

---

Q: Can the same player place multiple bounties on the same target? A: Yes, within their per-player active bounty limit. Each /bounty command creates a separate entry.

---

Q: What if a player kills themselves (suicide, fall damage)? A: Self-kills do not trigger a bounty payout. The OnPlayerDeath hook checks that the killer is a different player before processing.

---

Q: Does BountyBoard work with custom death plugins or PVE modes? A: BountyBoard uses the standard OnPlayerDeath hook. If your PVE plugin or death plugin suppresses this hook, bounty claims may not fire. Test in a controlled environment.

---

Q: Can I run BountyBoard alongside other economy plugins? A: Yes. BountyBoard only calls the specific plugin configured in its settings. Other economy plugins on the server are not affected.

---

Q: Is bounty data lost on a wipe? A: Only if you manually delete the data file or your server host wipes the /oxide/data/ folder. If you want a clean slate each wipe, delete bounties.json after wiping.

---

Q: Can I see who claimed a bounty after the fact? A: Once claimed, the bounty entry is removed from the data file. Broadcast messages (if enabled) are the only real-time record. For audit logging, consider a companion logging plugin that captures chat broadcasts.

---

15. Changelog

v2.0.0 — Current Release

• Full rewrite with modern dark CUI board UI
• Added two-step confirmation modal for bounty placement
• Added HUD toast notification system with safe timer management
• Added online/offline status dots for targets
• Added gold/silver/bronze rank badges for top 3 bounties
• Added reward pooling (multiple bounties on one target, single payout)
• Added pagination with configurable entries per page
• Added _processingKill debounce guard to prevent double-payouts
• Added full cleanup on OnPlayerDisconnected and Unload()
• Added bountyboard.admin permission and /bountycancel command
• Added online refund for admin-cancelled bounties
• Added Age column showing how old each bounty is
• Added live total pool and active count to board header
• Switched to event-driven-only architecture (no InvokeRepeating)
• Full ServerRewards and Economics dual backend support

---

Documentation for BountyBoard v2.0.0 — maintained by OhShit100x