Skip to content
VincentChevalier44Public

About

SetupLab: Custom Shaders Patch app that computes, explains and refines your Assetto Corsa setups (qualifying and race), fitted to your own laps. Beta.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

SetupLab, race engineering for Assetto Corsa

SetupLab — setup generator for Assetto Corsa

Version 1.0 — beta 2.0.2 (1.0.0-beta.2.0.2) · Lua app for Custom Shaders Patch (free version 0.2.11 or newer) · MIT licence

SetupLab computes, for every car and track, a qualifying setup (practice, track day, hotlap, time attack, qualifying) and a race setup (full stint). It explains every setting, fits its model to your own laps, and refines the setup while you drive: it proposes a version, you try it in the pits in one click, keep or refuse each of its settings, and validate it.

The app is in English by default, with a full French translation (one click on the EN/FR badge).

📖 Interactive user guide: vincentchevalier44.github.io/SetupLab (updated with each version; French version). The guide is also in the app archive: docs/notice.html, French docs/notice.fr.html.

❤️ Support the project: Patreon WHK Racing. SetupLab is free and will stay free for everyone. I build it in my spare time; if you enjoy it and want to give a little help, you can support it from 1 € a month (cancel at any time).


Contents

Features

  • Qualifying and race setups computed from the car's data files (tyres, aero, engine, gearbox, brakes, suspension, differential, DRS, ERS) and the track's AI line (curvature, slope, camber, DRS zones).
  • Every setting explained: one sentence per proposed setting, its gain, the balance per corner; every untouched setting with its reason. Help on hover for every button and every app setting.
  • Start from the setup you want: your current setup (your own, loaded from AC's menu, or the default one), the car's default setup, or your validated reference on the track; SetupLab evolves it version after version.
  • Built up step by step: "Try" puts each proposed version in the car in one click, in the pits; "Validate" keeps it, then SetupLab asks whether to carry on refining or lock it. "Modify…" refuses one particular setting (for example the rear wing) and keeps the rest; a refused setting keeps its old value in the next computations.
  • A guided flow: a "Step N/4" card always at the top (Start, Drive, Try, Validate) with one main button for the next step.
  • Everything it takes into account, shown: weather, air and track temperature, track grip, wet track, slow/medium/fast corners, chicanes, longest straight, share of full throttle and braking (SETTINGS tab); every setup setting is optimised or kept with its reason.
  • Your times first, the same as AC's: your best lap of the session with each setup, as AC's timing counts it (laps in traffic or with a small incident included, the clean lap shown next to it when different), or your average lap for the race; the estimated target and the real gain of each version. The track memory shows your real best (or average) with each validated setup, never a simulated time as yours. The model is calibrated on your clean laps only.
  • Refinement while you drive: tick SetupLab active and drive. A proposal only comes after a minimum of clean laps and minutes with the current setup (both adjustable). On track, SetupLab says once that it has the minimum information and keeps analysing; the version is ready when you return to the pits.
  • Race setup after qualifying: the RACE tab lists your validated qualifying versions on the track (v1, v2, v3…, including those from an earlier AC launch); "Start from qualifying vN" puts it in the car and starts the race refinement in one click, for the number of laps you enter. "Resume my race vN" carries on from a validated race setup.
  • In-game update: once per AC launch, SetupLab checks on GitHub whether a newer version is published; "Update" installs it in one click, after checking the archive's SHA-256 fingerprint (setting can be unticked).
  • In-game overlay: while driving, whether the setup on track is better or worse than the previous one on your laps, the settings that changed most with their predicted gain, and what is left before the next proposal.
  • Track memory: the validated or locked setup is kept per car, track, session (practice, qualifying, race) and track state (dry, wet), and offered on the next visit.
  • Rain (CSP weather, Pure included): compound choice (slicks, intermediates, wets), pressures, wing, stricter driving aids; separate wet calibration. The track switches between dry and wet only after the new state has lasted 20 seconds, so a brief reading of water on the track no longer flips the setups.
  • Qualifying tyres: on a dry track, a qualifying setup uses the softest compound of the mounted range (hypersoft, ultrasoft, supersoft, then soft), recognised by its name in English or French; a compound you refused, or one imposed in the settings, comes first.
  • Clear file names in the chosen language: SetupLab_Quali_v1.ini, SetupLab_Race_Wet_v3.ini… (SetupLab_Qualif_v1.ini, SetupLab_Course_Pluie_v3.ini in French), numbered in sequence on the track; your best lap with a qualifying version (AC's timing) is added to its name. Only the versions you keep remain: trial files, versions not kept and useless copies go to the Recycle Bin.

Installation

Requirements: Assetto Corsa with Custom Shaders Patch 0.2.11 (the free version installed by Content Manager) or newer, previews included; offline or online.

  1. Download the latest SetupLab-….zip from the Releases.
  2. Close Assetto Corsa, then extract the archive into assettocorsa/apps/lua/: it already contains the SetupLab/ folder. In the end, assettocorsa/apps/lua/SetupLab/ holds SetupLab.lua and manifest.ini (no SetupLab folder inside another SetupLab).
  3. In game, open SetupLab from the app bar or the setup screen. Three more windows exist: SetupLab Track (the same interface, opened from the app bar while driving: in a race you start on the grid), SetupLab Overlay (on track) and SetupLab Debug (diagnostics).

Updating

From beta 1.5.4 on, SetupLab can update itself: when a newer version is published, an Update button appears at the top of its window (to click in the pits, car stopped). It downloads the release archive from GitHub, checks its size and SHA-256 fingerprint and its content, then replaces the app's files in one go (the previous files are put back if anything fails); CSP then reloads the app, which comes back on standby.

To install by hand (and to go from 1.5.2 or older to this version): delete the old SetupLab folder first. Close Assetto Corsa completely (CSP reloads apps while the game runs), delete assettocorsa/apps/lua/SetupLab, then extract the new archive into assettocorsa/apps/lua/. This also removes files from older betas that are no longer used. Your settings, calibration, track memory and saved setups are kept: CSP stores the app data outside that folder, and setups stay in your setups folder. From beta 1.5 the interface starts in English; the FR badge switches it to French.

Quick start

  1. Start a session, offline or online (practice, track day, qualifying or race). Open SetupLab with the car in the pits and wait for "Discovery finished". In a race session, see "During a race" in the user guide: from the grid, SetupLab Track, RACE tab, Refine during the race; the race setup is computed at the finish, for your next race.
  2. Step 1, Start: choose My current setup, Car's default setup or Resume my reference. This activates SetupLab. Drive clean laps.
  3. When a version is ready, it is announced at the top of the screen. In the pits, Try v1 puts it in the car in one click (its trial file then goes to the Recycle Bin). Start over puts the previous setup back.
  4. Drive with it, then click Validate v1 (or Modify… to refuse a particular setting first). SetupLab then asks: Carry on refining (a new version with your next laps, starting from it) or Lock v1.
  5. For the race: the RACE tab lists your validated qualifying versions. Start from qualifying vN puts it in the car and starts the race refinement; enter the race lap count.

Every button, tab and setting is described in the interactive user guide.

What SetupLab never does

  • It never changes the content of a file or the game physics, and never overwrites a setup: each save is a new file in the car and track setups folder.
  • It only writes on your click: "Car's default setup" (step 1), "Try", "Save", "Validate", "Lock", plus a backup copy of the current setup just before a load, when useful.
  • It never touches your own files. It only tidies files it wrote, intact (recognised by name and content fingerprint), with the car stopped: to the Windows Recycle Bin for trial files once loaded, versions you do not keep and redundant backup copies; it renames a kept qualifying version to add your best lap. With CSP 0.2.11, the Recycle Bin is not yet available to apps: these files are deleted permanently.
  • The car setup only changes on your explicit request: in the pits (or on the grid before a race start), car stopped, setup menu open, in one click, after a backup copy when useful; only a file written by SetupLab can be loaded. When SetupLab loads a race setup this way, the selected quick pit preset also gets its tyre pressures and tyres, so a tyre change is planned at the stop (fuel and repairs are left as you set them).
  • No game or personal data is ever sent over the Internet (GitHub only sees your IP address, as for any web page). The only connection reads, once per AC launch, the latest version number in this repository (update.txt; setting Check for updates at launch can be unticked); an update is only downloaded on your click, and checked before anything is replaced. No loadstring or dofile, and no os.* except CSP's precise clock (os.preciseClock), used to time its computation slices, and os.date, read only for the local time in saved file names.
  • Online it works exactly as offline (setting Active online, ticked by default: untick it if a league's rules forbid apps). Nothing is sent to the server. It is inactive in replays.
  • It trusts no data it reads (car files, game state, storage): everything is bounded and validated.

Beta status and known limitations

This beta is built and checked on an offline test bench (508 tests: models, optimiser, interface, translation, loading, persistence, fuzzing). It has been tried in game, but many cars and tracks have not been seen in game yet. To be confirmed in game:

  • how closely the simulated lap matches AC (target: lap time within 2 %); until calibration reaches its thresholds, gains are indicative and the app says so;
  • the rain model, which relies on assumptions: your wet laps calibrate it;
  • the free CSP 0.2.11: checked against its SDK and on the bench (simulated 0.2.11); a player confirmed that SetupLab starts normally with it since 1.5.6. Since 1.5.9, when this CSP gives empty car files or no setup settings (issue #2), SetupLab reads the car files' raw text and deduces the settings from the car's setup.ini; the J0 report then says so, and settings locked by a series are not known in that mode;
  • loading a setup on the grid before a race start (1.5.9), checked on the bench only;
  • the 1.5.11 model changes (camber, braking with ABS, rotating inertia instead of a fixed drivetrain loss, rolling resistance following the tyre load, packer range, hybrids past the combustion top speed), checked on the bench only; the 1.5.11 CSP 0.2.11 car-data fix (issue #2), checked on the bench, which reproduces the report;
  • the 2.0.0 link with AdvancedIA and SpotterEngineer (optional companion apps by the same author): laps under safety car, VSC, red flag, yellow or with a penalty counted in AC's times only, race rules, the key read by SpotterEngineer; checked on the bench only;
  • the 1.5.5 race laps entry during the race refinement, the folding setup settings table and the overlay hidden in replays, checked on the bench only. The page layouts, the overlay bar, the local time in file names, the in-game update (from 1.5.3 to 1.5.4 and from 1.5.5 to 1.5.6), the online mode and the race refinement during a race have been tried in game;
  • with cars whose data is packed (data.acd): gear ratio files are read through CSP (see the J0 report, DIAGNOSTICS tab); with layout tracks: the layout's own data folder (surfaces, DRS zones).

Some settings are deliberately kept, with their reason shown: toe, coast and preload differential (transient effects outside the model), packers and bump stops (reference to confirm), springs and dampers until a valid dry lap has measured the track roughness, ride height until a load in the pits has verified the height reference, settings defined by a car's script (unknown effect).

The J0 report and the copied lap (DIAGNOSTICS and MEASURE tabs), meant for development, are in French. The source code comments are in French.

Feedback is welcome in the Issues. For a problem, attach the report from the DIAGNOSTICS tab ("Copy the J0 report"). If AC is already closed, SetupLab's journal is also in CSP's log, Documents\Assetto Corsa\logs\custom_shaders_patch.log (lines [Lua: App: SetupLab]), until AC is started again.

Development

Offline test bench

The bench loads SetupLab.lua as is into LuaJIT 2.1 (CSP's engine) through lupa, with a simulated CSP host (tests/fakehost.lua). State objects raise an error on an unknown field, like a CSP FFI structure; any undeclared global is an error.

Requirements: Python 3, preferably in a virtual environment (commands use python -I, which ignores user-installed packages):

python -m venv .venv
.venv\Scripts\activate
python -m pip install -r tests/requirements.txt

Data sets: the tests use cars and tracks from the game (Kunos and mod data files). They are not published in this repository: generate them from your own installation (with the repository placed in assettocorsa/apps/lua/SetupLab/):

python -I tests/tools/make_fixtures.py [assettocorsa_root]
Type Sets
Cars formula_k (Kunos SDK), lamborghini_huracan_gt3_evo2, urd_px1_aura (URD mod, ERS), whk_dtm_2026 (WHK mod, DRS)
Tracks (AI line fast_lane.ai) Spa, Monza, Red Bull Ring GP, Nordschleife

A missing car or track is skipped; the tests that use it fail.

python -I tests/run_tests.py              # linter and its self-tests, then every suite
python -I tests/run_tests.py --filter AU  # only the tests whose name contains "AU"
python -I tests/run_tests.py --soak       # + endurance: 1,000 chained discoveries
python -I tests/lint.py                   # linter only
sh tests/calm_bench.sh [filter]           # wait for a calm machine, then run the bench (timing tests fail under load)
python -I tests/package.py                # distribution archive dist/SetupLab-<version>.zip

Results are written to tests/results.json. Timing tests (budget per frame) measure in real time: a busy machine (Assetto Corsa running at the same time, for example) can make them fail.

Translation

The source texts are French; the English interface comes from a dictionary in tests/tools/lang/*.py, generated into src/lang_en.lua:

python -I tests/tools/gen_lang.py         # regenerate src/lang_en.lua (the bench fails if it is out of date)
python -I tests/tools/extract_keys.py --missing   # candidate keys with no entry (noisy: the J0 report stays French on purpose)

tests/test_i18n.lua replays the main flows in English, with every tooltip and section open, and fails on any French text left, whether it went through the dictionary or was drawn on screen directly.

Rules enforced by the linter

  • only the glue (SetupLab.lua) reads CSP globals; modules receive the host as a parameter;
  • the pure core only depends on the pure core;
  • os (except os.preciseClock and os.date, read by the glue only), load, loadstring and dofile are forbidden; the web global is read by the glue only and passed to src/updater.lua (the packager only allows web.get and web.timeouts there);
  • ac.setSetupSpinnerValue and ac.saveCurrentSetup are forbidden everywhere, ac.loadSetup everywhere except in src/exporter.lua;
  • no unused local variable, no TODO, lines of at most 140 characters.

Project structure

SetupLab.lua         CSP glue: injected host, callbacks, safeguards, background tasks, persistence, refinement
manifest.ini         CSP app manifest
icon.png
src/util.lua         pure core: maths, LUTs, INI, RNG, log, scheduler, dates, file names
src/config.lua       single schema of the settings, their help, internal constants
src/i18n.lua         interface language: translation of displayed texts
src/lang_en.lua      English dictionary (generated)
src/caps.lua         CSP capabilities, precise clock, local time, J0 report
src/datasource.lua   car / track / session / setup reading -> pure tables
src/track_model.lua  track model
src/car_model.lua    car model: tyres (dry and wet), aero, engine, brakes, suspension
src/laptime_sim.lua  quasi-static lap simulation
src/ers.lua          ERS: reading, battery, dynamic programming
src/ers_plan.lua     ERS: zones, options, steady state
src/setup_space.lua  setup steps <-> physical values, file rendering
src/optimizer.lua    optimiser, qualifying and race, compound choice
src/stint_sim.lua    stint simulation: fuel, wear, traffic
src/explain.lua      setting explanations (both languages), balance per corner
src/recorder.lua     lap recorder, your times per setup, export
src/calibration.lua  calibration, "measure only" mode
src/exporter.lua     writing new files, loading into the car
src/store.lua        validated persistence (settings, calibrations, track memory)
src/updater.lua      in-game update: version check, download, checks, file replacement
src/ui.lua           windows (read-only view of the state)
src/skin.lua         "Racing 26" theme: colours, fonts, slanted buttons and tabs, cut-corner panels
src/window.lua       overlay window bar: lock, reduce, close, drag
src/dash.lua         "Racing 26" page layouts (header, tabs, every page, overlay and debug windows)
fonts/               Barlow, Barlow Condensed, JetBrains Mono (SIL Open Font License 1.1, licence next to each family)
docs/                user guide (English and French)
tests/               offline bench, linter, dictionary, data set generator (never distributed)
assets/              banner of the README and the releases
update.txt           latest published version, read by the in-game update
.github/             issue template

Support

SetupLab is free and will stay free for everyone. It is built in my spare time, with a lot of testing on many cars and tracks. If it helps you on track and you want to support its development, you can do so on Patreon WHK Racing, from 1 € a month, cancel at any time. Thank you!

Licence

MIT © 2026 VincentChevalier44 (Vincent Chevalier).

Fonts in fonts/: Barlow and Barlow Condensed © 2017 The Barlow Project Authors, JetBrains Mono © 2020 The JetBrains Mono Project Authors, both under the SIL Open Font License 1.1.

Assetto Corsa is a trademark of Kunos Simulazioni. SetupLab is an independent project, not affiliated with Kunos Simulazioni or the authors of Custom Shaders Patch.

About

SetupLab: Custom Shaders Patch app that computes, explains and refines your Assetto Corsa setups (qualifying and race), fitted to your own laps. Beta.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages