View source for Grimwar/VSig reference

{{GameNav}}

This is the detailed VSig reference for Grimwar. Start with [[Grimwar/VSig|the door tutorial]] or [[Vertex/VSig|the language basics]]. Examples below show individual language features; keep the required refs and modules in your map when combining them.

== 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 entity names make refs readable and keep wildcard matches predictable. VSig refs use the object hierarchy and entity class.

== Entity lifecycle and operational state ==

Every concrete map entity exposes the same terminal lifecycle:

{| class="wikitable"
! Member !! Kind !! Meaning
|-
| <code>kill</code> || Input || Permanently remove this entity instance for the current map load.
|-
| <code>killed</code> || Output || Fire once immediately before the runtime is removed.
|}

<code>kill</code> is distinct from domain actions such as a damageable entity's <code>break</code>. A broken entity can be healed or reset; a killed entity returns only when the scene or map is loaded again. The server synchronizes terminal state to current clients and late joiners and records it in demo entity state. Client-local presentation entities use their owning client runtime.

The SDK calls this operation <code>kill</code>, not <code>destroy</code>. It does not expose hierarchy destruction because a Unity Transform hierarchy is an authoring relationship, not an entity-ownership boundary.

Entities that declare the '''Operational''' capability also expose:

{| class="wikitable"
! Member !! Kind !! Meaning
|-
| <code>enable</code> || Input || Make the entity operational.
|-
| <code>disable</code> || Input || Make the entity non-operational.
|-
| <code>toggle</code> || Input || Switch operational state.
|-
| <code>enabled</code> || Output || Fire on an actual disabled-to-enabled transition.
|-
| <code>disabled</code> || Output || Fire on an actual enabled-to-disabled transition.
|-
| <code>is_enabled</code> || Property || Read the current operational state.
|-
|}

Repeated <code>enable</code> or <code>disable</code> calls succeed without emitting duplicate transition outputs. Operational state never calls <code>GameObject.SetActive</code> and never changes Unity's component <code>enabled</code> property. The entity remains registered and applies its own behavior. For example, a disabled <code>func_damageable</code> ignores gameplay damage but still accepts <code>heal</code>, <code>reset</code>, <code>break</code>, operational inputs, and <code>kill</code>.

Keep more precise verbs when they carry different meaning. Doors remain <code>open</code>/<code>close</code>, damageables remain <code>break</code>/<code>reset</code>, and continuous movers remain <code>start</code>/<code>stop</code>.

== Activator, caller, and self ==

Every entity signal carries immutable execution context:

{| class="wikitable"
! Name !! Meaning
|-
| <code>activator</code> || Gameplay object that began the chain, such as the participant touching a trigger.
|-
| <code>caller</code> || Map entity that invoked the current entity.
|-
| <code>self</code> || Entity whose output handler or input is currently executing.
|}

Use the procedural targets <code>!activator</code>, <code>!caller</code>, and <code>!self</code>:

<syntaxhighlight lang="text">
ref entry_trigger: trigger_multiple match entry_trigger
ref first_gate: func_door match first_gate

on entry_trigger.start_touch:
    first_gate.open

on first_gate.open:
    !caller.disable
    !self.kill
</syntaxhighlight>

If a player activates entity A and A invokes B, B receives the original player as <code>activator</code>, A as <code>caller</code>, and B as <code>self</code>. Each later entity invocation advances <code>caller</code> and <code>self</code> while preserving the original activator. Procedures, waits, scheduled blocks, and delayed entity outputs preserve their originating context. Autonomous and global signals have no activator or caller.

Targets resolve separately for every execution; there is no global last activator. A missing target produces a bounded warning and does nothing. Player and gameplay-object activators remain opaque provenance handles, so <code>!activator.kill</code> cannot kill a player or arbitrary GameObject. Clients cannot forge handles or invoke server-owned entities through this path.

== 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 ===

