Vellocet Developer Community - User contributions [en]

Vellocet Developer Community:Community portal

2026-08-25T05:34:36Z

DocumentationBot: Publish SDK documentation

This wiki documents public modding tools and APIs for Vellocet games.

== Page types ==

* '''Official guides''' explain supported workflows and are reviewed alongside game changes.
* '''Generated reference pages''' are produced from public SDK code and stored in the protected <code>Generated:</code> namespace.
* '''Community pages''' collect tutorials, examples, troubleshooting, and practical knowledge from mod authors.

== Contributing ==

Public account registration is closed while Vellocet completes outbound email, anti-abuse protection, and contribution terms. Vellocet staff can create editor accounts.

Before editing, read the [[Vellocet Developer Community:Content policy|content policy]]. Use article talk pages for questions about a specific document and [[Help:Contents]] for wiki help.

== Maintenance ==

* [[Special:RecentChanges|Recent changes]]
* [[Special:NewPages|New pages]]
* [[Category:Draft documentation|Draft documentation]]
* [[Special:WantedPages|Wanted pages]]
* [[Special:BrokenRedirects|Broken redirects]]

Upcoming games

2026-08-25T05:34:35Z

DocumentationBot: Publish SDK documentation

Vellocet has not published authoring tools for its unannounced or unreleased games.

Grimwar entities, package schemas, VSig features, and VMod APIs apply only to Grimwar. Shared tools are documented under [[Vellocet SDK]].

[[Category:Vellocet games]]

ANEURISM IV

2026-08-25T05:34:34Z

DocumentationBot: Publish SDK documentation

ANEURISM IV does not have a public authoring SDK or supported mod API. Grimwar package, VSig, and VMod instructions do not apply unless an ANEURISM IV page says otherwise.

[[Category:ANEURISM IV]]

Grimwar

2026-08-25T05:34:22Z

DocumentationBot: Publish SDK documentation

{{GameNav}}

Grimwar supports custom Unity maps, VSig map logic, VMod server scripts, addon packages, Steam Workshop maps, and community dedicated servers.

== Start here ==

