Build production-ready editor authoring workflows
CI / Format, lint, test, build (push) Waiting to run

This commit is contained in:
Rbanh committed 2026-07-11 12:41:04 -04:00
1 parent cc1fa6ea3b
commit 0553a85220
163 files changed
+34547 -1565

No files matched your search

+331
View File
@@ -0,0 +1,331 @@
use std::collections::{HashMap, HashSet};
use std::fmt;
use bevy::prelude::*;
use serde::{Deserialize, Serialize};
pub const AUDIO_BUS_MASTER_ID: &str = "master";
pub const AUDIO_BUS_MUSIC_ID: &str = "music";
pub const AUDIO_BUS_SFX_ID: &str = "sfx";
pub const AUDIO_GAIN_DB_MIN: f32 = -80.0;
pub const AUDIO_GAIN_DB_MAX: f32 = 24.0;
/// One stable node in the project audio bus graph.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Reflect)]
#[reflect(Default, Debug, PartialEq, Serialize, Deserialize)]
pub struct AudioBusSettings {
/// Stable serialized ID. Display names may change without breaking source routing.
#[serde(default)]
pub id: String,
#[serde(default)]
pub label: String,
#[serde(default)]
pub parent: Option<String>,
#[serde(default)]
pub gain_db: f32,
#[serde(default)]
pub muted: bool,
}
impl AudioBusSettings {
pub fn new(
id: impl Into<String>,
label: impl Into<String>,
parent: Option<impl Into<String>>,
) -> Self {
Self {
id: id.into(),
label: label.into(),
parent: parent.map(Into::into),
gain_db: 0.0,
muted: false,
}
}
}
impl Default for AudioBusSettings {
fn default() -> Self {
Self::new(AUDIO_BUS_MASTER_ID, "Master", None::<String>)
}
}
/// Versioned project audio routing settings.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Reflect)]
#[reflect(Default, Debug, PartialEq, Serialize, Deserialize)]
pub struct AudioSettings {
#[serde(default = "default_audio_buses")]
pub buses: Vec<AudioBusSettings>,
}
impl AudioSettings {
pub fn bus(&self, id: &str) -> Option<&AudioBusSettings> {
self.buses.iter().find(|bus| bus.id == id)
}
pub fn bus_mut(&mut self, id: &str) -> Option<&mut AudioBusSettings> {
self.buses.iter_mut().find(|bus| bus.id == id)
}
pub fn validate(&self) -> Result<(), AudioSettingsValidationError> {
validate_audio_settings(self)
}
}
impl Default for AudioSettings {
fn default() -> Self {
Self {
buses: default_audio_buses(),
}
}
}
fn default_audio_buses() -> Vec<AudioBusSettings> {
vec![
AudioBusSettings::default(),
AudioBusSettings::new(AUDIO_BUS_MUSIC_ID, "Music", Some(AUDIO_BUS_MASTER_ID)),
AudioBusSettings::new(AUDIO_BUS_SFX_ID, "SFX", Some(AUDIO_BUS_MASTER_ID)),
]
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AudioSettingsValidationError {
EmptyBusId { index: usize },
InvalidBusId { bus_id: String },
EmptyBusLabel { bus_id: String },
DuplicateBusId { bus_id: String },
InvalidBusGain { bus_id: String },
MissingRequiredBus { bus_id: &'static str },
MasterBusHasParent,
BusMissingParent { bus_id: String },
UnknownParent { bus_id: String, parent_id: String },
BusParentCycle { bus_id: String },
}
impl fmt::Display for AudioSettingsValidationError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::EmptyBusId { index } => write!(formatter, "audio bus {index} has an empty ID"),
Self::InvalidBusId { bus_id } => write!(
formatter,
"audio bus ID `{bus_id}` must use lowercase ASCII letters, digits, '.', '-', or '_'"
),
Self::EmptyBusLabel { bus_id } => {
write!(formatter, "audio bus `{bus_id}` has an empty label")
}
Self::DuplicateBusId { bus_id } => {
write!(formatter, "audio bus ID `{bus_id}` is duplicated")
}
Self::InvalidBusGain { bus_id } => write!(
formatter,
"audio bus `{bus_id}` gain must be finite and between {AUDIO_GAIN_DB_MIN} and {AUDIO_GAIN_DB_MAX} dB"
),
Self::MissingRequiredBus { bus_id } => {
write!(formatter, "required audio bus `{bus_id}` is missing")
}
Self::MasterBusHasParent => write!(formatter, "the master audio bus cannot have a parent"),
Self::BusMissingParent { bus_id } => {
write!(formatter, "audio bus `{bus_id}` does not route to a parent")
}
Self::UnknownParent { bus_id, parent_id } => write!(
formatter,
"audio bus `{bus_id}` references unknown parent `{parent_id}`"
),
Self::BusParentCycle { bus_id } => {
write!(formatter, "audio bus `{bus_id}` participates in a parent cycle")
}
}
}
}
impl std::error::Error for AudioSettingsValidationError {}
/// Validates stable IDs, required buses, scalar bounds, and the parent graph.
pub fn validate_audio_settings(
settings: &AudioSettings,
) -> Result<(), AudioSettingsValidationError> {
let mut buses = HashMap::with_capacity(settings.buses.len());
for (index, bus) in settings.buses.iter().enumerate() {
if bus.id.is_empty() {
return Err(AudioSettingsValidationError::EmptyBusId { index });
}
if !valid_bus_id(&bus.id) {
return Err(AudioSettingsValidationError::InvalidBusId {
bus_id: bus.id.clone(),
});
}
if bus.label.trim().is_empty() {
return Err(AudioSettingsValidationError::EmptyBusLabel {
bus_id: bus.id.clone(),
});
}
if !bus.gain_db.is_finite()
|| !(AUDIO_GAIN_DB_MIN..=AUDIO_GAIN_DB_MAX).contains(&bus.gain_db)
{
return Err(AudioSettingsValidationError::InvalidBusGain {
bus_id: bus.id.clone(),
});
}
if buses.insert(bus.id.as_str(), bus).is_some() {
return Err(AudioSettingsValidationError::DuplicateBusId {
bus_id: bus.id.clone(),
});
}
}
for required in [AUDIO_BUS_MASTER_ID, AUDIO_BUS_MUSIC_ID, AUDIO_BUS_SFX_ID] {
if !buses.contains_key(required) {
return Err(AudioSettingsValidationError::MissingRequiredBus { bus_id: required });
}
}
if buses[AUDIO_BUS_MASTER_ID].parent.is_some() {
return Err(AudioSettingsValidationError::MasterBusHasParent);
}
for bus in settings
.buses
.iter()
.filter(|bus| bus.id != AUDIO_BUS_MASTER_ID)
{
let Some(parent_id) = bus.parent.as_deref().filter(|parent| !parent.is_empty()) else {
return Err(AudioSettingsValidationError::BusMissingParent {
bus_id: bus.id.clone(),
});
};
if !buses.contains_key(parent_id) {
return Err(AudioSettingsValidationError::UnknownParent {
bus_id: bus.id.clone(),
parent_id: parent_id.to_string(),
});
}
}
for bus in settings
.buses
.iter()
.filter(|bus| bus.id != AUDIO_BUS_MASTER_ID)
{
let mut current = bus.id.as_str();
let mut visited = HashSet::new();
while current != AUDIO_BUS_MASTER_ID {
if !visited.insert(current) {
return Err(AudioSettingsValidationError::BusParentCycle {
bus_id: bus.id.clone(),
});
}
current = buses[current]
.parent
.as_deref()
.expect("non-master parents were validated above");
}
}
Ok(())
}
fn valid_bus_id(id: &str) -> bool {
id.bytes().all(|byte| {
byte.is_ascii_lowercase() || byte.is_ascii_digit() || matches!(byte, b'.' | b'-' | b'_')
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn default_bus_graph_uses_stable_required_ids() {
let settings = AudioSettings::default();
assert_eq!(
settings
.buses
.iter()
.map(|bus| bus.id.as_str())
.collect::<Vec<_>>(),
[AUDIO_BUS_MASTER_ID, AUDIO_BUS_MUSIC_ID, AUDIO_BUS_SFX_ID]
);
assert_eq!(
settings.bus(AUDIO_BUS_MUSIC_ID).unwrap().parent.as_deref(),
Some(AUDIO_BUS_MASTER_ID)
);
assert_eq!(
settings.bus(AUDIO_BUS_SFX_ID).unwrap().parent.as_deref(),
Some(AUDIO_BUS_MASTER_ID)
);
assert!(settings.validate().is_ok());
}
#[test]
fn rejects_duplicate_and_unknown_bus_references() {
let mut settings = AudioSettings::default();
settings.buses.push(AudioBusSettings::new(
AUDIO_BUS_SFX_ID,
"Duplicate",
Some(AUDIO_BUS_MASTER_ID),
));
assert_eq!(
settings.validate(),
Err(AudioSettingsValidationError::DuplicateBusId {
bus_id: AUDIO_BUS_SFX_ID.to_string()
})
);
let mut settings = AudioSettings::default();
settings.bus_mut(AUDIO_BUS_SFX_ID).unwrap().parent = Some("missing".into());
assert_eq!(
settings.validate(),
Err(AudioSettingsValidationError::UnknownParent {
bus_id: AUDIO_BUS_SFX_ID.to_string(),
parent_id: "missing".to_string(),
})
);
}
#[test]
fn rejects_parent_cycles_and_invalid_gain() {
let mut settings = AudioSettings::default();
settings.bus_mut(AUDIO_BUS_MUSIC_ID).unwrap().parent = Some(AUDIO_BUS_SFX_ID.into());
settings.bus_mut(AUDIO_BUS_SFX_ID).unwrap().parent = Some(AUDIO_BUS_MUSIC_ID.into());
assert_eq!(
settings.validate(),
Err(AudioSettingsValidationError::BusParentCycle {
bus_id: AUDIO_BUS_MUSIC_ID.to_string()
})
);
let mut settings = AudioSettings::default();
settings.bus_mut(AUDIO_BUS_SFX_ID).unwrap().gain_db = f32::NAN;
assert_eq!(
settings.validate(),
Err(AudioSettingsValidationError::InvalidBusGain {
bus_id: AUDIO_BUS_SFX_ID.to_string()
})
);
}
#[test]
fn rejects_missing_required_and_unstable_bus_ids() {
let mut settings = AudioSettings::default();
settings.buses.retain(|bus| bus.id != AUDIO_BUS_MUSIC_ID);
assert_eq!(
settings.validate(),
Err(AudioSettingsValidationError::MissingRequiredBus {
bus_id: AUDIO_BUS_MUSIC_ID
})
);
let mut settings = AudioSettings::default();
settings.buses.push(AudioBusSettings::new(
"Dialogue Bus",
"Dialogue",
Some(AUDIO_BUS_MASTER_ID),
));
assert_eq!(
settings.validate(),
Err(AudioSettingsValidationError::InvalidBusId {
bus_id: "Dialogue Bus".to_string()
})
);
}
}
+94
View File
@@ -1,8 +1,10 @@
//! Serializable project settings loaded from `assets/project.ron`.
mod audio;
mod plugin;
mod rendering;
pub use audio::*;
pub use plugin::{
save_project_settings, sync_sim_tuning, ProjectSettingsChanged, ProjectSettingsIo,
ProjectSettingsPlugin, SimTuning,
@@ -19,6 +21,15 @@ use serde::{Deserialize, Serialize};
pub const DEFAULT_PROJECT_PATH: &str = "assets/project.ron";
pub const SETTINGS_VERSION: u32 = 1;
pub const PROJECT_TEMPLATE_VERSION: u32 = 1;
#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, Reflect, PartialEq, Eq)]
#[reflect(Clone)]
pub enum ProjectKind {
#[default]
Game,
Sandbox,
}
/// Marker for cameras that receive the shared project rendering stack.
#[derive(Component, Debug, Clone, Copy, Default)]
@@ -29,10 +40,20 @@ pub struct ProjectRenderCamera;
#[reflect(Resource, Clone)]
pub struct ProjectSettings {
pub version: u32,
#[serde(default)]
pub project_id: String,
pub name: String,
#[serde(default)]
pub project_kind: ProjectKind,
#[serde(default = "default_project_template_version")]
pub template_version: u32,
#[serde(default)]
pub capabilities: Vec<String>,
pub default_level: String,
pub asset_roots: Vec<String>,
pub rendering: RenderingSettings,
#[serde(default)]
pub audio: AudioSettings,
pub physics: PhysicsSettings,
pub input: InputSettings,
}
@@ -41,21 +62,36 @@ impl Default for ProjectSettings {
fn default() -> Self {
Self {
version: SETTINGS_VERSION,
project_id: "blacksite-default".into(),
name: "Bevy FPS Foundation".into(),
project_kind: ProjectKind::Game,
template_version: PROJECT_TEMPLATE_VERSION,
capabilities: vec![
"editor".into(),
"gameplay".into(),
"rendering".into(),
"audio".into(),
],
default_level: "assets/levels/editor_scene.scn.ron".into(),
asset_roots: vec![
"assets/models".into(),
"assets/textures".into(),
"assets/materials".into(),
"assets/levels".into(),
"assets/audio".into(),
],
rendering: RenderingSettings::default(),
audio: AudioSettings::default(),
physics: PhysicsSettings::default(),
input: InputSettings::default(),
}
}
}
const fn default_project_template_version() -> u32 {
PROJECT_TEMPLATE_VERSION
}
/// Camera post-processing and world lighting defaults.
#[derive(Debug, Clone, Serialize, Deserialize, Reflect)]
#[reflect(Clone)]
@@ -221,10 +257,68 @@ mod tests {
let text = save_project_settings_to_string(&settings).expect("serialize");
let parsed: ProjectSettings = ron::from_str(&text).expect("deserialize");
assert_eq!(parsed.name, settings.name);
assert_eq!(parsed.project_id, settings.project_id);
assert_eq!(parsed.project_kind, settings.project_kind);
assert_eq!(parsed.template_version, settings.template_version);
assert_eq!(parsed.capabilities, settings.capabilities);
assert_eq!(parsed.audio, settings.audio);
assert_eq!(parsed.physics.walk_speed, settings.physics.walk_speed);
assert_eq!(parsed.rendering.gi_mode, settings.rendering.gi_mode);
}
#[test]
fn legacy_manifest_defaults_project_identity_fields() {
let legacy = r#"(
version: 1,
name: "Legacy",
default_level: "assets/levels/main.scn.ron",
asset_roots: [],
rendering: (
gi_mode: Auto, hdr: true, exposure_mode: Manual, exposure_ev100: 13.0,
auto_exposure_speed_brighten: 3.0, auto_exposure_speed_darken: 1.0,
tonemapping_aces: true, bloom: true, taa: true, ssao: true,
atmosphere: true, fog_color: (0.0, 0.0, 0.0), fog_density: 0.0,
ambient_color: (0.0, 0.0, 0.0), ambient_brightness: 0.0,
sun_illuminance: 100000.0, shadow_cascades: 4,
shadow_first_cascade: 6.0, shadow_max_distance: 220.0,
),
physics: (
player_radius: 0.4, player_length: 1.0, eye_offset_stand: 0.6,
eye_offset_crouch: 0.1, gravity: 22.0, walk_speed: 6.0,
run_speed: 9.5, crouch_speed: 3.0, jump_speed: 7.5,
ground_accel: 70.0, air_accel: 16.0, ground_check_dist: 0.2,
skin: 0.02, max_slide_iter: 4, ground_normal_y: 0.5,
coyote_time: 0.12, jump_buffer: 0.12,
),
input: (
yaw_sensitivity: 0.003, pitch_sensitivity: 0.0022,
editor_fly_speed: 14.0, editor_look_sensitivity: 0.003,
editor_pan_speed: 0.015,
),
)"#;
let parsed: ProjectSettings = ron::from_str(legacy).unwrap();
assert!(parsed.project_id.is_empty());
assert_eq!(parsed.project_kind, ProjectKind::Game);
assert_eq!(parsed.template_version, PROJECT_TEMPLATE_VERSION);
assert!(parsed.capabilities.is_empty());
assert_eq!(parsed.audio, AudioSettings::default());
assert!(parsed.audio.validate().is_ok());
}
#[test]
fn project_defaults_include_audio_capability_and_asset_root() {
let settings = ProjectSettings::default();
assert!(settings.capabilities.iter().any(|item| item == "audio"));
assert!(settings
.asset_roots
.iter()
.any(|item| item == "assets/audio"));
assert!(settings.audio.validate().is_ok());
}
#[test]
fn gi_mode_defaults_auto() {
assert_eq!(RenderingSettings::default().gi_mode, GiMode::Auto);
+3
View File
@@ -77,6 +77,9 @@ impl Plugin for ProjectSettingsPlugin {
fn build(&self, app: &mut App) {
app.init_resource::<ProjectSettingsIo>()
.register_type::<ProjectSettings>()
.register_type::<crate::ProjectKind>()
.register_type::<crate::AudioSettings>()
.register_type::<crate::AudioBusSettings>()
.register_type::<crate::GiMode>()
.register_type::<crate::ExposureMode>()
.register_type::<crate::ActiveCameraRenderProfile>()