{| class="wikitable"
! Precedence, high to low !! Operators !! Notes
|-
| Grouping || <code>(expression)</code> || Parentheses override normal precedence.
|-
| Unary || <code>-value</code>, <code>not value</code>, <code>!value</code> || Numeric negation and logical negation.
|-
| Multiplicative || <code>*</code>, <code>/</code>, <code>%</code> || Division or remainder by zero produces an invalid expression value.
|-
| Additive || <code>+</code>, <code>-</code> || <code>+</code> concatenates when either operand is a string; otherwise both operands must be numeric.
|-
| Comparison || <code>==</code>, <code>!=</code>, <code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>, <code>&gt;=</code> || Ordering requires numbers. Non-numeric equality compares invariant text without case sensitivity.
|-
| Logical AND || <code>and</code>, <code>&amp;&amp;</code> || Both operands are evaluated.
|-
| Logical OR || <code>or</code>, <code>&#124;&#124;</code> || Both operands are evaluated.
|}

Falsey values are <code>false</code>, numeric zero, an empty string, <code>null</code>, and a missing value. Nonzero numbers, nonempty strings, and entity-state values are truthy.

=== Built-in functions ===

These 20 expression functions are available:

{| class="wikitable"
! Function !! Result and constraints
|-
| <code>abs(value)</code> || Absolute numeric value.
|-
| <code>bool(value)</code> || Truthiness conversion using the rules above. A nonempty string, including <code>"false"</code>, is truthy.
|-
| <code>ceil(value)</code> || Smallest integer greater than or equal to the numeric value.
|-
| <code>choose(condition, when_true, when_false)</code> || Returns the second or third value according to the condition's truthiness.
|-
| <code>clamp(value, minimum, maximum)</code> || Numeric value constrained to the supplied bounds.
|-
| <code>convar(name)</code> || Reads one content-accessible console variable. Use a quoted name such as <code>convar("sv_gravity")</code>. The server allowlist and <code>sv_allow_content_commands</code> policy apply.
|-
| <code>float(value)</code> || Converts an integer, float, or invariant numeric string to a float.
|-
| <code>floor(value)</code> || Greatest integer less than or equal to the numeric value.
|-
| <code>format(pattern [, value1 [, value2]])</code> || Invariant composite formatting. Example: <code>format("{0}: {1:0.0}", name, score)</code>.
|-
| <code>int(value)</code> || Converts an integer, float, or invariant integer string to an integer. Float conversion truncates toward zero.
|-
| <code>lerp(a, b, t)</code> || Unclamped linear interpolation from <code>a</code> to <code>b</code>. Values of <code>t</code> outside <code>0..1</code> extrapolate.
|-
| <code>max(value1 [, value2])</code> || Maximum of one or more numeric arguments.
|-
| <code>min(value1 [, value2])</code> || Minimum of one or more numeric arguments.
|-
| <code>random()</code> || Random float from zero, inclusive, to one, exclusive.
|-
| <code>random(maximum)</code> || Random float between zero and <code>maximum</code>; reversed bounds are normalized.
|-
| <code>random(minimum, maximum)</code> || Random float between the two bounds; reversed bounds are normalized.
|-
| <code>random_int(maximum)</code> || Random integer from zero, inclusive, to <code>maximum</code>, exclusive. Maximum must be greater than zero.
|-
| <code>random_int(minimum, maximum)</code> || Random integer from <code>minimum</code>, inclusive, to <code>maximum</code>, exclusive. Maximum must be greater than minimum.
|-
| <code>remap(value, input_min, input_max, output_min, output_max)</code> || Unclamped mapping between numeric ranges. Equal input bounds are invalid.
|-
| <code>round(value)</code> || Rounds a numeric value to the nearest integer using the runtime's midpoint rule.
|-
| <code>shuffle(key, count)</code> || Returns every integer in <code>0..count-1</code> once in random order, then refills and reshuffles that key's bag. Count must be positive.
|-
| <code>string(value)</code> || Converts a value to invariant text.
|-
| <code>time()</code> || Current scaled game time in seconds.
|}

