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.
Memory values are approximate Linux RSS measurements. After init_from_default(),
create 100 Soccar arenas with the listed roster. Run 100 episodes of 10,000 ticks
per arena with generated stress_v3 input on two worker threads. Subtract the
initial RSS and divide by 100. RSS rose slowly in the final 10 episodes, so these
are end-of-run estimates, not a fixed upper bound. The 1v1 workload uses two cars.
The 3v3 workload uses six cars. Speed columns compare median TPS in the
generated-input release stress_v3 workload. Run-to-run ranges overlapped. In a separate
wisp_3v3_300s replay comparison, Heavy was about 4% slower than Balanced.
Results depend on the platform and workload.
| Mode | 1v1 memory per arena | 1v1 speed | 3v3 memory per arena | 3v3 speed |
|---|---|---|---|---|
Heavy |
1,106 KiB | Similar | 1,119 KiB | Similar |
Balanced |
133 KiB | Baseline | 147 KiB | Baseline |
Light |
95 KiB | About 1% slower | 108 KiB | About 1% slower |
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.