CustomAbilities

This is the repository for CustomAbilities, coded by Fryke (fryke) on Discord.

CustomAbilities is a V Rising dedicated server mod that allows server admins to assign custom abilities to players and items. Override any ability slot on any weapon category, apply abilities directly to specific items, and provide a public API for other mods to integrate with.

Features

• Player Ability Assignment - Set any ability on any slot (Attack, Q, E, Dash, Spell 1, Spell 2, Ultimate) for any weapon category.
• Item Ability Assignment - Apply abilities directly to specific weapons/items. Item abilities override category-level abilities.
• Quick Set Commands - Players can set their currently equipped R/C spell to Q/E with a single command.
• Spell Pool System - External mods register spell providers to define which spells a player has access to. Player spell assignment is gated by the pool; admin assignment bypasses it. Spells support user-friendly aliases and per-spell allowed/restricted slots, with fuzzy name matching on assign.
• Ability Presets - Players can save, load, list, and delete named presets capturing all weapon categories plus vanilla R/C/T/Dash baseline. Loading restores both custom slots and baseline spells.
• Banned Combination Notifications - Server-defined ability combos trigger a one-time system message when a player has the full combo equipped. Notify only, never blocks.
• Form Ability Overrides - API for other mods to supply custom ability arrays for shapeshift forms.
• Special Case Handlers - API for other mods to modify ability slots at runtime based on tags, buffs, or state.
• Jewelable Ability Blocking - Prevents jewelable abilities (spell school abilities) from being assigned to items, protecting against a known engine bug that can delete jewels and corrupt inventory data.
• Ability Merge Priority - Item abilities > category abilities > default, with a clear merge chain.
• Persistent Data - All player and item ability data saved to local JSON files and survives server restarts.

Commands

All commands use the .abilities prefix (shorthand: .ab).

Player Commands

Preset Commands

Admin Commands

Slot IDs: 0 = Attack, 1 = Q, 2 = E, 3 = Dash, 4 = Spell 1, 5 = Spell 2, 6 = Ultimate

Slots also accept friendly names: primary/attack, q/secondary, e/power, dash/travel, r/spell1/offensive, c/spell2/defensive, t/ultimate/ult. Examples: .ab as q 123456, .ab spa r Shadowbolt.

Weapon categories: All, Unarmed, Axe, Claws, Crossbow, Daggers, FishingPole, GreatSword, Longbow, Mace, Pistols, Reaper, Slashers, Spear, Sword, TwinBlades, Whip. Passing All as the weapon category applies the change across all categories.

Notes:

• FishingPole is a standalone category. Quick set/clear (set primary, set secondary, etc.) targets Unarmed only.
• Self-serve .abilities spell assign on slots 0-2 (Attack/Q/E) applies to Unarmed. Slots 3-6 apply across all weapon categories.

Configuration

Config is stored in BepInEx/config/io.vrising.CustomAbilities.cfg.

Data Storage

Data persists through server restarts and is saved automatically every 30 seconds.

Presets are stored inside the player data file per player, alongside ability slot definitions.

Installation

1. Install BepInEx and VampireCommandFramework on your V Rising dedicated server.
2. Place CustomAbilities.dll in your BepInEx/plugins/ directory.
3. Start the server, the mod will generate its config file automatically.
4. Configure settings in BepInEx/config/io.vrising.CustomAbilities.cfg.

API for Mod Developers

CustomAbilities provides a public API for other mods. Reference CustomAbilities.dll and add [BepInDependency("io.vrising.CustomAbilities")] to your Plugin class.

Registering Form Ability Overrides

Supply custom ability arrays for shapeshift forms. First non-null result wins.

CustomAbilities.AbilityAPI.RegisterFormAbilityOverride((playerEntity, formBuffGuid) =>
{
    if (formBuffGuid.Equals(MyFormBuff))
        return new int[8] { 0, 0, 0, 0, myAbility, 0, 0, 0 };
    return null;
});

Registering Special Case Handlers

Modify ability slots at runtime (e.g., based on tags or buffs).

CustomAbilities.AbilityAPI.RegisterSpecialCaseHandler((playerEntity, weaponEquipBuff, slots) =>
{
    if (MyTagSystem.HasTag(playerEntity, "empowered"))
        slots[4] = myEmpoweredAbility;
    return slots;
});

Refreshing Abilities

Force an ability refresh after external changes.

CustomAbilities.AbilityAPI.RefreshEquipBuff(playerEntity);

Registering Spell Pool Providers

Contribute spells to a player's available spell pool. The spell pool gates which spells players can self-assign via .abilities spell assign. Multiple providers are aggregated and deduplicated.

Legacy provider (GUID list):

CustomAbilities.AbilityAPI.RegisterSpellPoolProvider(playerEntity =>
{
    return new List<int> { mySpellGuid1, mySpellGuid2 };
});

Rich provider (alias plus per-spell slot gating):

