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
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
//! The plugin entry point.
use bevy::gltf::extensions::GltfExtensionHandlers;
use bevy::prelude::*;
use serde::de::DeserializeOwned;
use crate::loader::StageGltfHandler;
use crate::stage::anchor::{AnchorAlignment, StageAnchor};
use crate::persist::{
capture_unloading_stages, restore_spawned_stages, PersistedComponents, StageDeltas,
StageNodeId,
};
use crate::stream::{cull_inline_sectors, stream_external_sectors, StageSector};
use crate::view::{cull_distant_stages, wire_lod_groups, LodConfig, StageViewConfig};
use crate::stage::transition::{
attach_portal_state, detect_portal_crossings, link_return_portals, preload_through_portals,
unload_distant_stages, StagePortal,
};
use crate::stage::manager::{
begin_stage_loads, finish_stage_spawns, process_stage_unloads, spawn_loaded_stages, StageId,
StageManager, StageRoot, StageStatus,
};
use crate::tag::{
component::{StageTag, StageTags, TagSource},
parse::DEFAULT_DISCRIMINATOR,
resolve::{enqueue_tagged_nodes, resolve_queued_tags, StageTagQueue, UnknownTags},
value::{TagParams, TagValue},
StageTagRegistry,
};
/// How the plugin reads and resolves tags.
#[derive(Resource, Clone, Debug)]
pub struct StageTagConfig {
/// The `extras` property naming a node's tags.
pub discriminator: String,
/// How many nodes to resolve per frame, or `0` for no limit.
///
/// Defaults to no limit: for a normal level the resolution pass is cheap,
/// and a tag appearing a frame late is more surprising than a short hitch.
/// Raise the limit off zero when streaming large levels.
pub resolve_budget: usize,
}
impl Default for StageTagConfig {
fn default() -> Self {
Self {
discriminator: DEFAULT_DISCRIMINATOR.to_string(),
resolve_budget: 0,
}
}
}
/// Ordering for the plugin's work within a frame.
#[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
pub enum StageSystems {
/// Stages are loaded, placed and unloaded.
///
/// Runs in `PreUpdate` so that a stage's scene is handed to Bevy before the
/// `SpawnScene` schedule runs later in the same frame, rather than waiting
/// for the next one.
Manage,
/// Newly spawned tagged nodes are collected.
Collect,
/// Queued nodes are resolved against the registry.
Resolve,
/// Stages whose scenes have finished spawning are promoted to ready.
Settle,
/// LOD groups are wired as levels spawn.
View,
/// Remembered state is put back on levels that have just spawned.
Restore,
/// Portals preload, hand over and unload.
///
/// Runs in `PostUpdate` after transform propagation, because every decision
/// here is about where things are in the world this frame.
Stream,
}
/// Loads glTF levels and applies artist-authored tags.
#[derive(Default)]
pub struct StagePlugin {
/// Tag reading and resolution settings.
pub config: StageTagConfig,
}
impl Plugin for StagePlugin {
fn build(&self, app: &mut App) {
app.register_type::<StageTags>()
.register_type::<StageTag>()
.register_type::<TagSource>()
.register_type::<TagParams>()
.register_type::<TagValue>()
.insert_resource(self.config.clone())
.register_type::<StageRoot>()
.register_type::<StageId>()
.register_type::<StageStatus>()
.register_type::<StageAnchor>()
.register_type::<AnchorAlignment>()
.register_type::<StagePortal>()
.register_type::<StageSector>()
.init_resource::<StageTagRegistry>()
.init_resource::<StageTagQueue>()
.init_resource::<UnknownTags>()
.init_resource::<StageManager>()
.init_resource::<LodConfig>()
.init_resource::<StageViewConfig>()
.init_resource::<PersistedComponents>()
.init_resource::<StageDeltas>()
.register_type::<StageNodeId>()
.register_type::<LodConfig>()
.register_type::<StageViewConfig>()
.configure_sets(PreUpdate, StageSystems::Manage)
.configure_sets(
PostUpdate,
StageSystems::Stream.after(bevy::transform::TransformSystems::Propagate),
)
.configure_sets(
Update,
(
StageSystems::Collect,
StageSystems::Resolve,
StageSystems::Settle,
StageSystems::View,
StageSystems::Restore,
)
.chain(),
)
.add_systems(
PreUpdate,
(
// Capture first: unloading is the last moment the state
// still exists to be read.
capture_unloading_stages,
process_stage_unloads,
begin_stage_loads,
spawn_loaded_stages,
)
.chain()
.in_set(StageSystems::Manage),
)
.add_systems(
Update,
(
enqueue_tagged_nodes.in_set(StageSystems::Collect),
resolve_queued_tags.in_set(StageSystems::Resolve),
finish_stage_spawns.in_set(StageSystems::Settle),
wire_lod_groups.in_set(StageSystems::View),
// After tags have been applied, so remembered values win
// over whatever the level file says.
restore_spawned_stages.in_set(StageSystems::Restore),
),
)
.add_systems(
PostUpdate,
(
attach_portal_state,
link_return_portals,
preload_through_portals,
detect_portal_crossings,
unload_distant_stages,
stream_external_sectors,
cull_inline_sectors,
cull_distant_stages,
)
.chain()
.in_set(StageSystems::Stream),
);
// The plugin claims `anchor` for itself, on the same registry games use
// for their own tags. Nothing about it is privileged.
{
let mut registry = app.world_mut().resource_mut::<StageTagRegistry>();
registry.register::<StageAnchor>(crate::stage::scan::ANCHOR_TAG);
registry.register::<StagePortal>("portal");
registry.register::<StageSector>("sector");
}
// Parse metadata as the glTF loads rather than after it spawns. The
// resource is shared with the loader through an `Arc`, and the loader
// is only built in `GltfPlugin::finish`, so pushing here is seen by it
// regardless of plugin order.
app.init_resource::<GltfExtensionHandlers>();
let known_names = app.world().resource::<StageTagRegistry>().known_names();
let handlers = app.world().resource::<GltfExtensionHandlers>().0.clone();
handlers.write_blocking().push(Box::new(StageGltfHandler::new(
self.config.discriminator.as_str(),
known_names,
)));
}
}
/// Registering tags on the [`App`].
pub trait StageAppExt {
/// Register a tag that inserts `T`, built from the tag's parameters.
///
/// The component lands on the entity the glTF loader created for the node,
/// so the node's transform, name and parenting come along with it.
fn register_stage_tag<T>(&mut self, key: &str) -> &mut Self
where
T: Component + DeserializeOwned;
/// Register a tag that carries no component of its own, for games that
/// only want the [`StageTagFound`](crate::tag::resolve::StageTagFound) event.
fn register_stage_marker(&mut self, key: &str) -> &mut Self;
/// Remember `T` across unload and reload.
///
/// Only nodes that carry a tag have a stable identity, so only those can be
/// remembered. Registering the type for reflection is required too, and is
/// done here for you.
fn persist_stage_component<T>(&mut self) -> &mut Self
where
T: Component + Reflect + bevy::reflect::TypePath + bevy::reflect::GetTypeRegistration;
}
impl StageAppExt for App {
fn register_stage_tag<T>(&mut self, key: &str) -> &mut Self
where
T: Component + DeserializeOwned,
{
self.world_mut()
.resource_mut::<StageTagRegistry>()
.register::<T>(key);
self
}
fn register_stage_marker(&mut self, key: &str) -> &mut Self {
self.world_mut()
.resource_mut::<StageTagRegistry>()
.register_marker(key);
self
}
fn persist_stage_component<T>(&mut self) -> &mut Self
where
T: Component + Reflect + bevy::reflect::TypePath + bevy::reflect::GetTypeRegistration,
{
self.register_type::<T>();
self.world_mut()
.resource_mut::<PersistedComponents>()
.register::<T>();
self
}
}