The table has 20 function names; overload rows show the accepted forms of <code>random</code> and <code>random_int</code>. A wrong argument count or incompatible value reports a runtime diagnostic and produces no usable value.

Without <code>seed</code>, each map runtime starts with fresh random entropy. A declared seed makes <code>random</code>, <code>random_int</code>, and shuffle refills repeatable for the same execution order. Use a stable string key for a shared shuffle bag. Inside a module, <code>shuffle(self, count)</code> gives each expanded module instance its own bag.

=== Statement reference ===

{| class="wikitable"
! Form !! Purpose
|-
| <code>target.input</code> or <code>target.input(arguments)</code> || Invoke an entity, group, or module input.
|-
| <code>call procedure(arguments)</code> || Run a top-level procedure and wait for it to return.
|-
| <code>local_input(arguments)</code> || Invoke an input or procedure inside the current module instance.
|-
| <code>name = expression</code> || Assign a map <code>var</code> or module <code>state</code>. Constants and parameters are immutable.
|-
| <code>if</code> / <code>elif</code> / <code>else</code> || Run one conditional branch.
|-
| <code>match</code> / <code>case</code> / <code>default</code> || Run the first equal case or the default branch.
|-
| <code>wait duration</code> || Suspend only the current handler, procedure, or scheduled block.
|-
| <code>schedule name after duration:</code> || Start or replace one named delayed task.
|-
| <code>schedule name every duration [times count]:</code> || Start or replace one named repeating task.
|-
| <code>cancel name</code> || Stop a named task if it exists.
|-
| <code>emit output(arguments)</code> || Emit a declared module output.
|-
| <code>server_command(expression)</code> || Run one allowlisted command from server authority.
|}

== 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.

== Choose server or client authority ==

Handlers run on the server unless they begin with <code>client</code>. Use server handlers for rules, collision, objectives, and state changes. Use client handlers only for presentation entities whose contract allows client access.

<syntaxhighlight lang="text">
ref trigger: trigger_multiple match Trigger
ref door: func_door match Door
ref local_audio: env_ambient match LocalAudio

server on trigger.start_touch:
    door.open

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

Calls made by a handler keep that handler's authority. The compiler checks every entity input and output against its access rules. <code>server_command()</code> works only from server authority.

== Procedures, waits, 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>

=== Procedures and wait ===

A procedure declaration uses <code>def</code>, typed parameters, and optional defaults. <code>call</code> runs it inline: the caller resumes only after the procedure and all of its waits complete. Direct or indirect recursive calls are rejected at runtime.

<code>wait duration</code> evaluates a non-negative duration once and suspends only the current execution chain. Other handlers and named schedules continue. A zero duration resumes on the next frame. A wait has no task name and cannot be cancelled independently; put the work in a named schedule when it needs a cancellation handle.

=== Schedule syntax ===

One-shot form:

<syntaxhighlight lang="text">
schedule open_warning after 750ms:
    warning_light.on
    call announce("Door opening")
</syntaxhighlight>

Repeating forms:

<syntaxhighlight lang="text">
schedule heartbeat every 1s:
    light.toggle

schedule countdown every 1s times 10:
    counter.subtract(1)
</syntaxhighlight>

The schedule name must be an identifier. The interval and optional count are expressions, so they can read constants, variables, module state, parameters, and built-in functions. <code>after</code> cannot use <code>times</code>.

