VampireCommandFramework

VampireCommandFramework

A comprehensive framework for V Rising mod developers to easily build commands with advanced features like command overloading, history, smart matching, and plugin-specific execution.

Usage

For Server Operators

This plugin should be installed into the BepInEx/plugins folder and be kept up to date. It is required by other plugins for commands.

For Plugin Developers

How to use

1. Add a reference to the plugin

dotnet add package VRising.VampireCommandFramework

2. Add the plugin as a dependency by setting this attribute on your plugin class

[BepInDependency("gg.deca.VampireCommandFramework")]

3. Register your plugin when you're done loading:

CommandRegistry.RegisterAll()

4. Write commands

[Command("foo")]
public void Foo(ICommandContext ctx, int count, string orValues = "with defaults", float someFloat = 3f) 
    => ctx.Reply($"You'd do stuff here with your parsed {count} and stuff");

This command would execute for:

• .foo 5
• .foo 5 works
• .foo 5 "or really fancy" 3.145

But if you typed .foo 5.123 you'd see a generated usage message like:

### This simple example provides
- **Automatic help listings** - your command appears in `.help`
- **Parameter parsing** - `count`, `orValues`, and `someFloat` are automatically converted
- **Usage text generation** - help shows `(count) [orValues="with defaults"] [someFloat=3]`
- **Default parameter handling** - optional parameters work seamlessly
- **Type conversion** - strings become integers, floats, etc.

### More Examples

The framework handles these additional command patterns:

**Command with parameters:**

[Command("give")] public void GiveItem(ICommandContext ctx, string item, int count = 1) => ctx.Reply($"Gave {count} {item}");

- Executes with: `.give sword`, `.give sword 5`

**Command groups:**

[CommandGroup("admin")] public class AdminCommands { [Command("ban")] public void Ban(ICommandContext ctx, string player) => ctx.Reply($"Banned {player}"); }

- Executes with: `.admin ban PlayerName`

## Remainder Parameters
For commands that take free-form text (a message, a reason, a timezone ID), mark the final `string` parameter with `[Remainder]` to capture everything the user typed after the preceding arguments, with spacing and quotes preserved.

[Command("say")] public void Say(ICommandContext ctx, string channel, [Remainder] string message) => ctx.Reply($"[{channel}] {message}");

- `.say global hello everyone` → `channel = "global"`, `message = "hello everyone"`
- `.say global "hello, friends!"` → `message = "\"hello, friends!\""` (quotes kept as typed)

**Rules:**
- Must be the **last** parameter. Violations are rejected at registration time.
- Must be of type `string`.
- Captures the rest of the raw input verbatim, including quotes, whitespace, and special characters.
- Can be optional with a default value: `[Remainder] string reason = null`.
- Parameters before the remainder are parsed normally: type conversion, defaults, and custom converters all still apply.
- Composes with overloading: the framework picks a remainder variant when enough preceding arguments are present.

Auto-generated `.help` output renders a remainder parameter as ``, distinct from `(name)` for required and `[name=default]` for optional, so users get a visual cue for free, unless you supply a manual `usage:` string on `[Command]`.

## Command Overloading
You can now create multiple commands with the same name but different parameter types:

[Command("teleport")] public void TeleportToPlayer(ICommandContext ctx, string playerName) => ctx.Reply($"Teleporting to {playerName}");

[Command("teleport")] public void TeleportToCoords(ICommandContext ctx, float x, float y) => ctx.Reply($"Teleporting to {x}, {y}");

When there's ambiguity, players will be presented with options and can select using `.1`, `.2`, etc.

## Middleware

All commands execute through a middleware pipeline. You can add your own middleware by implementing `ICommandMiddleware` and adding it to the `CommandRegistry.Middlewares` list. 

Middleware is perfect for implementing permissions and roles, cooldowns, logging, command costs, rate limiting, and other cross-cutting concerns that should apply across commands even from other VCF plugins.

 [V Roles](https://github.com/Odjit/VRoles) is an example of a Middleware plugin for VCF that adds in roles that commands and users can get assigned.

Example middleware:

public class CooldownMiddleware : CommandMiddleware { public override bool CanExecute(ICommandContext ctx, CommandAttribute cmd, MethodInfo method) { // Your cooldown logic here return !IsOnCooldown(ctx.Name, cmd.Name); } }

## Response and Formatting Utilities

The framework includes rich formatting utilities for enhanced chat responses:

// Text formatting ctx.Reply($"{"Important".Bold()} message with {"emphasis".Italic()}"); ctx.Reply($"{"Warning".Underline()} - please read carefully");

// Colors (using predefined color constants) ctx.Reply($"{"Error".Color(Color.Red)} - something went wrong"); ctx.Reply($"{"Success".Color(Color.Green)} - command completed"); ctx.Reply($"{"Info".Color(Color.LightBlue)} message");

// Text sizing ctx.Reply($"{"Large Header".Large()} with {"small details".Small()}");

// Combining formatting ctx.Reply($"{"Critical".Bold().Color(Color.Red).Large()} system alert!");

// Paginated replies for long content var longText = "Very long text that might exceed chat limits..."; ctx.SysPagin