Command-Line Options#

This page describes each command-line option that the game reads. The Option Index lists the same options with their source files.

Group	Contents
Syntax	The form of an option and the rules of the parser.
Start-Up and View	The session type, the HUD and the view camera.
Vehicles and Agents	The vehicle of the session, the agent list and the parameter files.
Implement	The implement of the Maxxum and its operator settings.
Spawn and Places	The start pose of agent 0.
Sensors	The recorder, the sensor configuration and each sensor model.
Environment and Weather	The clock, the temperature, the wind, the clouds, the rain and the fog.
Farm and Fields	The crops, the soil water and the saved farm state.
Farm Traffic and Workers	The vehicles and the persons that the game controls.
Replay and Drive Scripts	Command replay, path replay, episode replay and drive scripts.
Bridges and Ports	The vehicle bridge, the CAN transports and the sensor stream.
Simulator Control and Logs	The simulator control channel, lockstep, the session log and the episode log.
Render Tier and Capture	The render tier, the sensor profile and the video capture.
Test and Diagnostic Options	Scripted tests, benchmarks, menu hooks and the legacy tractor.
Standard Unreal Options	The options of Unreal Engine that the scripts of the repository use.
Options That the Index Does Not List	The options that the generator of the index does not find.

Syntax#

An option starts with one hyphen. The names are not case-sensitive. A switch has no value, for example -SessionLog. A value option has the form -Name=value, for example -EnvHour=10.5. Put a path that contains spaces in quotation marks.

The packaged game is Packaged/Linux/Acres.sh on Linux and Packaged\Windows\Acres.exe on Windows. The menu writes a session folder and then starts the simulation with the options of this page. Thus a script can do each operation that the menu does. Configuration Files gives the sequence.

Rule	Description
Sequence	The sequence of the options has no effect. `-RenderTier=` is the exception: its last value applies.
Lists	A list value uses commas or semicolons. Do not put spaces in a list.
Agent 0	Most options apply to agent 0 only. The agents file gives the settings of the other agents.
Units	The unit column gives the unit of the value. A choice shows its values in the description.
Errors	The game stops with a message when a value is outside the permitted range. The log file contains the message.

Three tags mark special options.

Tag	Meaning
`Test`	An option for the automatic tests and for diagnosis.
`Internal`	An option that the menu sets.
`Legacy`	An option of the legacy tractor or of old test scripts.

Start-Up and View#

Session Type#

These switches select the pawn that the game mode starts. Without one of them, the game shows the menu.

Name	Type	Default	Description
`-VehicleDemo`	switch	off	Starts a session with a vehicle at the default spawn. No menu shows.
`-ShellView`	switch	off	Starts a free camera for an inspection of the map. No vehicle exists.
`-FromMenu`	switch	off	`Internal` The menu sets it. `Esc` then opens the pause menu and does not stop the game.
`-SessionMode=`	choice		`Internal` The menu sets `simulation`, `replay`, `pilot` or `optimizer`. The HUD shows a replay row for `replay`.

ShellPython

# The menu
Packaged/Linux/Acres.sh

# The Maxxum in front of the ICSC garage
Packaged/Linux/Acres.sh -VehicleDemo

# The free camera
Packaged/Linux/Acres.sh -ShellView

import subprocess

subprocess.run(["Packaged/Linux/Acres.sh", "-VehicleDemo"])

HUD and View Camera#

The view camera follows the vehicle on a boom. These options set its start position. The game limits each value to the range in the description.

Name	Type	Unit	Default	Description
`-NoHUD`	switch		off	Hides the HUD. Use it for clean recordings of the view.
`-CameraCab`	switch		off	Starts in the cab view. The key `C` changes back to the chase view.
`-FarmCameraYaw=`	number	deg	0	The yaw of the boom relative to the vehicle.
`-FarmCameraPitch=`	number	deg	-18	The pitch of the boom. The range is -80 to -5.
`-FarmCameraDistance=`	number	m	9	The length of the boom. The range is 4 to 20. The default for the Polaris is 7.
`-FarmCameraSide=`	number	m	0	The offset of the camera to the side. The range is -5 to 5.
`-FarmCameraBack=`	number	m	0	The offset of the boom pivot to the rear. The range is 0 to 10.

Shell

Packaged/Linux/Acres.sh -VehicleDemo -NoHUD \
  -FarmCameraYaw=35 -FarmCameraPitch=-14 \
  -FarmCameraDistance=14

Vehicles and Agents#

Vehicle Selection#

A session has one agent or a list of agents. The limit is 8 agents. The game reads these three options as full tokens, thus the generated index does not list them.

Name	Type	Default	Description
`-Vehicle=`	choice	`maxxum`	The vehicle of a session with one agent: `maxxum` or `polaris`. `tractor`, `maxxum_150` and `ranger` are aliases.
`-Vehicles=`	list		One agent for each entry, for example `maxxum,polaris`. An entry can contain a pose.
`-Agents=`	path		A JSON file with the list `agents`. Each agent has its own settings. This option has priority over `-Vehicles=`.
`-PolarisFinish=`	choice	`graphite`	The paint of the Polaris: `graphite`, `forest_green`, `desert_tan` or `deep_blue`.

A pose in -Vehicles= has the form vehicle@u:v:yaw in survey cells and Unreal yaw. The second form is vehicle@utm:easting:northing:heading in UTM zone 16N, NAD83(2011). Without a pose, the game puts agent k at 7 m × k to the right of agent 0. When an obstacle occupies that position, the game tries the left side, then the rear and the front. Two agents with the same name get a number, for example polaris_2.

Run Several Vehicles shows a session with two vehicles.

Shell

# The Polaris with tan paint
Packaged/Linux/Acres.sh -VehicleDemo -Vehicle=polaris \
  -PolarisFinish=desert_tan

# Two agents, the second with a UTM pose
Packaged/Linux/Acres.sh -VehicleDemo \
  -Vehicles=maxxum,polaris@utm:500577.54:4480144.64:0.05

# Agents with their own settings
Packaged/Linux/Acres.sh -VehicleDemo -Agents=/data/agents.json

