qproj wikiQuell’s application structure
The Quell crate (bin/quell) is organized around two ideas from its engine libraries. Screens decide what part of the game is running. Services provide the behavior that screens use.1
Contents
Start-up
main.rs builds a Bevy app from three groups of plugins:
- Bevy’s
DefaultPlugins, with textures set to repeat, because Jackdaw brush faces tile their UVs beyond the 0–1 range. AppPlugin, which installs q_screens’ScreenPlugin, all services, and all screens, and chooses the initial screen.- Jackdaw’s runtime plugins, which load
.bsnscenes authored in the Jackdaw level editor and build Avian colliders from them. The same binary can run windowless when Jackdaw asks it for its type schema or embeds it for play-in-editor.
The initial screen is the splash screen unless a screen name is given. In development builds, --screen <name> selects one directly, which is how the development screens are usually opened.
Screens
A screen is a Bevy component type that implements q_screens’ Screen trait. It registers systems for its loading, ready and update phases. When the game switches screens, every entity not marked persistent is despawned. See Screens for the lifecycle.
| Screen | What it does now |
|---|---|
SplashScreen | Switches straight to the world screen. |
WorldScreen | Waits for the player model to load, then spawns the Jackdaw greybox scene scenes/greybox_scene.bsn. A PlayerSpawn placed in that scene spawns the player and its camera. |
camera_test (dev) | Exercises the tracking and free cameras; see Cameras. |
greybox_arena (dev) | Loads the same greybox scene with the player, plus a free camera that Tab switches to. |
hex_paths (dev) | Previews terrain-first trail generation; see Terrain generation. |
The world screen loads a test level, not the game world. The worldgen service holds only a placeholder plane, which the world screen does not spawn.
Services
Services are ordinary Bevy plugins under src/service/, each of which owns one concern:
input— the global input context, cursor capture and release, and camera input. Bindings usebevy_enhanced_inputcontexts and actions.player— the kinematic character controller; see Player movement.ui— the persistent UI camera that draws overlays above the world.worldgen— the placeholder described above.third_party— installs external plugins, such as Avian physics, and re-exports their preludes.dev(development builds only) — the egui world inspector and a terminal console.
Services do not configure their own system ordering against a screen. A service exposes its systems, as player_systems() does, and each screen that wants them adds them to its own update schedule. This is why both the world screen and the greybox arena list the player systems explicitly.
src/common/ holds code shared by several screens, but not wide enough to be its own service. At the moment, that is only camera-facing billboards.
Development builds
The default dev feature adds the command-line parser, the egui inspector, Bevy’s free camera, and a console overlay opened with Ctrl+`. The console is a q_shell terminal. It provides a q command that runs a q_query_lang query against the live World, for example q '(@ Name ?Transform)[PlayerController]'. See q_os: processes, terminal and shell.
Release builds leave these out. The default features also include jackdaw, because the Jackdaw editor builds the game without choosing features.
File conventions
Within a module, data.rs holds types and systems.rs holds systems. A small plugin function, or plugin.rs, does the registration. Type definitions come before free functions. Every crate in the organization follows the same layout.
See also
- Repositories and workspace — where the crate sits in the organization.
- Screens — the screen lifecycle the application is built on.
- Player movement and Cameras — the gameplay services in use today.
What links here: q_os: processes, terminal and shell, Screens, Player movement, Glossary, Repositories and workspace