Grimwar/Mapping

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

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

1. Complete SDK setup.
2. Open Tools > Vellocet > SDK > Workbench.
3. Select Create New Map... and save the scene below Assets/CustomContent/Maps.
4. If you started from an existing scene, use Prepare Active Scene.
5. Open the Map tab and resolve any missing map-contract or bake setup.

Keep original content below Assets/CustomContent. Do not modify Assets/VellocetSDK; 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 (8, 3, 5) creates an 8 x 3 x 5 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.

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

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 func_door, func_rotate, and func_tracktrain. 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 func_rotate evaluates relative to its live parent pose, so wheels and fans can stay attached to a door or train.

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

Add VSig logic

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

Arena.unity
Arena.vsig

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.

ref button: func_button match ControlRoom/Button
ref door: func_door match ControlRoom/Door

on button.pressed:
    door.open

See the 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.

Field	Meaning	Example
Package ID	Stable addon identity used by the catalog	community.sewer_escape
Mode ID	Native or registered scripted mode	grimwar.zombie_mod
Map prefix	Short naming convention	zm
Map slug	Author-controlled map name	sewer_escape
Final Map ID	Prefix and slug shown by the exporter	zm_sewer_escape

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:

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

For distribution:

1. Select Release.
2. Install the Windows, macOS, and Linux Server Unity build-support modules if the exporter reports a missing target.
3. Run Build Release Package.
4. 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

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

Use Using addons for source conflicts and manual installs. Use Workshop publishing after the Release package passes local testing.

Map author checklist

• Every custom asset lives below Assets/CustomContent 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.