DocumentationBot: Publish SDK documentation

2026-08-25T05:12:57Z

Publish SDK documentation

New page

{{GameNav}}
{{Notice|title=Version target|This guide covers the VSig compiler and standard library included with Vellocet SDK 1.0.3.}}

'''VSig''' is Grimwar's map-logic language. A VSig program listens to entity or game outputs, changes state, calls entity inputs, schedules work, and exchanges bounded signals with VMods. The Map Exporter validates and compiles it into the map package.

Use VSig for map orchestration. Use an entity marker when the thing has a position, volume, renderer, collider, or native game behavior. Use [[Grimwar/VMod|VMod]] for server rules that need players, commands, persistent storage, permissions, or game-mode control.

== Create the map script ==

A map scene and its VSig source share a name and folder:

<syntaxhighlight lang="text">
Assets/CustomContent/Maps/Range/Range.unity
Assets/CustomContent/Maps/Range/Range.vsig
</syntaxhighlight>

Create a script with '''Assets > Create > Vellocet > SDK > VSig Script'''. A marker Inspector can also create or open the current scene's file and insert refs for selected entities.

Install syntax support from '''SDK Workbench > Project > VSig Editor Support'''. Unity still performs the authoritative parse and validation.

== First working script ==

<syntaxhighlight lang="text">
scene "Example"

ref trigger: trigger_multiple match Triggers/Entrance
ref door: func_door match Doors/MainDoor

var door_start: DoorEntityState = null

once on map.ready:
door_start = door.state

on trigger.start_touch:
door.open

on trigger.end_touch_all:
door.restore(door_start)
</syntaxhighlight>

The two <code>ref</code> declarations bind authored markers to short aliases. <code>map.ready</code> runs after server-side map entities are bound. The trigger's <code>start_touch</code> output calls the door's <code>open</code> input. The script captures the starting door state once and restores it after the last toucher leaves.

Marker Inspectors list the inputs, outputs, state type, and access rules for that entity class. Use that contract instead of guessing a signal name.

== 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 GameObject names make refs readable and keep wildcard matches predictable. A marker's hidden runtime ID is managed by the SDK; VSig authoring uses the object hierarchy and entity class.

== 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 include arithmetic, comparisons, <code>and</code>, <code>or</code>, and <code>not</code>. Built-in functions include:

* <code>min</code>, <code>max</code>, <code>clamp</code>, <code>abs</code>, <code>floor</code>, <code>ceil</code>, and <code>round</code>
* <code>lerp</code> and <code>remap</code>
* <code>random</code>, <code>random_int</code>, <code>shuffle</code>, and <code>choose</code>
* <code>time</code>, <code>format</code>, and <code>convar</code>
* <code>bool</code>, <code>int</code>, <code>float</code>, and <code>string</code> conversions

Without <code>seed</code>, each map runtime starts with fresh random entropy. A declared seed makes random sequences repeatable. <code>shuffle(self, count)</code> gives each module instance its own shuffle bag.

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

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

<code>wait</code> suspends the current handler or procedure. <code>schedule name after duration</code> runs once. <code>schedule name every duration</code> repeats, and <code>times</code> limits the count. Starting a named schedule replaces the existing task with that name. Cancelling a task that is not running is safe.

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

== Reusable modules ==

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

<syntaxhighlight lang="text">
module 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 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 and can be inspected 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:

<syntaxhighlight lang="text">
from "Packages/com.vellocet.sdk/Runtime/VSig/Libraries/Logic.vsiglib" use counter
use counter as captures(max_value = 5)
</syntaxhighlight>

The standard logic library contains <code>counter</code>, <code>accumulator</code>, <code>relay</code>, <code>timer</code>, <code>selector</code>, <code>random_selector</code>, <code>sequence</code>, <code>latch</code>, <code>toggle</code>, <code>state_machine</code>, <code>debounce</code>, and <code>cooldown</code>.

These modules are compiled logic. They do not create GameObjects or network objects.

== 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 designer should choose a module and its arguments in the scene Inspector. Select the <code>.vsiglib</code>, module name, alias, arguments, and local-ref binding mode. The compiler expands the marker into the same form as a source-authored <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.enable

on round.pre_round:
round_timer.reset

on round.live:
round_timer.start

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. Any changed console variable is restored 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.

== Signals shared with VMod ==

VMods can emit a source under <code>mod:<mod-id></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 debug ==

Press Play for quick testing. The compiled VSig runtime Inspector shows validation state, live module state, scheduled tasks, and a bounded recent-event trace. Marker Inspectors can show signal routes and add selected refs or a group to the paired script.

Before export:

# Save the scene and VSig file.
# Resolve parser, type, ref, module, and entity-contract diagnostics.
# Check wildcard refs against the final hierarchy.
# Exercise each round-phase handler more than once.
# Confirm repeating schedules stop at the intended lifecycle boundary.
# Run '''Compile Scene''' in the Map Exporter before building the addon package.

The exporter expands imported modules, validates the final program, and embeds a compact compiled program in the map. A Release export refuses incomplete required bakes or invalid VSig.

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

Grimwar/VSig - Revision history

DocumentationBot: Publish SDK documentation