DocumentationBot: Version 1

2026-10-01T04:13:05Z

Version 1

New page

{{GameNav}}
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, [[Grimwar/VSig|VSig]] is usually enough.

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.

== Create a standalone VMod ==

# Launch the Grimwar SDK's VSDK app. Script-only VMods build without Unity; native media uses the SDK compiler.
# Under '''Standalone resources''', choose '''VMod''' and select '''Create…'''. Choose a parent folder outside the SDK installation.
# Select '''Open folder''' and edit <code>mod.json</code>: set a stable ID, name, author, version, and entry point.
# Select '''Edit source''' and implement <code>Grimwar.ModApi.IMod</code>. Save your files in the external editor.
# Select '''Validate''' to check the source against Grimwar's public API.
# Choose a build output folder outside the source folder and select '''Build'''.
# 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 <code>mod.json</code> and its declared <code>.cs</code>/<code>.csx</code> sources. The SDK generates the installable package and its <code>addon.json</code>. Rebuilding replaces only an earlier standalone package with the same ID; it never overwrites your source folder or a mixed-content package.

<syntaxhighlight lang="json">
{
"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
}
</syntaxhighlight>

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 <code>IMod</code> class with a public parameterless constructor.

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

== Attach a VMod to a map ==

# Open and save the map in Vertex using the Grimwar game profile.
# In '''Map settings → SDK resources''', choose '''VMod''' and select '''Create…'''. To reuse source, choose '''Attach…''' and select its folder inside the map source folder.
# Select '''Edit source'''. Edit the generated <code>mod.json</code> in the same folder to set its identity and source list.
# Implement map behavior through the same <code>Grimwar.ModApi</code> used by standalone VMods. The starter subscribes to <code>map.ready</code>.
# Save the external files and map, then build the map. Invalid code or unsupported API calls stop compilation.
# 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 <code>map.ready</code>, 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 <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. 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 <code>context.Audio</code> for sounds and API 15's <code>context.Content</code> for declared text/data. See [[Grimwar/Custom content#Use media in a VMod|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 <code>vmod_runtime_list</code> to see loaded or faulted modules and <code>vmod_runtime_paths</code> 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 <code>vmod_runtime_reload</code>.

For a standalone release, set <code>thumbnail</code> in <code>mod.json</code> 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 [[Grimwar/Steam Workshop addons|Workshop publishing]] for dependencies and updates, or [[Grimwar/Dedicated servers|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 <code>for</code> 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.

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

Grimwar/VMod - Revision history

DocumentationBot: Version 1