acevo-shared-memory

A safe Rust interface for reading Assetto Corsa Evo live telemetry via Windows named shared memory.

Table of Contents

• Dependencies and requirements
• Getting started
• Usage
  • Opening the mapper
  • Reading physics data
  • Reading graphics / HUD data
  • Reading static session data
• Views
• Typed enums
• Snapshots
• Raw access
• Feature flags
• Side notes

Dependencies and requirements

• Windows only — uses Win32 named file-mapping APIs.
• AC Evo must be running before calling ACEvoSharedMemoryMapper::open().
• Requires Rust edition 2024.

Getting started

Add the library to your project:

cargo add acevo-shared-memory

Usage

All access goes through ACEvoSharedMemoryMapper, which opens the three named shared-memory segments and returns typed views over each one.

Opening the mapper

use acevo_shared_memory::ACEvoSharedMemoryMapper;

let mapper = ACEvoSharedMemoryMapper::open()
    .expect("AC Evo must be running");

Reading physics data

The physics page is updated every simulation step and contains raw vehicle-dynamics data: speed, gear, RPM, tyre state, G-forces, ERS, damage, and more.

use acevo_shared_memory::ACEvoSharedMemoryMapper;

let mapper = ACEvoSharedMemoryMapper::open().unwrap();
let physics = mapper.physics();

println!("Speed:  {:.1} km/h", physics.raw().speedKmh);
println!("Gear:   {}", physics.raw().gear);
println!("RPM:    {}", physics.raw().rpms);
println!("TC on:  {}", physics.tc_in_action());
println!("ABS on: {}", physics.abs_in_action());
println!("DRS:    {}", physics.drs_enabled());

Reading graphics / HUD data

The graphics page is updated every rendered frame and contains HUD state, driver info, flag state, lap timing, electronics settings, and more.

use acevo_shared_memory::ACEvoSharedMemoryMapper;

let mapper = ACEvoSharedMemoryMapper::open().unwrap();
let g = mapper.graphics();

println!("Driver:   {} {}", g.driver_name(), g.driver_surname());
println!("Car:      {}", g.car_model());
println!("Status:   {:?}", g.status());
println!("Flag:     {:?}", g.flag());
println!("Location: {:?}", g.car_location());
println!("Engine:   {:?}", g.engine_type());
println!("Pos:      {}/{}", g.raw().current_pos, g.raw().total_drivers);

Reading static session data

The static page is written once when a session loads and does not change while driving. It contains track name, session type, grip condition, and more.

use acevo_shared_memory::ACEvoSharedMemoryMapper;

let mapper = ACEvoSharedMemoryMapper::open().unwrap();
let s = mapper.static_data();

println!("Interface version: {}", s.sm_version());
println!("Game version:      {}", s.ac_evo_version());
println!("Track:             {} ({})", s.track(), s.track_configuration());
println!("Session:           {:?}", s.session());
println!("Starting grip:     {:?}", s.starting_grip());
println!("Nation:            {}", s.nation());

Views

All three data views share the same View<T> foundation and expose these methods:

Shared-memory segments

PhysicsView typed methods

GraphicsView typed methods

StaticView typed methods

Typed enums

Protocol integer constants are exposed as Rust enums. All enums derive Debug, Clone, Copy, PartialEq, Eq, Display, EnumString, EnumIter, and IntoStaticStr (via strum). Each enum has an Unknown(i32) or Other(i32) catch-all variant for forward-compatibility with future protocol values.

Every enum also provides a value() -> i32 method to convert back to the raw protocol integer:

use acevo_shared_memory::ACEvoStatus;

assert_eq!(ACEvoStatus::Live.value(), 2);
assert_eq!(ACEvoStatus::from(3), ACEvoStatus::Pause);

Snapshots

Views borrow directly from the shared-memory mapping and carry a lifetime tied to the ACEvoSharedMemoryMapper. Call .snapshot() to obtain a 'static heap copy that can be stored, queued, or sent across threads:

use acevo_shared_memory::ACEvoSharedMemoryMapper;

let mapper = ACEvoSharedMemoryMapper::open().unwrap();
let snap = mapper.physics().snapshot(); // Box<SPageFilePhysics> internally
drop(mapper);
println!("Captured speed: {:.1} km/h", snap.raw().speedKmh);

Raw access

Every field defined in the protocol is accessible via .raw(), including fields not yet covered by a typed accessor method:

let g = mapper.graphics().raw();
println!("Fuel:          {:.2} L",  g.fuel_liter_current_quantity);
println!("Lap time:      {} ms",    g.current_lap_time_ms);
println!("Predicted lap: {} ms",    g.predicted_lap_time_ms);
println!("Gap ahead:     {:.3} s",  g.gap_ahead);
println!("TC level:      {}",       g.electronics.tc_level);

Feature flags

Side notes

Please keep in mind that at the moment this is a side project developed with no planned continuity nor schedule. Therefore support, fixes and new features cannot be guaranteed.

As stated in the LICENSE, no contributor must be considered liable for the use of this project.