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.
• 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

* Viewing another player's spell pool requires admin.

Admin Commands

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

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.

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.

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.

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

Querying the pool:

// 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);

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.