Custom Rewards

CustomRewards 2.0.4 — user guide

This guide covers the Codefling version 2.0.4. PimpMyCUI editing belongs to the separate 2.2.0 beta, not this version.

CustomRewards is a reusable reward and UI engine for Rust servers running Oxide or Carbon. Version 2.0.4 includes safe player reattachment after an offline wipe preload. The earlier 2.0.3 build passed its approved live reward UI and claim smoke tests on Rust build 2631 with Oxide; 2.0.4 has not received a new live smoke. Carbon remains compile-validated only.

Installation

Install the generated deploy/CustomRewards.cs file in the framework plugin directory. Do not install files from src/ individually. Keep a backup of oxide/data/CustomRewards_* before upgrading.

Reward types

Each JSON file under oxide/data/CustomRewards_rewards/ defines one reward type. The file name is the exact reward type used by API calls and its dynamic use permission is CustomRewards.<Type>.Use. New templates are disabled by default until an administrator reviews item names, commands, permission changes, group changes, eligibility rules, image URLs, and UI commands.

The web configurator exports one reward type. Rename its generic reward-type.json download to the intended type, for example Starter.json, then install it as oxide/data/CustomRewards_rewards/Starter.json. Keep that exact type name in integrations and grant customrewards.starter.use to the appropriate group. Do not put this catalogue in oxide/config/.

Missing theme colors, rarity colors, and UI asset URLs are filled with safe defaults when a reward-type file is loaded. The exact known legacy Postimg URLs are migrated to hosted direct links whose content is verified against the source-controlled project assets; non-empty custom URLs are preserved. The neutral reward frame is tinted by the configured rarity color at runtime and has a transparent center.

Only %steamid% is accepted in server commands. Unknown placeholders and control characters are rejected. Reward configuration is privileged code and must remain administrator-controlled.

An enabled reward type must contain at least one fully valid, executable reward. Empty catalogues, malformed actions, permission grants without a plugin owner, and actions that revoke a required eligibility gate or grant a forbidden gate are rejected once at startup before commands or UI are registered.

Commands and permissions

• Reward-type show commands are configured per template and require CustomRewards.<Type>.Use, unless the player is an administrator.
• customrewards_give <type> <player> <quantity> requires CustomRewards.Admin.
• customrewards_wipe_owner <type> <owner> requires CustomRewards.Admin.
• customrewards_wipe_all <type> requires CustomRewards.Admin.
• Player console commands for paging and claims validate every argument and recheck eligibility on the server.

Upgrade and recovery

Legacy unversioned player files are migrated forward to data version 2 only after validation. Invalid JSON, unsupported versions, negative points, duplicate reward IDs, out-of-range IDs, or overlap between claimed and unclaimed rewards fail closed and require administrator repair from backup.

A claim writes intent before privileged delivery and records action progress durably. Completed actions are not replayed. An action with uncertain external outcome is held for manual reconciliation; the plugin does not claim cross-API transactional delivery.

A definite partial failure resumes the immutable plan authorized on the first attempt, even if an earlier completed action changed a permission or group. Completed journal records are compacted only after the matching entitlement removal is durably saved; retryable, in-flight, reconciliation, active-entitlement, and replay-protection evidence remains fail-closed.

API and CUI composition

Contract version 2, the existing capabilities, and ShowUI_API remain compatible. Capability reward-type-ui-open-v1 adds:

• GetRewardTypeStatus_API(string rewardType), returning enabled, disabled, or unknown;
• TryShowUI_API(string rewardType, ulong playerId, string parent), returning a dictionary with success, code, rewardType, known, and enabled.

parent is a parent layer, never an element ID. The accepted always-present layers are Overall, Overlay, OverlayNonScaled, Hud.Menu, Hud, Under, and UnderNonScaled; null selects Overlay. Each UI root is uniquely scoped to the reward type and player. Invalid parents fail closed without destroying unrelated CUI.

Limitations

Approved-assembly compilation is not a live-server test. UI layout, inventory delivery behavior, command effects, dynamic plugin lookup for permission grants, reload behavior, and Oxide/Carbon runtime parity still require the deferred in-game smoke matrix.

First-run checklist

1. Back up oxide/data/CustomRewards_*.
2. Install only CustomRewards.cs.
3. Create one disabled reward type with a single low-value item.
4. Reload and correct every startup validation error.
5. Grant customrewards.<type>.use to a test group.
6. Enable the type and test its show command, paging, insufficient-points state, successful claim, and reconnect behavior.
7. Add privileged commands, permission changes, or group changes only after the item-only path succeeds.

Configuration example

{
  "Enabled": false,
  "Commands for show UI": ["starter_rewards"],
  "UI Settings": {
    "Max Reward By Page": 5,
    "Show Description": true
  },
  "Rewards Settings": {
    "Rewards List": [
      {
        "Rarity (Common - Rare - Epic - Legendary)": "Common",
        "Quantity": 100,
        "Item Shortname (optional)": "wood",
        "Server command (optional)": [],
        "Grant Permissions :": [],
        "Grant Groups :": {},
        "Needed Permissions :": {},
        "Needed Groups :": {}
      }
    ]
  }
}

Keep the type disabled while reviewing it. Reward files are privileged configuration because they can execute server commands and change access.

Troubleshooting and FAQ

• If a show command is missing, confirm the type loaded successfully, is enabled, and does not reuse another registered command.
• If the UI denies access, grant customrewards.<type>.use; the historical mixed-case permission remains accepted for existing installations.
• If a catalogue is rejected, fix the first reported invalid reward or contradictory eligibility action rather than editing player state.
• If a claim requires reconciliation, inspect the administrator diagnostic and the external action before retrying.
• Custom Rewards does not require Vote System. It can be used by any integration that follows the documented compatibility contract.