AC Boilerplate App

A simple boilerplate Python app for Assetto Corsa that demonstrates UI creation, event handling, configuration management and telemetry data access.

What It Displays

• Speed: Current speed with toggle between KPH/MPH
• Gear: Current gear (R, N, 1, 2, 3, etc.)
• Lap Count: Number of completed laps
• Fuel: Current fuel level in liters

Installation

Method 1: Direct Installation to AC

1. Copy the entire ac-python-app-example folder to your Assetto Corsa installation:

   <AC Installation>/apps/python/ac-python-app-example/

   Typical AC installation path:

   • Windows: C:\Program Files (x86)\Steam\steamapps\common\assettocorsa\apps\python\ac-python-app-example\

2. Launch Assetto Corsa and start a session

3. Open the app sidebar (in-game) and activate "ac-python-app-example"

Method 2: Development Setup

If you're actively developing the app:

1. Create a symbolic link from your development folder to the AC apps directory:

   mklink /D "C:\...\assettocorsa\apps\python\ac-python-app-example.py" "e:\Dokumente2\Programmierung\ac-python-app-example\ac-python-app-example.py"

2. Edit files in your development folder and reload in AC

File Structure

ac-python-app-example/
├── ac-python-app-example.py    # Main application file
├── settings.ini                # User configuration (editable)
├── settings_defaults.ini       # Default configuration (reference)
├── lib/
│   └── sim_info.py             # Shared memory interface
├── stdlib/
│   ├── _ctypes.pyd             # 32-bit DLL (must be copied)
│   └── README.txt              # Instructions
└── stdlib64/
    ├── _ctypes.pyd             # 64-bit DLL (must be copied)
    └── README.txt              # Instructions

Configuration

Edit settings.ini to customize the app:

[Display]
speed_unit = kph               # or "mph"
show_extra_info = 1            # 0 to hide, 1 to show

[Updates]
high_frequency = 0.0167        # Update interval for speed/gear (~60 FPS)
medium_frequency = 0.5         # Update interval for lap/fuel (2 Hz)

Code Structure

Core Functions

The app follows the standard AC Python app structure:

1. acMain(ac_version): Called once when the app initializes

   • Creates the app window
   • Sets up all UI elements (labels, buttons)
   • Loads configuration
   • Returns the app name

2. acUpdate(deltaT): Called every frame

   • Updates telemetry data
   • Uses timers to control update frequency
   • Handles both high-frequency (speed, gear) and lower-frequency (lap, fuel) updates

3. acShutdown(): Called when the session ends

   • Saves configuration
   • Performs cleanup

Key Patterns Demonstrated

Global Variables

# Define at module level
label_speed = None

def acMain(ac_version):
    global label_speed  # Declare as global
    label_speed = ac.addLabel(appWindow, "Speed: 0")

Event Handling

def on_button_toggle(*args):
    # Handle button click
    global speed_unit
    speed_unit = "mph" if speed_unit == "kph" else "kph"

# In acMain:
button = ac.addButton(appWindow, "Toggle")
ac.addOnClickedListener(button, on_button_toggle)

Timer-Based Updates

timer_high = 0.0

def acUpdate(deltaT):
    global timer_high
    timer_high += deltaT
    
    if timer_high >= 0.0167:  # ~60 FPS
        timer_high = 0.0
        # Update speed, gear, etc.

Data Access

AC API (basic telemetry):

speed = ac.getCarState(0, acsys.CS.SpeedKMH)
laps = ac.getCarState(0, acsys.CS.LapCount)

Shared Memory (advanced data):

from lib.sim_info import info

fuel = info.physics.fuel
gear = info.physics.gear
rpm = info.physics.rpms

Extending the Boilerplate

Adding a New Label

# 1. Add global variable
label_new = None

# 2. Create in acMain
def acMain(ac_version):
    global label_new
    label_new = ac.addLabel(appWindow, "Text")
    ac.setPosition(label_new, x, y)
    ac.setFontSize(label_new, size)

# 3. Update in acUpdate
def acUpdate(deltaT):
    global label_new
    value = ac.getCarState(0, acsys.CS.SomeValue)
    ac.setText(label_new, "New: {}".format(value))

Adding a New Button

# 1. Define handler
def on_new_button_click(*args):
    ac.console("Button clicked!")

# 2. Create in acMain
button_new = ac.addButton(appWindow, "Click Me")
ac.setPosition(button_new, x, y)
ac.setSize(button_new, width, height)
ac.addOnClickedListener(button_new, on_new_button_click)

Adding Configuration Options

# 1. Add to settings.ini
[MySection]
my_option = value

# 2. Load in load_config()
if config.has_section('MySection'):
    my_option = config.get('MySection', 'my_option')

# 3. Save in save_config()
config.set('MySection', 'my_option', str(my_option))

Available Telemetry Data

Via AC API (ac.getCarState)

• acsys.CS.SpeedKMH - Speed in km/h
• acsys.CS.LapCount - Completed laps
• acsys.CS.LapTime - Current lap time (ms)
• acsys.CS.LastLap - Last lap time (ms)
• acsys.CS.BestLap - Best lap time (ms)
• Many more (see AC Python documentation)

Via Shared Memory (info)

• info.physics.fuel - Current fuel
• info.physics.gear - Current gear
• info.physics.rpms - Engine RPM
• info.physics.speedKmh - Speed
• info.physics.tyreCoreTemperature - Tire temps (array)
• info.physics.abs - ABS level
• info.physics.tc - TC level
• info.graphics.completedLaps - Laps completed
• info.graphics.position - Race position
• info.static.maxRpm - Max RPM
• info.static.maxFuel - Max fuel capacity
• Many more (see lib/sim_info.py for complete structure)

Debugging

Console Output

Press Home key in-game to open the console. Messages sent via ac.console() appear here.

Log Files

Located in <Documents>\Assetto Corsa\logs\:

• py_log.txt - Python app messages (from ac.log())
• log.txt - AC system logs (includes error messages with line numbers)

Common Issues

App doesn't appear in sidebar:

• Check log.txt for error messages
• Ensure folder name matches: boilerplate/boilerplate.py
• Verify _ctypes.pyd files are copied correctly

Import errors:

• ac and acsys imports will show errors in IDE - this is normal
• These modules only exist within AC's Python environment

Shared memory errors:

• Ensure _ctypes.pyd files are in correct stdlib/stdlib64 folders
• Check that lib/sim_info.py exists

Testing Workflow

1. Edit code in your editor
2. Start a session in AC (no need to restart AC completely)
3. Check console (Home key) for immediate errors
4. Test functionality
5. End session and repeat

Tip: Use Practice mode on a short track (like Silverstone International) for faster testing.

Resources

• AC App Development Tutorial - A GitHub tutorial on creating AC Python apps

License

MIT License - Feel free to use this as a starting point for your own apps!

Credits

Inspired by:

• LmpGUI app structure
• AC community tutorials and shared memory implementations