Skip to content
CSP Lua API Docs

Getting Started

This documentation assumes you are already proficient with Lua or LuaJIT. The SDK is a professional toolset and does not cover foundational programming concepts. If you are new to the language, or to programming in general, it is recommended to study the following resources before proceeding:

This tutorial walks you through the process of creating a basic utility app.

Project Structure

Section titled “Project Structure”

A typical Lua App requires a specific folder structure to be recognized by Content Manager and CSP. Scripts that do not follow this hierarchy will not be loaded.

  • Directoryassettocorsa/
    • Directoryapps/
      • Directorylua/
        • Directorymy_first_app/
          • manifest.ini Required
          • my_first_app.lua Required

Hello World

Section titled “Hello World”

Follow these steps to create a simple utility app with a functional button. Read more on creating your first app here.

  1. Create Application Folder

    Navigate to your Assetto Corsa root folder, then to apps/lua/. Create a new folder named hello_world.

  2. Define Manifest

    Create a file named manifest.ini. This metadata file tells Assetto Corsa how to handle your window instance.

    manifest.ini
    [ABOUT]
    NAME = Hello World
    AUTHOR = YourName
    VERSION = 1.0
    DESCRIPTION = My first Lua app
    

    ; write comments in .ini files with semi-colons
    

    [WINDOW_...]
    ID = main
    NAME = Your First Window
    ICON = icon.png
    FUNCTION_MAIN = windowMain
    SIZE = 300, 150

  3. Write Logic

    Create hello_world.lua. We will use the ui namespace to draw text and a button.

    hello_world.lua
    -- this function is called every frame while the window is visible.
    -- the name matches 'FUNCTION_MAIN' in the manifest.
    function script.windowMain()
        ui.text("Hello, Assetto Corsa!")
        ui.separator()
    

        if ui.button("Click Me", vec2(ui.availableSpaceX(), 40)) then
            ac.log("The button was clicked at " .. ac.getSim().gameTime .. "s")
            ui.toast(ui.Icons.Confirm, "Action Triggered!")
        end
    end

  4. Enable and Launch

    1. Open Content Manager.
    2. Launch a session.
    3. Expect to find an app named Your First Window in the side bar, under all apps.

Debugging and Output

Section titled “Debugging and Output”

When developing, you need to see what is happening under the hood. CSP provides several ways to monitor your script.

The Lua Debug App

Section titled “The Lua Debug App”

While in a session, open the Lua Debug app from the sidebar. It provides:

  • Console output via ac.log() or print().
  • CPU usage for each running script.

Real-time Watches

Section titled “Real-time Watches”

Use ac.debug() to track a value visually without spamming the log.

function script.update()
    local car = ac.getCar(0)
    -- creates a live updating entry in the Lua Debug app
    ac.debug("Current RPM", car.rpm)
end

Read Sim Data

Learn how to access car and track data in the ac namespace.

Build Interfaces

Discover buttons, sliders, and canvases in the ui namespace.