{| class="wikitable"
! Rule !! Runtime behavior
|-
| First execution || Both <code>after</code> and <code>every</code> wait for the interval before running the block. Neither form runs immediately.
|-
| Duration || Negative or non-numeric durations stop the task with a diagnostic. Zero waits until the next frame.
|-
| Repeat count || A positive integer runs exactly that many times. Zero schedules nothing. A negative integer repeats until cancellation or map unload. Omitting <code>times</code> from <code>every</code> is the same as an unlimited negative count.
|-
| Dynamic interval || An <code>every</code> interval is re-evaluated before each iteration. <code>every random(0.5s, 1.5s)</code> therefore chooses a new delay each time.
|-
| Deadline timing || Repeating schedules anchor each short wait to the previous scaled-time deadline, so ordinary frame overshoot does not accumulate into timer drift.
|-
| Long overruns || If a block, nested procedure, or wait runs past its next deadline, the scheduler coalesces the missed time and waits one fresh interval. It does not burst missed executions in one frame.
|-
| Replacement || Starting a schedule automatically cancels the task with the same name before registering the new one.
|-
| Cancellation || <code>cancel name</code> stops the delay or running block. Cancelling a missing task is safe.
|-
| Locals and context || The task copies the handler or procedure's parameter values and preserves authority plus <code>!activator</code>, <code>!caller</code>, and <code>!self</code>. Map variables and module state remain live shared state.
|-
| Module scope || Schedule names declared inside a module are private to each expanded module instance. Two instances can both run <code>timer_loop</code> without replacing each other.
|-
| Lifetime || All tasks stop when the map VSig runtime unloads.
|}

This replacement behavior makes debounce straightforward:

<syntaxhighlight lang="text">
on trigger.trigger:
    schedule close_after_quiet after 2s:
        door.close
</syntaxhighlight>

Every new trigger restarts the two-second delay because it replaces <code>close_after_quiet</code>.

=== Milestone timelines ===

Use parallel one-shot schedules when a stage has actions at specific times. Each deadline is measured from the event that starts the stage; it does not depend on a repeating timer's frame-measured elapsed value.

<syntaxhighlight lang="text">
ref zombie_teleport: trigger_teleport match ZombieTeleport
ref spawn_door: func_door match SpawnDoor
ref zombie_door: func_door match ZombieDoor

on round.pre_round:
    schedule island_intro after 1s:
        server_command("gm_message major Defend this island for 90 seconds")

    schedule island_warning after 80s:
        server_command("gm_message major 10 seconds until the gates open")

    schedule island_open after 90s:
        server_command("gm_message major The gates are open. GOGOGO")
        zombie_teleport.enable
        spawn_door.open

    schedule island_release after 115s:
        zombie_teleport.disable
        zombie_door.open
</syntaxhighlight>

Running this handler again replaces all four named tasks and restarts the timeline. Give unrelated timelines distinct task names. Use an explicit guard such as a relay or latch when a repeatable entity output must not restart a stage.

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

<syntaxhighlight lang="text">
on round.post_round:
    cancel heartbeat
    cancel countdown
</syntaxhighlight>

== Reusable modules ==

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

<syntaxhighlight lang="text">
module capture_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 capture_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; read it 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.

=== Standard logic library ===

The twelve standard logic modules are built into VSig. No library file, copy, or import is required. They work in both Vertex maps and existing Unity-authored maps. <code>use</code> creates an instance with its own state:

<syntaxhighlight lang="text">
use counter as captures(max_value = 5)
</syntaxhighlight>

Give every instance a unique alias; using the same alias twice is an error. Explicitly declared or imported custom modules take precedence over built-ins with the same name. Game-specific modules such as <code>spawn_door_set</code> still need their own library import.

Existing imports remain compatible, including <code>Logic.vsiglib</code>, <code>Packages/com.vellocet.sdk/Runtime/VSig/Libraries/Logic.vsiglib</code>, and <code>Packages/com.vellocet.vertex/Runtime/VSig/Libraries/Logic.vsiglib</code>. You can remove those imports when using the standard modules. An explicitly supplied custom library at one of those paths keeps its own definitions.

These modules are compiled logic. They do not create GameObjects or network objects. Recompile a map after changing its script so its embedded program is updated.

