Split/Second Modding

Lua scripting docs for sshook mods.

A mod for the PC build can carry a Scripts\main.lua next to its assets. The hook runs it in its own LuaJIT state when the game starts and gives it one global, ss. Through that you can listen to the race, read and write the cars, the players and the level's props as live objects, draw over the frame, and poke at the game's tweak tree and raw memory when nothing else will do.

Mods\MyMod\Scripts\main.lua

ss.on("race_start", function(ev)
  ss.log("green light: %s on %s", ev.mode, ss.race.track.level)
end)

ss.on("lap_time", function(ev)
  if ev.is_local and ev.is_best then
    ss.log("new best lap: %.3f s", ev.time)
  end
end)

ss.every(1, function()
  local car = ss.vehicle                      -- nil outside a race
  if car and car.speed_kmh > 300 then
    car:impulse(car.up * car.mass * 2)        -- a 2 m/s hop
  end
end)

Start with Installing and Your first mod. Then read Live objects once, because every object in the reference works the same way. The search box finds pages, sections and every property in the tables.

Getting started

InstallingWhat you need on disk: lua51.dll, a Mods folder, and a Scripts\main.lua in your mod.
Your first modA main.lua that logs, listens to the race and runs a timer, plus the rules it runs under.
The sample modsMagnet and Trucks, the two mods that ship with the hook, with the code and what it does.
Testing a modRunning a race without sitting at the keyboard, what a dev-boot race won't do, and where the log goes.

Concepts

Live objectsCars, players, props and the race are proxies. Read a property and you read the game. Assign it and you write it.
Game and race statesThe app state, the race state machine and the vehicle states, with the names the events use.
Coordinates and anglesWorld axes, a car's own frame, and how pitch, yaw and roll get applied.
Positions and scoresWhere a player's place in the field actually comes from, and why a plain race has no score.
Checkpoints and lap timesThe game has no sectors, so checkpoints are splits along the route. Lap times come from the Laps component.
Countdowns and finishingThe grid countdown, the mode timers the HUD shows, and the rules that end a player's race.

Reference

ssThe global everything hangs off: logging, handlers, timers, the mod, the clock, signals.
EventsEvery event you can listen to, with the fields in its payload.
RoutinesCoroutines that wait on the game mid-flow, so you don't need a handler per step.
ss.raceThe running race: mode, track, state, clock, local player, checkpoint splits.
ss.playersThe players as live objects: position, lap, progress, score, timers, the finish.
ss.vehiclesThe cars: position, rotation, velocity, impulses, and how a move goes through the game's own respawn.
vehicle.inputA car's controls as the physics sees them, holding them from a script, and the raw input record.
ss.vec3Vectors, the live vectors objects hand out, and what counts as vector-like.
ss.propsThe movable props in a level: bollards, barrels, boxes, signs, and the multi-part breakables.
ss.nemesisSurvival's trucks and the attack modes' cars, in any race you like.
ss.drawText, boxes, lines and images painted over the frame after the game's HUD.
ss.uiWidgets on the billboards of sshook's custom front-end screens.
ss.dataA table that survives between runs, saved to the mod's save.lua.
ss.memRaw memory access with a guard on reads, per-object offsets, and the offsets found so far.
ss.paramsThe game's tweak tree as nested properties. Every params key and game_setup value, live.
TypesWhat the API takes and gives back: numbers, vectors, colours, handler ids and so on.