GUI directives
GUI directives are special comments that expose your script's settings to the AimForge UI. They are parsed before execution and create live controls (sliders, dropdowns, color pickers, buttons) bound to the settings.* object.
All directives start with //!gui: followed by the directive name and attributes.
//!gui:slider var=strength label="Aim Strength" min=0 max=1 default=0.5
The user-facing UI shows a slider labelled "Aim Strength". Your script reads its value with settings.strength.
Available directives
| Directive | Purpose |
|---|---|
slider |
Numeric slider |
number |
Numeric input field |
checkbox |
Boolean toggle (0 or 1) |
dropdown |
Multi-choice selector |
text |
Text input field |
color |
Color picker (returns #RRGGBB) |
button |
Triggers a user function or sets a variable |
chart |
Live chart populated via setChartData() |
label |
Static text label |
paragraph |
Multi-line description |
section / endsection |
Collapsible group |
grid / endgrid |
Layout grid for nested controls |
image |
Embedded image |
list |
Dynamic list control |
region |
Debug visualization region |
config |
Script-level configuration (header, sidebar width, etc.) |
Common attributes
| Attribute | Description |
|---|---|
var=name |
Variable bound to this control. Read as settings.name. |
label="Text" |
User-visible label. Use quotes if it contains spaces. |
default=value |
Initial value. |
min=0 max=1 step=0.01 |
Numeric range (sliders, numbers). |
options="a,b,c" |
Comma-separated dropdown options. |
cols=4 |
Layout width (out of 12). |
condition="gpc=='mouse'" |
Only show this control if expression evaluates true. |
Examples
A slider with a custom symbol:
//!gui:slider var=fovScale label="FOV" min=0.5 max=2 default=1 step=0.1 symbol="x"
A dropdown:
//!gui:dropdown var=mode label="Mode" options="off,subtle,aggressive" default=1
A button that calls a user function:
//!gui:button label="Reset state" func="resetState"
function resetState() {
state.i = 0;
state.history = [];
return 0;
}
A collapsible section:
//!gui:section label="Advanced" mode="collapsed"
//!gui:slider var=kP min=0 max=2 default=1
//!gui:slider var=kI min=0 max=0.1 default=0.005
//!gui:endsection
A conditional control (only shown when a specific device is active):
//!gui:slider var=stickDeadzone min=0 max=20 default=5 condition="device=='controller'"