{| class="wikitable"
! Module !! Use
|-
| <code>counter</code> || Add, subtract, set, clamp, and report a numeric value.
|-
| <code>accumulator</code> || Maintain an unclamped numeric total.
|-
| <code>relay</code> || Gate, delay, or limit a string signal to one trigger.
|-
| <code>timer</code> || Emit indexed ticks at fixed or randomized intervals.
|-
| <code>selector</code> || Route a string to one of eight configured cases.
|-
| <code>random_selector</code> || Pick a zero-based random or shuffled index.
|-
| <code>sequence</code> || Walk an integer range once or in a loop.
|-
| <code>latch</code> || Model idempotent set and clear transitions.
|-
| <code>toggle</code> || Store, flip, or directly set a boolean value.
|-
| <code>state_machine</code> || Track named state transitions and their previous value.
|-
| <code>debounce</code> || Emit only after a quiet delay following the latest trigger.
|-
| <code>cooldown</code> || Accept one trigger, then reject triggers until ready again.
|}

==== <code>counter</code> ====

<code>counter(start: float = 0, min_value: float = 0, max_value: float = 1, step: float = 1, clamp_value: bool = true)</code>

The exported <code>value</code> state starts at <code>start</code>. Each input that applies a value emits <code>changed(value)</code>. It then emits <code>min_reached(value)</code> when the result is at or below <code>min_value</code> and <code>max_reached(value)</code> when it is at or above <code>max_value</code>. When <code>clamp_value</code> is true, applied values are clamped to the configured range.

{| class="wikitable"
! Input !! Behavior
|-
| <code>add(amount: float = step)</code> || Add <code>amount</code> to the current value.
|-
| <code>subtract(amount: float = step)</code> || Subtract <code>amount</code> from the current value.
|-
| <code>set(next_value: float)</code> || Replace the current value.
|-
| <code>reset</code> || Apply the configured <code>start</code> value.
|}

==== <code>accumulator</code> ====

<code>accumulator(start: float = 0)</code> exports its current <code>value</code>. <code>add(amount: float)</code>, <code>set(next_value: float)</code>, and <code>reset</code> update that value and emit <code>changed(value: float)</code>. It does not clamp or emit threshold signals; use <code>counter</code> when a range matters.

==== <code>relay</code> ====

<code>relay(enabled_on_load: bool = true, trigger_once: bool = false, delay: float = 0)</code> exports <code>enabled</code> and <code>fired</code> state. An accepted <code>trigger(value: string = "")</code> emits <code>triggered(value: string)</code> immediately or after <code>delay</code>. A new delayed trigger replaces the instance's pending delayed emission.

{| class="wikitable"
! Input !! Behavior
|-
| <code>trigger(value: string = "")</code> || Emit only while enabled and, when <code>trigger_once</code> is true, only before the instance has fired.
|-
| <code>enable</code> || Accept later triggers.
|-
| <code>disable</code> || Reject later triggers and cancel a pending delayed emission.
|-
| <code>reset</code> || Clear <code>fired</code> and cancel a pending delayed emission without changing <code>enabled</code>.
|}

==== <code>timer</code> ====

<code>timer(interval: float = 1s, times: int = -1, lower_bound: float = interval, upper_bound: float = interval, start_on_load: bool = false)</code>

Use <code>timer.tick</code> for recurring gameplay milestones. Its one-based integer <code>index</code> advances exactly once for every delivered tick. The <code>elapsed</code> value remains available for display, progress, and diagnostics, but it is measured scaled frame time and is not guaranteed to equal a whole number.

<syntaxhighlight lang="text">
ref gate: func_door match Gate

use timer as gate_timer(interval = 1s, times = 90, start_on_load = false)

on round.live:
    gate_timer.restart

on gate_timer.tick(index: int, elapsed: float, remaining: int):
    if index == 80:
        server_command("gm_message major 10 seconds until the gates open")
    if index == 90:
        gate.open

on round.post_round:
    gate_timer.reset
</syntaxhighlight>

Do not compare <code>elapsed</code> with exact equality, such as <code>elapsed == 90</code>, because a frame may deliver the tick at <code>90.016</code>. The compiler reports <code>VSIG_TIMER_ELAPSED_EQUALITY</code> when a timer elapsed parameter is used with <code>==</code>, <code>!=</code>, or as the direct value of a <code>match</code> block.