Agents File#

Each entry of the list agents is an object. For agent 0, a key that is not in the file uses the option in the third column. The other agents use only their keys.

Name	Type	Unit	Default	Description
`vehicle`	choice		`maxxum`	`maxxum` or `polaris`.
`name`	text		the vehicle	The name in the logs, the folders, the HUD and the bridge messages.
`finish`	choice		`graphite`	The paint of the Polaris. The option is `-PolarisFinish=`.
`implement`	text		`none`	The implement of the Maxxum. The option is `-Implement=`.
`gear`	integer		10	The start gear of the Maxxum. The option is `-VehicleGear=`.
`spawn`	list	cell, cell, deg		`[u, v, yaw]` on the survey grid.
`utm`	list	m, m, deg		`[easting, northing, heading]` in UTM zone 16N. The heading is clockwise from grid north.
`utm_frame`	choice		`nad83_2011`	The frame of `utm`: `nad83_2011` or `wgs84`.
`replay_file`	path			The option is `-ReplayFile=`.
`replay_mode`	choice		`commands`	The option is `-ReplayMode=`.
`replay_shift`	text	m,m		The option is `-ReplayShift=`.
`drive_script`	path			The option is `-DriveScript=`.
`rl_port`	integer		0	The port of the vehicle bridge. The option is `-RlPort=`.
`can_udp`	integer		0	The UDP port of the CAN transport. The option is `-RlCanUdp=`.
`sensor_stream`	integer		0	The port of the sensor stream. The option is `-SensorStream=`.
`sensor_record`	boolean			Records the sensors of this agent. The option is `-SensorRecord`.
`sensor_overlay`	path			A sensor file that the game puts on `sensors.json` for this agent.

Use absolute paths in the file. The game resolves a relative path from its working directory.

{"agents": [
  {"name": "maxxum", "vehicle": "maxxum",
   "implement": "chisel_plow",
   "drive_script": "/data/maxxum.json",
   "rl_port": 5555,
   "sensor_overlay": "/data/maxxum_sensors.json"},
  {"name": "polaris", "vehicle": "polaris",
   "finish": "desert_tan",
   "utm": [500577.540, 4480144.643, 0.054],
   "utm_frame": "nad83_2011",
   "rl_port": 5556}
]}

Parameter Files#

These options replace a shipped file of Acres/Content/Simulation with a different file. Configuration Files describes the files.

Name	Type	Default	Description
`-VehicleConfig=`	path	`tractor.json`	The parameters of the Maxxum, the soil, the surfaces and the implement settings.
`-PolarisConfig=`	path	`polaris.json`	The parameters of the Polaris.
`-PolarisSet=`	list		Changes parameters of the Polaris. The form is `key=value;key=value` with the dotted keys of `polaris.json`.
`-PolarisOccupants=`	integer	1	The number of persons in the Polaris. The range is 0 to 6. One person has a mass of 85 kg.
`-SensorConfig=`	path	`sensors.json`	The sensor configuration of the session.
`-PolarisSensorConfig=`	path	`sensors_polaris.json`	The sensor file that the game puts on the sensor configuration for the Polaris.
`-EnvConfig=`	path	`environment.json`	The clock and the weather.
`-FieldSetup=`	path		A folder with `field-setup.json` and `terrain-edits.f32`. The menu writes these files.
`-VehicleOutput=`	path	`Saved/Vehicle`	The session folder. Session Log describes its files.

Shell

# A steering delay of 50 ms and two persons
Packaged/Linux/Acres.sh -VehicleDemo -Vehicle=polaris \
  "-PolarisSet=dbw.steering.delay_s=0.05;mass.occupants=2"

# The files of an old session
S=Packaged/Linux/Acres/Saved/Sessions/20261002-101500-simulation
Packaged/Linux/Acres.sh -VehicleDemo \
  -VehicleConfig=$S/tractor.json -EnvConfig=$S/environment.json \
  -SensorConfig=$S/sensors.json -FieldSetup=$S \
  -VehicleOutput=/data/run2

Log line of the first command

ACRES_POLARIS_CONFIG file=.../Simulation/polaris.json
  keys=161 unknown=0 mass_kg=1318.0

Maxxum Drivetrain#

These options change the drivetrain state of the Maxxum at the start. Maxxum 150 Dynamics gives the model.

Name	Type	Unit	Default	Description
`-VehicleGear=`	integer		10	The start gear. The first gear is 1. The default is `vehicle.initial_gear` of `tractor.json`.
`-Vehicle2WD`	switch		off	Disengages the front-wheel drive.
`-VehicleDiffLock=`	choice		`off`	The differential lock at the start: `off`, `rear` or `all`. The key `L` changes it.
`-VehiclePtoKW=`	number	kW	0	A constant PTO load. The maximum is `vehicle.max_pto_kw`, 93.2 kW.
`-VehicleSurface=`	choice		`mapped`	Uses one surface of `tractor.json` at all positions. `mapped` uses the surface map of the tile.
`-VehicleSoilClass=`	choice		`auto`	Uses one soil class at all positions. `auto` uses the soil unit below each wheel.

The surface names are asphalt, concrete, gravel, dry_soil, wet_soil, mud, sod_lane, sod and dirt_track. The soil classes are sand, loamy_sand, sandy_loam, loam, silt_loam, silty_clay_loam and clay. Tyre and Soil gives the soil model.

Shell

Packaged/Linux/Acres.sh -VehicleDemo -VehicleGear=6 \
  -VehicleDiffLock=rear -VehicleSoilClass=clay

Implement#

Implement and Operator Settings#

These options apply to the Maxxum. They have priority over the block implement_model of tractor.json. The game stops when a value is outside the range. Implement Catalog describes each implement.

