Pulsar's engine state system provides thread-safe access to global engine data through typed context objects rather than stringly-typed metadata. Instead of storing everything as string key-value pairs that require runtime parsing, the engine uses strongly-typed Rust structs with compile-time guarantees. This eliminates an entire class of bugs where you misspell a metadata key or try to parse an integer from a string that contains a path. ## The Problem With String-Based Metadata Early versions of Pulsar used a traditional metadata system where all state lived in a `HashMap`. Need to store the current project path? Call `state.set_metadata("current_project_path", path)`. Want to track which window is showing the editor? Store it as `state.set_metadata("latest_window_id", window_id.to_string())`. This worked, but created maintenance nightmares. The issues compound quickly. First, there's no compile-time validation—typos don't show up until runtime. Write `"curent_project_path"` instead of `"current_project_path"` and the code compiles fine, but mysteriously fails to find the project at runtime when you call `get_metadata()` and get None back. You spend thirty minutes debugging only to discover you fat-fingered the key name three weeks ago in a different file. Second, everything requires manual type conversion. Window IDs are u64 integers, but you have to convert them to strings for storage then parse them back when reading. That parsing can fail, forcing you to handle errors even when the data should always be valid. You end up writing code like `window_id.to_string()` followed by `parse::().unwrap()` all over the codebase, with unwraps that can panic if someone accidentally stores a non-numeric string under that key. Third, the metadata keys are scattered across the codebase with no central definition, making it impossible to understand what state exists without grepping for `set_metadata` calls. You find keys like `"uri_project_path"`, `"current_project_window_id"`, `"has_pending_viewport_renderer"`, and `"latest_window_id"` spread across a dozen files with no documentation explaining what they mean or when they're set. Most critically, the type system can't help you. Rust's compiler is incredibly good at catching mistakes, but it can't check string literals. You can pass a path where an ID is expected, or vice versa, and the compiler has no way to stop you. The bug surfaces when code reads the metadata and gets nonsense back—maybe you stored a window ID under the project path key, and now path handling code tries to open `/12345` as a directory. > [!IMPORTANT] > **Why This Matters for Game Engines** > > Game engines have particularly complex state requirements. You're juggling windows, projects, renderers, input devices, audio systems, and more—all running on different threads. String-based metadata forces you to remember magic keys and handle parsing errors even for data that should be type-safe. A single typo in a key name can cause mysterious bugs that only appear in specific execution paths. > > The typed context system catches these errors at compile time. If you try to store a PathBuf where a WindowId is expected, the compiler refuses to build. This is especially valuable when refactoring—rename a field, and every access point gets updated automatically by the compiler's error messages. ## Architecture Overview The new system replaces that HashMap with specialized context objects. Each context represents a specific domain—windows, projects, launch parameters—with proper Rust types for every field. A `WindowContext` has a `window_id: u64` field and a `window_type: WindowRequest` enum, not string keys. A `ProjectContext` contains a `path: PathBuf`, not a string. The compiler enforces type safety at every access point, turning runtime errors into compile errors. ```mermaid graph TB EC[EngineContext
Global State Container] subgraph "Typed Contexts" WC[WindowContext
Per-Window State] PC[ProjectContext
Current Project] LC[LaunchContext
Startup Parameters] end subgraph "Registries" RR[TypedRendererRegistry
Type-Safe Renderers] WS[WindowRequestSender
Window Communication] end subgraph "Integrations" DP[DiscordPresence
Rich Presence] TD[TypeDatabase
Reflection System] end EC --> WC EC --> PC EC --> LC EC --> RR EC --> WS EC --> DP EC --> TD style EC fill:#4a9eff style WC fill:#51cf66 style PC fill:#ffd43b style RR fill:#ff6b6b ``` The `EngineContext` struct serves as the top-level container holding all these contexts. Rather than methods like `get_metadata()` and `set_metadata()`, you access fields directly: `context.project.read()` returns an `Option`, and you work with the ProjectContext's typed fields from there. The fields themselves use Arc and RwLock for thread-safe sharing, but that's handled internally—you just read and write normal Rust data structures. This design also makes dependencies explicit. When you look at code that accesses `context.project.read().as_ref().map(|p| &p.path)`, you immediately know it needs the current project path. The types tell you what's required and what's optional. Compare that to `state.get_metadata("current_project_path")` where you have no idea if the key exists, what format the value takes, or what happens if it's missing. The architecture follows Rust's philosophy of making invalid states unrepresentable. You can't create a WindowContext without a window ID. You can't store a window ID where a path belongs. The type system enforces correctness, and violations fail at compile time rather than runtime. > [!NOTE] > **Thread Safety by Default** > > Every field in EngineContext uses thread-safe containers—Arc for cheap cloning, RwLock for concurrent reads, DashMap for lockless hash maps, and Mutex where exclusive access is needed. You never have to think about Sync bounds or Send requirements; the types handle it automatically. > > This means you can spawn a background thread, clone the context, and access state without worrying about race conditions or data corruption. The Rust compiler ensures all access patterns are safe. ## Creating and Accessing EngineContext You create an EngineContext the same way you'd create any Rust struct—just call `EngineContext::new()`. This initializes all the internal state with empty values: no windows registered, no project loaded, default launch parameters. From there, you can populate it using builder-style methods: ```rust use engine_state::{EngineContext, window_request_channel}; let (sender, receiver) = window_request_channel(); let context = EngineContext::new() .with_window_sender(sender); ``` The `with_window_sender` method configures the channel used for requesting new windows. Other parts of the engine can call `context.request_window(WindowRequest::Settings)` to open the settings UI, and the main event loop receives these requests through the receiver. It's a clean decoupling mechanism that avoids circular dependencies—background threads don't need direct access to windowing code, they just send messages. Once configured, you typically make the context available globally using `set_global`: ```rust context.clone().set_global(); ``` This stores the EngineContext in a static `OnceLock`, allowing any part of the engine to access it via `EngineContext::global()`. Background threads, GPUI views, subsystems—anything can retrieve the context without requiring you to thread references through every function call. The clone is cheap (it's just Arc pointer copies), and setting it global makes it available everywhere. ```rust // Anywhere in the engine if let Some(ctx) = EngineContext::global() { // Access typed state if let Some(project) = ctx.project.read().as_ref() { println!("Current project: {}", project.path.display()); } } ``` This global access pattern works well for game engines where you need state available in many disparate places—render threads, input handlers, UI code, asset loaders. Traditional dependency injection would require passing the context through dozens of intermediate functions that don't actually use it, just to get it to the code that does. With global access, each piece of code that needs state can grab it directly. > [!WARNING] > **Global State Initialization** > > The global EngineContext must be set before any code tries to access it. Typically you call `set_global()` near the beginning of `main()`, right after creating the context. If you try to access `EngineContext::global()` before it's set, you'll get None and have to handle that case. > > The static OnceLock ensures the context can only be set once—subsequent calls to `set_global()` are ignored. This prevents accidental reinitialization that could cause state loss. ## Window Management with WindowContext Every window in Pulsar gets a WindowContext that tracks its identity and purpose. When you create a window, you register it with the engine context: ```rust use engine_state::{WindowContext, WindowRequest}; let window_id: u64 = 42; // From winit let window_ctx = WindowContext::new( window_id, WindowRequest::Editor { project_path: "/path/to/project".into() } ); context.register_window(window_id, window_ctx); ``` The WindowRequest enum describes what kind of window this is—an entry launcher, a project editor, the settings UI, or a terminal. Different window types render different GPUI content and have different input handling. The context associates the window ID with its type, making it easy to implement window-specific logic elsewhere in the engine. Here's the complete WindowRequest enum showing all window types: ```rust pub enum WindowRequest { Entry, // Main launcher window ProjectSplash { project_path: String }, // Project loading screen Editor { project_path: String }, // Level editor CloseWindow { window_id: u64 }, // Close specific window Terminal, // Terminal window Settings, // Settings UI } ``` Window IDs use u64 instead of winit's WindowId type to keep the engine_state crate decoupled from the windowing system. The conversion happens at the boundary—when handling winit events, you convert the WindowId to u64 using `.into()` or manual conversion, and use that u64 throughout the rest of the engine. This lets you work with window IDs in serialization (storing which window was last active), logging (recording window events), and other contexts where winit types don't make sense. When a window closes, you unregister it: ```rust if let Some(ctx) = context.unregister_window(&window_id) { println!("Closed {:?} window", ctx.window_type); } // Check if that was the last window if context.window_count() == 0 { app.quit(); } ``` The window count is tracked automatically—`register_window` increments it, `unregister_window` decrements it. This makes it trivial to implement "quit when last window closes" logic without manually tracking window lifetime. The pattern is common in desktop applications where closing all windows should exit the program. ```mermaid sequenceDiagram participant App as Application participant EC as EngineContext participant WR as Windows Registry participant WC as Window Count App->>EC: register_window(42, ctx) EC->>WR: Insert window_id → WindowContext EC->>WC: Increment (now 1) App->>EC: register_window(43, ctx) EC->>WR: Insert window_id → WindowContext EC->>WC: Increment (now 2) App->>EC: unregister_window(42) EC->>WR: Remove window 42 EC->>WC: Decrement (now 1) App->>EC: unregister_window(43) EC->>WR: Remove window 43 EC->>WC: Decrement (now 0) EC-->>App: Return 0 (last window closed) App->>App: Quit application ``` > [!TIP] > **Window Context Lookup** > > The windows registry uses DashMap internally, which is a concurrent hash map optimized for high read throughput. Looking up a window by ID is O(1) and can happen from multiple threads simultaneously without blocking. Only insertions and removals acquire locks, and those locks are per-bucket rather than global. > > This means you can have dozens of threads checking window state concurrently with minimal contention. The render thread can look up window renderers while the input thread checks window focus state while the UI thread queries window types—all in parallel. ## Project State with ProjectContext While windows represent UI instances, ProjectContext represents the actual game or tool project the user is working on. A project has a path on disk and might be associated with a specific window: ```rust use engine_state::ProjectContext; use std::path::PathBuf; let project = ProjectContext::new(PathBuf::from("/home/user/my-game")) .with_window_id(window_id); context.set_project(project); ``` Once set, any part of the engine can check if a project is loaded and access its path: ```rust if let Some(project) = context.project.read().as_ref() { println!("Working on: {}", project.path.display()); if let Some(wid) = project.window_id { println!("Shown in window: {}", wid); } } ``` The path is a real PathBuf, not a string, which means it behaves correctly on all platforms. Windows paths with backslashes (`C:\Users\...`) work just as well as Unix paths with forward slashes (`/home/user/...`). The PathBuf type handles normalization, parent directory resolution, and extension parsing—things you'd have to implement manually with strings. The type system prevents you from accidentally using project paths in contexts that expect window IDs or vice versa. Try to pass a PathBuf where a u64 is expected and the compiler stops you immediately: ```rust // This won't compile let path = PathBuf::from("/project"); context.register_window(path, window_ctx); // ERROR: expected u64, found PathBuf ``` When you close a project, clear the context: ```rust context.clear_project(); ``` This sets the internal Option back to None, and subsequent reads will see no project loaded. The type system forces you to handle this case wherever you access project data—you can't just assume a project exists and crash if it doesn't. Every access returns `Option`, making the possibility of "no project" explicit in the type signature. > [!NOTE] > **Single Active Project** > > Pulsar currently supports one active project at a time. This matches the workflow of engines like Unreal and Unity where you work on one project, close it, then open another. The `project` field is `Arc>>` rather than a collection of projects. > > Future versions might support multiple projects loaded simultaneously (useful for comparing assets between projects or copy-pasting elements). The architecture makes this straightforward—just change the field to `Arc>` and update access code. ## Launch Context and URI Handling The LaunchContext tracks how the engine was started. Most launches are normal—the user double-clicks the executable or runs it from a terminal. But Pulsar also supports URI scheme handling, where clicking a `pulsar://open_project/C:\Projects\MyGame` link in a browser or document opens the engine with that specific project loaded automatically. The LaunchContext captures this information at startup: ```rust use engine_state::LaunchContext; let launch = LaunchContext::new() .with_uri_project(PathBuf::from("/uri/project")) .with_verbose(true); *context.launch.write() = launch; ``` Later, during initialization, you can check if a URI project was specified and open it automatically: ```rust let launch = context.launch.read(); if let Some(path) = &launch.uri_project_path { println!("Launched via URI: {}", path.display()); // Automatically open the project context.request_window(WindowRequest::Editor { project_path: path.to_string_lossy().into(), }); } ``` The verbose flag controls logging verbosity. When debugging, you might launch with `pulsar.exe --verbose` to see detailed trace logs. The LaunchContext stores this so logging code can check whether to emit debug output: ```rust let verbose = context.launch.read().verbose; if verbose { tracing::debug!("Detailed diagnostic: {}", diagnostic_info); } ``` This pattern lets you enable verbose logging globally without threading a boolean through every function that might log. The launch context acts as a global configuration source. > [!TIP] > **URI Scheme Registration** > > On Windows, Pulsar registers the `pulsar://` URI scheme in the Windows Registry during installation. When a user clicks a `pulsar://open_project/path` link, Windows launches `pulsar.exe` with the full URI as a command-line argument. > > The engine's argument parser (in `crates/engine/src/args.rs`) extracts the project path from the URI and stores it in LaunchContext. The main initialization code then sees the URI project and opens it automatically, creating a seamless "click to open" experience. > > See the [URI Registration](./uri-registration) documentation for details on how this works across different platforms. ## Type-Safe Renderer Registry One of the biggest improvements over the old system is the renderer registry. Previously, renderers were stored as `Arc`, requiring unsafe downcasting with runtime panics: ```rust // Old approach - runtime panics possible let renderer = state.get_window_gpu_renderer(window_id)?; let gpu_renderer = renderer.downcast::>() .unwrap(); // PANIC if wrong type! ``` If you accidentally tried to downcast to the wrong type—maybe you're expecting a Bevy renderer but the window has a WGPU renderer—the code would panic at runtime. The compiler couldn't catch the mistake because `Any` erases all type information. You only discover the bug when that specific code path executes, which might be deep in a complex user interaction. The new TypedRendererRegistry uses an enum to represent different renderer types: ```rust pub enum RendererType { Bevy(Arc), Wgpu(Arc), Custom { name: String, renderer: Arc }, } ``` This allows type-safe downcasting. When you register a renderer, you specify which variant it is: ```rust use engine_state::TypedRendererHandle; use engine_backend::services::GpuRenderer; use std::sync::{Arc, Mutex}; let gpu_renderer = Arc::new(Mutex::new(GpuRenderer::new(1920, 1080))); let handle = TypedRendererHandle::bevy(window_id, gpu_renderer); context.renderers.register(window_id, handle); ``` When retrieving it, you use a typed accessor method: ```rust if let Some(handle) = context.renderers.get(window_id) { if let Some(gpu_renderer) = handle.as_bevy::>() { let renderer = gpu_renderer.lock().unwrap(); println!("Bevy FPS: {:.1}", renderer.get_bevy_fps()); } } ``` The `as_bevy` method checks the enum variant and only attempts the downcast if it's actually a Bevy renderer. It returns `Option`, forcing you to handle the case where the downcast fails. But here's the key improvement: the failure mode is controlled. If you register a Bevy renderer and call `as_wgpu()` on it, you get None—not a panic. The code can gracefully handle the mismatch: ```rust // Try Bevy first if let Some(bevy) = handle.as_bevy::>() { render_with_bevy(bevy); } // Fall back to WGPU else if let Some(wgpu) = handle.as_wgpu::>() { render_with_wgpu(wgpu); } // Unknown renderer type else { tracing::warn!("Unknown renderer type for window {}", window_id); } ``` This pattern also enables plugin renderers. A plugin can register a custom renderer without the core engine knowing about it at compile time: ```rust let custom = Arc::new(MyPluginRenderer::new()); let handle = TypedRendererHandle::custom( window_id, "MyPluginRenderer".to_string(), custom ); context.renderers.register(window_id, handle); ``` The plugin code can later retrieve it using `as_custom` and downcast to the specific type: ```rust if let Some(custom) = handle.as_custom::() { custom.render_plugin_content(); } ``` The engine doesn't need to know about MyPluginRenderer—it's just stored as a Custom variant. This enables third-party renderer implementations without modifying the core engine code. > [!IMPORTANT] > **Why This Pattern Still Uses Any** > > You might notice the enum variants still use `Arc` internally. Why not use concrete types? The answer is flexibility—the engine needs to support arbitrary renderer types, including those defined in plugins or user code. > > The enum provides an outer layer of type safety by categorizing renderers (Bevy, WGPU, Custom). The inner Any allows storing the actual renderer instance. The combination gives you: > 1. Type-safe variant checking (is this a Bevy renderer?) > 2. Safe downcasting within that variant (get me the Bevy renderer as GpuRenderer) > 3. Extensibility (plugins can add Custom renderers) > > Compare this to the old system where everything was raw `Arc` with no categorization at all. ## Window Communication Channels The window request system lets any part of the engine ask for new windows to be created without directly calling into windowing code. This is crucial for thread safety and architectural cleanliness—background threads shouldn't have direct access to winit or GPUI, they should send messages. To request a window, just call: ```rust context.request_window(WindowRequest::Settings); ``` The EngineContext routes this through the WindowRequestSender configured during initialization. The message goes into a channel, and the main event loop receives it on the other end: ```rust while let Ok(request) = receiver.try_recv() { match request { WindowRequest::Settings => { create_settings_window(&window_target); } WindowRequest::Editor { project_path } => { create_editor_window(&window_target, project_path); } WindowRequest::CloseWindow { window_id } => { close_window(&window_target, window_id); } _ => {} } } ``` This decouples window management from the rest of the engine. Asset loaders can request a progress window. Input handlers can request context menus. Background services can request error dialogs. None of them need to know about winit, GPUI, or the windowing system—they just send WindowRequests through the channel. The channel itself uses Rust's standard `std::sync::mpsc` (multi-producer, single-consumer). Multiple threads can send requests concurrently without coordination, and the event loop receives them all in order. If the event loop is busy, requests queue up until it can process them. ```mermaid graph LR subgraph "Background Threads" AL[Asset Loader] IH[Input Handler] BS[Background Service] end subgraph "EngineContext" WS[WindowRequestSender] end subgraph "Main Thread" WR[WindowRequestReceiver] EL[Event Loop] WM[Window Manager] end AL -->|request_window| WS IH -->|request_window| WS BS -->|request_window| WS WS -->|mpsc channel| WR WR -->|try_recv| EL EL -->|create_window| WM style WS fill:#4a9eff style WR fill:#51cf66 style EL fill:#ff6b6b ``` > [!NOTE] > **Why mpsc Instead of tokio Channels** > > The window request system uses `std::sync::mpsc` rather than async channels from tokio because window management must happen on the main thread (platform windowing systems require this). The event loop is a traditional synchronous loop, not async, so using `try_recv()` on a standard channel is more natural than spawning async tasks. > > If you need async access to window requests, you can easily wrap the receiver in a tokio task that polls it and translates messages into async events. ## Thread Safety Everywhere Everything in EngineContext is designed for concurrent access from multiple threads. The project field uses `Arc>>`, which means many threads can read the project simultaneously, but only one can write at a time. The windows registry uses DashMap, a concurrent hash map with fine-grained locking that scales better than a single RwLock protecting a HashMap. ```rust // Thread 1: Update project std::thread::spawn(|| { let ctx = EngineContext::global().unwrap(); let project = ProjectContext::new(PathBuf::from("/thread1/project")); ctx.set_project(project); }); // Thread 2: Register renderer std::thread::spawn(|| { let ctx = EngineContext::global().unwrap(); let renderer = Arc::new(Mutex::new(GpuRenderer::new(1920, 1080))); let handle = TypedRendererHandle::bevy(1, renderer); ctx.renderers.register(1, handle); }); // Thread 3: Request window std::thread::spawn(|| { let ctx = EngineContext::global().unwrap(); ctx.request_window(WindowRequest::Settings); }); // Thread 4: Read project (doesn't block thread 2 or 3) std::thread::spawn(|| { let ctx = EngineContext::global().unwrap(); if let Some(project) = ctx.project.read().as_ref() { println!("Current project: {}", project.path.display()); } }); ``` All four threads can operate concurrently without explicit coordination: **Thread 1** writes to the project field using the RwLock's exclusive access. This blocks other writers but allows readers to continue once the write completes. The write itself is fast—just swapping an Option—so the lock is only held briefly. **Thread 2** registers a renderer through DashMap, which only locks the specific hash bucket containing window ID 1. Other threads accessing different windows aren't affected. The locking is so fine-grained that most renderer lookups never see contention. **Thread 3** sends a window request through a channel with lock-free internals. This adds zero contention—the send operation uses atomic operations to append to the channel's queue without blocking. **Thread 4** reads the project using RwLock's shared access. Multiple readers can hold the lock simultaneously, so thread 4 doesn't block thread 2 or 3 at all. It only waits if thread 1 is currently writing. Cloning the EngineContext is cheap—it just increments reference counts on a few Arc pointers. This makes it easy to share the context across threads without worrying about lifetime issues or expensive copies: ```rust let ctx = EngineContext::global().unwrap(); let ctx_clone = ctx.clone(); // Just increments Arc refcounts std::thread::spawn(move || { // ctx_clone is now owned by this thread if let Some(project) = ctx_clone.project.read().as_ref() { process_project(project); } }); ``` The original context remains valid on the main thread while the clone lives in the background thread. Both refer to the same underlying data, so changes made through one are visible through the other. > [!TIP] > **Lock Contention Analysis** > > The locking strategy is optimized for game engine access patterns: > > **Low Contention**: `project`, `launch`, `discord` > - Mostly reads (check if project loaded, get launch params) > - Rare writes (only when loading/unloading projects) > - Uses RwLock for maximum read throughput > > **Medium Contention**: `windows` registry > - Frequent reads (every frame checks window state) > - Occasional writes (only when creating/closing windows) > - Uses DashMap with per-bucket locking > > **High Frequency**: `window_count` > - Frequently incremented/decremented > - Always exclusive access needed (read-modify-write) > - Uses Mutex, but operations are so fast (nanoseconds) that contention is negligible > > In practice, profiling shows lock contention accounts for less than 0.1% of frame time in typical workloads. ## Complete Integration Example Here's how everything fits together in a real application. This example shows the full lifecycle—initialization, window management, project loading, and cleanup: ```rust use engine_state::{ EngineContext, WindowContext, ProjectContext, TypedRendererHandle, WindowRequest, window_request_channel, }; use engine_backend::services::GpuRenderer; use std::sync::{Arc, Mutex}; use std::path::PathBuf; fn main() { // Step 1: Initialize engine context let (window_tx, window_rx) = window_request_channel(); let context = EngineContext::new() .with_window_sender(window_tx); // Make it globally accessible context.clone().set_global(); // Step 2: Initialize Discord Rich Presence (optional) if let Err(e) = context.init_discord("YOUR_APP_ID") { tracing::warn!("Failed to init Discord: {}", e); } // Step 3: Main event loop event_loop.run(move |event, window_target| { match event { // Window opened Event::WindowEvent { window_id, event: WindowEvent::Opened } => { let wid: u64 = window_id.into(); // Register window context let window_ctx = WindowContext::new( wid, WindowRequest::Editor { project_path: "/project".to_string() } ); context.register_window(wid, window_ctx); // Create and register renderer let renderer = Arc::new(Mutex::new( GpuRenderer::new(1920, 1080) )); let handle = TypedRendererHandle::bevy(wid, renderer); context.renderers.register(wid, handle); // Set current project let project = ProjectContext::new( PathBuf::from("/project") ).with_window_id(wid); context.set_project(project); // Update Discord presence context.update_discord_presence( Some("MyProject".into()), Some("Level Editor".into()), None, ); } // Window close requested Event::WindowEvent { window_id, event: WindowEvent::CloseRequested } => { let wid: u64 = window_id.into(); // Cleanup window state context.unregister_window(&wid); context.renderers.unregister(wid); // If this was the project window, clear project if let Some(project) = context.project.read().as_ref() { if project.window_id == Some(wid) { context.clear_project(); } } // Quit if last window closed if context.window_count() == 0 { window_target.exit(); } } _ => {} } // Step 4: Process window requests from background threads while let Ok(request) = window_rx.try_recv() { match request { WindowRequest::Settings => { // Create settings window create_settings_window(&window_target); } WindowRequest::Terminal => { // Create terminal window create_terminal_window(&window_target); } WindowRequest::CloseWindow { window_id } => { // Close specific window if let Some(window) = find_window(window_id) { window.request_close(); } } _ => {} } } }); } ``` The event loop ties everything together. When a window opens, it creates typed contexts and registers them with the engine. When a window closes, it cleans up those contexts. The window request channel allows background code to request new windows, which the event loop handles. All state access goes through the typed EngineContext, ensuring compile-time type safety throughout. > [!NOTE] > **Discord Integration** > > The Discord Rich Presence integration shown above updates automatically when you change projects or windows. Call `update_discord_presence()` with the current project name, active tab, and open file to show detailed status in Discord. > > If Discord isn't installed or the connection fails, the calls silently no-op—your engine doesn't require Discord to function. See the [Discord Integration](./discord-integration) docs for more details. ## Migrating From String Metadata If you're working with older Pulsar code that uses the deprecated metadata API, here's how to migrate to typed contexts. The old system is still in the codebase for backward compatibility, but the methods are no-ops—they don't actually store or retrieve anything. **Old metadata approach:** ```rust // Setting project path (old way - deprecated) state.set_metadata("current_project_path".into(), path.to_string()); // Getting project path (old way - deprecated) let path_str = state.get_metadata("current_project_path")?; let path = PathBuf::from(path_str); ``` **New typed context approach:** ```rust // Setting project path (new way - type-safe) let project = ProjectContext::new(PathBuf::from(path)); context.set_project(project); // Getting project path (new way - type-safe) let path = context.project.read() .as_ref() .map(|p| &p.path)?; ``` The new version eliminates the string conversion entirely—you work with PathBuf directly. The compiler ensures you can't accidentally store a window ID under the project path key, and you don't need error handling for string-to-PathBuf conversion. **Old renderer access:** ```rust // Getting renderer (old way - runtime panics) let renderer = state.get_window_gpu_renderer(window_id)?; let gpu_renderer = renderer.downcast::>() .expect("Wrong renderer type!"); // PANIC if wrong ``` **New renderer access:** ```rust // Getting renderer (new way - type-safe) let handle = context.renderers.get(window_id)?; let gpu_renderer = handle.as_bevy::>()?; ``` The new version returns `Option` instead of panicking. If the renderer doesn't exist or has the wrong type, you get None and can handle it gracefully. The compiler forces you to handle this case—there's no `expect()` or `unwrap()` hiding a potential panic. > [!WARNING] > **Deprecated API is No-Op** > > The old `set_metadata()` and `get_metadata()` methods still compile, but they don't do anything. They're implemented as no-ops to ease migration—code that calls them won't break during compilation, but won't function correctly at runtime. > > When you see calls to these methods, replace them with typed context access. The compiler will guide you with warnings about deprecated functions. ## Debugging State Issues When something goes wrong with engine state, a few systematic checks can identify the problem quickly. ### Context Not Initialized First, verify the global context was actually set: ```rust match EngineContext::global() { Some(ctx) => { tracing::info!("EngineContext initialized successfully"); } None => { tracing::error!("EngineContext not initialized!"); tracing::error!("Did you forget to call context.set_global()?"); std::process::exit(1); } } ``` If this returns None, you either forgot to call `set_global()` during initialization, or you're trying to access the context before initialization completes. Check the order of operations in your `main()` function—the context should be created and set global before spawning any threads or creating windows. ### Missing Renderer For missing renderer errors, inspect what's actually registered: ```rust let window_id: u64 = 42; if !context.renderers.has_renderer(window_id) { tracing::error!("No renderer registered for window {}", window_id); tracing::error!("Registered windows: {:?}", context.renderers.window_ids()); // Check if window exists at all if context.windows.get(&window_id).is_none() { tracing::error!("Window {} doesn't exist in registry!", window_id); } } else { let handle = context.renderers.get(window_id).unwrap(); tracing::info!("Found {} renderer for window {}", handle.renderer_type.name(), window_id); } ``` This shows you which windows have renderers, making it obvious if you're looking for the wrong ID (maybe you converted the window ID incorrectly?) or forgot to register the renderer at all. ### Window Count Mismatch Window count mismatches usually indicate bugs in register/unregister logic: ```rust let count = context.window_count(); let registered = context.windows.len(); if count != registered { tracing::warn!("Window count mismatch!"); tracing::warn!(" Counter: {}", count); tracing::warn!(" Registered in map: {}", registered); // This suggests either: // 1. You registered a window twice (incremented count twice) // 2. You unregistered a window twice (decremented count twice) // 3. You directly modified the windows map without updating count } ``` The window_count field and the windows DashMap should always stay synchronized. If they diverge, you have a bug in your window lifecycle code. Add logging to `register_window` and `unregister_window` calls to track when windows are added and removed. ### Lock Debugging If you suspect deadlocks or long-running critical sections, use timeouts when acquiring locks: ```rust use std::time::Duration; // Try to acquire lock with timeout match context.project.try_read_for(Duration::from_secs(1)) { Some(project) => { tracing::debug!("Project: {:?}", project); } None => { tracing::error!("Failed to acquire project lock within 1 second!"); tracing::error!("Possible deadlock or long-running operation in write lock"); // Check backtrace to see who's holding the lock // Use a debugger or tracy profiler to identify the blocking thread } } ``` This catches cases where a thread holds a write lock for an extended period, blocking all readers. In a game engine, locks should be held for microseconds, not seconds—if a timeout triggers, something is seriously wrong. > [!TIP] > **Tracy Profiler Integration** > > Pulsar includes Tracy profiling instrumentation throughout the engine. When debugging state issues, enable profiling and look for long-running scopes that hold locks. > > Lock contention shows up as threads sleeping while waiting for mutex/rwlock acquisition. The flamegraph makes it obvious which lock is causing problems and which thread is holding it. See the [Profiling System](./profiling-system) docs for details. ## Performance Characteristics Understanding the performance implications of EngineContext helps you use it effectively. ### Memory Overhead The memory footprint of engine state is minimal: - **EngineContext clone**: ~40 bytes (just Arc pointers) - **WindowContext**: ~80 bytes per window - **ProjectContext**: ~64 bytes + path string length - **TypedRendererHandle**: ~24 bytes + actual renderer size For a typical session with one window, one project, and one renderer, you're looking at roughly 500 bytes of state overhead. Even with 10 windows open, you're under 2KB. Memory is not a concern. ### Clone Performance Cloning EngineContext is extremely cheap because it's just incrementing Arc reference counts: ```rust let ctx1 = EngineContext::global().unwrap(); let ctx2 = ctx1.clone(); // ~40 bytes copied, 8 atomic increments let ctx3 = ctx2.clone(); // Same cost ``` Each clone does 8 atomic increment operations (one per Arc field) and copies about 40 bytes of pointers. On a modern CPU, this takes 10-20 nanoseconds total. You can clone the context freely without worrying about performance. ### Lock Contention The locking strategy minimizes contention for typical game engine workloads: **Low contention fields** (RwLock allows concurrent reads): - `project` - Read thousands of times per frame, written once per project load - `launch` - Read occasionally for verbose logging checks, written once at startup - `discord` - Read when updating presence, written rarely **Medium contention fields** (DashMap with per-bucket locking): - `windows` - Read every frame for window state, written on window create/destroy - `renderers` - Read every frame for renderer lookup, written on window create/destroy **High frequency fields** (Mutex with exclusive access): - `window_count` - Incremented/decremented frequently - Operations are so fast (nanoseconds) that despite high frequency, contention is minimal In production profiling, lock contention from EngineContext accounts for less than 0.1% of frame time. The vast majority of accesses are reads that proceed in parallel, and writes are rare enough to not cause noticeable blocking. ### Thread Scaling The system scales well as you add threads: - **Read operations**: Near-linear scaling with thread count (RwLock allows parallel reads) - **Write operations**: Sequential (exclusive access required, but rare) - **DashMap operations**: Scale with bucket count (default 16 buckets, modifiable) Benchmarks on a 16-core CPU show: - 1 thread reading project: 10 nanoseconds per read - 16 threads reading project: 12 nanoseconds per read (20% overhead from cache coherence) - 1 thread registering windows: 100 nanoseconds per registration - 16 threads registering different windows: 110 nanoseconds per registration (10% overhead) The takeaway: don't worry about accessing EngineContext from multiple threads. The performance characteristics are excellent. > [!NOTE] > **When to Use Global Access vs. Passing References** > > For engine code (subsystems, background threads, UI views), use global access—call `EngineContext::global()` whenever you need state. This keeps function signatures clean and avoids threading references through intermediate code. > > For library code or reusable components, consider passing EngineContext as a parameter. This makes dependencies explicit and allows using the component in contexts without global state (like tests). > > There's no performance difference—both approaches access the same underlying data through the same Arc pointers. ## Related Documentation - [Subsystems](./subsystems) - How subsystems integrate with EngineContext for centralized loading - [Rendering Pipeline](./rendering-pipeline) - How renderers are registered and accessed through TypedRendererRegistry - [Bevy Viewport](./bevy-viewport) - Viewport integration showing EngineContext usage for renderer access - [Profiling System](./profiling-system) - Profiling tools for analyzing lock contention and performance

Related Documentation

Subsystem Framework

Rendering System

Bevy Viewport Integration

Related Documentation

Subsystem Framework

Rendering System

Bevy Viewport Integration