rocketsim 0.3.6

Simulate Rocket League games at maximum efficiency
Documentation
use glam::Vec3A;

use crate::{BoostPadConfig, GameMode, MutatorConfig};

/// Broadphase memory/performance tradeoff for [`crate::Arena`].
///
/// Approximate Linux RSS per Soccar arena, averaged across 100 arenas on
/// 16 workers after 100 episodes of 120 ticks: `Heavy` uses 1,062 KiB,
/// `Balanced` (default) uses 86 KiB, and `Light` uses 51 KiB for 1v1.
/// The 3v3 values are 1,076 KiB, 102 KiB, and 65 KiB. These values are not
/// upper bounds. See the crate README for the measurement method.
#[derive(Clone, Copy, Debug, Default, Hash, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum ArenaMemWeightMode {
    /// Small ray-query cells with eight dynamic handles reserved per cell.
    /// Uses more memory. This mode does not guarantee higher simulation speed.
    Heavy,
    /// Larger ray-query cells with one dynamic handle reserved per cell.
    /// This is the default memory mode.
    #[default]
    Balanced,
    /// One ray-query cell across the longest world axis.
    /// Shares packed static bounds for ray culling between arenas.
    /// Uses less memory. Speed depends on the workload.
    Light,
}

/// Settings used to build an [`crate::Arena`].
///
/// Start with [`ArenaConfig::new`] (or [`ArenaConfig::DEFAULT` for Soccar)
/// and chain `with_*` builders. All positions are in Unreal units (uu).
#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct ArenaConfig {
    /// Game mode (arena meshes, goals, ball behavior).
    pub game_mode: GameMode,
    /// Physics/rule tweaks (defaults to `MutatorConfig::new(game_mode)`).
    pub mutators: MutatorConfig,
    /// Broadphase memory/performance tradeoff.
    pub mem_weight_mode: ArenaMemWeightMode,
    /// Broadphase world minimum (uu). Must contain the arena + cars/ball.
    pub min_pos: Vec3A,
    /// Broadphase world maximum (uu).
    pub max_pos: Vec3A,
    /// Target cell size for the broadphase grid (uu). Smaller = more memory.
    pub max_aabb_len: f32,
    /// Keep the sphere ball's rotation at identity. Ignore supplied rotations.
    /// Angular velocity still affects contacts. This does not apply to the puck.
    pub no_ball_rot: bool,
    /// Use this boost-pad list instead of the mode's default layout.
    /// Pads are re-sorted to RLBot/RLGym order (Y, then X). Their XY
    /// acquisition circles must not overlap. Their radii are 208 uu for big
    /// pads and 176 uu for small pads. A car can touch only one pad at a time.
    /// Do not place pads so one configured car hitbox can overlap multiple
    /// pad volumes.
    pub custom_boost_pads: Option<Vec<BoostPadConfig>>,
    /// RNG seed for kickoffs/respawns. `None` = random; `Some(seed)` =
    /// deterministic replays.
    pub rng_seed: Option<u64>,
}

impl Default for ArenaConfig {
    fn default() -> Self {
        Self::DEFAULT
    }
}

impl ArenaConfig {
    /// Soccar defaults with matching [`MutatorConfig`].
    pub const DEFAULT: Self = Self {
        game_mode: GameMode::Soccar,
        mutators: MutatorConfig::new(GameMode::Soccar),
        mem_weight_mode: ArenaMemWeightMode::Balanced,
        min_pos: Vec3A::new(-5600., -6000., 0.),
        max_pos: Vec3A::new(5600., 6000., 2200.),
        max_aabb_len: 370.,
        no_ball_rot: false,
        custom_boost_pads: None,
        rng_seed: None,
    };

    /// Config for a game mode with that mode's default mutators.
    #[must_use]
    pub fn new(game_mode: GameMode) -> Self {
        Self {
            game_mode,
            mutators: MutatorConfig::new(game_mode),
            ..Self::DEFAULT
        }
    }

    /// Override the physics/rule mutators.
    #[must_use]
    pub fn with_mutators(mut self, mutators: MutatorConfig) -> Self {
        self.mutators = mutators;
        self
    }

    /// Override the broadphase memory/performance tradeoff.
    #[must_use]
    pub fn with_mem_weight_mode(mut self, mem_weight_mode: ArenaMemWeightMode) -> Self {
        self.mem_weight_mode = mem_weight_mode;
        self
    }

    /// Override the broadphase world minimum (uu).
    #[must_use]
    pub fn with_min_pos(mut self, min_pos: Vec3A) -> Self {
        self.min_pos = min_pos;
        self
    }

    /// Override the broadphase world maximum (uu).
    #[must_use]
    pub fn with_max_pos(mut self, max_pos: Vec3A) -> Self {
        self.max_pos = max_pos;
        self
    }

    /// Override the broadphase grid cell size (uu).
    #[must_use]
    pub fn with_max_aabb_len(mut self, max_aabb_len: f32) -> Self {
        self.max_aabb_len = max_aabb_len;
        self
    }

    /// Keep the sphere ball's rotation at identity without removing angular velocity.
    #[must_use]
    pub fn with_no_ball_rot(mut self, no_ball_rot: bool) -> Self {
        self.no_ball_rot = no_ball_rot;
        self
    }

    /// Replace the mode's default boost-pad layout.
    ///
    /// Keep the pads' XY acquisition circles separate. Overlapping acquisition
    /// circles are unsupported. Big-pad radius is 208 uu. Small-pad radius is
    /// 176 uu. A car can touch only one pad at a time. Do not place pads so one
    /// configured car hitbox can overlap multiple pad volumes.
    #[must_use]
    pub fn with_custom_boost_pads(mut self, custom_boost_pads: Vec<BoostPadConfig>) -> Self {
        self.custom_boost_pads = Some(custom_boost_pads);
        self
    }

    /// Seed kickoff/respawn RNG for deterministic replays.
    #[must_use]
    pub fn with_rng_seed(mut self, rng_seed: u64) -> Self {
        self.rng_seed = Some(rng_seed);
        self
    }
}