Name	Type	Unit	Default	Description
`-Implement=`	choice		`none`	The implement identifier. The values are below the table.
`-ImplementDepth=`	number	m	0.15	The working depth on firm level ground. The maximum is 0.6. A negative value selects the design depth.
`-HitchMode=`	choice		`auto`	The control mode of the hitch: `auto`, `position`, `draft` or `float`.
`-DraftSetpoint=`	number	N	15000	The set-point of the draft control. The range is 1000 to 60000.
`-SprayRate=`	number	L/ha	150	The application rate of the sprayer. The range is 40 to 600.
`-SeedRate=`	number	kg/ha	150	The seed rate of the drill. The range is 2 to 400.
`-WindrowDensity=`	number	kg/m	3	The mass of hay in one metre of windrow. The range is 0 to 12.
`-BaleMass=`	number	kg	450	The mass of the round bale for the loader. The range is 50 to 1200.
`-BoomLift=`	number	m	0.5	The lift of the sprayer boom. The range is 0 to 0.6.
`-ImplementSet=`	list			Changes keys of the implement file. The form is `key=value;key=value`.

The implement identifiers are none, cultivator, chisel_plow, disc_harrow, seed_drill, mounted_sprayer, loader_bale_fork, backhoe_attachment and square_baler. The keys of -ImplementSet= are the dotted keys of Acres/Content/Simulation/implements/<id>.json.

Shell

# A chisel plow in draft control, with changed hitch gains
Packaged/Linux/Acres.sh -VehicleDemo -Implement=chisel_plow \
  -ImplementDepth=0.20 -HitchMode=draft -DraftSetpoint=22000 \
  "-ImplementSet=control.draft_gain_deg=8;hitch.drop_rate_deg_s=6"

ACRES_IMPLEMENT_READY id=chisel_plow keys=69
  mass_kg=1100.0 width_m=2.70
  depth_range_m=0.000-0.279 hitch_mode=1
  draft_setpoint_n=22000

Shell

# A sprayer at 200 L/ha
Packaged/Linux/Acres.sh -VehicleDemo \
  -Implement=mounted_sprayer -SprayRate=200

Spawn and Places#

Start Pose#

A session without a pose starts at the place spawn-icsc-garage, in front of the ICSC garage. The game moves the vehicle forward in steps of 0.5 m when an obstacle occupies the place. The log line ACRES_SPAWN gives the final pose.

Name	Type	Unit	Default	Description
`-SpawnAt=`	text		`spawn-icsc-garage`	A place of `ACRE/places.json`. Give the identifier or the name of a point.
`-VehicleSpawnU=`	number	cell		The east coordinate on the survey grid. A value has priority over `-SpawnAt=`.
`-VehicleSpawnV=`	number	cell		The south coordinate on the survey grid.
`-VehicleSpawnYaw=`	number	deg	-90	The Unreal yaw. 0 points east and 90 points south.

The survey grid has 1000 × 1000 cells of 1.524 m. The spawn must be more than 5 cells from the edge of the tile. These poses have priority over the options: the pose of an agent, the first pose of a path replay, and a review route. Map Products describes places.json.

Shell

# A named place
Packaged/Linux/Acres.sh -VehicleDemo -SpawnAt=spawn-beck-lot

# A pose on the survey grid, to the north
Packaged/Linux/Acres.sh -VehicleDemo \
  -VehicleSpawnU=533 -VehicleSpawnV=470 -VehicleSpawnYaw=-90

ACRES_SPAWN place=spawn-beck-lot u=638.00 v=664.00
  x_m=210.31 y_m=249.94 z_m=0.44 yaw_deg=-90.0 nudge_m=0.0

Sensors#

Recorder#

The sensor recorder writes episodes into the session folder. Session Log describes the files. Collect Data shows the procedure.

Name	Type	Unit	Default	Description
`-SensorRecord`	switch		off	Records the sensors of all agents from the start. The key `F6` stops and starts an episode.
`-SensorOutput=`	path		`<session folder>/sensors`	The folder for the episode folders. The first is `episode-001`.
`-SensorSeed=`	integer		42	The seed of the sensor noise. The same seed gives the same noise.
`-SensorDelay=`	number	s	0.05	The delivery delay of each sensor sample. The range is 0 to 10.
`-SensorNoNoise`	switch		off	Removes the noise of the GNSS, the IMU, the INS, the LiDAR and the camera.
`-SensorNoCamera`	switch		off	Disables the camera.
`-SensorNoLidar`	switch		off	Disables the LiDAR.
`-SensorNoGnss`	switch		off	Disables the GNSS receiver.
`-SensorNoImu`	switch		off	Disables the IMU.
`-SensorNoCan`	switch		off	Disables the CAN log.
`-SensorNoIns`	switch		off	Disables the INS of the Polaris.

In a session with more than one agent, each agent records into <folder>/<agent name>.

ShellPython

Packaged/Linux/Acres.sh -VehicleDemo -SessionLog -SensorRecord \
  -SensorSeed=7 -SensorNoCan -VehicleOutput=/data/run1

import subprocess

subprocess.run(["Packaged/Linux/Acres.sh", "-VehicleDemo",
                "-SessionLog", "-SensorRecord",
                "-SensorSeed=7", "-SensorNoCan",
                "-VehicleOutput=/data/run1"])

/data/run1/sensors/episode-001/
  episode.json  sensors-config.json
  truth.jsonl  actions.jsonl  gnss.jsonl  imu.jsonl
  lidar.jsonl  camera.jsonl  can.jsonl
  camera/  lidar/

Camera#

These options change the camera of sensors.json. Camera gives the model. A change of the size keeps the field of view of a calibrated camera.

Name	Type	Unit	Default	Description
`-SensorCameraHz=`	number	Hz	10	The frame rate. The range is 1 to 120.
`-SensorCameraWidth=`	integer	px	896	The width of the image. The range is 64 to 4096.
`-SensorCameraHeight=`	integer	px	512	The height of the image. The range is 64 to 2160.
`-SensorCameraHfov=`	number	deg	90	The horizontal field of view of the pinhole camera. The range is 20 to 120.
`-SensorCameraWarmup=`	integer	frame	2	The number of renders before each image. The range is 0 to 16. 0 renders each frame.
`-SensorCameraExposure=`	choice		`volume`	The exposure mode: `volume`, `physical` or `copy`.
`-SensorCameraReadout=`	number	s	0.025	The readout time of the rolling shutter.
`-SensorCameraIdeal`	switch		off	Gives pinhole images without distortion, rolling shutter, sensor model and noise.
`-SensorCameraNoNoise`	switch		off	Removes the sensor noise of the camera.
`-SensorCameraNoDistortion`	switch		off	Removes the lens distortion.
`-SensorCameraNoRollingShutter`	switch		off	Removes the rolling shutter.
`-SensorCameraNoHistory`	switch		off	Disables the temporal history of the capture. Each image renders alone.
`-SensorCameraMainFamily`	switch		off	`Test` Renders the capture in the view family of the main view.
`-SensorCameraShowFlags=`	list			`Test` Sets engine show flags of the capture. The form is `Name=0,Name=1`.
`-SensorCameraSelfTest`	switch		off	`Test` Does the CPU checks of the camera model. It writes the folder `camera_selftest` into the episode.

Shell

# Clean pinhole images at 5 Hz
Packaged/Linux/Acres.sh -VehicleDemo -Vehicle=polaris \
  -SensorRecord -SensorCameraIdeal -SensorCameraHz=5

# A larger image with manual exposure
Packaged/Linux/Acres.sh -VehicleDemo -SensorRecord \
  -SensorCameraWidth=1280 -SensorCameraHeight=720 \
  -SensorCameraExposure=physical

LiDAR#

These options change the LiDAR of sensors.json. LiDAR gives the model. The defaults are those of the Maxxum. The Polaris file sensors_polaris.json sets other values.

Name	Type	Unit	Default	Description
`-SensorLidarHz=`	number	Hz	10	The scan rate. The range is 1 to 120.
`-SensorLidarRings=`	integer		8	The number of rings. The range is 1 to 128.
`-SensorLidarColumns=`	integer		180	The number of points in one ring. The range is 4 to 3600.
`-SensorLidarRange=`	number	m	60	The maximum range. The range is 1 to 200.
`-SensorLidarReturnMode=`	choice		`dual_strongest_last`	`strongest`, `last`, `first`, `dual_strongest_last`, `dual_first_last` or `triple`.
`-SensorLidarSubRays=`	integer		7	The number of rays that sample one beam.
`-SensorLidarDivergence=`	number	mrad	3	The full divergence angle of the beam.
`-SensorLidarIdeal`	switch		off	Gives a scan at one instant in clear air. The noise stays on.
`-SensorLidarNoMotion`	switch		off	Removes the motion distortion of the scan.
`-SensorLidarNoWeather`	switch		off	Removes the attenuation by rain and fog.
`-SensorLidarRain=`	number	mm/h		Sets the rain rate that the LiDAR model uses.
`-SensorLidarVisibility=`	number	m		Sets the visibility that the LiDAR model uses.
`-SensorCpuLidar`	switch		off	Uses the CPU ray caster and not GPU ray tracing.

Shell

# A 32-ring scan with one return for each beam
Packaged/Linux/Acres.sh -VehicleDemo -SensorRecord \
  -SensorLidarRings=32 -SensorLidarColumns=900 \
  -SensorLidarRange=120 -SensorLidarReturnMode=strongest

# The LiDAR in rain of 20 mm/h, without a change of the weather
Packaged/Linux/Acres.sh -VehicleDemo -Vehicle=polaris \
  -SensorRecord -SensorLidarRain=20

GNSS and IMU#

These options change the GNSS receiver and the IMU. INS and GNSS gives the models.

Name	Type	Unit	Default	Description
`-SensorGnssHz=`	number	Hz	10	The rate of the GNSS receiver. The range is 1 to 120.
`-SensorImuHz=`	number	Hz	120	The rate of the IMU. The range is 1 to 120.
`-SensorGnssStart=`	choice		`converged`	`converged` starts with an RTK fix. `cold` starts without a fix.
`-SensorGnssFrame=`	choice		`wgs84_g2139`	The frame of the output position: `wgs84_g2139` or `nad83`.
`-SensorGnssBaselineKm=`	number	km	5	The distance to the RTK base station. The error increases with the distance.
`-SensorGnssOutage=`	text	s:s		An interval without corrections. The form is `start:end` in seconds of episode time.

Shell

# A cold start and an outage from 20 s to 35 s
Packaged/Linux/Acres.sh -VehicleDemo -SensorRecord \
  -SensorGnssStart=cold -SensorGnssOutage=20:35

Environment and Weather#

Clock and Weather#

These options have priority over the environment file. Weather gives the model. The game ignores a value that is outside the range and writes a warning into the log.

Name	Type	Unit	Default	Description
`-EnvDate=`	text		`2026-07-15`	The start date in the form `YYYY-MM-DD`.
`-EnvHour=`	number	h	10	The local start time. 10.5 is 10:30. The range is 0 to 24.
`-EnvMinute=`	number	s	60	The real seconds for one minute of game time. 60 is real time. The range is 0.01 to 600.
`-EnvLowC=`	number	°C	16	The low temperature of the day. The minimum is -40.
`-EnvHighC=`	number	°C	28	The high temperature of the day. The maximum is 50.
`-EnvWind=`	number	m/s	3.5	The mean wind speed at 10 m. The range is 0 to 40.
`-EnvWindFrom=`	number	deg	225	The direction that the wind comes from. 0 is north and 90 is east.
`-EnvClouds=`	choice		`fair`	The cloud preset: `clear`, `fair`, `partly` or `overcast`.
`-EnvRain=`	list	h,h,mm		One rain event: the start hour, the end hour and the total depth.
`-EnvFog=`	text	m	`auto`	`auto`, `off` or a fixed visibility in metres.
`-EnvSeed=`	integer		42	The seed of the gusts, the clouds and the temperature noise.
`-EnvNoRainLens`	switch		off	Removes the rain streaks and the drops from the view and from the camera images.

The hours of -EnvRain= count from midnight of the start day. 26 is 02:00 of the next day. The mean rain rate must be below 150 mm/h.

Shell

