DocumentationBot: Version 1

2026-10-01T04:13:05Z

Version 1

New page

{{GameNav}}

This page covers VMod services and larger scripting tasks. Start with [[Grimwar/VMod|the working VMod example]]. New modules target API 15; the current runtime accepts APIs 11 through 15.

== 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 administration entries.
|-
| <code>Effects</code> || Health, damage, slap, slay, timed damage, movement, and player-scale effects, weapon restrictions, and screen shake.
|-
| <code>Audio</code> || Play add-on-owned audio globally, for one listener, at a world position, or from a player's authoritative pawn; apply bounded gain and stop returned playback IDs.
|-
| <code>Content</code> || Describe declared assets and read supported text/data from owned or required packages.
|-
| <code>Panels</code> || Create supported game panels through the public API.
|-
| <code>Status</code> || Set or clear bounded, expiring, per-player HUD slots owned by this VMod.
|-
| <code>Spawn</code> || Let only the active scripted game mode return a living participant to a host-selected legal team spawn.
|-
| <code>Bots</code> || Let only the active scripted game mode create, inspect, and remove its own server bots at host-selected legal spawns.
|-
| <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, award personal objective points, 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>Configuration</code> || Bounded operator-editable JSON owned by this VMod under <code><data>/config/mods/<mod-id>.json</code>.
|-
| <code>Storage</code> || Sandboxed typed key/value data under the VMod's state directory.
|-
| <code>VSig</code> || Emit or subscribe to bounded VSig signals and resolve callback-scoped participant snapshots.
|-
| <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.

== Operator configuration ==

Use <code>Configuration</code> for operator policy and settings. Use <code>Storage</code> for mutable runtime state that the VMod owns. Each VMod can access only its own configuration file.

Configuration paths contain 1 through 16 dot-separated segments. Values may be strings, finite numbers, Booleans, nulls, or scalar arrays. Read typed values with methods such as <code>GetString</code>, <code>GetInt</code>, and <code>GetBool</code>. Write documented defaults with <code>SetString</code>, <code>SetInt</code>, or <code>SetBool</code>, then call <code>Save</code>.

Validate settings before applying them. If <code>Reload</code> fails, keep the last valid values and report <code>LastError</code>. Do not duplicate operator settings in <code>mod.json</code> or VMod source.

== 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>

=== Scheduler reference ===

{| class="wikitable"
! Method !! Contract
|-
| <code>Scheduler.Once(delaySeconds, handlerMethod, state = null)</code> || Schedule one callback and return its opaque timer ID.
|-
| <code>Scheduler.Repeat(intervalSeconds, handlerMethod, state = null)</code> || Schedule callbacks until cancellation or gameplay-scope cleanup and return the timer ID.
|-
| <code>Scheduler.Cancel(timerId)</code> || Remove an active timer. Returns <code>false</code> for an empty, unknown, completed, or already-cancelled ID.
|}

The handler must be a public invokable method with exactly one <code>ModTimerInvocation</code> parameter. An empty timer ID means scheduling failed because the gameplay scope is inactive, the handler signature is invalid, the delay is not finite, or the VMod already owns 256 timers. Store and test the returned ID when later cancellation matters.

<code>ModTimerInvocation.TimerId</code> is the same opaque ID returned by the scheduler. <code>State</code> is the optional string captured when the timer was created; the host truncates it to 4,096 characters. <code>InvocationCount</code> starts at 1 and increases for each repeat callback.

Delays and intervals are clamped to 50 ms through 24 hours. Repeating timers deliver at most one callback when checked and schedule their next callback at least 50 ms in the future, so a stalled server does not dispatch a burst of catch-up invocations. <code>Cancel</code> can be called from the repeating timer's own handler:

<syntaxhighlight lang="csharp">
private string _pulseTimerId;

public void StartPulse()
{
_pulseTimerId = _context.Scheduler.Repeat(1f, "OnPulse", "round-pulse");
if (_pulseTimerId.Length == 0)
_context.Log.Warn("Could not start the pulse timer.");
}

public void OnPulse(ModTimerInvocation value)
{
_context.Messages.Broadcast("Pulse " + value.InvocationCount);
if (value.InvocationCount >= 10)
{
_context.Scheduler.Cancel(value.TimerId);
_pulseTimerId = null;
}
}
</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>DamageSourceKind</code>, <code>DamageSourceId</code>, <code>WasHeadshot</code>, <code>WasCritical</code>, <code>WasAirShot</code>, <code>WasDomination</code>, <code>WasRevenge</code>, <code>WasMelee</code>, and <code>WasSuicide</code> for event data.

