rocketsim
Use rocketsim to simulate Rocket League car and ball physics without
starting the game. It supports bot testing, agent training, and ball-motion
prediction. Your application controls the simulation and reads its state.
The library does not open a window.
Enable the optional serde feature if you need to serialize simulation types.
The core library does not need a C++ compiler or graphics libraries.
For an existing application, see the 0.2-to-0.3 migration guide.
Prepare the collision meshes
Supply compatible .cmf collision meshes before you create an arena. The
crate does not include these files. Use the following directory layout:
collision_meshes/
soccar/ 16 .cmf files
hoops/ 12 .cmf files
dropshot/ 2 .cmf files
You only need the mesh sets for the modes you use. Soccar, Snowday, and
Heatseeker share the Soccar set. TheVoid does not need meshes.
init_from_default reads ./collision_meshes/ relative to the process's
working directory. Use rocketsim::init for another directory. Use
init_from_mem to supply .cmf byte buffers.
Load all required modes on the first successful initialization. Later calls do not replace the loaded meshes. You can retry a failed initialization. Handle its error before you create an arena. Creating an arena for an unloaded mode panics.
Mesh files are external assets. Review their source and license before you redistribute them.
Run a simulation
This complete program creates a car, applies throttle, and runs one simulated
second. Run it from the directory that contains collision_meshes/:
use ;
Each step_tick advances the simulation by 1/120 second. It does not wait
for real time. Omit sleeps when you need the simulation to run as fast as
possible.
Apply controls and read results
- Set inputs with
set_car_controlsbefore a tick. Controls remain active until you replace them. SendCarControls::default()to release all inputs. - Release
jumpbefore you press it again for another jump or flip. - Read car and ball state with
get_car_stateandget_ball_state. - Read collision and boost-pickup events from the slice returned by
step_tick. Copy events you need to keep before you step again. - Check
is_ball_scoredafter stepping. Your application must keep the match score and reset play after a goal.
Configure an arena
Use ArenaConfig to select a game mode, mutators, memory mode, and random
seed. After you load the meshes, you can create an arena like this:
use ;
let config = new
.with_rng_seed
.with_mem_weight_mode;
let mut arena = new_with_config;
Supported modes are Soccar, Hoops, Dropshot, Snowday, Heatseeker, and TheVoid.
Use the same initial state, seed, and inputs for repeatable runs.
Balanced is the default memory mode. Use Light to reduce memory use.
Heavy uses smaller ray-query cells and reserves more handles per cell.
It does not guarantee higher speed. Compare modes on your workload.
The following values are approximate Linux RSS measurements on a Ryzen 9
7940HS. After mesh initialization and worker startup, create 100 Soccar arenas
with Octane cars and default mutators. Run 100 episodes of 120 ticks per
arena with fixed generated controls on 16 workers, one per logical CPU.
Use platform math (the default), SAT, and the parallel feature. Subtract
initial RSS from live RSS and divide by 100 while the arenas are still alive.
The 1v1 workload uses two cars per arena. The 3v3 workload uses six.
Use the median of three separate processes for each entry.
| Mode | 1v1 memory per arena | 3v3 memory per arena |
|---|---|---|
Heavy |
1,062 KiB | 1,076 KiB |
Balanced |
86 KiB | 102 KiB |
Light |
51 KiB | 65 KiB |
These values are not upper bounds. RSS includes allocator retention and shared pages. This run measures 12,000 ticks per arena. Do not compare these values directly with the earlier 1,000,000-tick measurement. The input sequence also differs. This memory probe does not measure simulation speed.
The separate speed screen uses 512 arenas on 16 workers. It replays 32
120-tick windows from each of the Nexto 1v1 and Wisp 3v3 recordings. Builds
use native-math, SAT, and the parallel feature. Each entry is the median
of three samples. Controls and the full per-tick batch join are timed.
Construction, restore, and result reads are not timed.
| Mode | 1v1 thousand arena-ticks/s | 3v3 thousand arena-ticks/s |
|---|---|---|
Heavy |
2,237 | 977 |
Balanced |
2,312 | 1,060 |
Light |
2,478 | 1,191 |
This short screen does not establish a speed order for all workloads. Measure your own roster, arena count, and worker count.
Light shares a packed static-AABB table for ray culling. Dynamic proxies,
retained contacts, events, pad timers, and random state remain local to each
arena. Balanced and Heavy keep their existing query path.
Step many arenas in parallel
Enable the optional parallel feature to use Arena::step_batch and
Arena::step_batch_with:
[]
= { = "0.3", = ["parallel"] }
An empty batch or a batch with one arena runs on the calling thread. It does
not use the Rayon pool. A batch with two or more arenas uses the current Rayon
pool. By default, the current pool is the process-global pool. Set
RAYON_NUM_THREADS before the first parallel call to choose its size. Use
pool.install(|| Arena::step_batch(&mut arenas)) to select a local pool.
Each arena keeps its own physics state and random generator. The worker that runs an arena does not change its result. The arena order across workers is not specified. A panic does not roll back the batch. Other arenas can continue, and each arena that finishes keeps its new state. The batch can make partial progress.
The batch methods do not use ArenaStepBuffers automatically. Use your own
worker loop with step_tick or step_tick_with_buffers when you need to
control buffer reuse. Measure the parallel option on your workload.
Run many arenas on each worker
Use ArenaStepBuffers to reuse temporary solver and contact buffers between
arenas. Create one buffer set for each worker. Reuse it for every tick:
use ;
The arena still owns its physics state, retained contacts, events, and random
generator. Buffer reuse does not change the physics result. It does not create
worker threads. Drop the buffer set to release its allocations. Arenas that
also use step_tick retain their own grown buffers.
Use ordinary step_tick for one arena per worker. The buffer exchange adds
work and does not help every arena count. Compare both methods with your
roster, memory mode, arena count, and worker count. The memory-mode table above
uses step_batch, which calls ordinary step_tick; it does not measure
buffer reuse.
Use MutatorConfig to change rules and physics settings. ArenaConfig also
accepts a custom boost-pad layout. See the
API reference for configuration, state, event,
and raycast APIs.
Units and coordinates
- Positions and dimensions use Unreal units. There are 50 Unreal units per meter. Linear velocities use Unreal units per second.
+Zpoints up. Blue defends the-Ygoal; Orange defends the+Ygoal.- Angular velocities use radians per second.
View your simulation
Viewing is optional. Add rocketsim_vis
to send frames to the separate
rocketsim_viewer application.
Your simulation does not need the viewer's graphics dependencies.
License
The source uses the MIT license. Collision meshes are external inputs with separate terms. This crate does not include them.