# A wet October morning with rain from 09:00 to 11:00
Packaged/Linux/Acres.sh -VehicleDemo -EnvDate=2026-10-02 \
  -EnvHour=8.5 -EnvLowC=6 -EnvHighC=14 -EnvClouds=overcast \
  -EnvRain=9,11,18 -EnvWind=6 -EnvWindFrom=300

# One game hour in one real minute
Packaged/Linux/Acres.sh -VehicleDemo -EnvMinute=1

ACRES_ENVIRONMENT_READY day 1 08:30 | 8.0 C RH 94% |
  sun 8 deg | cloud 96% | rain 0.0 mm/h (0.0 mm) |
  wind 4.8 m/s from 300 | vis 6.8 km | x1

Farm and Fields#

Crops and Soil Water#

These options set the start state of the farm. Crops and Ground Classes and Soil Water give the models.

Name	Type	Unit	Default	Description
`-CropSeason=`	text		`2026`	The crop map `ACRE/crops_<name>.json`. `legacy` keeps the surveyed crops and plants corn on the other fields.
`-CropStage=`	choice		`mature`	`mature` gives full growth. `date` grows each field from its planting date to the session date.
`-FarmInitialGrowth=`	number		1	The growth fraction of all fields, 0 to 1. It has priority over `-CropStage=date`.
`-FarmGeneratedCrops=`	boolean		1	0 leaves the fields without surveyed crop patches bare.
`-FarmInitialTheta=`	number		0.5	The start water content as a fraction between wilting point and field capacity, 0 to 1.
`-FarmKsatScale=`	number		1	A multiplier of the saturated conductivity of all soils. The range is above 0 to 10.
`-FarmPreDays=`	number	d	0	Runs the farm for this number of days before the start. The maximum is 366.
`-FarmEvap=`	number	mm/d		Sets a constant evaporation. Without it, the weather model gives the evaporation. The range is 0 to 20.
`-FarmDisabled`	switch		off	Starts without crops, soil water and ruts. The weather stays.

Shell

# Wet soil and crops at their state on 20 June
Packaged/Linux/Acres.sh -VehicleDemo -FarmInitialTheta=0.9 \
  -EnvDate=2026-06-20 -CropStage=date

# Plain terrain for a quick start
Packaged/Linux/Acres.sh -VehicleDemo -FarmDisabled

ACRES_CROP_SEASON 2026 fields planted=47 default_rule=20
  weather_days=244
ACRES_FARM_READY patches=705070 harvester=0
  water_cells=145924 units=36 mean_theta=0.287

Farm State and Ground Detail#

A session writes the farm state into the session folder at its end. A later session can continue from that state.

Name	Type	Default	Description
`-FarmLoad=`	path		Starts from a saved `farm-state.json`. The game stops when the file is for a different farm setup.
`-FarmFresh`	switch	off	With `-ReplayFile=`: ignores `farm-start-state.json` of the replayed session and starts on new fields.
`-FarmHarvester`	switch	off	Installs the 3 m harvest cutter and the 600 kg bunker on the hitch. No implement is then possible.
`-FarmHarvestOn`	switch	off	With `-FarmHarvester`: starts with the cutter on.
`-NoFieldDetail`	switch	off	Draws field work with the coarse ground tiles only. Use it for frame-time comparisons.
`-NoGroundCoverFit`	switch	off	Keeps the grass instances of the level at their positions. The game does not fit them to the surface map.

Shell

# Continue on the fields of an old session
Packaged/Linux/Acres.sh -VehicleDemo \
  -FarmLoad=/data/run1/farm-state.json -VehicleOutput=/data/run2

Farm Traffic and Workers#

Vehicles and Workers of the Game#

The game can control farm vehicles, highway cars and walking workers. Farm Traffic and Workers gives the model. The game writes incidents into npc-events.csv of the session folder.

Name	Type	Default	Description
`-NpcVehicles`	switch	off	Adds pickups on the roads and tractors in the fields. It also adds 16 highway cars.
`-NpcWorkers`	switch	off	Adds walking farm workers.
`-NpcTraffic=`	integer	16 or 0	The number of cars on US 52. The range is 0 to 200. Alone, it starts only the highway cars.
`-NpcTestVictim`	switch	off	`Test` Puts a worker 14 m in front of the vehicle.

Shell

# Farm vehicles, workers and 16 highway cars
Packaged/Linux/Acres.sh -VehicleDemo -NpcVehicles -NpcWorkers

ACRES_NPC_TRAFFIC cars=16 models=9 road_m=1536
ACRES_NPC_READY road_nodes=2306 spots=34 empty_fields=4
  service=4 npcs=36

Shell

# Only 40 highway cars
Packaged/Linux/Acres.sh -VehicleDemo -NpcTraffic=40

ACRES_NPC_TRAFFIC cars=40 models=9 road_m=1536
ACRES_NPC_READY road_nodes=2306 spots=34 empty_fields=4
  service=4 npcs=40

Replay and Drive Scripts#

Command Replay and Path Replay#

A replay drives the vehicle from a CSV file. The file is a session log or a file from a different program. Replay shows the procedure and gives the format of the file.

Name	Type	Unit	Default	Description
`-ReplayFile=`	path			A CSV file or a session folder. For a folder, the game reads `tractor.csv`.
`-ReplayMode=`	choice		`commands`	`commands` applies the logged speed and curvature. `path` follows the logged path.
`-ReplayShift=`	list	m,m		Moves the logged path east and north. Use it for a track without an RTK fix.

The file must have the columns time_s, speed_mps and curvature_1pm. The mode path also needs east_m and north_m, or ue_x_m and ue_y_m. A replay writes replay-tracking.csv and replay-summary.json into the session folder.

Shell

# Follow the path of an old session
Packaged/Linux/Acres.sh -VehicleDemo -SessionLog \
  -ReplayFile=/data/run1 -ReplayMode=path \
  -VehicleOutput=/data/run1-replay

ACRES_REPLAY_READY rows=441 duration=22.0 s path=1
  mode=path source=/data/run1/tractor.csv

Drive Script#

A drive script is a JSON file with timed controls, a path and camera moves. Replay describes the keys of the file.

Name	Type	Unit	Default	Description
`-DriveScript=`	path			The drive script of agent 0. The key `exit` of the script stops the game.

