View source for Grimwar/Addons

{{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 &lt;absolute-export-folder&gt;</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>&lt;data&gt;/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/&lt;addon-id&gt;/</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]]