Skip to content

C++ Headers#

This section lists the public declarations of each C++ header. The pages come from the /// comments in the source code.

Generated Run mkdocs build to generate the pages again. Write Documentation gives the comment format.

Source Tree Folder Headers
Game module Acres/Source/Acres 43
ACRES Core Core/Source 10
acres_sim ROS/acres_sim/include/acres_sim 6
acres_core_sim ROS/acres_core_sim/include/acres_core_sim 5

Only public members are in the reference. Unreal for C++ Developers explains the Unreal types.

Vehicles#

Header Description
AcresVehicle.h The tractor (and its trailed implement) as an Unreal pawn: the glue between the SI vehicle model and Chaos, Unreal's physics engine.
AcresVehicleModel.h Tractor dynamics: tyres, soil contact, suspension, drivetrain and steering (pure C++, no Unreal objects).
AcresUtvModel.h Polaris Ranger CREW XP 1000 dynamics and its Dataspeed drive-by-wire (DBW) layer (pure C++, no Unreal objects).
AcresSimModel.h Small engine-independent vehicle helpers: engine torque curve, wheel slip ratio and Ackermann steering.
AcresSoilModel.h Soil library and tyre-soil terramechanics (pure C++, no Unreal objects).
AcresPowerModel.h Engine fuel map and the vehicle energy ledger (pure C++, no Unreal objects).
AcresCommandTiming.h When a controller's commands reach the physics: each message applies at the physics step that matches the time it arrived (pure C++, no Unreal objects).
AcresAgents.h Which vehicles a session drives, and each one's own settings (single- and multi-agent sessions).

Implements and Rigs#

Header Description
AcresImplementModel.h Implement-soil interaction for the Maxxum's eight attachments (pure C++, no Unreal objects).
AcresImplementCoupling.h Glue between the soil library (AcresSoilModel.h), the implement model (AcresImplementModel.h) and the places that drive it: the pawn (AcresVehicle.cpp), the menu's validation (AcresSession.cpp) and the optimizer (AcresOptimizer.cpp). Pure C++ in SI units, no Unreal types, so Tools/ImplementModel builds and tests it.
AcresFieldWorkModel.h What field work leaves on the ground: the visible surface of tillage, drilling, spraying, tyres and the backhoe, from the same physical state the implement and tyre models use. Pure C++ in SI units, no Unreal types, so Tools/ImplementModel builds and tests it.
AcresRig.h Data-driven rigs for the farm-equipment and Polaris skeletal meshes (Acres/Raw/farm-equipment).

Farm, Soil and Water#

Header Description
AcresFarmRuntime.h The live farm: crops, soil water, ruts and the harvester, wired into the Unreal world.
AcresFarmModel.h Crop and soil-water maths for the farm (pure C++, no Unreal objects, no wall-clock time).
AcresSoilVisuals.h Render-only ground effects for the farm: rut tiles, field-work detail, standing water and cosmetic particles.
AcresFieldSetup.h Per-session field configuration from the menu's Fields tab: crop type, soil, starting wetness and terrain edits.
AcresSurfaceMap.h Ground surface classes of the ACRE tile from vector polygons (pure C++, no Unreal types; Tools/Terramechanics builds and tests it).
AcresCrops.h
AcresPlaces.h Named places on the ACRE tile (Content/Simulation/ACRE/places.json, written by Tools/ACRE/Map/places.py from the "ACRE Map Labels" page) and the spawn places the simulator starts from.

Weather#

Header Description
AcresEnvironment.h Unreal adapter for the weather model: steps AcresEnv::Model and drives the sky, light, fog and rain from it.
AcresEnvironmentModel.h Weather, sky and clock model for the ACRE site (pure C++, no Unreal objects).

Sensors#