Shell

Packaged/Linux/Acres.sh -VehicleDemo -Implement=chisel_plow \
  -DriveScript=/data/drive.json

{"frame": "spawn", "path": [[0, 0], [80, 0]],
 "keys": [
  {"t": 0, "gear": 8, "speed_kmh": 0, "raise": true},
  {"t": 2, "speed_kmh": 8},
  {"t": 6, "raise": false},
  {"t": 22, "exit": true}]}

ACRES_DRIVE_SCRIPT keys=4 path_points=2 file=/data/drive.json

Episode Replay#

An episode replay shows an episode log. The agents follow the logged states and the game applies the logged farm events. The sensors record as in a live session. Episode Log describes the file.

Name	Type	Unit	Default	Description
`-EpisodeReplay=`	path			The MCAP file. Without an agent list, the game creates the agents of the log.
`-EpisodeReplayExit`	switch		off	Stops the game at the end of the replay.

Shell

# Make the images of a logged episode
Packaged/Linux/Acres.sh -VehicleDemo \
  -EpisodeReplay=/data/episode.mcap -EpisodeReplayExit \
  -SensorRecord -VehicleOutput=/data/render

Bridges and Ports#

Vehicle Bridge and CAN#

A client controls a vehicle through the vehicle bridge. All sockets listen on 127.0.0.1 only. Vehicle Bridge gives the protocol.

Name	Type	Default	Description
`-RlPort=`	integer	0	The TCP port of the vehicle bridge of agent 0. 0 disables the bridge.
`-RlPorts=`	list		One port for each agent, in the sequence of the agents. The key `rl_port` of an agent has priority.
`-RlCan=`	text		A SocketCAN interface of Linux for the J1939 frames of agent 0, for example `vcan0`.
`-RlCanUdp=`	integer	0	A UDP port for the same CAN frames. No `vcan` interface is necessary.

Shell

# One vehicle
Packaged/Linux/Acres.sh -VehicleDemo -Vehicle=polaris -RlPort=5556

# Two vehicles
Packaged/Linux/Acres.sh -VehicleDemo -Vehicles=maxxum,polaris \
  -RlPorts=5555,5556

# J1939 frames in UDP datagrams
Packaged/Linux/Acres.sh -VehicleDemo -RlCanUdp=5601

Sensor Stream#

The sensor stream sends the INS, the LiDAR clouds and the camera images to the ROS 2 bridge. A vehicle with a sensor stream always has an INS. Sensor Stream gives the format.

Name	Type	Unit	Default	Description
`-SensorStream=`	integer		0	The TCP port of the sensor stream of agent 0. Without `-SensorRecord`, the sensors write no files.
`-SensorStreams=`	list			One port for each agent, in the sequence of the agents.

Shell

Packaged/Linux/Acres.sh -VehicleDemo -Vehicle=polaris \
  -RlPort=5556 -SensorStream=5557 -SimControl=5600

ACRES_SENSOR_STREAM_LISTENING agent=polaris port=5557
ACRES_RL_LISTENING port=5556
ACRES_SIM_CONTROL_LISTENING port=5600

ROS 2 CLI

source ROS/Env/setup_env.sh
ros2 launch acres_sim sim.launch.py

Simulator Control and Logs#

Simulator Control Channel and Lockstep#

The simulator control channel controls the session: pause, steps, resets, conditions and recording. Simulator Control Channel gives the protocol. Lockstep Stepping shows the procedure.

Name	Type	Unit	Default	Description
`-SimControl=`	integer		0	The TCP port of the simulator control channel.
`-Lockstep`	switch		off	Starts in lockstep. The simulation advances only when a client requests physics steps.

Shell

Packaged/Linux/Acres.sh -VehicleDemo -Vehicle=polaris \
  -SimControl=5600 -Lockstep -RlPort=5556

ACRES_RL_LISTENING port=5556
ACRES_SIM_CONTROL_LISTENING port=5600
ACRES_LOCKSTEP on
ACRES_SIM_CONTROL_READY port=5600 lockstep=1 replay=0 log=

Session Log and Episode Log#

The session log is a set of CSV and JSON files. The episode log is one MCAP file with the states of all agents. Session Log and Episode Log describe the formats.

Name	Type	Default	Description
`-SessionLog`	switch	off	Writes `tractor.csv` at 120 Hz and `session-summary.json` for each agent.
`-VehicleRecord`	switch	off	Keeps the telemetry in memory and writes `vehicle.csv` and `metadata.json` at the end.
`-DbwLog`	switch	off	Writes `dbw.csv` of the Polaris without `-SessionLog`.
`-EpisodeLog=`	path		Records the episode log into this MCAP file from the first physics step.

Shell

Packaged/Linux/Acres.sh -VehicleDemo -Vehicles=maxxum,polaris \
  -SessionLog -EpisodeLog=/data/run3/episode.mcap \
  -VehicleOutput=/data/run3

Render Tier and Capture#

Render Tier and Sensor Profile#

The render tier sets the quality of the main view. Platforms and GPU Tiers describes the tiers. Console and Config Options lists the settings of each tier.

Name	Type	Unit	Default	Description
`-RenderTier=`	choice		`auto`	`low`, `high` or `auto`. `auto` selects `high` for a GPU with 11.5 GiB of memory or more.
`-SensorRenderProfile=`	choice			The render state of the sensors: `calibrated` or `reduced`. Without it, the tier selects the state.

Shell

Packaged/Linux/Acres.sh -VehicleDemo -RenderTier=low \
  -SensorRenderProfile=calibrated

ACRES_RENDER_TIER tier=high vram_mb=16311 source=auto
  screen_percentage=100 pinned=0 sensor_profile=calibrated

Video Capture#

The game can record its own view, with the HUD, into an MP4 file. The capture needs ffmpeg on the search path. The game tries the encoders h264_nvenc, libx264, libopenh264 and mpeg4 in this sequence.

