View source for Grimwar/VMod

{{GameNav}}
{{Notice|title=Version target|This guide covers VMod API 5 and addon schema 9. A server rejects packages built for another API or schema.}}

'''VMod''' is Grimwar's server-authoritative C# mod runtime. The server compiles source with Roslyn C# 2.0 and runs the result through dotnow. Grimwar itself remains an IL2CPP build.

A VMod can use the public <code>Grimwar.ModApi</code> services. It cannot reference Unity, FishNet, Grimwar internals, arbitrary files, sockets, reflection, processes, or native code.

== What a VMod package contains ==

The addon folder is the install unit.

<syntaxhighlight lang="text">
community.hello/
  addon.json
  mod.json
  HelloMod.csx
</syntaxhighlight>

Use <code>.csx</code> below a Unity project's <code>Assets</code> folder so the editor recognizes C# without asking Unity to compile the file. A VMod kept outside Unity can use <code>.cs</code>.

<code>addon.json</code> registers the folder with Grimwar's addon catalog:

<syntaxhighlight lang="json">
{
  "schemaVersion": 9,
  "id": "community.hello",
  "title": "Hello Server",
  "author": "Ada",
  "version": "1.0.0",
  "distributionProfile": "development",
  "buildId": "0123456789abcdef0123456789abcdef",
  "createdUtc": "2026-08-25T00:00:00Z",
  "sdkVersion": "1.0.3",
  "unityVersion": "6000.3.17f1",
  "requires": [],
  "contents": [
    {
      "kind": "mods",
      "id": "community.hello",
      "title": "Hello Server",
      "mod": { "manifest": "mod.json" }
    }
  ]
}
</syntaxhighlight>

The addon ID, content ID, and VMod ID must resolve to the same normalized ID. <code>requires</code> contains addon IDs. Grimwar enables and loads required addons before the package that names them.

<code>mod.json</code> defines the code entry point:

<syntaxhighlight lang="json">
{
  "id": "community.hello",
  "name": "Hello Server",
  "version": "1.0.0",
  "apiVersion": 5,
  "kind": "addon",
  "entryPoint": "CommunityMods.HelloMod",
  "sourceFiles": ["HelloMod.csx"],
  "dependencies": [],
  "permissions": [],
  "enabled": true,
  "serverOnly": true
}
</syntaxhighlight>

{| class="wikitable"
! Field !! Rule
|-
| <code>id</code> || Stable ID up to 96 characters. Use lowercase letters, digits, dots, underscores, and hyphens.
|-
| <code>apiVersion</code> || Must equal the server's current VMod API, currently <code>5</code>.
|-
| <code>kind</code> || <code>addon</code>, <code>admin</code>, or <code>gameMode</code>. Administrative host operations require <code>admin</code>.
|-
| <code>entryPoint</code> || Fully qualified, non-abstract class implementing <code>IMod</code>.
|-
| <code>sourceFiles</code> || Relative <code>.cs</code> or <code>.csx</code> paths contained by this addon.
|-
| <code>dependencies</code> || VMod IDs that must load first.
|-
| <code>permissions</code> || Permission names the VMod may attach to its commands and menu items. This does not grant those permissions to players.
|-
| <code>serverOnly</code> || Must be <code>true</code> in API 5.
|}

== Write the entry class ==

This mod registers <code>hello</code> for chat and authenticated consoles:

<syntaxhighlight lang="csharp">
using System;
using Grimwar.ModApi;

namespace CommunityMods
{
    public sealed class HelloMod : IMod
    {
        private IModContext _context;

        public void OnLoad(IModContext context)
        {
            _context = context;
            var result = context.Commands.Register(new ModCommandSpec
            {
                Name = "hello",
                Description = "Say hello to the server.",
                MinimumArguments = 0,
                MaximumArguments = 0,
                AllowChat = true,
                AllowConsole = true,
                ChatAliases = new[] { "hi" }
            }, "OnHello");

            if (!result.Success)
                throw new InvalidOperationException(result.Message);

            context.Log.Write("Hello Server loaded.");
        }

        public void OnUnload()
        {
            _context = null;
        }

        public void OnHello(IModCommandInvocation command)
        {
            var name = command.Caller == null
                ? "server console"
                : command.Caller.DisplayName;
            _context.Messages.Broadcast("Hello from " + name + "!");
        }
    }
}
</syntaxhighlight>