<code>MatchStarted</code> fires when the host creates a match. <code>RoundPreparing</code> fires on entry to pre-round. <code>RoundStarted</code> fires when play becomes live and fires again for overtime. Round and match end events include <code>WinningTeam</code>.

The host clears timers when the gameplay scope deactivates or the VMod unloads. Cancel repeating timers earlier when their owning round, objective, or activity ends.

== Gameplay presentation and provenance ==

<code>Status.Set(playerId, slotId, text, duration)</code> creates or replaces a VMod-owned logical HUD slot for one connected client and returns a clearable lease ID. The host sanitizes text, bounds duration and slot counts, expires state on both sides, and removes it on disconnect or unload.

<code>Spawn.ReturnToSpawn(playerId)</code> is deliberately narrower than transform access. Only the active scripted game-mode owner may call it, only for a living participant, and the native mode chooses a legal spawn through its spawn policy. The host clears carried velocity, rate-limits each participant, and removes cooldown state on disconnect.

<code>Audio.PlayFromPlayer</code> resolves the named player's current authoritative pawn position instead of accepting coordinates from interpreted code. Optional playback gain is bounded from <code>0</code> through <code>1</code> and multiplies the cue's catalog gain.

== Scripted bots ==

Only the VMod that owns the active scripted game mode can spawn bots. The host validates the team and class, chooses an enabled spawn, and returns the stable bot player ID in <code>ModOperationResult.Value</code>. VMods cannot provide transforms or client-authored coordinates.

<syntaxhighlight lang="csharp">
var result = _context.Bots.Spawn(new ModBotSpawnSpec
{
Team = "Union",
ClassId = "scamp",
DisplayName = "Hunter",
Behavior = ModBotBehavior.HuntEnemies
});

if (!result.Success)
_context.Log.Warn(result.Message);
</syntaxhighlight>

<code>Standard</code> uses the normal objective-aware bot policy. <code>HuntEnemies</code> pursues enemy participants across the map and does not retreat because of low health.

Use <code>Bots.GetOwned()</code> to read current snapshots, <code>Bots.Despawn(playerId)</code> to remove one owned bot, and <code>Bots.DespawnAll()</code> to remove all bots owned by the VMod. A VMod cannot inspect or remove bots owned by the host or another package.

One VMod can own up to 64 bots, with a server-wide limit of 128.

The first scripted spawn disables the automatic bot quota and removes automatic quota bots for that gameplay scope. An active scripted game mode may call <code>Bots.DespawnAll()</code> during setup to claim the scope before its first spawn. This prevents automatic bots from appearing during pre-round or intermission phases.

Grimwar removes scripted bots and restores the previous quota when the mode changes, the gameplay scope ends, or the package unloads. If a spawn claimed the scope and then failed, Grimwar restores the previous quota. A prior <code>Bots.DespawnAll()</code> claim remains active until the gameplay scope ends.

== Define a game mode ==

A <code>gameMode</code> package declares its mode in <code>mod.json</code>. The mode ID must match the VMod ID.

<syntaxhighlight lang="json">
{
"gameMode": {
"id": "community.outbreak",
"name": "Outbreak",
"mapPrefix": "ob",
"aliases": ["outbreak"],
"teamNames": {
"union": "INFECTED",
"order": "SURVIVORS"
},
"teamWeaponSlots": {
"union": "melee",
"order": "all"
},
"disabledMovementFeatures": "grapple",
"defaultClassId": "klepper",
"automaticTeamBalance": false,
"infiniteReserveAmmo": false,
"warmupSeconds": 15,
"preRoundSeconds": 5,
"roundSeconds": 600,
"overtimeSeconds": 120,
"postRoundSeconds": 10,
"respawnWaveSeconds": 10,
"minimumPlayers": 2,
"winLimit": 1,
"maximumRounds": 0
}
}
</syntaxhighlight>

The native mode host owns phase timing, readiness, scores, respawn waves, and synchronized match state. The active VMod can assign teams, respawn players, award personal objective points, and end rounds or matches through <code>GameMode</code>. Other VMods cannot use those mutations.

The entry class can also implement <code>OnGameModeStart()</code>, <code>OnGameModeTick(float)</code>, <code>OnGameModePhaseChanged(string, float)</code>, <code>OnGameModeTimeExpired()</code>, <code>OnGameModeDamage(ModDamageRequest)</code>, and <code>OnGameModeDispose()</code>. Listen servers and community dedicated servers support scripted modes. Official servers do not.

<code>OnGameModeDamage</code> receives a mutable request before the host applies damage. The mode can change <code>Amount</code>, <code>KnockbackScale</code>, or <code>MaximumKnockback</code>, or set <code>Cancelled</code> to <code>true</code>.

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