Name	Type	Unit	Default	Description
`-CaptureVideo=`	path			The MP4 file. The option starts the capture.
`-CaptureFps=`	number	Hz	30	The frame rate of the video. The range is 1 to 120.
`-CaptureSeconds=`	number	s	0	Stops the game after this time. 0 records until the game stops.
`-CaptureSize=`	text	px	view size	The size of the video in the form `WIDTHxHEIGHT`. The GPU scales the frames.
`-CaptureCodec=`	text			Uses one encoder of the list only.
`-ResX=`	integer	px	1920	The width of the view. The capture sets the view to this size.
`-ResY=`	integer	px	1080	The height of the view.

Shell

Packaged/Linux/Acres.sh -VehicleDemo -RenderOffscreen \
  -ResX=1920 -ResY=1080 -CaptureVideo=/data/drive.mp4 \
  -CaptureSeconds=30 -DriveScript=/data/drive.json

Test and Diagnostic Options#

The automatic tests and the developers use these options. A normal session does not need them.

Scripted Vehicle Tests#

A scripted test drives the vehicle on a flat test pad of 400 m and then stops the game. The sequence is: brake for 3 s, 70 % throttle until 11 s, then brake.

Name	Type	Unit	Default	Description
`-VehicleTest=`	choice			`Test` `straight`, `turn`, `reverse`, `coast` or `impact`. The test writes `vehicle.csv`.
`-VehicleTestDuration=`	number	s	17	`Test` The length of the test.
`-VehicleTestPad`	switch		off	`Test` Uses the flat test pad without a scripted test.
`-VehicleSlope=`	number	deg	0	`Test` The pitch of the test pad. The range is -20 to 20. A value selects the test pad.
`-VehicleTerrainTest`	switch		off	`Test` Does the scripted test on the terrain of the tile.
`-VehicleCapture`	switch		off	`Test` Writes the screenshot `vehicle.png` 2 s before the end of the test.
`-TerrainVerify`	switch		off	`Test` Compares the terrain collision with the survey at 441 points. It writes `terrain-probes.csv`.
`-RigSelfTest`	switch		off	`Test` Compares each equipment rig with its test poses. The log shows one line `ACRES_RIG_SELFTEST` for each rig.

Shell

Packaged/Linux/Acres.sh -VehicleDemo -RenderOffscreen \
  -VehicleTest=turn -VehicleSlope=5 \
  -VehicleOutput=/data/test-turn

ACRES_VEHICLE_TEST_FINISHED steps=2040 written=1
  output=/data/test-turn

Review Routes#

A review route is a road of ACRE/site.json. The game drives the Maxxum along the route and writes the camera poses.

Name	Type	Unit	Default	Description
`-VehicleRoute=`	integer			`Test` The index of the road, from 0. The game writes `review-frames.csv` and `route-result.json`.
`-VehicleRouteSpeed=`	number	m/s	7.5	`Test` The target speed on the route.
`-VehicleRouteReverse`	switch		off	`Test` Drives the route from its end to its start.

Shell

# Road 3 is "north cross farm"
Packaged/Linux/Acres.sh -VehicleDemo -VehicleRoute=3 \
  -VehicleRouteSpeed=5 -VehicleOutput=/data/route3

Render Benchmark and Inventory#

The benchmark measures the frame time. With -VehicleDemo, the Maxxum drives a circle. With -ShellView, the camera stays at its position. Tools and Scripts describes the benchmark scripts.

Name	Type	Unit	Default	Description
`-RenderBenchmark`	switch		off	`Test` Starts the benchmark. It writes `engine.csv`, `wall-frames.csv` and `review.png`.
`-RenderBenchmarkWarmup=`	number	s	20	`Test` The time before the measurement.
`-RenderBenchmarkDuration=`	number	s	31 or 30	`Test` The time of the measurement. The default is 31 with a vehicle and 30 with the free camera.
`-RenderBenchmarkOutput=`	path		`Saved/VehiclePerformance`	`Test` The output folder. With the free camera, the default is `Saved/Performance`.
`-RenderInventory`	switch		off	`Test` Writes one log line `ACRES_RENDER_MESH` for each static mesh of the level.
`-ShellSmoke`	switch		off	`Test` With `-ShellView`: moves the camera, writes `shell-smoke.png` and stops after 35 s.

Shell

python Tools/Performance/benchmark_linux.py --name high-maxxum \
  --field-loop --render-tier high

# The same benchmark without the script
Packaged/Linux/Acres.sh -VehicleDemo -RenderOffscreen \
  -RenderBenchmark -RenderBenchmarkWarmup=20 \
  -RenderBenchmarkDuration=31 -RenderBenchmarkOutput=/data/bench

These options operate the menu without a mouse. The tests of the menu and the demonstration scripts use them.

Name	Type	Default	Description
`-MenuDemo=`	path		Plays a scripted sequence in the menu and then starts the session. `Demo/Menu` contains examples.
`-MenuOpen=`	choice		`Test` Opens a configuration: `simulation`, `replay`, `pilot` or `optimizer`.
`-MenuTab=`	text		`Test` With `-MenuOpen=`: selects a tab, for example `Weather`.
`-MenuSet=`	list		`Test` With `-MenuOpen=`: sets parameters. The form is `id=value;id=value`.
`-MenuBrushTest=`	integer		`Test` With `-MenuOpen=`: applies test edits to the terrain of a field.
`-MenuRunNow`	switch	off	`Test` With `-MenuOpen=`: starts immediately. For the optimizer, it solves before the screenshot.
`-MenuShot=`	path		`Test` Writes a screenshot of the menu after 6 s.
`-MenuOptVisualize=`	integer		`Test` After the screenshot: starts the replay that shows the optimizer result of this field.
`-MenuAutoStart`	switch	off	`Test` After the screenshot: starts the session.
`-MenuExitAfterShot`	switch	off	`Test` After the screenshot: stops the game.

The identifiers of -MenuSet= are those of Menu Settings, for example trac:vehicle.mass_kg. The log line ACRES_MENU_ISSUES shows the validation messages of the menu.

Shell

