Skip to content
KILLSCRIPT Docs

Module structure

A folder module is a regular directory under Modules. A minimal client project looks like this:

MyModule/
├── module.json
└── scripts/
    └── main.lua

The game also creates asset directories and editor settings:

MyModule/
├── module.json
├── config.json          # optional
├── inputs.json          # optional
├── localization.csv     # optional
├── images/
├── sounds/
├── scripts/
│   ├── main.lua
│   └── server.lua       # Reflex only
├── ui/                  # add when needed
└── .vscode/

Main files

Section titled “Main files”
Path Purpose
module.json Required metadata and module type.
scripts/main.lua Client entry point.
scripts/server.lua Server side of a Reflex module.
config.json Settings exposed to the user.
inputs.json Custom actions and their initial bindings.
localization.csv Module strings in multiple languages.

See Config, InputAction, and Localization for the optional file formats. The roles of main.lua and server.lua are explained in Reflex architecture, while organizing Lua code covers additional client files.

module.json

Section titled “module.json”

Example metadata for a regular module:

{
  "Id": "d70e52dc-2fa0-4b53-a040-a36c987b9adb",
  "Name": "MyModule",
  "Version": "0.1.0",
  "Author": "YourName",
  "Description": "My first KILLSCRIPT module",
  "IsReflex": false,
  "Tags": []
}
Field Meaning
Id Unique identifier generated by the game.
Name Display name of the module.
Version Module version.
Author Author name.
Description Short description or null.
IsReflex true when the module has a server side.
Tags Functional categories of the module.

Do not copy one Id across separate projects. Creating a new module through the game generates a new identifier automatically.

Tags

Section titled “Tags”

Tags help the game detect modules that cover the same feature. A shared tag produces a possible-conflict warning but does not prevent both modules from running.

Tag Purpose
Minimap Minimap
PingMarks Markers and pings
OverheadLabels Labels above objects
Crosshair Crosshair
Health Health display
Notifications Notifications
MatchStatus Match state
CombatReport Combat report
Scoreboard Scoreboard
Loadout Equipment
BuyMenu Buy menu
GrenadePreview Grenade preview
Chat Chat
ThreatIndicator Threat indicators
KillFeed Kill feed
Spectator Spectator UI
DebugInfo Debug information

Assets

Section titled “Assets”
Directory Supported files
images/ .png, .jpg, .jpeg
sounds/ .wav, .mp3, .ogg
scripts/ .lua
ui/ .uxml, .uss

Special images:

  • images/Icon.png — module icon;
  • images/DescriptionImage.png — image shown in the detailed description.

Keep their exact names and casing. Image path behavior is covered in Texture.

Size limits

Section titled “Size limits”
  • one asset file: up to 10 MiB;
  • entire module: up to 50 MiB;
  • config.json: up to 64 KiB.

Individual APIs may apply additional limits. The texture loader, for example, also checks image format and dimensions.

Lua environment

Section titled “Lua environment”

Module code runs in a restricted Lua environment rather than a full system Lua installation. It includes game globals and a small standard subset:

  • functions: print, tostring, tonumber, pairs, ipairs, setmetatable;
  • client-side require for additional files under scripts/;
  • libraries: string, math, table, coroutine.

Do not assume that other standard globals exist. In particular, pcall and type are unavailable. Game API availability also differs between the client and Reflex server contexts.