nightshade 0.52.0

A cross-platform data-oriented game engine.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

//! Audio playback using the Kira audio engine.
//!
//! Provides components for spatial and non-spatial audio:
//!
//! - [`AudioSource`]: Audio clip playback with volume, looping, and spatial settings
//! - [`AudioListener`]: Marker for the entity that receives spatial audio
//!
//! Audio assets are loaded through the asset system and referenced by name.
//! Spatial audio uses the entity's transform for 3D positioning.
//! The audio feature is optional and requires the `audio` feature flag.
//!
//! # Loading Audio
//!
//! Load audio files and register them with the audio manager:
//!
//! ```ignore
//! let sound_data = load_sound_from_bytes(include_bytes!("../assets/music.ogg"));
//! audio_engine_load_sound(&mut world.resources.audio, "background_music", sound_data);
//! ```
//!
//! # Playing Non-Spatial Audio
//!
//! ```ignore
//! let entity = spawn_entities(world, AUDIO_SOURCE, 1)[0];
//! world.set(entity, AudioSource::new("background_music")
//!     .with_volume(0.8)
//!     .with_looping(true)
//!     .playing());
//! ```
//!
//! # Spatial Audio Setup
//!
//! For 3D positional audio, add an [`AudioListener`] to your camera and use
//! spatial audio sources with transforms:
//!
//! ```ignore
//! // Add listener to camera (typically done once in initialize)
//! world.ecs.worlds[CORE].add_audio_listener(camera_entity);
//! world.set(camera_entity, AudioListener);
//!
//! // Create spatial audio source at a position
//! let source = spawn_entities(world,
//!     AUDIO_SOURCE | LOCAL_TRANSFORM | GLOBAL_TRANSFORM,
//!     1
//! )[0];
//! world.set(source, AudioSource::new("explosion")
//!     .with_spatial(true)
//!     .with_volume(1.0)
//!     .playing());
//! world.set(source, LocalTransform {
//!     translation: Vec3::new(10.0, 0.0, 5.0),
//!     ..Default::default()
//! });
//! ```
//!
//! # WebAssembly Note
//!
//! On WASM, browsers require audio to be initialized after a user interaction
//! (click, touch, or keypress). The audio system handles this automatically,
//! but sounds triggered before any user input will be queued and played once
//! interaction occurs. For best results, trigger initial audio playback in
//! response to user input (e.g., a "Start" button click).

pub mod components;
#[cfg(feature = "audio")]
pub mod resources;
#[cfg(feature = "audio")]
pub mod systems;

pub use components::*;
#[cfg(feature = "audio")]
pub use resources::*;
#[cfg(feature = "audio")]
pub use systems::*;

/// Registers the bus construction and per-frame source sync at the start
/// of the frame, right after the event swap, where they have always run.
#[cfg(feature = "audio")]
pub fn install(world: &mut crate::ecs::world::World) {
    use crate::schedule::{FramePhase, schedule_push};
    let schedule = &mut world.resources.schedules.frame;
    schedule_push(
        schedule,
        FramePhase::Start,
        systems::build_audio_buses_system,
    );
    schedule_push(schedule, FramePhase::Start, systems::update_audio_system);
}

/// Installs the audio engine: on native the device opens at startup, on
/// the web at the first user gesture, and [`install`] adds the audio
/// systems to the frame schedule. Without this plugin the engine never
/// opens the audio device and the frame schedule carries no audio work.
#[cfg(feature = "audio")]
pub struct AudioPlugin;

#[cfg(feature = "audio")]
impl crate::app::Plugin for AudioPlugin {
    fn build(&self, app: &mut crate::app::App) {
        #[cfg(not(target_arch = "wasm32"))]
        app.add_startup_system(systems::initialize_audio_system);
        #[cfg(target_arch = "wasm32")]
        app.add_system(
            crate::app::Stage::First,
            systems::lazy_initialize_audio_system,
        );
        app.add_startup_system(install);
    }
}