An administration VMod reads <code>admin-groups.json</code> and <code>admins.json</code> from <code><data>/config/mods</code>. The server creates standard groups and an empty user list when those files do not exist. 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 add-on configuration.

== Add custom audio and data ==

Use the VMod's Content controls to import owned media or reference a shared pack. API 15 provides <code>Content.Describe</code> and <code>Content.TryReadText</code> for declared text/data, alongside <code>Audio</code> playback. [[Grimwar/Custom content#Use media in a VMod|Custom content]] includes examples and dependency rules.

== Send signals to VSig ==

Every VMod owns a source alias named <code>mod:<mod-id></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 and resolve the participant snapshot emitted by <code>trigger_multiple.executed</code>:

<syntaxhighlight lang="csharp">
context.VSig.Subscribe("extraction_zone", "executed", "OnExtraction");

public void OnExtraction(ModVSigEvent value)
{
if (value.Values.Length == 0)
return;

var token = value.Values[0] as string;
var occupants = _context.VSig.GetParticipantSnapshot(token);
var playerIds = new string[occupants.Length];
for (var i = 0; i < occupants.Length; i++)
playerIds[i] = occupants[i].Id;

if (playerIds.Length > 0)
_context.GameMode.AwardObjective("extraction", playerIds);
}
</syntaxhighlight>

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

<code>trigger_multiple.execute</code> captures the participants currently inside the volume and emits an opaque token. <code>VSig.GetParticipantSnapshot</code> resolves that token only during the matching synchronous callback. Expired, malformed, and unknown tokens return an empty array. The host deduplicates participants, limits a snapshot to 256 entries, and exposes immutable <code>ModPlayer</code> data instead of colliders or live Unity objects.

<code>GameMode.AwardObjective(objectiveId, playerIds)</code> gives one personal objective point to each distinct resolved participant without changing team score. The call accepts at most 256 IDs, rejects the complete request if any ID is unknown, requires an active round, and is restricted to the VMod that owns the active scripted game mode.

Entity <code>activator</code>, <code>caller</code>, and <code>self</code> handles remain inside the host. Other VMod subscriptions receive only validated scalar <code>ModVSigEvent</code> data.

== 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>, resource-scoped <code>using</code> statements, <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<T></code>, <code>Dictionary<string, T></code>, and <code>HashSet<string></code> using types present in the documented public API.

== Runtime limits ==

A server accepts at most 128 VMods. Each package can list up to 64 source files, 64 dependencies, and 256 declared permissions. One source file can be up to 512 KiB; combined source can be up to 2 MiB.

Each callback has a 100 ms time limit and a 100,000-iteration budget. Five callback failures fault the package and unload its dependents. Storage accepts up to 1,024 keys with 65,536 characters in each value. VMods still run inside the server process, so install code only from sources you trust.

== Install and test a VMod ==

# Build a Development package through VSDK's standalone resource controls.
# Point <code>--addon-root</code>, <code>GRIMWAR_ADDON_ROOT</code>, or the Unity Editor Add-on Overlay at the folder that contains your package folders.
# Run <code>vmod_runtime_paths</code> through an authenticated server console or RCON session. Use the printed add-on path instead of guessing a platform-specific data directory.
# For a manual install, copy the complete add-on folder into <code><data>/addons</code>.
# Restart the server, or run <code>vmod_runtime_reload</code> while no scripted game mode or map-bound VMod 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 add-ons and permissions, recompiles changed source, and reloads in dependency order.
|-
| <code>vmod_runtime_reload_host_config</code> || Reloads admin groups, users, and VMod configuration without unloading VMods.
|-
| <code>vmod_runtime_paths</code> || Prints add-on, 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 or map-bound VMod is active. Unload that map and change to a native mode first.

== Distribute a VMod ==

In VSDK, enable '''Release package''' before building a standalone VMod. Set <code>thumbnail</code> in <code>mod.json</code> to a relative 1920 × 1080 PNG. Install the complete generated add-on folder on the server or publish it as '''VMod''' through Grimwar's Addons screen.

Publish map-bound scripts as part of the map's Release package using the '''Map''' upload type. The source snapshot stays inside the scene and is covered by its compilation receipt. Clients carry those bytes without executing them. Rebuild and republish the map whenever its attached source changes.

See [[Grimwar/Steam Workshop addons|Steam Workshop publishing]] and [[Grimwar/Dedicated servers|Dedicated servers]] for installation and dependencies.

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

Grimwar/VMod reference - Revision history

DocumentationBot: Version 1