Header Description
AcresSensors.h Synthetic sensor episode recorder for the ACRE tractor: truth, actions, GNSS, IMU, LiDAR, camera and CAN.
AcresCameraModel.h Photometric and geometric model of a machine-vision RGB camera, applied on the CPU to the scene-capture render.
AcresLidarModel.h Radiometric and multi-return LiDAR model shared by the CPU-proxy and GPU ray-tracing paths.
AcresLidarPhysics.h Engine-free pieces of the LiDAR radiometry that the Helios calibration added (Calibration/Polaris/lidar_results.md): the Minnaert incidence law, the peak loss of an echo stretched by a grazing footprint, the in-plane divergence of an elliptical beam, and a deterministic footprint-scale surface micro-slope. Plain C++ (no Unreal types) so that Tools/LidarModel/lidar_tests.cpp can check them against the Python fit (Calibration/Polaris/lidar_model.py). AcresLidarModel.cpp and AcresSensors.cpp call these; every function is inline and allocation-free.
AcresLidarGpu.h GPU LiDAR: traces scan rays against the renderer's ray-tracing scene with inline ray queries.
AcresGnssModel.h GNSS receiver model for the sensor recorder, in the position domain.
AcresGeoUtm.h Universal Transverse Mercator projection (pure C++, header only, no Unreal types).
AcresSensorStream.h Binary sensor stream: one vehicle's heavy sensor data (full organized LiDAR clouds, camera images) and its 100 Hz INS epochs, live, as length-prefixed binary frames over a local TCP socket. The ROS 2 bridge (ROS/acres_sim, the sim_bridge executable) turns them into sensor_msgs; the JSON RL bridge (AcresRlBridge.h) carries the drive-by-wire commands and reports next to it.
AcresRenderTier.h Render tiers and the pinned sensor render profile.

Logs and Control#

Header Description
AcresSessionLog.h Streaming 120 Hz tractor log for menu sessions: <session>/tractor.csv plus session-summary.json on close.
AcresEpisodeLog.h The episode log: an MCAP file of ROS 2 messages (CDR) with every agent's state at the physics rate, the farm events, conditions, hardware shifts and the episode clock (Documentation/Reference/episode-log.md). Pure C++17, no Unreal types and no ROS: the game (AcresSimControl.cpp) writes and replays it, ACRES Core compiles the same file, and Tools/EpisodeLog/build.sh tests it. The message layouts mirror ROS/acres_interfaces/msg; the schema texts are generated into AcresEpisodeSchemas.h (Tools/EpisodeLog/gen_schemas.py).
AcresEpisodeSchemas.h Generated by Tools/EpisodeLog/gen_schemas.py from ROS/acres_interfaces and the ROS 2 message packages: the ros2msg definitions the episode log (AcresEpisodeLog.h) writes into its MCAP schema records. Do not edit; rerun the script after changing a message.
AcresSimControl.h Simulator control: the session-wide channel the ROS 2 side (ROS/acres_sim) and learners use to pause, play and step the world in lockstep, reset it, move and spawn entities, change the conditions and the vehicles' hardware shifts, record the episode log and replay one. Protocol: Documentation/Reference/sim-control.md (newline-delimited JSON on 127.0.0.1, -SimControl=<port>); episode log: Documentation/Reference/episode-log.md.
AcresRlBridge.h Live reinforcement-learning bridge: lets an external agent (a Python client such as acres_learn, or ROS/acres_sim) drive the player's tractor in the running game, with full rendering and sensors running, over one of two transports:
AcresReplay.h Replay input: a recorded drive the tractor can follow again.
AcresVideoCapture.h

Application#

Header Description
AcresShell.h Game mode, HUD and the free-fly inspection camera.
AcresMenu.h Front end: the full-screen menu, the terrain-brush editor and the in-session pause menu.
AcresSession.h A simulation session as configured in the front-end menu, and how it becomes a running simulation.
AcresOptimizer.h Run Optimizer: three planning tools that run from the menu in well under a second.
AcresNpc.h Farm life: pickups and tractors that drive the farm roads, workers who walk and scout crops, and highway traffic on US 52 along the south edge of the farm.
Acres.h

ACRES Core#

