CSP Lua API Reference Skill

Use this skill when working with CSP (Custom Shaders Patch) Lua code for Assetto Corsa.

Development Rules

NEVER use shell commands or external tools (io.popen, os.execute, etc.) to solve problems. CSP provides comprehensive APIs for most tasks.

Before implementing any functionality:

1. Check reference/lib.lua in this skill folder for existing CSP APIs
2. Use CSP's built-in functions (e.g., io.scanDir instead of dir command)
3. Only fall back to shell if absolutely no CSP API exists

Key File System APIs

From reference/lib.lua:

• io.scanDir(directory, "*.csv") - List files matching a pattern
• io.dirExists(path) - Check if directory exists
• io.fileExists(path) - Check if file exists
• io.fileSize(path) - Get file size in bytes (-1 on error)
• io.getAttributes(path) - Get file attributes (fileSize, creationTime, lastWriteTime, etc.)

Track Information

ac.getTrackID()

Returns the track identifier string (e.g., "ks_brands_hatch-gp", "daytona").

lua
1local trackId = ac.getTrackID()
2-- Returns: "ks_brands_hatch-gp"

Note: ac.getSim().trackId does NOT exist. Use ac.getTrackID() instead.

ac.getTrackDataFilename(filename)

Returns the full path to a file in the track's data folder.

lua
1local path = ac.getTrackDataFilename('traffic.json')

ac.getSim()

Returns ac.StateSim reference with information about the simulation state.

Key fields:

• sim.dt - Delta time in seconds (0 when paused, affected by replay speed)
• sim.isPaused - Simulation is paused
• sim.isOnlineRace - True if in an online session
• sim.trackLengthM - Track length in meters
• sim.time - Total time in milliseconds since AC started
• sim.gameTime - Total time in seconds since AC started
• sim.sessionTimeLeft - Remaining session time in ms
• sim.currentSessionIndex - 0-based session index
• sim.rainIntensity - Current rain intensity (0-1)
• sim.roadGrip - Current track grip (0-1)
• sim.connectedCars - Number of connected players (online)

Spline & World Coordinates

• ac.worldCoordinateToTrackProgress(vec3) - Converts world position to spline position (0-1)
• ac.trackProgressToWorldCoordinate(pos, linear) - Converts spline position to world position
• ac.getTrackSectorName(pos) - Returns the name of the sector at given spline position

Car Information

ac.getCar(index)

Returns ac.StateCar for the specified car index (0 = player).

Key fields:

• car.id - Car identifier string
• car.speedKmh - Speed in km/h
• car.splinePosition - Position on track (0-1)
• car.lapCount - Number of completed laps
• car.lapTimeMs - Current lap time in milliseconds
• car.bestLapTimeMs - Best lap time in this session (ms)
• car.gas - Throttle (0-1)
• car.brake - Brake (0-1)
• car.clutch - Clutch (0-1, 1 = fully depressed)
• car.steer - Steering angle in degrees
• car.gear - Current gear (0 = N, -1 = R)
• car.handbrake - Handbrake (0-1)
• car.isLapValid - True if current lap is considered valid by AC
• car.resetCounter - Increments each time car is reset (teleported)
• car.lastLapCutsCount - Number of cuts in the last lap
• car.collisionDepth - Depth of current collision in meters
• car.isInPitlane - True if in pitlane area
• car.racePosition - Current position in session/race

Car Events

• ac.onTrackPointCrossed(carIndex, progress, callback) - Triggered when car crosses a specific spline point
• ac.onCarCollision(carIndex, callback) - Triggered on collision
• ac.onCarJumped(carIndex, callback) - Triggered when car jumps

Hotkeys

ac.ControlButton(name, defaults)

Creates a bindable hotkey control.

lua
1local myButton = ac.ControlButton('ac-tracer/MyHotkey', {
2    keyboard = { key = ui.KeyIndex.T, ctrl = true },
3    gamepad = ac.GamepadButton.Y
4})
5
6-- Check if pressed this frame
7if myButton:pressed() then ... end
8
9-- Check if currently held
10if myButton:down() then ... end
11
12-- Render binding control in settings (UI function)
13myButton:control(vec2(120, 0))

Storage

ac.storage(layout, prefix) - PREFERRED

Advanced persistent storage with default values and automatic synchronization. This is the recommended approach.

lua
1-- Define layout with defaults (at module level)
2local config = ac.storage{
3    showTraces = true,
4    autoHide = false,
5    hideSpeed = 20,
6    colorOwn = rgb(0.2, 0.2, 0.2)
7}
8
9-- Access/Modify (automatically persists on assignment)
10if ui.checkbox('Show traces', config.showTraces) then
11    config.showTraces = not config.showTraces  -- Auto-saved!
12end
13
14config.hideSpeed = ui.slider('##speed', config.hideSpeed, 0, 100, 'Speed: %.0f')

Values can be: strings, numbers, booleans, vectors (vec2/vec3/vec4), colors (rgb/rgbm).

Note: Direct access ac.storage[key] = value only supports strings and requires manual serialization. Avoid this pattern - use the table-based approach instead.

SDK Examples

See working examples in other CSP apps:

