Grimwar/VMod

Overview · Getting started · SDK setup · Maps · Custom content · Entities · VSig · VMod · Workshop · Addons · Servers · Help

A VMod adds server behavior to Grimwar using C#. Use it for commands, player services, persistent settings, or a custom game mode. For doors, triggers, and map event routing, VSig is usually enough.

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

Create a standalone VMod

1. Launch the Grimwar SDK's VSDK app. Script-only VMods build without Unity; native media uses the SDK compiler.
2. Under Standalone resources, choose VMod and select Create…. Choose a parent folder outside the SDK installation.
3. Select Open folder and edit mod.json: set a stable ID, name, author, version, and entry point.
4. Select Edit source and implement Grimwar.ModApi.IMod. Save your files in the external editor.
5. Select Validate to check the source against Grimwar's public API.
6. Choose a build output folder outside the source folder and select Build.
7. Choose the installed Grimwar executable and select Play in game. This rebuilds the package and launches Grimwar with that output folder as its add-on overlay. Start a local host to execute the VMod.

You maintain mod.json and its declared .cs/.csx sources. The SDK generates the installable package and its addon.json. Rebuilding replaces only an earlier standalone package with the same ID; it never overwrites your source folder or a mixed-content package.

{
  "id": "community.hello",
  "name": "Hello Server",
  "author": "Your name",
  "version": "1.0.0",
  "apiVersion": 15,
  "kind": "addon",
  "entryPoint": "CommunityMods.HelloMod",
  "sourceFiles": ["HelloMod.cs"],
  "dependencies": [],
  "requires": [],
  "permissions": [],
  "enabled": true,
  "serverOnly": true
}

Use lowercase letters, digits, dots, underscores, and hyphens for stable IDs (up to 96 characters). New code targets API 15; APIs 11 through 15 are supported. The entry point must be a public, concrete IMod class with a public parameterless constructor.

kind is addon, admin, or gameMode. dependencies lists VMod IDs that must load first; requires lists add-on IDs that provide content. permissions declares command/menu permission names; it does not grant them to players. serverOnly must remain true.

Attach a VMod to a map

1. Open and save the map in Vertex using the Grimwar game profile.
2. In Map settings → SDK resources, choose VMod and select Create…. To reuse source, choose Attach… and select its folder inside the map source folder.
3. Select Edit source. Edit the generated mod.json in the same folder to set its identity and source list.
4. Implement map behavior through the same Grimwar.ModApi used by standalone VMods. The starter subscribes to map.ready.
5. Save the external files and map, then build the map. Invalid code or unsupported API calls stop compilation.
6. Select Play in game to compile and test in the installed game.

Map scripts are included inside the compiled scene. There is one map package to install or publish; do not build a companion standalone package for the attached scripts. Detach removes the map reference and keeps your source files.

The server initializes attached modules before map.ready, filters their VSig subscriptions to that map, and disposes them before removing map entities. Each load creates fresh module instances; explicitly persisted storage remains per module ID. Standalone VMods retain server-session lifetime. Clients receive the scene data but never execute VMods.

Attached scripts cannot request admin permissions, external-service capabilities or declarations. Install privileged VMods separately on the server. Dependencies resolve across the map and installed server modules. Missing dependencies, duplicate active module IDs, compilation errors, and failed initialization prevent the map from starting. Unload maps with attached scripts before reloading server VMods.

Write the entry class

This mod registers hello for chat and authenticated consoles:

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 + "!");
        }
    }
}

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

Registration	Handler signature
Command	One IModCommandInvocation parameter
Event	One ModEvent parameter
Timer	One ModTimerInvocation parameter
VSig subscription	One ModVSigEvent parameter
Menu	One ModMenuInvocation parameter

OnUnload must clear references and release any VMod-owned state that is not already scoped through the host. The host removes commands, event subscriptions, timers, effects, scripted bots, and dynamic modes when the package unloads.

Add sounds or data

Open the module's Content controls to import files or reference an installed media pack. Use context.Audio for sounds and API 15's context.Content for declared text/data. See Custom content in VMods for examples.

An attached module's Content button is beside its Edit source control in Vertex. Its assets travel with the map. A standalone module builds its assets into its own package.

Test and distribute

Build and validate before testing. Start a local host to run the script; simply opening a client menu does not exercise server behavior. Check the command with ordinary players as well as administrators when it uses permissions.

Use vmod_runtime_list to see loaded or faulted modules and vmod_runtime_paths to find the server's add-on directory. Copy complete built add-on folders for manual installs. Unload maps with attached modules and leave scripted game modes before using vmod_runtime_reload.

For a standalone release, set thumbnail in mod.json to a relative 1920 × 1080 PNG and enable Release package in VSDK. Publish it as VMod through Grimwar's Addons screen. Map-bound modules publish inside the map's Release package. Workshop subscribers receive the declared source, but only servers execute it.

See Workshop publishing for dependencies and updates, or Dedicated servers for installation.

Larger scripts

Grimwar/VMod reference covers API services, events and timers, operator configuration, game modes, permissions, bots, and VSig integration.

VMods use a restricted C# subset. Use named public handler methods and indexed for loops. Direct file/network access, reflection, threads, tasks, lambdas, LINQ, and precompiled DLLs are not supported. VSDK validation reports unsupported code; a successful desktop C# build alone does not establish VMod compatibility.