{| class="wikitable"
! Input !! Behavior
|-
| <code>start</code> || Start a reset timer or resume a stopped timer from its preserved elapsed time, index, and remaining count. Calling it while running is safe and does nothing.
|-
| <code>stop</code> || Cancel the active wait while preserving elapsed time, index, and remaining count.
|-
| <code>restart</code> || Cancel, reset to index zero, and start from the beginning.
|-
| <code>reset</code> || Cancel and restore elapsed time and index to zero without starting.
|-
| <code>fire</code> || Emit <code>tick</code> immediately and advance the index without consuming a scheduled repeat.
|-
| <code>toggle</code> || Stop a running timer or start/resume a stopped timer.
|-
| <code>set_interval(value: float)</code> || Set one fixed non-negative interval for later waits.
|-
| <code>set_random_bounds(lower: float, upper: float)</code> || Set normalized non-negative bounds; each wait samples a fresh interval.
|-
| <code>set_times(value: int)</code> || Set the repeat count used by the next reset. When the timer is stopped, also replace its current remaining count. A negative count repeats until stopped or unloaded.
|}

A finite timer emits <code>finished()</code> after its last scheduled <code>tick(index: int, elapsed: float, remaining: int)</code>. Call <code>restart</code>, not <code>start</code>, to run a completed timer again. The exported <code>running</code>, <code>remaining</code>, <code>tick_index</code>, and <code>elapsed</code> states report status. <code>started_at</code>, <code>current_interval</code>, <code>current_lower_bound</code>, <code>current_upper_bound</code>, and <code>repeat_count</code> expose the backing schedule configuration; prefer the timer inputs when changing it.

==== <code>selector</code> ====

<code>selector(case_1: string = "", case_2: string = "", case_3: string = "", case_4: string = "", case_5: string = "", case_6: string = "", case_7: string = "", case_8: string = "")</code> compares <code>select(value: string)</code> with the configured cases in order. The first match emits <code>selected(index: int, value: string)</code> with a one-based case index. No match emits <code>defaulted(value: string)</code>. The module has no state.

==== <code>random_selector</code> ====

<code>random_selector(count: int = 2, shuffle_mode: bool = false)</code> exposes <code>pick</code> and emits <code>selected(index: int)</code> with a zero-based index from <code>0</code> through <code>count - 1</code>. The exported <code>last</code> state starts at <code>-1</code> and records the last emitted index. <code>count</code> must be positive.

With <code>shuffle_mode = false</code>, each pick is independent. With <code>shuffle_mode = true</code>, the instance emits every index once in randomized order before refilling its private shuffle bag.

==== <code>sequence</code> ====

<code>sequence(length: int = 1, start_index: int = 0, loop: bool = false)</code> exports its current <code>index</code>. While <code>index &lt; length</code>, <code>next</code> emits <code>step(index: int)</code> and advances the index. Reaching the exclusive <code>length</code> emits <code>finished()</code>; a looping sequence then returns to <code>start_index</code>. <code>reset</code> returns to <code>start_index</code> without emitting an output.

==== <code>latch</code> ====

<code>latch(initial: bool = false)</code> exports <code>active</code> state and represents idempotent set/clear transitions.

{| class="wikitable"
! Input !! Outputs
|-
| <code>set</code> || When inactive, set active and emit <code>latched()</code> followed by <code>changed(true)</code>. When already active, emit nothing.
|-
| <code>clear</code> || When active, clear active and emit <code>released()</code> followed by <code>changed(false)</code>. When already inactive, emit nothing.
|-
| <code>reset</code> || Restore <code>initial</code> and emit <code>changed(active)</code>.
|}

==== <code>toggle</code> ====

