Title Perks 1.0.0

Quote

Turn your achievement titles into real gameplay rewards. TitlePerks automatically applies combat, gathering, fishing, and cooldown bonuses when players select titles in Title Selector — no commands, no extra steps.

 

- Requires Title Selector

Overview

TitlePerks is a companion plugin for Title Selector that brings your title system to life. Instead of titles being purely cosmetic, each title can grant configurable gameplay perks that activate instantly when equipped and deactivate when removed.

Players earn titles through gameplay achievements (raids, heli kills, boss kills, etc.) and those titles now carry real mechanical weight — creating a meaningful progression loop where effort translates into tangible power.

Key Features

Automatic Activation & Deactivation

• Perks activate instantly when a title is selected in Title Selector
• Perks deactivate instantly when a title is removed, hidden, or cleared
• Full integration with Title Selector's Hide All, Show All, Clear, and Preset systems
• Perks auto-restore on player reconnect and server restart

15+ Perk Types

Perk Stacking

Players can equip multiple titles simultaneously, and their perks stack additively. For example:

• Title "RaidHard" grants +15% structure damage
• Title "RaidExpert" grants +20% structure damage
• Combined: +35% structure damage

Smart Entity Detection

The damage system correctly identifies and categorizes all entity types:

• Structures: BuildingBlock (walls, foundations, floors, etc.)
• Deployables: Doors, storage containers, turrets, barricades, traps, sleeping bags, SAM sites, search lights, ovens
• NPCs: Scientists, murderers, scarecrows, tunnel dwellers, underwater dwellers, zombies, HumanNPC
• Vehicles: Patrol Helicopter, Bradley APC, CH47 Chinook
• Animals: All BaseAnimalNPC entities
• Players: Real Steam-authenticated players (for PvP perk)

External Integrations

• PveMode: Automatically sets/removes player cooldown modifiers via API_SetPlayerCooldownModifier / API_RemovePlayerCooldownModifier
• Permission Groups: Configurable perk-to-group mapping — when a player activates a perk, they're added to a permission group; when deactivated, they're removed

How It Works

Player selects title in Title Selector
        |
        v
TitlePerks checks config for matching perks
        |
        v
Perks activated
        |
        v
Game apply bonuses in real-time

Lifecycle Events

Default Configuration

{
  "TitlePerks": {
    "raideasy":       [{ "Type": "damage_structure", "Value": 0.05 }, { "Type": "damage_deployable", "Value": 0.05 }],
    "raidmedium":     [{ "Type": "damage_structure", "Value": 0.10 }, { "Type": "damage_deployable", "Value": 0.10 }],
    "raidhard":       [{ "Type": "damage_structure", "Value": 0.15 }, { "Type": "damage_deployable", "Value": 0.15 }],
    "raidexpert":     [{ "Type": "damage_structure", "Value": 0.20 }, { "Type": "damage_deployable", "Value": 0.20 }],
    "raidnightmare":  [{ "Type": "damage_structure", "Value": 0.25 }, { "Type": "damage_deployable", "Value": 0.25 }],
    "helieasy":       [{ "Type": "damage_heli", "Value": 0.05 }],
    "helimedium":     [{ "Type": "damage_heli", "Value": 0.10 }],
    "helihard":       [{ "Type": "damage_heli", "Value": 0.15 }],
    "heliexpert":     [{ "Type": "damage_heli", "Value": 0.20 }],
    "helielite":      [{ "Type": "damage_heli", "Value": 0.25 }],
    "helinightmare":  [{ "Type": "damage_heli", "Value": 0.30 }],
    "bradleyeasy":    [{ "Type": "damage_bradley", "Value": 0.05 }],
    "bradleymedium":  [{ "Type": "damage_bradley", "Value": 0.10 }],
    "bradleyhard":    [{ "Type": "damage_bradley", "Value": 0.15 }],
    "bradleyexpert":  [{ "Type": "damage_bradley", "Value": 0.20 }],
    "bradleynightmare": [{ "Type": "damage_bradley", "Value": 0.25 }],
    "bosskiller":     [{ "Type": "damage_boss", "Value": 0.15 }],
    "npcslayer":      [{ "Type": "damage_npc", "Value": 0.15 }],
    "wildhunter":     [{ "Type": "damage_animal", "Value": 0.15 }, { "Type": "gather_animal", "Value": 0.20 }],
    "rareminer":      [{ "Type": "gather_ore", "Value": 0.20 }],
    "fisherman":      [{ "Type": "xp_fishing", "Value": 0.25 }, { "Type": "fishing_rate", "Value": 0.15 }],
    "farmer":         [{ "Type": "gather_plant", "Value": 0.25 }],
    "explorer":       [{ "Type": "cooldown_event", "Value": -0.20 }, { "Type": "legendary_bonus_xp", "Value": 0.25 }],
    "tryhard":        [{ "Type": "damage_pve", "Value": 0.10 }, { "Type": "damage_pvp", "Value": 0.05 }]
  },
  "Show perk activation messages": true,
  "Show perk deactivation messages": true,
  "Group Perks (perk type -> permission group)": {
    "legendary_bonus_xp": "legendarybonus"
  },
  "Debug mode": false
}