Header Description
AcresCoreBatch.h Batched environments of ACRES Core: N independent Polaris environments on one shared world, stepped together on all CPU cores. This is what the Python module (Core/Python) and the learners use; ROS/acres_core_sim will wrap the same class.
AcresCoreEpisodeLog.h ACRES Core's episode log: the game's own writer (AcresEpisodeLog.h, the format of Documentation/Reference/episode-log.md) fed from the Core, so a Core episode is the same MCAP file the game writes and replays in Unreal with -EpisodeReplay=. Every physics step: /sim/agent_states (the agents' base_footprint poses, wheels, drive-by-wire state, energy ledger, fuel, crop) and /sim/farm_stamps (the tyre and body contacts, so the game's farm repeats them); at the start and after every reset: /sim/episode, /sim/agents, /sim/conditions, /sim/shifts. The Core also writes the ds_dbw_msgs commands as the vehicle received them (/<agent>/vehicle/{steering,throttle,brake,ulc,gear}/cmd, /<agent>/vehicle/dbw_enabled), which the format allows.
AcresCoreFarm.h What one environment's machines leave on the farm: crushed crop and wheel ruts, the per-episode half of FAcresFarmRuntime (Wheel, Body, Stamp and the rut map) without Unreal. The crop layout, growth and soil come from the shared FAcresWorld; this holds only the changes, sparsely, so thousands of environments stay small and a reset is a clear().
AcresCoreJson.h A small JSON document reader for ACRES Core (no Unreal, no third-party library): the Core loads the same Content/Simulation files the game reads with Unreal's FJsonObject (site.json, surface_polygons.json, fields.json, tractor.json, farm.json, soils.json, sensors_polaris.json, ...). Numbers are doubles, objects keep their key order. Load-time only; not thread-safe while parsing, read-only (and thread-safe) afterwards.
AcresCoreLidar.h Ray-cast LiDAR for ACRES Core: the Polaris' RoboSense Helios (1800 columns x 32 rings at 10 Hz, sensors_polaris.json "lidar") and the scouting task's planar 360-beam scan, traced against the terrain (AcresCoreTerrain.h), the static obstacle scene (AcresCoreScene.h) and the other vehicles' boxes.
AcresCoreMath.h Vector, quaternion and 3 x 3 matrix helpers for ACRES Core (header-only, double precision).
AcresCorePolaris.h The Polaris Ranger in ACRES Core: the game's own drive-by-wire, powertrain, tyre and driveline model (AcresUtvModel.h, compiled unchanged) on a rigid chassis that reproduces what the game does with Chaos in AAcresVehiclePawn::AsyncPhysicsTickActor (AcresVehicle.cpp) and StepPolarisControls (AcresPolaris.cpp):
AcresCoreScene.h The static obstacles of the ACRE map for ACRES Core: buildings, grain bins and trees as simplified shapes (Core/Data/acre_scene.json, written by Core/Scripts/build_scene.py from building_models.json and the level's tree instances), for the ray-cast LiDAR (AcresCoreLidar.h) and the vehicles' collision test.
AcresCoreTerrain.h The ACRE survey terrain as the game's wheels see it: the corner heights of heights.f32 (1001 x 1001 float32 on the 1.524 m survey grid of site.json), each cell split into two triangles along its anti-diagonal, exactly as the triangulated collision mesh the wheel traces hit (AAcresVehiclePawn::AcreHeight, checked against the mesh to 1 cm by VerifyAcreTerrain). Heights, face normals and ray casts are exact on that mesh.
AcresCoreWorld.h The static world of ACRES Core, shared read-only by every environment: the ACRE terrain, the surface map, the tyre surface templates and soil parameters of tractor.json, the soil texture and soil-water unit grids, the field raster, the crop patches and the named places. It replaces what the game does inside Unreal around the engine-free models: AAcresVehiclePawn::SampleSurface and SoilLibraryClassAt, FAcresFarmRuntime::Initialize (units, cells, patches) and Sample (soil water at a wheel), FAcresFieldSetup (fields, surface polygons, crop season).

ROS 2 Bridge: acres_sim#

Header Description
conversions.hpp Conversions between the game's stream frames and JSON lines and the vehicles' ROS 2 messages: the INS epoch to odometry, TF, ground truth, NavSatFix, Imu (the OxTS AV200 mounting on the Polaris) and TwistStamped; the DBW reports; the DBW and tractor commands to the RL bridge's JSON; a UTM reset pose to the game's reset command; the camera intrinsics and the Maxxum's mounts from the stream's hello. Everything here is a pure function (unit tested, test/test_conversions.cpp) and matches the Python bridge (acres_ros/sim_bridge.py) value for value.
j1939.hpp SAE J1939 / ISO 11783 (ISOBUS) encoding of the game's CAN protocol (AcresRlBridge.h, -RlCan= / -RlCanUdp=): the C++ port of the Python module acres_sim.j1939 (installed with this package), function for function and bit for bit (test/test_j1939.cpp round trips, test/test_j1939_golden.py compares both on the same inputs).
json.hpp JSON helpers shared by the game's line protocols (the RL / drive-by-wire bridge and the simulator control channel).
sim_control.hpp Client of the game's simulator-control channel (Documentation/Reference/sim-control.md, -SimControl=&lt;port>) that offers it on ROS 2 at the root namespace: the simulation_interfaces services and action (/get_simulator_features, /get_simulation_state, /set_simulation_state, /step_simulation, /simulate_steps, /reset_simulation, /get_entities, /get_entity_state, /set_entity_state, /spawn_entity, /delete_entity, /get_spawnables, /get_named_poses), the ACRES services (/acres/set_conditions, /acres/set_vehicle_shift, /acres/record, /acres/farm_state, /acres/field_query) and the topic /sim/episode (transient local).
stream.hpp The game's local transports, without ROS: the binary sensor stream (Acres/Source/Acres/AcresSensorStream.h, -SensorStream=&lt;port>), newline-delimited JSON over TCP (the RL / drive-by-wire bridge -RlPort=&lt;port> and the simulator control channel -SimControl=&lt;port>) and CAN frames over UDP (-RlCanUdp=&lt;port>). The game listens on 127.0.0.1 only, and these clients refuse any other host.
vehicle_bridge.hpp One vehicle of the running game on the topics its real counterpart uses (the C++ successor of acres_ros sim_bridge.py, topic for topic, frame for frame and value for value).

Core Server: acres_core_sim#

Header Description
CoreSimDbw.h The Polaris' drive-by-wire command path between the RL / DBW bridge's JSON messages and the vehicle model, as the game runs it (AcresRlBridge.cpp HandleDbw, AcresPolaris.cpp StepPolarisControls and PublishPolaris, AcresRlBridge.cpp SendDbwReports), without the keyboard driver and the session's own drivers (replay, drive script), which the Core does not have:
CoreSimGeo.h The simulator's georeference without Unreal: the game's datum chain from the grid ENU frame of the ACRE tile to NAD83(2011) latitude / longitude and UTM zone 16N, as the Polaris' INS stream reports them (AcresSensors.cpp FAcresSensorRecorder::InsEpoch with sensors.json "ins.frame": "nad83"), and the affine world <-> UTM map of the simulator-control channel (AcresSimControl.cpp WorldToUtm / UtmToWorld).
CoreSimIns.h The Polaris' OxTS AV200 INS as the game's sensor recorder models it (AcresSensors.cpp FAcresSensorRecorder::InsEpoch), fed from the Core's chassis: one epoch of the sensor stream's INS frame (AcresSensorStream.h EIns, 40 float64) at base_footprint, with the game's error model and datum chain.
CoreSimNet.h The game's local transports, served: a TCP port on 127.0.0.1 with one client at a time (a second client waits in the listen backlog until the first disconnects), as the game's sensor stream (AcresSensorStream.h), RL / DBW bridge (AcresRlBridge.h) and simulator-control channel (AcresSimControl.h) are. acres_sim's clients (stream.hpp) connect to it unchanged.
CoreSimServer.h ACRES Core behind the game's local protocols: the Polaris of ACRES Core (Core/Source, FAcresBatch with one environment per agent) served on the same three kinds of socket the packaged game opens, so the ROS 2 bridge (ROS/acres_sim sim_bridge) and every other client of those sockets talk to it unchanged: