Console and Config Options#

This page lists the console variables of the project, the engine settings in Acres/Config, the settings of the render tiers and the environment variables. Command-Line Options describes the options of the game, and Configuration Files describes the JSON files.

Group	Contents
Console Variables	The three variables that the game source defines, and how to set a variable.
Render Tier Settings	The engine variables that each render tier and each sensor render profile sets.
Engine Settings	`DefaultEngine.ini`: the map, the renderer, the physics step and the collision channel.
Game and Packaging Settings	`DefaultGame.ini`: the map to cook and the folders of the package.
User Settings and Input	`DefaultGameUserSettings.ini` and `DefaultInput.ini`.
Environment Variables	The variables that the tools, the tests and the ROS 2 environment read.

Console Variables#

The game source defines three console variables. It defines no console command. The simulation settings are command-line options and JSON keys, not console variables.

Variables of the Project#

Name	Type	Unit	Default	Description
`acres.FoliageWindDistance`	integer	cm	10000	The maximum distance of the wind animation of foliage. 0 keeps the distances of the assets. Each render tier sets 3000.
`acres.FoliageMaskDistance`	integer	cm	0	Beyond this distance, Nanite foliage renders as opaque geometry. 0 keeps the settings of the assets. The low tier sets 6000.
`acres.SunUpdateAngleDegrees`	number	deg	0.02	The minimum movement of the sun before the game updates its shadow projection. 0 updates in each frame. The maximum is 1.

The game applies the two foliage variables at the start of the map and when the render state changes. The foliage variables do not change the physics, the collision or the crop state.

The sources are AcresRenderTier.cpp and AcresEnvironment.cpp. In a Development build, the key ` opens the console.

A console variable at the start

Shell

Packaged/Linux/Acres.sh -VehicleDemo \
  "-ExecCmds=acres.SunUpdateAngleDegrees 0"

An engine setting for one run

Shell

Packaged/Linux/Acres.sh -VehicleDemo \
  "-ini:Engine:[/Script/Engine.PhysicsSettings]:MaxPhysicsDeltaTime=0.1"

Engine Commands That the Game Uses#

The game source sends these engine commands and sets this engine variable.

Name	Type	Unit	Description
`quit`	command		The game sends it for `Esc` in a session that did not start from the menu and in the free camera. `-ShellSmoke` sends it at its end.
`r.SetRes`	command	px	The video capture sends it to set the view to the size of `-ResX=` and `-ResY=`.
`csv.Benchmark`	integer		`-RenderBenchmark` sets it to 0. The CSV profiler then does not start its CPU benchmark.

r.SetRes 1920x1080w

Commands of the benchmark script

r.SetRes 1920x1080w,r.GPUCsvStatsEnabled 1

Render Tier Settings#

The render tier sets a group of engine variables in code at the start. These values have priority over the .ini files. The game selects the tier from the memory of the GPU: high for 11776 MiB or more, low below that. -RenderTier= selects a tier. Platforms and GPU Tiers describes the tiers and their cost.

While a camera or a LiDAR records, the game holds the render state at the sensor render profile. The profile is calibrated on the high tier and reduced-6gb on the low tier. -SensorRenderProfile= selects a profile. An episode records the values in force in episode.json, key sensor_profile_detail.render.

Variables of the Tiers#

The column "High" is the high tier and the profile calibrated. The column "Low" is the low tier without a recording sensor. The column "Reduced" is the profile reduced-6gb.

Variable	High	Low	Reduced
`sg.ViewDistanceQuality`, `sg.TextureQuality`, `sg.FoliageQuality`, `sg.ShadingQuality`	3	3	3
`sg.AntiAliasingQuality`	3	2	3
`sg.ShadowQuality`	3	2	3
`sg.GlobalIlluminationQuality`	3	1	3
`sg.ReflectionQuality`	3	1	3
`sg.PostProcessQuality`	3	2	3
`sg.EffectsQuality`	3	2	3
`r.LumenScene.SurfaceCache.AtlasSize`	8192	2048	2048
`r.Lumen.ScreenProbeGather.RadianceCache.ProbeResolution`	32	32	16
`r.Streaming.PoolSize`	3072	2048	2048
`r.Nanite.MaxPixelsPerEdge`	1	4	1
`r.StaticMeshLODDistanceScale`	1	2	1
`foliage.LODDistanceScale`	1	0.5	1
`r.Shadow.Virtual.ResolutionLodBiasDirectional`	0.5	3.5	0.5
`r.Shadow.Virtual.MaxPhysicalPages`	4096	2048	2048
`r.Shadow.Virtual.NonNanite.IncludeInCoarsePages`	1	0	1
`r.Shadow.Virtual.SMRT.RayCountDirectional`	8	4	8
`r.Shadow.Virtual.Clipmap.WPODisableDistance.LodBias`	0	0	0
`r.VolumetricCloud.ShadowMap.MaxResolution`	2048	128	2048
`r.VolumetricCloud.ShadowMap.RaySampleMaxCount`	128	16	128
`r.TSR.History.UpdateQuality`	3	3	3
`r.TSR.RejectionAntiAliasingQuality`	2	2	2
`r.TSR.ShadingRejection.Flickering`	1	1	1
`r.TSR.ShadingRejection.Flickering.Period`	2	3	2
`acres.FoliageWindDistance`	3000	3000	3000
`acres.FoliageMaskDistance`	0	6000	0

Record of the Render State#

r.ScreenPercentage is 100 on the high tier and 60 on the low tier. The sensor render profile does not change it. The scene captures of the camera ignore this variable.

When a console command changes one of these variables, an episode records settings_overridden true.

Log line of the tier

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

Part of the record in the episode manifest

"render": {
  "tier": "high",
  "tier_source": "auto",
  "gpu_memory_mib": 16311,
  "sensor_render_profile": "calibrated",
  "pinned": true,
  "settings": {
    "sg.ShadowQuality": "3",
    "r.LumenScene.SurfaceCache.AtlasSize": "8192",
    "r.Streaming.PoolSize": "3072",
    "r.Nanite.MaxPixelsPerEdge": "1",
    "acres.FoliageWindDistance": "3000",
    "acres.FoliageMaskDistance": "0"
  },
  "settings_overridden": false
}

Engine Settings#

Acres/Config/DefaultEngine.ini sets the engine for the project. The tables give each setting and its reason.

Physics#

Section [/Script/Engine.PhysicsSettings]. Time Stepping and Determinism gives the model.

Name	Type	Unit	Default	Description
`bTickPhysicsAsync`	boolean		True	The physics runs on its own thread with a fixed step.
`AsyncFixedTimeStepSize`	number	s	0.008333	The physics step, 1/120 s. The vehicle models use the same step.
`MaxPhysicsDeltaTime`	number	s	0.1	The maximum physics time for one frame. The physics stays in real time down to 10 frames in one second.
`DefaultGravityZ`	number	cm/s²	-980.665	The standard gravity.

The engine default of MaxPhysicsDeltaTime is 1/30 s. With that value, the simulation becomes slower than real time below 30 frames in one second.

Section [/Script/Engine.Engine]:

Name	Type	Unit	Default	Description
`bSmoothFrameRate`	boolean		False	The engine does not limit the frame rate.
`bUseFixedFrameRate`	boolean		False	The frame time is the real time. Lockstep sets its own timing.

[/Script/Engine.PhysicsSettings]
bTickPhysicsAsync=True
AsyncFixedTimeStepSize=0.008333333333333333
MaxPhysicsDeltaTime=0.1
DefaultGravityZ=-980.665

Renderer#

Section [/Script/Engine.RendererSettings]. These settings select the render features. A change needs a new build of the shaders.

Name	Type	Unit	Default	Description
`r.DynamicGlobalIlluminationMethod`	integer		1	Lumen gives the global illumination.
`r.ReflectionMethod`	integer		1	Lumen gives the reflections.
`r.Lumen.HardwareRayTracing`	boolean		True	Lumen uses hardware ray tracing.
`r.RayTracing`	boolean		True	Enables ray tracing. The GPU LiDAR traces the same ray-tracing scene.
`r.Shadow.Virtual.Enable`	integer		1	Enables virtual shadow maps.
`r.SkinCache.CompileShaders`	boolean		True	Ray tracing of skeletal meshes needs the skin cache.
`r.AntiAliasingMethod`	integer		4	Temporal Super Resolution.
`r.GenerateMeshDistanceFields`	boolean		True	Builds the distance fields of the meshes.
`r.DefaultFeature.AutoExposure`	boolean		True	Enables automatic exposure.
`r.DefaultFeature.AutoExposure.ExtendDefaultLuminanceRange`	boolean		True	Uses the extended luminance range for outdoor light.
`r.DefaultFeature.MotionBlur`	boolean		False	Disables motion blur.
`r.Streaming.PoolSize`	integer	MiB	2048	The texture pool. The render tier sets its own value.

The target shader formats are SF_VULKAN_SM6 on Linux, PCD3D_SM6 with DirectX 12 on Windows and SF_METAL_SM6 on macOS. The geometry is Nanite. The terrain tiles and the US 52 road are not Nanite meshes.

[/Script/Engine.RendererSettings]
r.DynamicGlobalIlluminationMethod=1
r.ReflectionMethod=1
r.Shadow.Virtual.Enable=1
r.RayTracing=True
r.Lumen.HardwareRayTracing=True
r.AntiAliasingMethod=4

[/Script/LinuxTargetPlatform.LinuxTargetSettings]
-TargetedRHIs=SF_VULKAN_SM5
+TargetedRHIs=SF_VULKAN_SM6

System Settings#

Section [SystemSettings]. These are the values of the low tier. The render tier sets the tier variables again in code. The table gives the settings that the render tier does not change.

Name	Type	Unit	Default	Description
`r.MaxAnisotropy`	integer		16	The anisotropic filter of the textures.
`r.Lumen.ScreenProbeGather.ShortRangeAO.FoliageOcclusionStrength`	number		0.25	Decreases the occlusion of foliage. The engine default makes the shaded side of dense corn black.
`r.EyeAdaptation.CachedLightingPreExposure`	number	EV	7	Moves the range of the cached lighting for the fixed outdoor exposure of EV100 13.
`r.TSR.History.ScreenPercentage`	number	%	100	The TSR history has the size of the output.
`r.RayTracing.ResidentGeometryMemoryPoolSizeInMB`	integer	MiB	1024	The pool for ray-tracing geometry that stays in memory. The terrain tiles need 144 MiB.

[SystemSettings]
r.ScreenPercentage=60
r.MaxAnisotropy=16
r.LumenScene.SurfaceCache.AtlasSize=2048
r.Lumen.ScreenProbeGather.ShortRangeAO.FoliageOcclusionStrength=0.25
r.EyeAdaptation.CachedLightingPreExposure=7
r.RayTracing.ResidentGeometryMemoryPoolSizeInMB=1024

Map, Game Mode and Collision#

Name	Type	Default	Description
`GameDefaultMap`, `EditorStartupMap`	text	`/Game/Maps/V03ACRE`	The map of the tile.
`GlobalDefaultGameMode`	text	`/Script/Acres.AcresShellGameMode`	The game mode. It selects the menu, the vehicle or the free camera from the command line.
`TargetedHardwareClass`	text	`Desktop`	The hardware class of the project.
`DefaultGraphicsPerformance`	text	`Maximum`	The graphics preset of the project.
`+DefaultChannelResponses`	text	`WheelGround`	The trace channel `ECC_GameTraceChannel1`. The default response is "ignore". Only surfaces that carry wheels block it.

The wheels and the LiDAR ground trace use the channel WheelGround.

[/Script/EngineSettings.GameMapsSettings]
EditorStartupMap=/Game/Maps/V03ACRE
GameDefaultMap=/Game/Maps/V03ACRE
GlobalDefaultGameMode=/Script/Acres.AcresShellGameMode

[/Script/Engine.CollisionProfile]
+DefaultChannelResponses=(Channel=ECC_GameTraceChannel1,
  DefaultResponse=ECR_Ignore,bTraceType=True,
  bStaticObject=False,Name="WheelGround")

Game and Packaging Settings#

`DefaultGame.ini`#

The file gives the project identity and the contents of the packaged game. Build the Game shows the package procedure.

Name	Type	Default	Description
`ProjectName`	text	`Acres`	The name of the Unreal project.
`BuildConfiguration`	text	`PPBC_Development`	The default configuration of a package.
`bUsePakFile`, `bUseIoStore`	boolean	True	The package contains the assets in container files.
`+MapsToCook`	text	`/Game/Maps/V03ACRE`	The only map of the package.
`+DirectoriesToAlwaysStageAsNonUFS`	text	`Simulation`	Copies `Content/Simulation` into the package as loose files. The game and the tools read them directly.
`+DirectoriesToAlwaysCook`	text	7 folders	The assets that the game loads by path at runtime. The example shows the folders.
`+DirectoriesToNeverCook`	text	`/Game/Python`	The editor scripts.

An asset that the game loads only by its path must be in a folder of +DirectoriesToAlwaysCook. Without that, the packaged game does not contain the asset.

[/Script/UnrealEd.ProjectPackagingSettings]
BuildConfiguration=PPBC_Development
bUsePakFile=True
bUseIoStore=True
+MapsToCook=(FilePath="/Game/Maps/V03ACRE")
+DirectoriesToNeverCook=(Path="/Game/Python")
+DirectoriesToAlwaysStageAsNonUFS=(Path="Simulation")
+DirectoriesToAlwaysCook=(Path="/Game/ACRE/Weather")
+DirectoriesToAlwaysCook=(Path="/Game/ACRE/NPC")
+DirectoriesToAlwaysCook=(Path="/Engine/BasicShapes")
+DirectoriesToAlwaysCook=(Path="/Game/ACRE/Materials")
+DirectoriesToAlwaysCook=(Path="/Game/ACRE/Vegetation/Meshes")
+DirectoriesToAlwaysCook=(Path="/Game/ACRE/Structures/Props")
+DirectoriesToAlwaysCook=(Path="/Game/FarmEquipment")

User Settings and Input#

`DefaultGameUserSettings.ini`#

The defaults of the window and of the scalability groups. The render tier sets the scalability groups again at the start.

Name	Type	Unit	Default	Description
`ResolutionSizeX`, `ResolutionSizeY`	integer	px	1920, 1080	The size of the view. `-ResX=` and `-ResY=` have priority.
`FullscreenMode`	integer		2	A window, not full screen.
`bUseVSync`	boolean		False	No vertical synchronisation.
`bUseDynamicResolution`	boolean		False	No dynamic resolution.
`FrameRateLimit`	number	Hz	0	No limit of the frame rate.
`sg.*` in `[ScalabilityGroups]`	integer		1 to 3	The values of the low tier.

[/Script/Engine.GameUserSettings]
bUseVSync=False
bUseDynamicResolution=False
ResolutionSizeX=1920
ResolutionSizeY=1080
FullscreenMode=2
FrameRateLimit=0.000000

[ScalabilityGroups]
sg.ResolutionQuality=100
sg.ShadowQuality=2
sg.GlobalIlluminationQuality=1

`DefaultInput.ini`#

The file contains the axis defaults of the engine and the console key. It contains no key bindings of the game. The game reads the keys in code (AcresVehicle.cpp, AcresVehicleControl.cpp, AcresShell.cpp). Drive the Maxxum Tractor and Drive the Polaris Ranger list the keys.

Name	Type	Default	Description
`+AxisConfig`	text	engine values	The dead zone and the sensitivity of each axis.
`DefaultPlayerInputClass`	text	`EnhancedPlayerInput`	The input class of the engine.
`DefaultViewportMouseCaptureMode`	text	`CapturePermanently_IncludingInitialMouseDown`	The view captures the mouse.
`+ConsoleKeys`	text	`Tilde`	The key that opens the console.

[/Script/Engine.InputSettings]
DefaultPlayerInputClass=/Script/EnhancedInput.EnhancedPlayerInput
DefaultViewportMouseCaptureMode=CapturePermanently_IncludingInitialMouseDown
+ConsoleKeys=Tilde

Environment Variables#

The game reads no environment variable. The tools, the tests and the ROS 2 environment read the variables below. Tools and Scripts describes the tools.

ROS 2 Environment#

ROS/Env/setup_env.sh sets these variables through ROS/Env/dds_safety.sh. They make the DDS loopback fence.

Name	Type	Default	Description
`ROS_LOCALHOST_ONLY`	integer	1	Each ROS 2 node uses only the address `127.0.0.1`.
`ROS_AUTOMATIC_DISCOVERY_RANGE`	text	`LOCALHOST`	The same limit for newer ROS 2 distributions.
`ROS_DOMAIN_ID`	integer	77	The DDS domain of the workstation. The real vehicle uses domain 0.
`RMW_IMPLEMENTATION`	text	`rmw_cyclonedds_cpp`	The middleware.
`CYCLONEDDS_URI`	path	`ROS/Env/cyclonedds_localhost.xml`	The Cyclone DDS configuration: loopback only, no multicast.
`COLCON_DEFAULTS_FILE`	path	`ROS/Env/colcon_defaults.yaml`	The build defaults of the workspace.
`ACRES_ROS_ENV`	text	`ros2`	Input: the name of the conda environment.
`ACRES_ROS_DDS_XML`	path		Input: a different Cyclone DDS file.
`CONDA_ROOT`	path	`~/miniconda3`	Input: the conda installation.

WARNING

Do not change these variables in a shell that can reach the real vehicle. Without the DDS loopback fence, a command can move the vehicle.

Shell

source ROS/Env/setup_env.sh
bash ROS/Env/check_dds_isolation.sh

acres_ros: ROS 2 humble | rmw_cyclonedds_cpp |
  ROS_DOMAIN_ID=77 | ROS_LOCALHOST_ONLY=1

Data Folders#

The calibration tools and the comparison tools read recorded data of the real vehicle from folders outside the repository.

Name	Type	Default	Description
`POLARIS_EXTRACT`	path	`~/Codes/polaris/extract`	The extracted logs of the Polaris.
`POLARIS_EPISODES`	path	`~/Codes/polaris/episodes`	The episodes that the tools cut from the logs.
`POLARIS_CACHE`	path	`$POLARIS_EPISODES/_cache`	The cache of the episode tools.
`POLARIS_FOLLOWER`	path	`$POLARIS_EPISODES/follower`	The runs of the path follower.
`POLARIS_LIDAR_WORK`	path	`$POLARIS_EPISODES/lidar_sim`	The work folder of the LiDAR comparison.
`ACRE_WEATHER`	path	`~/Codes/polaris/weather`	The data of the ACRE weather station.
`CLOSED_LOOP_OUT`	path	`$POLARIS_FOLLOWER/sim`	The output of `closed_loop_sim.py`.
`ACRES_CORE_SCRATCH`	path	`/tmp/acres-core-compare`	The work folder of `Core/Scripts/compare_unreal.py`.

Calibrate against Real Logs shows the procedure.

Shell

export POLARIS_EXTRACT=/data/polaris/extract
export POLARIS_EPISODES=/data/polaris/episodes
python Calibration/Polaris/inventory.py

Build, Run and Test Variables#

Name	Type	Default	Description
`UE`	path	`~/Downloads/UnrealEngine5.8.2`	The Unreal Engine folder for the tools that start the editor binary.
`CXX`	text	`g++`	The C++ compiler of the `build.sh` scripts in `Tools`.
`BUILD_DIR`	path		The output folder of `Core/build.sh`, `Tools/EpisodeLog/build.sh` and `Tools/PolarisModel`.
`PYTHON`	path	`python3`	The Python interpreter of `Core/build.sh` and of the demonstration scripts.
`ROS_SHARE`	path	`~/miniconda3/envs/ros2/share`	The message definitions for `Tools/EpisodeLog/gen_schemas.py`.
`ACRES_CORE_THREADS`	integer	0	The number of threads of a Core batch in the learning stack.
`ACRES_GAME_ARGS`	text		More game options for `Calibration/Polaris/camera_render.py`.
`VIDEO`	text		When set, `Demo/multi_agent_demo.sh` records a video with `-CaptureVideo=`.
`ACRES_CORE_SIM`, `ACRES_ROOT`	path		The binary and the repository root for the tests of `acres_core_sim`.
`ACRES_SIM_BRIDGE`, `ACRES_SIM_J1939_GOLDEN`, `ACRES_SIM_PARITY_REPORT`, `ACRES_SIM_DEBUG_HANG`	text		Inputs of the tests of `acres_sim`.
`FIELDDAY_ROOT`, `FIELDDAY_DATE`	path, text	`~/fieldday`, today	The session folder of the field-day kit.
`ACRES_POLICY_DIR`	path		The folder with the policy package for the field-day kit.

The editor scripts of Tools/ACRE read switches such as ACRES_ONLY, ACRES_RESTORE, ACRES_PASS and ACRES_SKIP_MATERIALS. The header of each script describes them.

Shell

# The engine in a different folder
UE=/opt/UnrealEngine python Tools/SimControl/lockstep_determinism.py \
  --out /tmp/lockstep --game editor

# ACRES Core in a different build folder
BUILD_DIR=/tmp/acres-core Core/build.sh --no-tests

# The terramechanics tests with clang
CXX=clang++ Tools/Terramechanics/build.sh

Console and Config Options#

Console Variables#

Variables of the Project#

Engine Commands That the Game Uses#

Render Tier Settings#

Variables of the Tiers#

Record of the Render State#

Engine Settings#

Physics#

Renderer#

System Settings#

Map, Game Mode and Collision#

Game and Packaging Settings#

DefaultGame.ini#

User Settings and Input#

DefaultGameUserSettings.ini#

DefaultInput.ini#

Environment Variables#

ROS 2 Environment#

Data Folders#

Build, Run and Test Variables#

`DefaultGame.ini`#

`DefaultGameUserSettings.ini`#

`DefaultInput.ini`#