CustomAbilities.AbilityAPI.RegisterSpellPoolProvider(playerEntity =>
{
    return new List<CustomAbilities.AbilityAPI.SpellPoolEntry>
    {
        new() { PrefabGuid = mySpellGuid1, Alias = "Shadowbolt", AllowedSlots = new[] { 1, 2 } },
        new() { PrefabGuid = mySpellGuid2, RestrictedSlots = new[] { 6 } }
    };
});

Querying the pool:

// Get all available spell entries for a player
List<CustomAbilities.AbilityAPI.SpellPoolEntry> entries = CustomAbilities.AbilityAPI.GetAvailableSpellEntries(playerEntity);

// Get all available spells for a player
List<int> spells = CustomAbilities.AbilityAPI.GetAvailableSpells(playerEntity);

// Check if a specific spell is available
bool hasSpell = CustomAbilities.AbilityAPI.HasAvailableSpell(playerEntity, spellPrefabGuid);

// Resolve a GUID, name, alias, or fuzzy match to a GUID
int? guid = CustomAbilities.AbilityAPI.ResolveSpellIdentifier(playerEntity, "Shadowbolt");

Presets and Item Queries

// Presets
CustomAbilities.AbilityAPI.SavePreset(playerEntity, "pvp");
CustomAbilities.AbilityAPI.LoadPreset(playerEntity, "pvp");
CustomAbilities.AbilityAPI.DeletePreset(playerEntity, "pvp");
var presets = CustomAbilities.AbilityAPI.GetPresets(playerEntity);

// Item abilities
int guid = CustomAbilities.AbilityAPI.GetItemAbility(itemEntity, AbilityTypeEnum.Secondary);
int[] all = CustomAbilities.AbilityAPI.GetAllItemAbilities(itemEntity);

Changelog

1.1.0

• Added ability presets: .abilities preset save/load/list/delete with vanilla baseline restore and optional combat block.
• Added banned combination notifications via BannedAbilityCombinations config.
• Added SpellAssign.AllowedSlots config plus per-spell AllowedSlots/RestrictedSlots and alias support in the spell pool API.
• Spell assign accepts GUID, exact name, alias, or fuzzy match. Spell and preset lists are paged.
• Commands accept friendly slot names (q, e, dash, r, c, t, etc.) in addition to slot IDs.
• Separated FishingPole from Unarmed. Quick set/clear targets Unarmed only.
• Performance: cached PrefabGUID name lookups, cached reusable entity queries with proper disposal, edge-driven stale weapon cleanup, deduped ability buffer writes, and reduced per-frame allocations.

Compatibility with Bloodcraft

Bloodcraft is another V Rising server mod that provides ability slot customization. Both mods patch the same ReplaceAbilityOnSlotSystem to apply ability changes.

How they interact:

• Both mods run as Harmony prefixes on the same system, so both execute on every weapon equip buff update.
• CustomAbilities applies abilities with a priority of 1 (or 9 for form overrides), while Bloodcraft applies with priority 0. Higher priority values take effect, so CustomAbilities assignments override Bloodcraft's when they target the same slot.
• Bloodcraft supports assigning abilities to the unarmed/fishing pole Q and E slots, plus a class spell (dash slot). CustomAbilities supports all 8 ability slots across all weapon categories and individual items.
• The mods do not break each other. If both are installed, Bloodcraft's unarmed slot assignments will still apply to any slots that CustomAbilities hasn't configured.

Recommendation: If you use both mods, assign abilities through CustomAbilities for full control. Bloodcraft's unarmed slot assignments will be automatically superseded where CustomAbilities has a slot configured.

Known Engine Issues and Safeguards

CustomAbilities has safeguards around jewelable abilities (abilities that can have jewels socketed into them) and abilities with recast mechanics. These protections exist because of a known engine-level bug in V Rising:

When a jewelable ability is assigned directly to an item, weapon swapping can cause the jewel on that ability to be deleted and can create a duplicate inventory slot entry for the weapon. This can potentially lead to data corruption. As a precaution, the BlockJewelableAbilitiesOnItems config option (enabled by default) prevents jewelable abilities from being assigned to items entirely.

Additionally, if a player assigns a recastable ability to their unarmed Q or E slot and weapon swaps in the middle of a recast, the jewel on that ability can disappear. This is why the mod warns players when they assign a recastable ability to those slots. These are engine-level issues that the mod cannot fix, so the safeguards are in place to protect player data.

Attribution

This project is licensed under AGPL-3.0.

Portions of code and design patterns in this project were inspired by or adapted from the following projects:

• KindredCommands https://github.com/odjit/KindredCommands Licensed under AGPL-3.0
• Bloodcraft https://github.com/mfoltz/Bloodcraft Licensed under CC BY-NC 4.0

This is an independent project with its own purpose and functionality. It is not a fork, modification, or derivative of any of the above projects. Some utility code and patterns were referenced during development.