Configuration Options

Adding Custom Perks

Simply add new entries to the TitlePerks dictionary. Title names must be lowercase and match the title names configured in Title Selector.

"pvpchampion": [
  { "Type": "damage_pvp", "Value": 0.15 },
  { "Type": "damage_global", "Value": 0.05 }
],
"lumberjack": [
  { "Type": "gather_wood", "Value": 0.30 }
]

Each title supports multiple perks — combine damage, gather, and special bonuses in a single title.

Commands

/perks Output Example

======== Your Active Perks ========
Damage Bonuses:
  - Structure Damage: +15%
  - Deployable Damage: +15%
  - Helicopter Damage: +10%

Gather Bonuses:
  - Ore Gather: +20%

Active Titles:
  - raidhard
  - helimedium
  - rareminer

Permissions

Title Selector Integration

TitlePerks is designed as a seamless extension of Title Selector. The integration is fully automatic through Oxide/Carbon hooks:

Hooks Listened

Developer API

TitlePerks exposes a complete API for other plugins to query perk data:

// Get all active perks for a player (type -> total value)
Dictionary<string, float> perks = TitlePerks.Call<Dictionary<string, float>>("API_GetActivePerks", (ulong)player.userID);

// Get a specific perk value (returns 0f if not active)
float heliDmg = TitlePerks.Call<float>("API_GetPerkValue", (ulong)player.userID, "damage_heli");

// Check if player has a specific perk active
bool hasPerk = TitlePerks.Call<bool>("API_HasPerk", (ulong)player.userID, "damage_bradley");

// Get list of active title names for a player
List<string> titles = TitlePerks.Call<List<string>>("API_GetActiveTitles", (ulong)player.userID);

// Get perk definitions for a title (config lookup)
var perks = TitlePerks.Call<List<Dictionary<string, object>>>("API_GetTitlePerks", "raidhard");

// Get formatted perk display string for a title (for UI integration)
string display = TitlePerks.Call<string>("API_GetTitlePerksDisplay", "raidhard");
// Returns: "Struct+15% Deploy+15%"

Use Cases

1. Raid Progression Rewards

Players who complete raid milestones (easy through nightmare) receive scaling damage bonuses to structures and deployables, making them more effective raiders.

2. PvE Combat Specialization

Titles like "BossKiller", "NPCSlayer", and "WildHunter" reward players who focus on PvE content with relevant damage bonuses, encouraging engagement with PvE systems.

3. Resource Gathering Bonuses

"RareMiner", "Farmer", and "WildHunter" titles provide gathering multipliers, creating an alternative progression path for players who prefer resource-focused gameplay.

4. Event Cooldown Reduction

The "Explorer" title reduces event cooldowns by 20% via PveMode integration, rewarding active event participants with faster re-entry.

5. Permission-Based Rewards

Through the Group Perks system, titles can grant access to permission groups — enabling integration with any permission-based plugin. Example: "Explorer" title adds players to the "legendarybonus" group for bonus XP.

6. PvP vs PvE Balancing

The "Tryhard" title demonstrates dual-category bonuses: +10% PvE damage and +5% PvP damage, allowing fine-tuned balance between gameplay modes.

7. Multi-Title Stacking Strategy

Since perks stack, players must strategize which titles to equip based on their planned activities — raiding, farming, fishing, or mixed gameplay.

Localization

Built-in support for 3 languages out of the box:

All perk names, categories, activation/deactivation messages, and UI labels are fully translatable through the standard lang system.

Requirements

Installation

1. Place TitlePerks.cs in your carbon/plugins/ folder
2. Ensure Title Selector is installed and running
3. Restart or load the plugin
4. Edit carbon/configs/TitlePerks.json to match your title names
5. Run titleperks.reload in console to apply changes

Data Storage

Player perk data is stored in carbon/data/TitlePerks.json:

{
  "Players": {
    "76561198000000000": {
      "active_titles": ["raidhard", "helimedium", "rareminer"],
      "last_update": "2026-03-03T12:00:00.0000000Z"
    }
  }
}

Data is used for restoration on reconnect and cleaned automatically after 30 days of inactivity.