Registrations take a method name because delegates do not cross the interpreter boundary. Grimwar verifies the method before accepting the registration.

{| class="wikitable"
! Registration !! Handler signature
|-
| Command || One <code>IModCommandInvocation</code> parameter
|-
| Event || One <code>ModEvent</code> parameter
|-
| Timer || One <code>ModTimerInvocation</code> parameter
|-
| VSig subscription || One <code>ModVSigEvent</code> parameter
|-
| Menu || One <code>ModMenuInvocation</code> parameter
|}

<code>OnUnload</code> must clear references and release any VMod-owned state that is not already scoped through the host. Commands, event subscriptions, timers, effects, and dynamic modes are removed when the package unloads.

== Public API services ==

<code>IModContext</code> supplies the following services:

{| class="wikitable"
! Service !! Use
|-
| <code>Log</code> || Namespaced server log messages.
|-
| <code>Commands</code> || Chat, local console, server console, and RCON commands with aliases, argument limits, and permissions.
|-
| <code>Players</code> || Immutable player snapshots and selectors such as exact name, unique partial name, Steam ID, client ID, <code>@me</code>, and <code>@random</code>.
|-
| <code>Messages</code> || Broadcast or private chat, escaped colored segments, and major or minor HUD messages.
|-
| <code>Menus</code> || Server-owned numeric menus and shared VMod Admin entries.
|-
| <code>Effects</code> || Health, damage, slap, slay, timed damage or movement multipliers, weapon restrictions, and screen shake.
|-
| <code>Audio</code> || Play addon-owned audio globally, for one player, or at a world position.
|-
| <code>Admin</code> || Permission checks, immunity-aware targeting, kick, ban, and unban for <code>admin</code> packages.
|-
| <code>GameMode</code> || Read mode state. The active <code>gameMode</code> package can change teams, respawn players, and end rounds or matches.
|-
| <code>Events</code> || Player, combat, round, match, and mode-change subscriptions.
|-
| <code>Scheduler</code> || One-shot and repeating callbacks.
|-
| <code>Clock</code> and <code>Random</code> || Monotonic or Unix time and a per-VMod random source.
|-
| <code>Storage</code> || Sandboxed typed key/value data under the VMod's state directory.
|-
| <code>VSig</code> || Emit or subscribe to bounded VSig signals.
|-
| <code>Mods</code> || Inspect loaded packages. Administrative VMods can request reloads.
|}

<code>ModPlayer</code> and other API objects are snapshots. Keep the stable player ID and call <code>Players.Find</code> again when current state matters.

== Events and timers ==

<syntaxhighlight lang="csharp">
public void OnLoad(IModContext context)
{
    _context = context;

    var subscription = context.Events.Subscribe(
        ModEventKind.PlayerSpawned,
        "OnPlayerSpawned");
    if (!subscription.Success)
        throw new InvalidOperationException(subscription.Message);

    context.Scheduler.Once(5f, "OnTimer", "startup");
}

public void OnPlayerSpawned(ModEvent value)
{
    if (value.Player != null)
        _context.Messages.Tell(value.Player.Id, "Welcome back.");
}

public void OnTimer(ModTimerInvocation value)
{
    _context.Log.Write(value.TimerId + " fired with state " + value.State);
}
</syntaxhighlight>

Combat events put the victim in <code>Player</code> and a connected attacker or killer in <code>OtherPlayer</code>. Read <code>Amount</code>, <code>HealthAfter</code>, <code>WeaponId</code>, <code>AbilityId</code>, <code>WasHeadshot</code>, <code>WasCritical</code>, and <code>WasSuicide</code> for scalar event data.

Timers have a 50 ms minimum interval, a 24-hour maximum delay, and a limit of 256 timers per VMod. Cancel repeating timers when their owning activity ends.

== Permissions ==

A permission on <code>ModCommandSpec.Permission</code> must also appear in <code>mod.json</code>. The manifest declaration allows the VMod to ask for the permission; server admin configuration decides who has it.

VMod Admin reads groups and users from <code>&lt;data&gt;/config/mods</code>. A wildcard such as <code>admin.*</code> grants one namespace. A leading minus sign is an explicit deny and wins over grants. Immunity prevents one administrator from targeting another administrator with the same or higher value.

