SDK v2

Modding SDK

A mod is a single folder. It can carry any mix of content: training scenarios, sound packs, interface themes, skyboxes and textures. This page describes SDK version 2, the one in the current beta build.

Status: mods already load from a local folder. Steam Workshop (browsing, subscribing, publishing from the game) opens with the Steam release.

Getting started

Open Documents/My Games/AimWorks/Mods/ (the game creates it; Mods → Open folder also opens it).
Create a folder for your mod, for example MyMod, with a mod.json inside.
Add content folders (see below) and restart the game. Your mod appears on the Mods page.

Folder layout

MyMod/
  mod.json            required
  preview.png         Workshop picture (16:9, < 1 MB)
  scenarios/*.json    training scenarios            → tag "Scenarios"
  sounds/*.wav|ogg|mp3          sound pack, any event → "Sound Packs"
  sounds/Shot|Hit|Kill|Miss|UI/  sound pack, one event
  themes/*.json       interface themes              → "Themes"
  skyboxes/*.png|jpg  equirectangular skies (2:1)    → "Skyboxes"
  textures/*.png|jpg  wall / floor textures          → "Textures"

Workshop tags are set automatically from what the folder contains, so players can filter by content type.

mod.json

{
  "id": "mymod",
  "name": "My Mod",
  "author": "you",
  "version": "1.0.0",
  "description": "What it adds",
  "sdkVersion": 2
}

After the first upload the game writes workshopId into this file, and Update in Workshop updates the same item.

Scenarios

Same format as the built-in scenarios. The player stands at the origin facing +Z; distances are in metres. Values are clamped to safe ranges when loaded. Lists like move or shape accept a name ("move": "Strafe") or a number ("move": 1).

{
  "id": "tiny_strafe",
  "name": "Tiny Strafe",
  "category": "Tracking",
  "difficulty": 3,
  "duration": 60,
  "fireMode": "Auto",
  "rpm": 600,
  "radius": 0.2,
  "health": 0,
  "maxTargets": 1,
  "move": "Strafe",
  "speedMin": 3,
  "speedMax": 5,
  "spawnCenter": { "x": 0, "y": 1.6, "z": 9 },
  "spawnSize":   { "x": 8, "y": 0.4, "z": 0 },
  "scorePerHit": 10
}

Field	Meaning
`id, name, description`	the id gets a namespace automatically: mod.<modId>.<id>
`category`	0 Tracking, 1 Clicking, 2 Switching
`difficulty`	1–5
`duration`	seconds, 10–300 (default 60)
`fireMode, rpm`	0 semi-auto, 1 full-auto; rpm 60–1200
`shape`	0 Sphere, 1 Capsule, 2 Tile, 3 Pill, 4 Duo
`radius, radiusJitter`	metres; radiusJitter 0.3 = every target is randomly 30% smaller to 30% bigger
`height, health`	pill/capsule height; health 0 = invincible
`maxTargets, layout, gridCols, gridRows`	layout 0 Random, 1 Grid
`minSpawnSeparation`	minimum distance between targets, metres
`spawnCenter, spawnSize`	{"x":0,"y":1.6,"z":10}
`move`	0 Static, 1 Strafe, 2 Smooth, 3 Bounce, 4 Drift, 5 Arc, 6 Air
`speedMin, speedMax, changeMin, changeMax`	speed in m/s; direction change every changeMin–changeMax seconds
`driftTurns, verticalAmp, gravity, startLeft`	driftTurns: Drift targets turn sharply; gravity for Bounce
`scorePerHit, scorePerKill, killTimeBonus, penalizeMiss, missPenalty`	scoring
`room`	studio, neon, hangar, skydeck, bunker, arena, courtyard, void

Mod scenarios never submit to the official leaderboards or the ELO rating.

Themes

A theme recolors the whole interface. Colors are HTML hex with optional alpha (#RRGGBBAA). Any field you leave out keeps the stock AimWorks color. Players pick it in Settings → General → Interface theme; it applies after a restart.

{
  "id": "sunset",
  "name": "Sunset",
  "accent": "#FF7A45",
  "accentBright": "#FFA67D",
  "cyan": "#FFD166",
  "bg": "#140A08EB",
  "panel": "#21110DEB",
  "panelLight": "#2E1913F2",
  "stroke": "#FF7A4538",
  "text": "#FFF4EE",
  "textDim": "#D9B8A8",
  "textMuted": "#8C6E62",
  "good": "#52E08F",
  "warn": "#FFC24D",
  "bad": "#FF4D5E",
  "gold": "#FFD24D"
}

Sound packs

Files in sounds/ are offered for every event. Files in sounds/Shot, Hit, Kill, Miss or UI are offered only for that event. Short, normalized WAV or OGG files work best (shots under 0.4 s). Players choose them in Settings → Audio.

Skyboxes and textures

skyboxes/: equirectangular panoramas (2:1), PNG or JPG, appear in Settings → Sky. textures/: seamless tileable images for walls and floors; the game repeats a texture every 4 metres.

Your own folders (no mod needed)

For personal use you can skip mod.json completely and drop files into Documents/My Games/AimWorks/: Sounds/ (with the same sub-folders), Music/ for the in-menu player, Skyboxes/ (panoramas, or 6-face skyboxes as a zip or folder) and Textures/.

Steam Workshop

With the Steam release, every local mod gets a Publish to Workshop button on the Mods page. Add a preview.png (16:9, under 1 MB) for the Workshop picture. Players browse and subscribe in Play → Steam Workshop; subscribed items load just like local mods after a restart.

Updates and errors

Game updates don't break mods. Fields are never renamed or removed, and the numbers of existing values never change; new fields always default to the old behaviour. Every game build is checked against this automatically.
Keep sdkVersion in mod.json at the version you wrote the mod for. If the format ever has to change, the game converts older mods on load by itself.
A mod made for a newer SDK than your game supports is not loaded; the Mods page says so.
Problems are shown, not hidden: typos in field names (with a suggestion), unknown values, out-of-range numbers and broken files appear on the Mods page and in aimworks_mods_log.txt in the Mods folder (rewritten on every start).

Rules

Only content you made yourself or have a license to share.
No real weapon or brand names, no logos, no copyrighted music.
No hateful, sexual or illegal content.
Rooms and weapons are not moddable yet.