Skip to content
aqua!v2docs

Script workspace

Scripts live in isolated subdirectories under the config folder:

  • Base directory: ~/.config/nvidia/scripts/
  • Layout: 
    ~/.config/nvidia/scripts/
    ├── my_esp_script/
    │   ├── main.lua
    │   ├── script.json           # optional title, description, author, version, icon
    │   ├── icon.png              # optional 128 x 128 icon
    │   └── img/                  # optional assets for aqua.draw.image
    │       ├── icons/*.png
    │       └── weapons/*.png
    └── ...
  • Entry point: must be named exactly main.lua.
  • Multi-file: other .lua files under the script folder are editable as file tabs in the workspace (create with +, rename/delete via right-click; main.lua is protected).
  • PNG assets: any subfolder under the script root; see aqua.draw.image.
  • UI (Scripts tab):
    • Script list: grouped Running / Idle, filter, status, hover actions, inline folder rename and hold-to-delete.
    • OPTIONS: the script’s controls use the same cards and controls as the built-in menu. Run on load and Enable FFI sit in a separate strip beneath the header.
    • CODE: file tabs, JetBrains Mono editor, Save / Ctrl+S, Run / Stop, scrollbars with current-line and error markers, and a maximise button that hides the list.
    • CONSOLE / PROBLEMS: collapsible output, this-script / all filter, clear, and clickable error locations.
    • The ... menu offers folder rename, duplication, Open folder, Reload from disk and hold-to-delete. Reload asks before replacing a dirty open buffer. Renaming saves all edited buffers first.
  • Auto-run: the independent Run on load switch stores Scripts.<name>.AutoRun. Run / Stop controls the current session without changing that preference. Profile switches apply that profile’s AutoRun settings. Renaming migrates the AutoRun and FFI preferences. A duplicate starts stopped with FFI disabled.

Optional script.json sits beside main.lua:

{
  "title": "My script",
  "description": "What this script does.",
  "author": "Your name",
  "version": "1.0",
  "icon": "icon.png"
}

The list and header show title, falling back to the folder name. The description falls back to the first nonblank comment in main.lua. The header keeps the folder, author and version visible. A relative PNG icon replaces the name’s two-letter tile; 128 x 128 is recommended. Missing or invalid metadata and icons use the fallbacks. The empty Scripts page stays empty until you create or install a script.

External edits to the open file refresh the editor buffer (throttled) when the buffer is not dirty.