Do not put an RCON password or another secret in VMod source, manifests, or addon configuration.

== Send signals to VSig ==

Every VMod owns a source alias named <code>mod:&lt;mod-id&gt;</code>.

<syntaxhighlight lang="csharp">
_context.VSig.Emit("round_started", _context.GameMode.ActiveId);
_context.VSig.EmitFrom(
    "mod:community.hello.stage",
    "opened",
    3,
    "sewer_gate");
</syntaxhighlight>

A custom source must be the owned alias or a child below it. Payloads can contain at most eight null, string, Boolean, or numeric values. Send a 64-bit identifier such as a Steam ID as a string.

A VMod can subscribe to a map signal:

<syntaxhighlight lang="csharp">
context.VSig.Subscribe("escape_trigger", "on_executed", "OnEscape");

public void OnEscape(ModVSigEvent value)
{
    _context.Log.Write(value.SourceAlias + "." + value.OutputName);
}
</syntaxhighlight>

See [[Grimwar/VSig#Signals shared with VMod|Signals shared with VMod]] for the map side.

== Supported C# subset ==

VMods can use ordinary control flow, classes, structs, enums, arrays, strings, <code>StringBuilder</code>, and approved <code>System.Collections</code> and <code>System.Collections.Generic</code> shapes.

The validator rejects file and network I/O, reflection, processes, console or environment access, threads, tasks, Unity or Grimwar internals, native interop, unsafe code, <code>typeof</code>, async methods, iterators, lambdas, LINQ queries, <code>try</code>/<code>catch</code>/<code>finally</code>, <code>using</code>, <code>lock</code>, <code>foreach</code>, precompiled DLLs, and extra assembly references. Use indexed <code>for</code> loops and explicit cleanup.

Compilation alone does not guarantee that an arbitrary generic combination exists in the IL2CPP host. Start with arrays, <code>List&lt;T&gt;</code>, <code>Dictionary&lt;string, T&gt;</code>, and <code>HashSet&lt;string&gt;</code> using types present in the public API and bundled examples.

== Install and test a VMod ==

# Run <code>vmod_runtime_paths</code> through an authenticated server console or RCON session. Use the printed addon path instead of guessing a platform-specific data directory.
# Copy the complete addon folder into <code>&lt;data&gt;/addons</code>.
# Restart the server, or run <code>vmod_runtime_reload</code> while no scripted game mode is active.
# Run <code>vmod_runtime_list</code> and confirm the package is loaded and not faulted.
# Exercise every chat and console alias with empty, quoted, invalid, and maximum-length arguments.
# Run the test again with a non-admin player when the VMod declares permissions.
# Reload it more than once and check that handlers, timers, commands, and effects do not duplicate.

Useful server commands:

{| class="wikitable"
! Command !! Result
|-
| <code>vmod_runtime_list</code> || Lists loaded and faulted VMods.
|-
| <code>vmod_runtime_reload</code> || Refreshes addons and permissions, recompiles changed source, and reloads in dependency order.
|-
| <code>vmod_runtime_reload_admins</code> || Reloads admin groups and users without unloading VMods.
|-
| <code>vmod_runtime_paths</code> || Prints addon, config, state, and compiler-cache roots.
|-
| <code>sv_vmod_enabled 0</code> || Disables the VMod runtime at startup.
|}

The server refuses <code>vmod_runtime_reload</code> while a scripted game mode is active. Change to a native mode first.

== Distribution rules ==

VMod-only packages are currently installed manually or through the development overlay. Steam Workshop publishing accepts map-only Release packages and rejects packages that contain VMods. Server-only VMod source is not installed on remote players.

Use <code>--addon-root &lt;absolute-folder&gt;</code> or <code>GRIMWAR_ADDON_ROOT</code> during development to load a package directly. For ordinary installation, copy the complete folder containing <code>addon.json</code>; a loose <code>.csx</code> file is never an installable VMod.

Bundled examples are available in Grimwar's <code>StreamingAssets/Grimwar/Addons</code> source tree. <code>grimwar.rtd</code> is the smallest command and effect example. <code>grimwar.admin</code> covers permissions and menus. <code>grimwar.zombie_mod</code> is a scripted mode. <code>grimwar.quake_sounds</code> combines server logic with addon-owned audio.

[[Category:Grimwar]] [[Category:VMod]] [[Category:Server modding]]