DocumentationBot: Version 1

2026-10-01T04:13:05Z

Version 1

New page

{{GameNav}}

Use VSig to connect Grimwar entities and react to map or round events. Start with a working map from [[Grimwar/Mapping]]. [[Vertex/VSig]] explains the editor and language basics; [[Grimwar/VSig reference]] covers expressions, schedules, modules, and the standard library.

== Make a door open from a trigger ==

# Place a <code>func_door</code> named <code>main_door</code> and parent its geometry underneath it. Set a useful Move Direction and leave Start Locked off.
# Place a <code>trigger_multiple</code> named <code>entry_trigger</code> in front of it. Set Allowed Activators to Participants and Allowed Teams to Order and Union.
# Keep those entity names at the hierarchy root for this example.
# Save the map and open '''Code → Map script'''. Enter the script below.
# Build with '''Play in Game'''. Enter the trigger, leave it, and check that the door opens and closes.

<syntaxhighlight lang="text">
scene "Door test"

ref entry: trigger_multiple match entry_trigger
ref door: func_door match main_door

on entry.start_touch:
door.open

on entry.end_touch_all:
door.close
</syntaxhighlight>

A ref gives an entity a script alias. <code>start_touch</code> fires for an accepted occupant; <code>end_touch_all</code> fires after the last occupant leaves. The door's own <code>open</code> and <code>close</code> outputs fire when its motion finishes.

If you move the door under a group named <code>Building</code>, update its match path to <code>Building/main_door</code>. A wildcard such as <code>Doors/Door*</code> can target several doors, but reading a state or property requires exactly one match.

== Server and client logic ==

Gameplay handlers run on the server by default. Ambient audio is client presentation. Add an <code>env_ambient</code> named <code>door_audio</code>, choose a one-shot sound, and disable Play On Start. Add these lines to the door script:

<syntaxhighlight lang="text">
ref sound: env_ambient match door_audio

client on door.open:
sound.play
</syntaxhighlight>

The clients hear the sound when the door finishes opening. The compiler checks the authority of entity calls. Use the [[Grimwar/Entities|entity reference]] to check the contract before choosing a handler side.

== Map and round events ==

These global events do not need an entity:

{| class="wikitable"
! Event !! Use
|-
| <code>map.ready</code> || Set up once map entities and required map scripts are ready.
|-
| <code>round.warmup</code> || Apply warmup behavior.
|-
| <code>round.pre_round</code> || Reset round state before play.
|-
| <code>round.live</code> || Start live-round behavior.
|-
| <code>round.overtime</code> || Handle overtime.
|-
| <code>round.post_round</code> || Stop round tasks and show the result.
|-
| <code>round.intermission</code> || Handle the interval between matches or rounds.
|-
| <code>gravewar.wave_started(wave: int, zombies: int)</code> || React to a Gravewar wave starting.
|-
| <code>gravewar.wave_ended(wave: int, result: string)</code> || React to a Gravewar wave ending.
|}

Use <code>once on map.ready:</code> for setup once per map load. Use round events for work that must repeat each round. They only fire when the running mode reaches that phase.

== Delays and repeating work ==

A wait pauses one chain. A named schedule lets you cancel pending work:

<syntaxhighlight lang="text">
on round.pre_round:
cancel open_gate
door.close

on round.live:
schedule open_gate after 3s:
door.open

on round.post_round:
cancel open_gate
door.close
</syntaxhighlight>

This fragment uses the <code>door</code> ref from the first example. For repeated actions, use <code>schedule pulse every 1s:</code> and cancel it when its round or activity ends. Avoid comparing elapsed time with exact equality; use a one-shot schedule or indexed timer ticks. See [[Grimwar/VSig reference#Procedures, waits, and schedules|the schedule reference]].

== Entity lifecycle and operational state ==

<code>kill</code> permanently removes an entity until the map reloads. Use an entity's reversible action when that is what you need: <code>door.close</code>, <code>damageable.reset</code>, or an operational entity's <code>disable</code>.

Operational entities support enable, disable, toggle, enabled, disabled, and is_enabled. The meaning of disabled depends on the type; it does not remove the entity from the map. See [[Grimwar/VSig reference#Entity lifecycle and operational state|the lifecycle reference]].

== Activator, caller, and self ==

<code>!activator</code> identifies what began a signal chain, such as a touching participant. <code>!caller</code> identifies the entity that made the current call, and <code>!self</code> identifies the current entity. These values travel with that execution, including delayed work.

They do not provide arbitrary access to game objects or permission to kill a player. Use [[Grimwar/VSig reference#Activator, caller, and self|the context reference]] for supported procedural calls.

== Reuse an assembly ==

Put reusable modules in local <code>.vsiglib</code> files, or use a <code>logic_script</code> host that selects a library and module. Hierarchy binding lets each placed assembly find its own child entities.

Grimwar's spawn-door prefabs already include a hierarchy-bound script host. Give its alias an explicit unique name if the map script needs to call it. See [[Grimwar/VSig reference#Spatial modules and logic_script|modules and script hosts]].

== Signals shared with VMod ==

Use a VMod when you need player services, server commands, persistent storage, or custom mode control. A VMod can subscribe to map signals and emit under its own <code>mod:<mod-id></code> alias. Clients do not execute VMod code.

For an extraction zone, <code>trigger_multiple.execute</code> emits <code>executed</code> with a participant snapshot token. The subscribed VMod resolves it during that callback; the token expires when dispatch returns. See [[Grimwar/VMod reference#Send signals to VSig|the VMod example]].

== Build and test ==

Resolve the Code workspace diagnostics, save externally edited sources, and rebuild the map. Compilation embeds VSig in the scene. Test each route in Grimwar, including a second round and a map reload. A changed loose script beside the installed add-on does not replace the embedded program.

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

Grimwar/VSig - Revision history

DocumentationBot: Version 1