# A screenshot of the weather tab with a rain event
Packaged/Linux/Acres.sh -RenderOffscreen -MenuOpen=simulation \
  -MenuTab=Weather \
  "-MenuSet=env:rain.enabled=1;env:rain.total_mm=25" \
  -MenuShot=/data/menu-weather.png -MenuExitAfterShot

# The scripted menu sequence of the demonstration
Packaged/Linux/Acres.sh -MenuDemo=Demo/Menu/rain.json

ACRES_MENU_ISSUES ✔  Configuration is physically consistent.

Legacy Tractor and Legacy Farm Options#

The legacy tractor is the vehicle model before the Maxxum equipment rig. It has static meshes and a draft implement from ASABE D497. The regression tests use it. The legacy farm options stay for old test scripts.

Name	Type	Unit	Default	Description
`-VehicleModel=`	choice		`maxxum_150`	`maxxum_150` or `legacy`. The key `vehicle.model` of `tractor.json` gives the default.
`-VehicleImplement=`	choice		`none`	`Legacy` `none`, `mounted` or `trailed`. The Maxxum ignores it with a warning.
`-VehicleImplementType=`	choice		`custom`	`Legacy` `custom`, `moldboard`, `chisel`, `disk`, `cultivator`, `planter` or `potato_digger`.
`-VehicleImplementWidth=`	number	m	3	`Legacy` The working width. The maximum is 20.
`-VehicleImplementDepth=`	number	cm	18	`Legacy` The working depth. The maximum is 60.
`-VehicleDraft=`	number	N	0	`Legacy` The draft of a `custom` implement at its design speed. The maximum is 100000.
`-VehiclePayload=`	number	kg	0	`Legacy` The payload of the implement. The maximum is `implement.rated_payload_kg`.
`-VehicleSoilTexture=`	choice		`auto`	`Legacy` The soil texture for the draft: `auto`, `fine`, `medium` or `coarse`.
`-FarmRain=`	number	mm/h		`Legacy` A constant rain rate. The range is 0 to 200. Use `-EnvRain=` in new scripts.
`-FarmTimeScale=`	number			`Legacy` The ratio of game time to real time. Use `-EnvMinute=` in new scripts.
`-FarmMinC=`	number	°C		`Legacy` The low temperature, without variation between days. Use `-EnvLowC=`.
`-FarmMaxC=`	number	°C		`Legacy` The high temperature, without variation between days. Use `-EnvHighC=`.

Shell

# The legacy tractor with a mounted chisel plow from ASABE D497
Packaged/Linux/Acres.sh -VehicleDemo -VehicleModel=legacy \
  -VehicleImplement=mounted -VehicleImplementType=chisel \
  -VehicleImplementDepth=20

Standard Unreal Options#

Unreal Engine reads these options. The scripts of the repository use them. The game source reads -nullrhi, -ResX= and -ResY= also.

Engine Options in the Scripts#

Name	Type	Unit	Default	Description
`-RenderOffscreen`	switch		off	Renders without a window. Use it on a computer without a display and through SSH.
`-nullrhi`	switch		off	Starts without a renderer. The physics, the bridges and lockstep operate. The camera gives no images.
`-windowed`	switch			Shows the game in a window.
`-ResX=`, `-ResY=`	integer	px	1920, 1080	The size of the view.
`-ForceRes`	switch		off	Keeps the size of `-ResX=` and `-ResY=` when the display is smaller.
`-nosound`	switch		off	Disables the audio device.
`-unattended`	switch		off	Shows no dialogue windows.
`-log`	switch		off	Shows the log in a console window.
`-abslog=`	path			Writes the log file to this absolute path.
`-ExecCmds=`	list			Does console commands at the start. Separate the commands with commas.
`-ini:Engine:[Section]:Key=Value`	text			Changes one setting of the engine configuration for this run.

With -nullrhi, the render tier and the ground visuals do not start. A console command that changes a setting of the sensor profile makes the profile of a recording custom.

Shell

# A session without a display
Packaged/Linux/Acres.sh -VehicleDemo -RenderOffscreen \
  -ResX=1280 -ResY=720 -nosound

# Physics only, in lockstep
Packaged/Linux/Acres.sh -VehicleDemo -Vehicle=polaris -nullrhi \
  -Lockstep -SimControl=5600 -RlPort=5556

# Real-time physics down to 10 frames in one second
Packaged/Linux/Acres.sh -VehicleDemo \
  "-ini:Engine:[/Script/Engine.PhysicsSettings]:MaxPhysicsDeltaTime=0.1"

Options That the Index Does Not List#

The generator of the Option Index finds the FParse calls of the game source. It does not find the three options that AcresAgents.cpp reads as full tokens: -Vehicle=, -Vehicles= and -Agents=. Vehicle Selection describes them.

The index lists -ReplayFile= for AcresHud.cpp. That file tests the switch form -ReplayFile, which has no function. The index lists -nullrhi, -ResX= and -ResY=. These are engine options that the game source reads also.

Command-Line Options#

Syntax#

Start-Up and View#

Session Type#

HUD and View Camera#

Vehicles and Agents#

Vehicle Selection#

Agents File#

Parameter Files#

Maxxum Drivetrain#

Implement#

Implement and Operator Settings#

Spawn and Places#

Start Pose#

Sensors#

Recorder#

Camera#

LiDAR#

GNSS and IMU#

Environment and Weather#

Clock and Weather#

Farm and Fields#

Crops and Soil Water#

Farm State and Ground Detail#

Farm Traffic and Workers#

Vehicles and Workers of the Game#

Replay and Drive Scripts#

Command Replay and Path Replay#

Drive Script#

Episode Replay#

Bridges and Ports#

Vehicle Bridge and CAN#

Sensor Stream#

Simulator Control and Logs#

Simulator Control Channel and Lockstep#

Session Log and Episode Log#

Render Tier and Capture#

Render Tier and Sensor Profile#

Video Capture#

Test and Diagnostic Options#

Scripted Vehicle Tests#

Review Routes#

Render Benchmark and Inventory#

Menu Hooks#

Legacy Tractor and Legacy Farm Options#

Standard Unreal Options#

Engine Options in the Scripts#

Options That the Index Does Not List#