• apps/lua/Radar/Radar.lua - Simple config with checkboxes, sliders, colors
• apps/lua/CSPDataLogger/CSPDataLogger.lua - Basic boolean/number settings

Logging & UI

ac.log(message)

Writes to CSP log.

ac.setMessage(title, description)

Shows a toast-style message in the game UI.

ac.lapTimeToString(ms, allowHours)

Utility to format milliseconds into "M:SS.ms" format.

UI & Windows

Window Types

Prefer these wrappers over ui.beginWindow / ui.endWindow as they handle crashes gracefully and provide standard styling.

ui.toolWindow(id, pos, size, noPadding, inputs, content)

Standard app window with background. Best for main app windows.

lua
1function script.windowMain(dt)
2    ui.toolWindow('MyAppMain', vec2(100, 100), vec2(400, 300), false, true, function()
3        -- Window content here
4        ui.text("Hello World")
5    end)
6end

ui.transparentWindow(id, pos, size, noPadding, inputs, content)

Window with no background. Best for HUD overlays or non-intrusive elements.

lua
1function script.windowHUD(dt)
2    -- Transparent, pass-through inputs unless interactive
3    ui.transparentWindow('MyAppHUD', vec2(0, 0), ui.windowSize(), true, false, function()
4        ui.textColored("HUD Overlay", rgbm.colors.red)
5    end)
6end

Layout Best Practices

Scrollable Areas (ui.beginChild)

Use child windows for scrollable content lists.

lua
1-- Reserve 30px at bottom for footer
2ui.beginChild('ScrollableList', vec2(0, -30), false, ui.WindowFlags.None)
3    for i = 1, 100 do
4        ui.text("Item " .. i)
5    end
6ui.endChild()
7
8-- Footer (pinned to bottom due to child height reservation)
9ui.button("Close", vec2(-1, 0)) -- -1 width = full width

Grouping & Layout

• ui.beginGroup() / ui.endGroup(): Group items to treat them as one for hover checks or same-line layout.
• ui.sameLine(offset, spacing): Place next item on the same horizontal line.
• vec2(-1, 0): Use as size to fill remaining horizontal space.

Styling

Use ui.pushFont, ui.pushStyleVar, and ui.pushStyleColor to customize look, but ALWAYS pair with ui.pop....

lua
1ui.pushFont(ui.Font.Title)
2ui.text("Title")
3ui.popFont()
4
5ui.pushStyleVar(ui.StyleVar.Alpha, 0.5)
6ui.button("Dimmed Button")
7ui.popStyleVar()

Settings Integration

ui.addSettings(params, callback)

Registers a settings window accessible via the taskbar context menu or settings apps.

lua
1ui.addSettings({
2    name = "My App Settings",
3    id = "MyAppSettings",
4    icon = ui.Icons.Settings,
5    size = {
6        default = vec2(400, 300),
7        min = vec2(300, 200)
8    }
9}, function()
10    ui.header("General Options")
11
12    if ui.checkbox("Enable Feature", state.enabled) then
13        state.enabled = not state.enabled
14    end
15
16    ui.separator()
17
18    ui.header("Visuals")
19
20    local newVal, changed = ui.slider("Opacity", state.opacity, 0, 1, "%.2f")
21    if changed then state.opacity = newVal end
22
23    ui.combo("Mode", state.mode, ui.ComboFlags.None, function()
24        if ui.selectable("Mode A", state.mode == "A") then state.mode = "A" end
25        if ui.selectable("Mode B", state.mode == "B") then state.mode = "B" end
26    end)
27
28    ui.text("Toggle Key:")
29    ui.sameLine()
30    myBindableHotkey:control(vec2(-1, 0))
31end)

Window Visibility & Management

Use ac.getAppWindows() to list all windows and check their status, and ac.accessAppWindow() to modify them.

ac.getAppWindows()

Returns an array of descriptors for all available windows.

lua
1local windows = ac.getAppWindows()
2for _, w in ipairs(windows) do
3    ac.log(string.format("Window: %s, Visible: %s", w.name, tostring(w.visible)))
4end

ac.accessAppWindow(windowName)

Returns an ac.AppWindowAccessor for the specified window name.

lua
1local window = ac.accessAppWindow("ac-tracer/corners")
2if window and window:valid() then
3    window:setVisible(true)
4end

ac.setAppWindowVisible(appID, windowFilter, visible)

Toggle windows that might be hidden or not yet initialized.

lua
1ac.setAppWindowVisible("ac-tracer", "telemetry", true)

Full API Reference

For the complete API reference with all types, enums, and functions, read the file reference/lib.lua in this skill folder (17,000+ lines of type definitions and documentation).

Scripts

scripts/logs.ps1

View CSP logs filtered for ac-tracer entries.

powershell
1# Default: last 20 entries
2.\.claude\skills\scripts\logs.ps1
3
4# Last 50 entries
5.\.claude\skills\scripts\logs.ps1 -l 50
6
7# Only errors
8.\.claude\skills\scripts\logs.ps1 -only ERROR
9
10# Only warnings
11.\.claude\skills\scripts\logs.ps1 -only WARN