Grimwar/Addons

Getting started · Maps · VSig · VMod · Addons · Workshop · Servers · SDK

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, .csx file, or mod.json by itself.

Package layout

Every addon starts with addon.json:

community.example/
  addon.json
  maps/
    as_example/
      compile-receipt.json
      StandaloneWindows64/
      StandaloneOSX/
      StandaloneLinux64/
  mod.json
  ExampleMod.csx
  audio/

The manifest's contents 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 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:

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 id in addon.json. Initial source priority is:

Priority	Source	Notes
300	SDK overlay	Read-only folder supplied with --addon-root or GRIMWAR_ADDON_ROOT.
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 state/addons.json. 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

1. Export a Development package from the SDK Map Exporter.
2. Put the package below Grimwar's addon directory, or start Grimwar with --addon-root <absolute-export-folder>.
3. Open Addons, confirm the package is valid and enabled, and select Use This Copy when necessary.
4. Open Host. Entering or returning to the Host tab rescans addon folders.
5. Select the map. If it has no guest download source, Grimwar sets Access to Local and changes the action to Test Map.
6. 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

1. Launch Grimwar through Steam.
2. Open Addons and choose Browse Steam Workshop, or open Grimwar Workshop.
3. Subscribe to the map.
4. Return to the Addons screen and wait for Steam's download and installation to finish.
5. Enable the package if it is disabled.
6. 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

1. Run vmod_runtime_paths from authenticated server console or RCON.
2. Copy the complete folder containing addon.json into the printed <data>/addons root.
3. Restart the process, or run vmod_runtime_reload while no scripted game mode is active.
4. Run vmod_runtime_list 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 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:

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

Use Dedicated servers for server-addons.json, manual bindings, and rotation examples.

Fix a package that does not load

Check these in order:

1. The selected directory itself contains addon.json; it is not one level above or below it.
2. The package is complete and has not been copied while an export or Steam download is still running.
3. The Addons screen marks the candidate valid and enabled.
4. Use This Copy points to the build you intend to test.
5. The addon and content IDs do not collide with another installed package or built-in map.
6. The package was rebuilt with the current schema and contains the platform artifact needed by this process.
7. 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.