<code>toggle(initial: bool = false)</code> exports boolean <code>value</code> state. <code>flip</code> inverts it, <code>set(value_to_set: bool)</code> replaces it, and <code>reset</code> restores <code>initial</code>. Every input emits <code>changed(value: bool)</code>, including <code>set</code> when the supplied value already matches.

==== <code>state_machine</code> ====

<code>state_machine(initial: string = "")</code> exports <code>current</code> and <code>previous</code> state. <code>set(next: string)</code> does nothing when <code>next</code> equals <code>current</code>. A real transition updates both states, then emits <code>exited(previous: string)</code>, <code>entered(current: string)</code>, and <code>changed(previous: string, current: string)</code> in that order. <code>reset</code> records the old current value as <code>previous</code>, restores <code>initial</code>, and emits only <code>changed(previous, current)</code>.

==== <code>debounce</code> ====

<code>debounce(delay: float = 0.1s)</code> exposes <code>trigger(value: string = "")</code> and <code>cancel</code>. Each trigger replaces the pending wait. If no newer trigger or cancellation arrives during <code>delay</code>, the module emits <code>fired(value: string)</code> with the latest payload. It has no exported state.

==== <code>cooldown</code> ====

<code>cooldown(duration: float = 1s, ready_on_load: bool = true)</code> exports <code>ready</code> state. While ready, <code>trigger(value: string = "")</code> clears readiness, emits <code>fired(value: string)</code>, waits for <code>duration</code>, restores readiness, and emits <code>became_ready()</code>. Triggers received while not ready do nothing. <code>reset</code> cancels the wait, sets ready, and emits <code>became_ready()</code> immediately.

=== Shipped spatial helper ===

Grimwar's Order and Union spawn-door prefabs include a <code>logic_script</code> host for <code>spawn_door_set</code>. Place one from Vertex's Prefabs browser. It binds the trigger, matching doors, and audio under that instance; you do not need a source-level import in the map script.

The helper exposes <code>restore_initial_state</code>, <code>enable</code>, and <code>disable</code>. Give the host a unique explicit alias if the map script needs to call it. Keep the assembly's expected child hierarchy when editing it.

== 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 map should configure a module without a source-level <code>use</code>. Set the <code>.vsiglib</code>, module name, alias, arguments, and local-ref binding mode on the marker. The compiler expands it into the same form as a written <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.on

on round.pre_round:
    round_timer.reset

on round.live:
    round_timer.start

client 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. The runtime restores changed console variables 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.

== Snapshot a participant zone ==

<code>trigger_multiple.execute</code> captures the participants currently inside the volume and emits <code>executed</code> with an opaque snapshot token. Use it for extraction zones and other one-shot outcomes that a VMod must award to specific occupants.

Name the trigger and the entity that completes the objective, then connect them in the scene script:

<syntaxhighlight lang="text">
ref extraction_zone: trigger_multiple match ExtractionZone
ref extraction_door: func_door match ExtractionDoor

server on extraction_door.close:
    extraction_zone.execute
</syntaxhighlight>

Set '''Allowed Activators''' and '''Allowed Teams''' on the trigger so the snapshot includes only the intended participants. The <code>close</code> output occurs after the door finishes closing. <code>execute</code> still emits an empty snapshot when nobody is inside, which lets the game mode resolve a failed extraction deterministically.

The subscribed VMod must call <code>context.VSig.GetParticipantSnapshot(token)</code> during the matching callback. The token expires when signal dispatch returns. See [[Grimwar/VMod reference#Send signals to VSig|Send signals to VSig]] for the callback and objective-award example.

== Signals shared with VMod ==

VMods can emit a source under <code>mod:&lt;mod-id&gt;</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 test ==

Use the Code workspace to resolve syntax and binding errors, then build through '''Play in Game''' or '''Export add-on'''. The build validates against the entities captured for that map and embeds the compiled program. Save external source edits before starting the build.

Check wildcard matches, exercise round handlers more than once, and cancel repeating schedules at their intended lifecycle boundary. Editing loose source beside an installed package does not change the compiled map.

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