{| class="wikitable"
! Goal !! First document
|-
| Install the authoring tools || [[Vellocet SDK]]
|-
| Build a map || [[Grimwar/Mapping]]
|-
| Script map logic || [[Grimwar/VSig]]
|-
| Write server gameplay || [[Grimwar/VMod|VMod C# scripting]]
|-
| Install or select a package || [[Grimwar/Addons|Using addons]]
|-
| Publish a map || [[Grimwar/Steam Workshop addons|Steam Workshop publishing]]
|-
| Operate a community server || [[Grimwar/Dedicated servers]]
|}

== Versions ==

{| class="wikitable"
! Component !! Version
|-
| Vellocet SDK || 1.0.3
|-
| Unity editor || 6000.3.17f1
|-
| SDK content schema || 3
|-
| Addon schema || 9
|-
| VMod API || 5
|}

Packages built for an older rejected schema or a different VMod API must be rebuilt against the current SDK. Steam Workshop publishing currently accepts map-only Release packages; VMod packages use manual installation or the development overlay.

[[Category:Grimwar]]

Upcoming games

2026-08-25T05:13:20Z

DocumentationBot: Publish SDK documentation

This page does not document unannounced games or unreleased interfaces. A game receives technical pages only after Vellocet publishes its authoring tools and compatibility boundary.

Do not assume that a Grimwar entity, package schema, VSig feature, or VMod API works in another game. Shared tooling is documented under [[Vellocet SDK]]; runtime behavior belongs under the game that implements it.

[[Category:Vellocet games]]

ANEURISM IV

2026-08-25T05:13:19Z

DocumentationBot: Publish SDK documentation

No public ANEURISM IV authoring SDK or supported modding contract is documented here yet. Do not apply Grimwar package, VSig, or VMod instructions to ANEURISM IV unless a game-specific page explicitly says they are compatible.

[[Category:ANEURISM IV]]

Vellocet SDK

2026-08-25T05:13:17Z

DocumentationBot: Publish SDK documentation

{{Notice|title=Version target|These instructions cover Vellocet SDK 1.0.3, Unity 6000.3.17f1, SDK content schema 3, addon schema 9, and Grimwar VMod API 5.}}

The '''Vellocet SDK''' is the Unity authoring package for Grimwar maps and addon content. It installs the map compiler, entity markers, VSig tools, validation, spatial baking, custom audio support, and the addon exporter.

== Install the SDK ==

# Install the current SDK with the VSDK app.
# Open '''Window > Package Manager''' in Unity.
# Select '''+ > Add package from disk...'''.
# Open <code>SDKPackage/package.json</code> inside the VSDK install folder.
# Use Unity <code>6000.3.17f1</code> if Unity reports a version mismatch.
# When setup asks for SDK content, select the VSDK folder that contains <code>SDKPackage</code> and <code>SDKContent</code>.
# Choose an addon export folder outside the Unity project.
# Install VSig editor support when prompted, then reload VS Code or restart Rider.

Run '''Tools > Vellocet > SDK > Welcome & Setup''' to repeat setup. The SDK rejects map compilation and export in other Unity versions.

== Keep authored and managed files separate ==

{| class="wikitable"
! Path !! Owner !! Rule
|-
| <code>Assets/CustomContent</code> || Map author || Put maps, materials, models, audio, and other original assets here.
|-
| <code>Assets/CustomContent/Maps</code> || Map author || New SDK maps use this folder by default.
|-
| <code>Assets/VellocetSDK</code> || VSDK and SDK sync || Do not edit these files. Copy an asset into <code>CustomContent</code> before changing it.
|-
| <code>ProjectSettings/VellocetSdkContentOwnership.json</code> || SDK sync || Commit this receipt in team projects. It preserves ownership and GUID migration state.
|}

Referenced custom assets are found during export and included in the addon package. SDK-owned Grimwar props remain shared references where the package format permits it.

== SDK Workbench ==

Open '''Tools > Vellocet > SDK > Workbench'''.

{| class="wikitable"
! Tab !! Use it for
|-
| Project || Link or sync the installed SDK content and manage VSig editor support.
|-
| Map || Create or prepare a scene, run map bakes, and inspect map state.
|-
| Entities || Find, place, and manage entity markers in loaded scenes.
|-
| Spatial || Bake and inspect the spatial octree and path probes.
|}

The Workbench quick actions can create a map, prepare the active scene, or open the Map Exporter. Preparing a scene adds the map contract and enables Probe Volumes when the current Unity project supports them.

== Pick the right authoring path ==

{| class="wikitable"
! Goal !! Files and tools !! Guide
|-
| Build a map || Unity scene, entity markers, paired <code>.vsig</code>, Map Exporter || [[Grimwar/Mapping|Map authoring]]
|-
| Script map logic || <code>.vsig</code> and optional <code>.vsiglib</code> modules || [[Grimwar/VSig|VSig guide]]
|-
| Write server gameplay || <code>addon.json</code>, <code>mod.json</code>, and <code>.csx</code> sources || [[Grimwar/VMod|VMod scripting]]
|-
| Install or select content || Grimwar Addons screen or the server addon directory || [[Grimwar/Addons|Using addons]]
|-
| Publish a map || Release package and 1920 x 1080 Workshop thumbnail || [[Grimwar/Steam Workshop addons|Workshop publishing]]
|}

Maps and VMods use the same addon package format. An addon can contain a map, a VMod, audio, or a supported combination of those entries.

== Sync SDK content after an update ==

After VSDK updates the installed SDK, open '''SDK Workbench > Project''' and run '''Sync SDK Content'''. Sync keeps Unity GUIDs when managed assets move. When an asset must receive a new GUID, the content manifest supplies the old and new identities and the sync process rewrites references in creator-owned scenes, prefabs, materials, and assets.

Older projects may still contain SDK files under <code>Assets/Art</code> or <code>Assets/GameContent</code>. Verified managed files move to <code>Assets/VellocetSDK</code>. Modified legacy files move to <code>Assets/CustomContent/LegacySdkBackup</code> with independent GUIDs.

If sync reports an ownership error, stop and make a project backup before changing files. Do not delete the ownership receipt to force a clean state.

== VSig editor support ==

Open '''SDK Workbench > Project > VSig Editor Support''' or '''Tools > Vellocet > SDK > VSig Editor Support...'''. The installer detects VS Code and Rider profiles and installs syntax support for <code>.vsig</code> and <code>.vsiglib</code>. The '''Auto''' option updates that editor integration when its packaged content changes.

Editor support provides syntax coloring and file association. Unity and the Map Exporter remain the authority for parsing, type checks, entity contracts, and package validation.

== Custom audio ==

The SDK accepts WAV, Ogg Vorbis, and MP3 sources below <code>Assets/CustomContent</code>. Create an '''Addon Audio Cue''' from '''Assets > Create > Vellocet > Audio''', give it an addon-owned dotted ID, choose a playback template, and assign the source file.

Map export includes cues referenced by <code>env_ambient</code> markers. A VMod can ship cues through an '''Addon Audio Collection''' and the collection Inspector's '''Build Into Existing Mod Addon...''' action. The target folder must already contain a schema-current <code>addon.json</code>.

Supported templates are <code>Announcer</code>, <code>Sfx2D</code>, <code>Sfx3D</code>, <code>AmbientLoop</code>, and <code>MusicLoop</code>. The package contains source audio and <code>audio.json</code>; authors do not build Wwise SoundBanks or WEM files.

== Before exporting content ==

* Save the scene and every referenced asset.
* Keep custom files below <code>Assets/CustomContent</code>.
* Resolve every entity and VSig diagnostic.
* Use a stable addon ID, map ID, and VMod ID. Do not recycle an ID for unrelated content.
* Export a Development package for local iteration.
* Export a Release package for distribution. Release map packages always build Windows client, macOS client, and Linux dedicated-server artifacts and require complete lighting and spatial bakes.

[[Category:Vellocet SDK]] [[Category:Grimwar]]

Grimwar/Dedicated servers

2026-08-25T05:13:13Z

DocumentationBot: Publish SDK documentation

{{GameNav}}
Community dedicated servers use an isolated writable data directory for configuration, addons, state, cache, replays, and secrets. Game installation files remain read-only and replaceable.

== Create the server data directory ==

Assign a different absolute data directory to each server process:

<syntaxhighlight lang="text">
GrimwarServer --data-dir /srv/grimwar/community-1 --server-preflight-only
</syntaxhighlight>

The preflight checks the server runtime and creates missing operator files, then exits. A normal first launch creates the same layout. Existing operator files are not overwritten.

Use <code>--instance-id <id></code> instead when the default per-user server location is appropriate. <code>GRIMWAR_DATA_DIR</code> and <code>GRIMWAR_INSTANCE_ID</code> provide the corresponding environment settings. Do not point two running servers at one data directory.

Run <code>cmdlhelp</code> in server console for the command-line contract and <code>cfg_paths</code> for the resolved install, data, config, secret, addon, replay, state, and cache paths.

== Operator files ==

The generated layout includes:

{| class="wikitable"
! Path !! Purpose
|-
| <code>config/server.cfg</code> || Base non-secret server settings.
|-
| <code>config/server.d/</code> || Split non-secret configuration files.
|-
| <code>config/rulesets/</code> || Operator-defined rulesets.
|-
| <code>config/modes/</code> || Per-mode overrides.
|-
| <code>config/maps/</code> || Per-map overrides.
|-
| <code>config/autoexec.cfg</code> || Final non-secret overrides.
|-
| <code>config/rotation.json</code> || Startup map and rotation selection.
|-
| <code>config/server-addons.json</code> || Workshop items, manual bindings, and collections.
|-
| <code>config/mods/</code> || VMod Admin groups, users, and operator-owned mod configuration.
|-
| <code>secrets/server.secrets.cfg</code> || Sensitive settings such as the RCON password.
|-
| <code>secrets/server.secrets.d/</code> || Split sensitive configuration files.
|}

The server applies <code>server.cfg</code> and <code>server.d</code>, the selected ruleset, mode and map overrides, <code>autoexec.cfg</code>, command-line overrides, secret files, then deployment overrides. Run authenticated <code>cfg_reload</code> to reapply the stack.

Keep passwords and tokens out of <code>server.cfg</code>. Sensitive commands found in an ordinary config layer are ignored.

== Basic configuration ==

Uncomment only the settings you need in <code>config/server.cfg</code>. For example:

<syntaxhighlight lang="text">
sv_ruleset casual
bot_quota 0
mp_timelimit 0
mp_roundtime 0
mp_winlimit 0
mp_maxrounds 0
</syntaxhighlight>

Community and listen servers default to the bundled <code>casual</code> ruleset. A custom ruleset goes in <code>config/rulesets/<name>.cfg</code> and may inherit another ruleset:

<syntaxhighlight lang="text">
// config/rulesets/community_plus.cfg
exec rulesets/casual.cfg
mp_allowspectators 0
</syntaxhighlight>

Select it with <code>sv_ruleset community_plus</code>. During a live or overtime round, a change applies at the next round boundary unless <code>now</code> is supplied.

== Configure RCON ==

Put RCON settings in <code>secrets/server.secrets.cfg</code>:

<syntaxhighlight lang="text">
rcon_enable 1
rcon_password "use-a-long-unique-password"
rcon_port 27015
rcon_maxclients 3
rcon_timeout 30
rcon_failures 3
rcon_ban_time 300
rcon_log 1
</syntaxhighlight>

Restrict access to the secret directory at the operating-system level. Expose the RCON TCP port only to administrator addresses or a private network. Do not reuse the server password or a Steam credential as the RCON password.

== Configure map rotation ==

The default <code>whitelist</code> mode uses entries in file order:

<syntaxhighlight lang="json">
{
"listMode": "whitelist",
"entries": [
"as_compound",
"community_castle"
]
}
</syntaxhighlight>

Use internal map IDs from the package manifests. The server skips unavailable entries after addon synchronization and selects the first loadable entry. Startup fails when no entry can be loaded.

Set <code>listMode</code> to <code>blacklist</code> to rotate every registered map except the named entries:

<syntaxhighlight lang="json">
{
"listMode": "blacklist",
"entries": [
"as_compound",
"community_ruins"
]
}
</syntaxhighlight>

Blacklist expansion occurs after Workshop synchronization, so installed addon maps participate. Excluding every registered map is a startup error. Use <code>changelevel <map> [mode]</code> from authenticated console or RCON for an immediate manual change.

== Install Workshop maps ==

Configure direct items and collections in <code>config/server-addons.json</code>. Store all Steam IDs as JSON strings:

<syntaxhighlight lang="json">
{
"schemaVersion": 1,
"workshop": {
"depotId": "",
"items": [
"1234567890"
],
"manualItems": [],
"collections": [
"3456789012"
]
}
}
</syntaxhighlight>

<code>items</code> contains Workshop published-file IDs acquired by Steam. <code>collections</code> contains collection IDs; the server expands and installs their child items. Clients subscribe only to the addon required by the current map, not the whole collection.

Leave <code>depotId</code> empty unless Vellocet support directs you to override it. Grimwar supplies the fixed dedicated-server depot value.

=== Manually staged Workshop package ===

An operator can place an exact Workshop Release package below <code><data>/addons</code> and bind it to the published item:

<syntaxhighlight lang="json">
{
"schemaVersion": 1,
"workshop": {
"depotId": "",
"items": [],
"manualItems": [
{
"publishedFileId": "1234567890",
"addonId": "community_castle"
}
],
"collections": []
}
}
</syntaxhighlight>

Put an identity in exactly one acquisition list. The staged package must match the exact build currently uploaded to the Workshop item. Replace it after every Workshop update. Clients still download the Steam item; they never receive files from the server's staged folder.

== Install VMods ==

# Run <code>vmod_runtime_paths</code> and use the printed addon directory.
# Copy the complete VMod addon folder below <code><data>/addons</code>.
# Restart, or run <code>vmod_runtime_reload</code> while no scripted mode is active.
# Confirm the package with <code>vmod_runtime_list</code>.

VMod-only packages are server-only and are not currently acquired through Workshop. Admin users and groups live below <code><data>/config/mods</code>. See [[Grimwar/VMod|VMod scripting and administration]].

== Startup and diagnostics ==

Before opening the server publicly:

# Run preflight with the production data directory and deployment port mapping.
# Start the server and confirm it reaches its ready/listening state.
# Run <code>status -v</code> and verify role, build, protocol, transport, map, mode, ruleset, data path, and player limit.
# Run <code>cfg_paths</code> and confirm the expected data and secret roots.
# Check that every rotation map is registered after Workshop synchronization.
# Join with a separate Steam account and test authentication, map delivery, round transition, and map change.
# Test RCON from an allowed administrator address.

Useful log prefixes are <code>[ServerWorkshop]</code> for server acquisition and activation, <code>[WorkshopDL]</code> for exact client/server addon matching, <code>[SteamWorkshop]</code> for Steam installation, <code>[ContentDL]</code> for provider selection, and <code>[Net]</code> for pre-login requirements. Set <code>net_log 2</code> when per-addon network identities are needed.

Back up the data directory before game or addon updates. It contains operator configuration, VMod state, source selections, bans, and other mutable server data. The game install directory is not a substitute for that backup.

[[Category:Grimwar]] [[Category:Dedicated servers]]

Grimwar/Steam Workshop addons

2026-08-25T05:13:11Z

DocumentationBot: Publish SDK documentation

{{GameNav}}
{{Notice|title=Current publishing boundary|Grimwar Workshop publishing accepts non-empty, map-only Release packages. A package containing VMods or another addon content kind cannot be published through this workflow.}}

Steam Workshop is one source in Grimwar's addon catalog. The same package can be tested locally, published, subscribed to, selected, validated, and loaded without a separate Workshop format.

== Prepare the map package ==

# Finish local testing with a Development package.
# Open '''Tools > Vellocet > SDK > Map Exporter'''.
# Select '''Release'''. Release builds Windows client, macOS client, and Linux dedicated-server artifacts and requires complete lighting and spatial bakes.
# Assign '''Map Image (in-game)''' for the map browser.
# Assign separate '''Addon Thumbnail (Workshop)''' artwork. It must be a decodable 1920 x 1080 PNG or JPEG.
# Build the Release package and resolve every validator error.

The exporter places the Workshop image at the addon root and records it as <code>addonThumbnail</code>. A map's <code>map.thumbnail</code> is separate and does not satisfy the Workshop requirement.

Do not modify a Release folder after export. Grimwar validates the manifest, schema, compilation receipt, build ID, file paths, sizes, SHA-256 hashes, and platform payload before upload and again before mounting.

== Test the unpublished package ==

# Put the Release package in Grimwar's normal addon folder or an SDK overlay.
# Launch Grimwar and open '''Addons'''.
# Confirm the package is installed, valid, enabled, and offers '''Publish / Update'''.
# If another copy has the same addon ID, select '''Use This Copy''' on the local Release build.
# Open '''Host'''. The Host tab rescans addon folders when entered.
# Select '''Test Map''' and exercise the packaged map.

An unpublished package has no guest download source, so Grimwar restricts the session to '''Local'''. This is expected.

== Publish a new item ==

# Launch Grimwar through the Steam account that will own the Workshop item.
# Open '''Addons''' and select '''Publish / Update''' on the local map package.
# Enter the title, description, change note, and visibility. A new item defaults to '''Private'''.
# Review the linked Workshop terms and submit. Steam cannot cancel the upload after item submission begins.
# If Steam reports an unaccepted contributor agreement, open the agreement or item page from the result dialog and accept it.
# Inspect the item page before changing its visibility.

The publisher uploads the complete addon directory and uses the addon thumbnail as the Workshop preview. It assigns the <code>Map</code> tag plus Grimwar addon ID, schema, kind, and optional build metadata.

== Update an existing item ==

# Export a new Release package with the same addon ID.
# Start Grimwar with the same Steam account that created the item.
# Select the intended local copy with '''Use This Copy'''.
# Choose '''Publish / Update''', supply an accurate change note, and submit.
# Wait for upload and subscribed-copy refresh to finish, then test the installed Workshop copy.

The publication mapping is keyed by Steam user and addon ID. Before an update, Grimwar checks Steam ownership and item metadata and refuses an ambiguous match. A successful upload refreshes an installed subscribed copy; do not unsubscribe and resubscribe just to pick up the author's update.

== Visibility and hosting access ==

The least-public required Workshop item limits the Host screen:

{| class="wikitable"
! Workshop visibility !! Available hosting access
|-
| Private || Local only
|-
| Friends Only || Local, Friends Only, and Invite Only
|-
| Public or Unlisted || All Host access modes, subject to other required content
|}

Guest hosting also remains disabled while Steam requires the current contributor agreement. Grimwar checks that state again after upload.

== Subscribe and use a map ==

# Open [https://steamcommunity.com/app/4219460/workshop/ Grimwar Workshop] or select '''Browse Steam Workshop''' in the Addons screen.
# Subscribe to the map.
# Wait until Steam reports the item installed with no pending update.
# In Grimwar, confirm the package is valid and enabled.
# Use '''Use This Copy''' if a local package with the same addon ID is selected.
# Host the map or join a server that advertises the same published-file ID and exact build ID.

Joining occurs before Grimwar login completes. The client subscribes when necessary, waits for Steam installation, validates the Release package, mounts the exact candidate, and verifies the map came from that package. A failure stops the join instead of loading a different build.

== Dedicated servers ==

Dedicated servers list direct Workshop items, collections, or manual Workshop bindings in <code><data>/config/server-addons.json</code>. Put the installed map IDs in <code><data>/config/rotation.json</code>.

A manually staged server package can still advertise its Workshop item to clients, but the staged folder must be the exact Release build uploaded to that item. See [[Grimwar/Dedicated servers#Install Workshop maps|Install Workshop maps on a dedicated server]].

== Publishing failures ==

{| class="wikitable"
! Symptom !! Check
|-
| No '''Publish / Update''' action || Select a local or SDK-overlay Release package. It must contain at least one content entry and every entry must be a map.
|-
| Thumbnail rejected || Supply a readable 1920 x 1080 PNG or JPEG as <code>addonThumbnail</code>, not only a map image.
|-
| Package validation failed || Re-export Release and do not edit its manifest or files afterward.
|-
| Update ownership failed || Use the Steam account that owns the mapped item and confirm the addon ID has not changed.
|-
| Guests cannot join || Check item visibility, contributor-agreement state, selected source, exact build, and whether every required addon has a delivery source.
|-
| Old copy still loads || Select the intended source with '''Use This Copy''' and wait for Steam's update state to clear.
|}

See [[Grimwar/Addons|Using addons]] for catalog conflicts and local installs.

[[Category:Grimwar]] [[Category:Steam Workshop]]

Grimwar/Server-side modding

2026-08-25T05:13:10Z

DocumentationBot: Publish SDK documentation

#REDIRECT [[Grimwar/VMod]]

Grimwar/Server-side C

2026-08-25T05:13:09Z

DocumentationBot: Publish SDK documentation

#REDIRECT [[Grimwar/VMod]]

Grimwar/Addons

2026-08-25T05:13:08Z

DocumentationBot: Publish SDK documentation

{{GameNav}}
{{Notice|title=Version target|These instructions cover addon schema 9 and the Grimwar addon catalog shipped with Vellocet SDK 1.0.3.}}

An '''addon''' is the folder Grimwar discovers, validates, enables, and mounts. Maps, VMods, and addon-owned audio all use this package boundary. Do not install a loose scene, asset bundle, <code>.csx</code> file, or <code>mod.json</code> by itself.

== Package layout ==

Every addon starts with <code>addon.json</code>:

<syntaxhighlight lang="text">
community.example/
addon.json
maps/
as_example/
compile-receipt.json
StandaloneWindows64/
StandaloneOSX/
StandaloneLinux64/
mod.json
ExampleMod.csx
audio/
</syntaxhighlight>

The manifest's <code>contents</code> array declares each map, VMod, or other supported content entry. A mixed package can contain a map and the VMod that supplies its game mode. The complete folder remains one install and update unit.

Use the SDK exporter to produce map packages. For VMods, follow [[Grimwar/VMod#What a VMod package contains|the VMod manifest format]]. Keep addon IDs stable between releases; a changed ID is a different addon rather than an update.

== Use the Addons screen ==

Open '''Addons''' from Grimwar's main menu. The library combines every discovered source and reports whether each candidate is installed, valid, enabled, current, or in conflict.

The available actions depend on the source and package:

{| class="wikitable"
! Action !! Result
|-
| '''Enable''' / '''Disable''' || Changes whether the selected addon may be mounted.
|-
| '''Use This Copy''' || Selects this physical copy when several sources provide the same addon ID.
|-
| '''Open Folder''' || Opens the install location for a disk-backed package.
|-
| '''View on Steam''' || Opens the selected Workshop item.
|-
| '''Download/Update''' || Requests the current Workshop build from Steam.
|-
| '''Unsubscribe''' || Removes the Steam subscription. Steam controls final file removal.
|-
| '''Publish / Update''' || Publishes an eligible local map-only Release package.
|}

An invalid, incomplete, unavailable, or currently downloading candidate cannot be enabled or selected.

== Sources and conflicts ==

Grimwar groups physical copies by the <code>id</code> in <code>addon.json</code>. Initial source priority is:

{| class="wikitable"
! Priority !! Source !! Notes
|-
| 300 || SDK overlay || Read-only folder supplied with <code>--addon-root</code> or <code>GRIMWAR_ADDON_ROOT</code>.
|-
| 200 || Steam Workshop || Steam-managed client install.
|-
| 200 || Dedicated-server Workshop || Steam-managed or operator-staged server copy with a Workshop identity.
|-
| 100 || Manual or FastDL || Writable addon library below the active Grimwar data root.
|}

'''Use This Copy''' overrides that priority and stores the selection in <code>state/addons.json</code>. Only one valid copy of an addon ID is mounted. Built-in maps cannot be replaced by an addon, and a duplicate map ID that collides with built-in or already mounted content is rejected.

If an edited local package appears to have no effect, check the Addons screen for another selected copy with the same ID.

== Test an authored map ==

# Export a Development package from the SDK Map Exporter.
# Put the package below Grimwar's addon directory, or start Grimwar with <code>--addon-root <absolute-export-folder></code>.
# Open '''Addons''', confirm the package is valid and enabled, and select '''Use This Copy''' when necessary.
# Open '''Host'''. Entering or returning to the Host tab rescans addon folders.
# Select the map. If it has no guest download source, Grimwar sets Access to '''Local''' and changes the action to '''Test Map'''.
# Start the map and test the compiled package, not only the Unity authoring scene.

Local test mode admits only the listen host. It creates no public listing or join string, disables invites, and rejects remote connections. This allows an unpublished map to run without pretending that clients can download it.

== Install a Workshop map ==

# Launch Grimwar through Steam.
# Open '''Addons''' and choose '''Browse Steam Workshop''', or open [https://steamcommunity.com/app/4219460/workshop/ Grimwar Workshop].
# Subscribe to the map.
# Return to the Addons screen and wait for Steam's download and installation to finish.
# Enable the package if it is disabled.
# Open '''Host''' or join a server that requires the same Workshop build.

Steam owns subscribed files and their updates. Grimwar validates and mounts Steam's installed folder directly. An installed item can remain visible from the local cache while Steam is offline, but subscription, update, and Workshop enable-state changes require Steam online.

When joining a server, Grimwar downloads only the addon that owns the active map plus any session-wide requirements. Login completes only after every advertised package has the required addon ID and exact build ID and passes Release validation.

== Install a VMod on a server ==

# Run <code>vmod_runtime_paths</code> from authenticated server console or RCON.
# Copy the complete folder containing <code>addon.json</code> into the printed <code><data>/addons</code> root.
# Restart the process, or run <code>vmod_runtime_reload</code> while no scripted game mode is active.
# Run <code>vmod_runtime_list</code> and check that the VMod loaded without a compiler, capability, or dependency error.

VMod-only packages are not currently publishable through Grimwar Workshop. Use manual installation or the SDK overlay. See [[Grimwar/VMod#Install and test a VMod|Install and test a VMod]].

== Dedicated-server addon files ==

The first server launch creates its operator-owned layout without replacing existing files. Relevant paths below the active data root are:

{| class="wikitable"
! Path !! Purpose
|-
| <code>addons/<addon-id>/</code> || Manual and FastDL-installed packages.
|-
| <code>config/server-addons.json</code> || Workshop item IDs, manual Workshop bindings, collections, and the optional depot override.
|-
| <code>config/rotation.json</code> || Whitelist or blacklist of map IDs and optional game modes.
|-
| <code>state/addons.json</code> || Enabled candidates and explicit source selections.
|-
| <code>cache/steam-workshop-server/</code> || Steam-managed dedicated-server Workshop installs.
|}

Use [[Grimwar/Dedicated servers#Install Workshop maps|Dedicated servers]] for <code>server-addons.json</code>, manual bindings, and rotation examples.

== Fix a package that does not load ==

Check these in order:

# The selected directory itself contains <code>addon.json</code>; it is not one level above or below it.
# The package is complete and has not been copied while an export or Steam download is still running.
# The Addons screen marks the candidate valid and enabled.
# '''Use This Copy''' points to the build you intend to test.
# The addon and content IDs do not collide with another installed package or built-in map.
# The package was rebuilt with the current schema and contains the platform artifact needed by this process.
# For a Release package, every declared file, size, SHA-256 hash, path, and compilation receipt is unchanged.

The validator also rejects absolute or escaping paths, symbolic links or reparse points, unsupported file types, more than 8,192 files, and packages larger than 20 GiB.

[[Category:Grimwar]] [[Category:Addons]]

Grimwar/VMod

2026-08-25T05:13:03Z

DocumentationBot: Publish SDK documentation

{{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><data>/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:<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:

<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<T></code>, <code>Dictionary<string, T></code>, and <code>HashSet<string></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><data>/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 <absolute-folder></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]]

Grimwar/VSig

2026-08-25T05:12:57Z

DocumentationBot: Publish SDK documentation

{{GameNav}}
{{Notice|title=Version target|This guide covers the VSig compiler and standard library included with Vellocet SDK 1.0.3.}}

'''VSig''' is Grimwar's map-logic language. A VSig program listens to entity or game outputs, changes state, calls entity inputs, schedules work, and exchanges bounded signals with VMods. The Map Exporter validates and compiles it into the map package.

Use VSig for map orchestration. Use an entity marker when the thing has a position, volume, renderer, collider, or native game behavior. Use [[Grimwar/VMod|VMod]] for server rules that need players, commands, persistent storage, permissions, or game-mode control.

== Create the map script ==

A map scene and its VSig source share a name and folder:

<syntaxhighlight lang="text">
Assets/CustomContent/Maps/Range/Range.unity
Assets/CustomContent/Maps/Range/Range.vsig
</syntaxhighlight>

Create a script with '''Assets > Create > Vellocet > SDK > VSig Script'''. A marker Inspector can also create or open the current scene's file and insert refs for selected entities.

Install syntax support from '''SDK Workbench > Project > VSig Editor Support'''. Unity still performs the authoritative parse and validation.

== First working script ==

<syntaxhighlight lang="text">
scene "Example"

ref trigger: trigger_multiple match Triggers/Entrance
ref door: func_door match Doors/MainDoor

var door_start: DoorEntityState = null

once on map.ready:
door_start = door.state

on trigger.start_touch:
door.open

on trigger.end_touch_all:
door.restore(door_start)
</syntaxhighlight>

The two <code>ref</code> declarations bind authored markers to short aliases. <code>map.ready</code> runs after server-side map entities are bound. The trigger's <code>start_touch</code> output calls the door's <code>open</code> input. The script captures the starting door state once and restores it after the last toucher leaves.

Marker Inspectors list the inputs, outputs, state type, and access rules for that entity class. Use that contract instead of guessing a signal name.

== Refs and groups ==

A ref can match one hierarchy path or a wildcard:

<syntaxhighlight lang="text">
ref main_door: func_door match BuildingA/Door
ref spawn_doors: func_door match SpawnDoors/Door*

group exits:
main_door
spawn_doors

on round.post_round:
exits.close
</syntaxhighlight>

An input sent to a wildcard ref or group broadcasts to every match. Property reads and state capture require exactly one entity.

Stable GameObject names make refs readable and keep wildcard matches predictable. A marker's hidden runtime ID is managed by the SDK; VSig authoring uses the object hierarchy and entity class.

== Values and expressions ==

Primitive types are <code>bool</code>, <code>int</code>, <code>float</code>, and <code>string</code>. Entity state uses the state type declared by its marker contract. Durations accept seconds or milliseconds, including <code>1.5s</code> and <code>250ms</code>.

<syntaxhighlight lang="text">
seed 1847

const max_score: int = 10
var score: int = 0
var title: string = "Arena"

on button.pressed:
score = clamp(score + 1, 0, max_score)
label.set_text("{0}: {1}/{2}", title, score, max_score)
</syntaxhighlight>

Strings must be quoted. Declare and initialize map variables and module state before use. Handler parameters and procedure parameters are immutable; assign mutable data to a map <code>var</code> or module <code>state</code>.

Operators include arithmetic, comparisons, <code>and</code>, <code>or</code>, and <code>not</code>. Built-in functions include:

* <code>min</code>, <code>max</code>, <code>clamp</code>, <code>abs</code>, <code>floor</code>, <code>ceil</code>, and <code>round</code>
* <code>lerp</code> and <code>remap</code>
* <code>random</code>, <code>random_int</code>, <code>shuffle</code>, and <code>choose</code>
* <code>time</code>, <code>format</code>, and <code>convar</code>
* <code>bool</code>, <code>int</code>, <code>float</code>, and <code>string</code> conversions

Without <code>seed</code>, each map runtime starts with fresh random entropy. A declared seed makes random sequences repeatable. <code>shuffle(self, count)</code> gives each module instance its own shuffle bag.

== Conditions and matching ==

<syntaxhighlight lang="text">
on counter.changed(value: float):
if value >= 10:
door.open
elif value > 0:
light.on
else:
light.off

match int(value):
case 1:
label.set_text("one")
case 2:
label.set_text("two")
default:
label.set_text("many")
</syntaxhighlight>

Indentation defines the statement block. A type mismatch, unknown name, invalid call, missing ref, or wrong handler payload is a compile error.

== Procedures and schedules ==

<syntaxhighlight lang="text">
def announce(message: string, delay: float = 0s):
wait delay
label.set_text(message)

on round.live:
call announce("Fight!", 0.25s)
schedule heartbeat every 1s times 10:
light.toggle

on round.post_round:
cancel heartbeat
</syntaxhighlight>

<code>wait</code> suspends the current handler or procedure. <code>schedule name after duration</code> runs once. <code>schedule name every duration</code> repeats, and <code>times</code> limits the count. Starting a named schedule replaces the existing task with that name. Cancelling a task that is not running is safe.

Cancel round-owned repeating work on <code>round.post_round</code> or another lifecycle event that always closes the activity.

== Reusable modules ==

A module contains parameters, private state, inputs, outputs, procedures, and handlers:

<syntaxhighlight lang="text">
module counter(start: float = 0, max_value: float = 10):
state value: float = start
output changed(value: float)
output reached(value: float)

input add(amount: float = 1):
value = min(value + amount, max_value)
emit changed(value)
if value >= max_value:
emit reached(value)

input reset:
value = start
emit changed(value)

use counter as captures(max_value = 3)

ref capture_point: game_capture_point
ref exit: func_door

on capture_point.captured:
captures.add

on captures.reached(value: float):
exit.open
</syntaxhighlight>

Module parameters are immutable configuration. State is private mutable data and can be inspected as <code>instance.state_name</code>. Inputs are typed procedures. Outputs carry typed payloads and work like entity outputs.

Put shared modules in <code>.vsiglib</code> files and import only the required module:

<syntaxhighlight lang="text">
from "Packages/com.vellocet.sdk/Runtime/VSig/Libraries/Logic.vsiglib" use counter
use counter as captures(max_value = 5)
</syntaxhighlight>

The standard logic library contains <code>counter</code>, <code>accumulator</code>, <code>relay</code>, <code>timer</code>, <code>selector</code>, <code>random_selector</code>, <code>sequence</code>, <code>latch</code>, <code>toggle</code>, <code>state_machine</code>, <code>debounce</code>, and <code>cooldown</code>.

These modules are compiled logic. They do not create GameObjects or network objects.

== Spatial modules and logic_script ==

A spatial module declares local refs and binds each instance to a scene hierarchy:

<syntaxhighlight lang="text">
module gate:
ref trigger: trigger_multiple
ref door: func_door

on trigger.start_touch:
door.open

input reset:
door.close

use gate as exits match Gates/Exit_*
</syntaxhighlight>

A wildcard <code>use</code> creates one module instance per matching root and a broadcast group named by the authored alias.

Place a <code>logic_script</code> marker when a designer should choose a module and its arguments in the scene Inspector. Select the <code>.vsiglib</code>, module name, alias, arguments, and local-ref binding mode. The compiler expands the marker into the same form as a source-authored <code>use</code>. It does not become a runtime entity.

== Map and round lifecycle ==

Lifecycle sources need no scene marker:

<syntaxhighlight lang="text">
once on map.ready:
doors.close

on round.warmup:
warmup_lights.enable

on round.pre_round:
round_timer.reset

on round.live:
round_timer.start

on round.overtime:
overtime_alarm.play

on round.post_round:
cancel heartbeat

on round.intermission:
doors.open
</syntaxhighlight>

Available lifecycle sources are <code>map.ready</code>, <code>round.warmup</code>, <code>round.pre_round</code>, <code>round.live</code>, <code>round.overtime</code>, <code>round.post_round</code>, and <code>round.intermission</code>.

Use <code>once on map.ready</code> to capture an authored entity's initial state or perform setup that must run once per map load.

== Safe server commands ==

<code>server_command()</code> sends one command through the server's content-accessible command boundary:

<syntaxhighlight lang="text">
once on map.ready:
server_command("mp_roundtime 3")
server_command("sv_gravity -6")
server_command("say Map rules loaded")

on door.open:
server_command("gm_message major DOOR HAS BEEN OPENED")
</syntaxhighlight>

The server allows a curated set of match timing, chat or HUD messages, round completion, friendly fire, movement tuning, class enforcement, and weapon-slot rules. It rejects semicolons, newlines, secret-like identifiers, and commands without the <code>ContentAccessible</code> flag. Any changed console variable is restored when the map unloads.

Server operators can disable map commands with <code>sv_allow_content_commands 0</code>. <code>convar()</code> reads use the same allowlist.

== Signals shared with VMod ==

VMods can emit a source under <code>mod:<mod-id></code>. Handle that signal like any other output:

<syntaxhighlight lang="text">
on mod:community.hello.round_started(mode_id: string):
status_label.set_text("Mode: {0}", mode_id)

on mod:community.hello.stage.opened(index: int, gate_name: string):
gate_counter.set(index)
</syntaxhighlight>

The first handler receives output <code>round_started</code> from source <code>mod:community.hello</code>. The second receives output <code>opened</code> from child source <code>mod:community.hello.stage</code>.

A VMod can subscribe to a map entity or module output by source alias and output name. This exchange carries scalar values only. It does not expose scene objects to VMod code.

== Compile and debug ==

Press Play for quick testing. The compiled VSig runtime Inspector shows validation state, live module state, scheduled tasks, and a bounded recent-event trace. Marker Inspectors can show signal routes and add selected refs or a group to the paired script.

Before export:

# Save the scene and VSig file.
# Resolve parser, type, ref, module, and entity-contract diagnostics.
# Check wildcard refs against the final hierarchy.
# Exercise each round-phase handler more than once.
# Confirm repeating schedules stop at the intended lifecycle boundary.
# Run '''Compile Scene''' in the Map Exporter before building the addon package.

The exporter expands imported modules, validates the final program, and embeds a compact compiled program in the map. A Release export refuses incomplete required bakes or invalid VSig.

[[Category:Grimwar]] [[Category:VSig]] [[Category:Mapping]]

Grimwar/Mapping

2026-08-25T05:12:55Z

DocumentationBot: Publish SDK documentation

{{GameNav}}
{{Notice|title=Version target|Map export requires Vellocet SDK 1.0.3 and Unity 6000.3.17f1. Release packages use addon schema 9.}}

Grimwar maps are Unity scenes compiled and packaged by the Vellocet SDK. A map package can include custom assets, entity markers, VSig, audio, and platform-specific scene artifacts.

== Create the scene ==

# Complete [[Vellocet SDK#Install the SDK|SDK setup]].
# Open '''Tools > Vellocet > SDK > Workbench'''.
# Select '''Create New Map...''' and save the scene below <code>Assets/CustomContent/Maps</code>.
# If you started from an existing scene, use '''Prepare Active Scene'''.
# Open the '''Map''' tab and resolve any missing map-contract or bake setup.

Keep original content below <code>Assets/CustomContent</code>. Do not modify <code>Assets/VellocetSDK</code>; SDK sync owns that folder.

The scene name becomes the default map slug. Rename it before other files or packages depend on that identity.

== Build geometry ==

Use ordinary Unity renderers, meshes, materials, terrain, colliders, and supported SDK assets. The exporter finds referenced custom assets and includes them in the addon.

Use Unity's Transform tools as the final source of position, rotation, and scale. An area marker's scale is its world-space bounds. A scale of <code>(8, 3, 5)</code> creates an <code>8 x 3 x 5</code> volume; there is no separate size property or hidden multiplier.

Avoid unnecessary high-poly collision meshes. Run the exporter collider audit and test player movement, projectiles, doors, and physics props against the compiled scene, not only the authoring scene.

== Place entity markers ==

Open the Workbench '''Entities''' tab. Markers turn authored positions, volumes, and objects into Grimwar runtime entities.

{| class="wikitable"
! Prefix !! Purpose !! Examples
|-
| <code>func_</code> || Physical or interactive world objects || <code>func_door</code>, <code>func_rotate</code>, <code>func_tracktrain</code>, <code>func_button</code>
|-
| <code>trigger_</code> || Reactive volumes || <code>trigger_multiple</code>, <code>trigger_hurt</code>, <code>trigger_push</code>, <code>trigger_teleport</code>
|-
| <code>info_</code> || Points and authored references || <code>info_player_spawn</code>, <code>info_teleport_destination</code>, <code>info_observer_point</code>
|-
| <code>env_</code> || Audio, light, and effects || <code>env_ambient</code>, <code>env_light</code>, <code>env_explosion</code>, <code>env_screenshake</code>
|-
| <code>logic_</code> || Scene-configured VSig hosts || <code>logic_script</code>
|-
| <code>item_</code> || Pickups || <code>item_pickup</code>
|-
| <code>game_</code> || Rules and objectives || <code>game_capture_point</code>, <code>game_crystal</code>, <code>game_blitz_checkpoint</code>
|}

Give marker GameObjects short, stable names. VSig refs use those names and hierarchy paths. The marker Inspector shows the entity's inputs, outputs, state, properties, and server or client access rules.

=== Moving brushes ===

The marker GameObject and its children are the geometry owned by <code>func_door</code>, <code>func_rotate</code>, and <code>func_tracktrain</code>. Parent intact prop prefabs, renderers, colliders, and child entities below the marker. Do not add an authoring Rigidbody, network component, or Transform constraint to the moving brush.

The runtime mounts the hierarchy below one predicted kinematic body. Nested entities follow the mover, including entities below ordinary grouping objects. A nested continuous <code>func_rotate</code> evaluates relative to its live parent pose, so wheels and fans can stay attached to a door or train.

Keep a <code>func_tracktrain</code> spline outside the train hierarchy and assign its <code>SplineContainer</code> in the marker Inspector.

== Add VSig logic ==

The map script sits beside the scene and uses the same base filename:

<syntaxhighlight lang="text">
Arena.unity
Arena.vsig
</syntaxhighlight>

A marker Inspector can create the file, add refs for selected markers, build a group, and open the script. Use VSig to connect outputs to inputs, keep map state, schedule actions, and reuse logic modules.

<syntaxhighlight lang="text">
ref button: func_button match ControlRoom/Button
ref door: func_door match ControlRoom/Door

on button.pressed:
door.open
</syntaxhighlight>

See the [[Grimwar/VSig|VSig guide]] for refs, typed values, modules, lifecycle events, schedules, safe server commands, and VMod signals.

== Bake map data ==

Use the Workbench '''Map''' and '''Spatial''' tabs to run and inspect required bakes. The final package can contain lighting data, Probe Volume data, navigation, the spatial octree, and other compilation receipts used by the runtime validator.

Development compile settings can skip lighting, the spatial octree, or both. A skipped octree is omitted from the compiled scene while the previous cached authoring asset remains available for a later bake. These options shorten iteration only.

A Release package always requires complete lighting and spatial-octree bakes. It also builds every required desktop artifact. Do not distribute a Development package as a final release.

== Set map and package identity ==

Open '''Tools > Vellocet > SDK > Map Exporter'''. Select '''Addon''' workflow and choose the scene and export folder.

{| class="wikitable"
! Field !! Meaning !! Example
|-
| Package ID || Stable addon identity used by the catalog || <code>community.sewer_escape</code>
|-
| Mode ID || Native or registered scripted mode || <code>grimwar.zombie_mod</code>
|-
| Map prefix || Short naming convention || <code>zm</code>
|-
| Map slug || Author-controlled map name || <code>sewer_escape</code>
|-
| Final Map ID || Prefix and slug shown by the exporter || <code>zm_sewer_escape</code>
|}

These identities are independent. Changing the default mode does not rename the map. Use '''Use selected mode's prefix''' when you intend to change the prefix.

Set the title, author, version, in-game map image, and separate Workshop addon thumbnail. Workshop publishing requires a decodable 1920 x 1080 PNG or JPEG addon thumbnail; the in-game image does not replace it.

== Compile and export ==

Use '''Compile Scene''' to build a local compiled scene and catch errors before packaging.

For routine iteration:

# Select '''Development'''.
# Build only the platform targets needed for the current test.
# Leave required bakes enabled for the first complete pass, then use skip options only while changing unrelated content.
# Select '''Export Development Package'''.

For distribution:

# Select '''Release'''.
# Install the Windows, macOS, and Linux Server Unity build-support modules if the exporter reports a missing target.
# Run '''Build Release Package'''.
# Keep the generated folder intact. The catalog validates its manifest, build ID, receipts, file sizes, hashes, paths, and platform payloads.

The exporter writes into a staging directory first and publishes the package only after every selected target and integrity check succeeds.

== Test the map in Grimwar ==

# Export into Grimwar's addon directory or launch Grimwar with <code>--addon-root <export-folder></code>.
# Open '''Addons''' from the main menu.
# Find the package, confirm it is valid and enabled, and select '''Use This Copy''' if another copy has the same addon ID.
# Open '''Host'''. Returning to the Host tab rescans addon folders.
# If the map has no guest download source, Grimwar selects '''Local''' access and changes the main action to '''Test Map'''.
# Load the map and test spawns, objectives, all VSig paths, moving geometry, audio, lighting, navigation, and round transitions.

Use [[Grimwar/Addons|Using addons]] for source conflicts and manual installs. Use [[Grimwar/Steam Workshop addons|Workshop publishing]] after the Release package passes local testing.

== Map author checklist ==

* Every custom asset lives below <code>Assets/CustomContent</code> and has a valid reference from the scene or package.
* Marker names and hierarchy paths are stable.
* Volume scale, rotation, and parent scale match the intended runtime bounds.
* Moving-brush children are parented below the correct marker.
* VSig compiles without unknown refs, payload errors, type mismatches, or orphan schedules.
* Lighting, navigation, and spatial data were rebuilt after geometry changed.
* The Development package works through the Grimwar Addons and Host screens.
* The Release package contains all required platform targets and a Workshop thumbnail when it will be published.

[[Category:Grimwar]] [[Category:Mapping]] [[Category:Vellocet SDK]]

Grimwar/Getting started

2026-08-25T05:12:54Z

DocumentationBot: Publish SDK documentation

{{GameNav}}
{{Notice|title=Version target|Use Vellocet SDK 1.0.3 with Unity 6000.3.17f1. Current packages use addon schema 9 and VMod API 5.}}

Start with the result you want:

{| class="wikitable"
! Goal !! Guide
|-
| Create a playable map || [[Grimwar/Mapping|Map authoring]]
|-
| Script doors, triggers, objectives, timers, and round logic || [[Grimwar/VSig|VSig]]
|-
| Write C# server gameplay, commands, or a game mode || [[Grimwar/VMod|VMod]]
|-
| Install, enable, select, or test a package || [[Grimwar/Addons|Using addons]]
|-
| Publish a map on Steam || [[Grimwar/Steam Workshop addons|Steam Workshop publishing]]
|-
| Run a community server || [[Grimwar/Dedicated servers|Dedicated servers]]
|}

== Install the authoring tools ==

# Install the current Vellocet SDK with the VSDK app.
# Install Unity <code>6000.3.17f1</code>.
# In Unity, open '''Window > Package Manager''' and select '''+ > Add package from disk...'''.
# Select <code>SDKPackage/package.json</code> inside the VSDK install folder.
# Complete '''Tools > Vellocet > SDK > Welcome & Setup'''.
# Choose an addon export folder outside the Unity project.
# Open '''Tools > Vellocet > SDK > Workbench''' and confirm the Project tab reports current managed content.

See [[Vellocet SDK#Install the SDK|Install the SDK]] for project paths, content sync, and editor support.

== Build and test a first map ==

# In SDK Workbench, select '''Create New Map...''' and save it below <code>Assets/CustomContent/Maps</code>.
# Add geometry, collision, at least one <code>info_player_spawn</code>, and any required mode entities from the '''Entities''' tab.
# Give marker GameObjects stable names.
# Create a <code>.vsig</code> file beside the scene when the map needs scripted behavior.
# Open '''Tools > Vellocet > SDK > Map Exporter''', set stable package and map IDs, and run '''Compile Scene'''.
# Export a Development package.
# Open Grimwar's '''Addons''' screen, enable the package, and select '''Use This Copy''' if another source has the same addon ID.
# Open '''Host''' and select '''Test Map'''. Test the exported scene, spawns, collision, logic, lighting, audio, and round transitions.

Use a Release package only after the Development package works. Release export builds all required desktop artifacts and requires complete lighting and spatial bakes.

== Build and test a first VMod ==

# Create one addon folder with <code>addon.json</code>, <code>mod.json</code>, and a <code>.csx</code> source file.
# Implement <code>Grimwar.ModApi.IMod</code> and register one command in <code>OnLoad</code>.
# On the test server, run <code>vmod_runtime_paths</code> and copy the complete folder into the printed addons root.
# Run <code>vmod_runtime_reload</code>, then <code>vmod_runtime_list</code>.
# Invoke the command through chat and authenticated console, then reload the package again to check cleanup.

The [[Grimwar/VMod#Write the entry class|minimal VMod]] contains working manifests and C# source. VMod packages are server-authoritative and are currently installed manually or through the development overlay.

== Keep these boundaries straight ==

* Original Unity assets belong below <code>Assets/CustomContent</code>.
* <code>Assets/VellocetSDK</code> is managed by SDK content sync.
* A Unity scene is authored content; the exported addon folder is what Grimwar installs.
* VSig controls map entities and map-local logic. VMod controls server gameplay through <code>Grimwar.ModApi</code>.
* The complete addon folder is the install unit.
* Steam Workshop publishing currently accepts map-only Release packages. It does not accept a package containing VMods.

[[Category:Grimwar]] [[Category:Getting started]]

Grimwar

2026-08-25T05:12:53Z

DocumentationBot: Publish SDK documentation

{{GameNav}}

<div class="vellocet-eyebrow">GRIMWAR DEVELOPER PORTAL</div>

These guides cover the public Grimwar content toolchain: Unity map authoring, VSig map logic, VMod server scripting, addon installation, Steam Workshop maps, and community dedicated servers.

== Start here ==

{| class="wikitable"
! Goal !! First document
|-
| Install the authoring tools || [[Vellocet SDK]]
|-
| Build a map || [[Grimwar/Mapping]]
|-
| Script map logic || [[Grimwar/VSig]]
|-
| Write server gameplay || [[Grimwar/VMod|VMod C# scripting]]
|-
| Install or select a package || [[Grimwar/Addons|Using addons]]
|-
| Publish a map || [[Grimwar/Steam Workshop addons|Steam Workshop publishing]]
|-
| Operate a community server || [[Grimwar/Dedicated servers]]
|}

== Current version boundary ==

{| class="wikitable"
! Component !! Version
|-
| Vellocet SDK || 1.0.3
|-
| Unity editor || 6000.3.17f1
|-
| SDK content schema || 3
|-
| Addon schema || 9
|-
| VMod API || 5
|}

Packages built for an older rejected schema or a different VMod API must be rebuilt against the current SDK. Steam Workshop publishing currently accepts map-only Release packages; VMod packages use manual installation or the development overlay.

[[Category:Grimwar]]