5dca8ecc79
- Introduced a new "Getting Started" guide to help users set up and use the YAZE software effectively. - Added detailed "Testing Guide" outlining the testing framework and best practices for contributors. - Created "Build Instructions" for macOS, Linux, and Windows, including environment verification and quick start with CMake presets. - Documented the architecture and networking aspects of YAZE, focusing on service-oriented design and gRPC integration. - Updated the index to reflect new documentation structure and improve navigation.
95 lines
6.9 KiB
Markdown
95 lines
6.9 KiB
Markdown
# E2 - Development Guide
|
|
|
|
This guide outlines the core architectural patterns, UI systems, and best practices for developing and maintaining the Yaze editor. Adhering to these patterns is crucial for ensuring consistency, maintainability, and performance.
|
|
|
|
## 1. Core Architectural Patterns
|
|
|
|
These patterns, established during the Overworld Editor refactoring, should be applied to all new and existing editor components.
|
|
|
|
### Pattern 1: Modular Systems
|
|
|
|
**Principle**: Decompose large, monolithic editor classes into smaller, single-responsibility modules.
|
|
|
|
- **Rendering**: All drawing logic should be extracted into dedicated `*Renderer` classes (e.g., `OverworldEntityRenderer`). The main editor class should delegate drawing calls, not implement them.
|
|
- **UI Panels**: Complex UI panels should be managed by their own classes (e.g., `MapPropertiesSystem`), which then communicate with the parent editor via callbacks.
|
|
- **Interaction**: Canvas interaction logic (mouse handling, editing modes) should be separated from the main editor class to simplify state management.
|
|
|
|
**Benefit**: Smaller, focused modules are easier to test, debug, and maintain. The main editor class becomes a coordinator, which is a much cleaner architecture.
|
|
|
|
### Pattern 2: Callback-Based Communication
|
|
|
|
**Principle**: Use `std::function` callbacks for child-to-parent communication to avoid circular dependencies.
|
|
|
|
- **Implementation**: A parent editor provides its child components with callbacks (typically via a `SetCallbacks` method) during initialization. The child component invokes these callbacks to notify the parent of events or to request actions (like a refresh).
|
|
- **Example**: `MapPropertiesSystem` receives a `RefreshCallback` from `OverworldEditor`. When a property is changed in the UI, it calls the function, allowing the `OverworldEditor` to execute the refresh logic without the `MapPropertiesSystem` needing to know anything about the editor itself.
|
|
|
|
### Pattern 3: Centralized Progressive Loading via `gfx::Arena`
|
|
|
|
**Principle**: All expensive asset loading operations must be performed asynchronously to prevent UI freezes. The `gfx::Arena` singleton provides a centralized, priority-based system for this.
|
|
|
|
- **How it Works**:
|
|
1. **Queue**: Instead of loading a texture directly, queue it with the arena: `gfx::Arena::Get().QueueDeferredTexture(bitmap, priority);`
|
|
2. **Prioritize**: Assign a numerical priority. Lower numbers are higher priority. Use a high priority for assets the user is currently viewing and a low priority for assets that can be loaded in the background.
|
|
3. **Process**: In the main `Update()` loop of an editor, process a small batch of textures each frame: `auto batch = gfx::Arena::Get().GetNextDeferredTextureBatch(4, 2);` (e.g., 4 high-priority, 2 low-priority).
|
|
- **Benefit**: This provides a globally consistent, non-blocking loading mechanism that is available to all editors and ensures the UI remains responsive.
|
|
|
|
## 2. UI & Theming System
|
|
|
|
To ensure a consistent and polished look and feel, all new UI components must adhere to the established theme and helper function system.
|
|
|
|
### 2.1. The Theme System (`AgentUITheme`)
|
|
|
|
- **Principle**: **Never use hardcoded colors (`ImVec4`)**. All UI colors must be derived from the central theme.
|
|
- **Implementation**: The `AgentUITheme` system (`src/app/editor/agent/agent_ui_theme.h`) provides a struct of semantic color names (e.g., `panel_bg_color`, `status_success`, `provider_ollama`). These colors are automatically derived from the application's current `ThemeManager`.
|
|
- **Usage**: Fetch the theme at the beginning of a draw call and use the semantic colors:
|
|
|
|
```cpp
|
|
const auto& theme = AgentUI::GetTheme();
|
|
ImGui::PushStyleColor(ImGuiCol_ChildBg, theme.panel_bg_color);
|
|
```
|
|
|
|
### 2.2. Reusable UI Helper Functions
|
|
|
|
- **Principle**: Encapsulate common UI patterns into helper functions to reduce boilerplate and ensure consistency.
|
|
- **Available Helpers** (in `AgentUI` and `gui` namespaces):
|
|
- **Panels**: `AgentUI::PushPanelStyle()` / `PopPanelStyle()`
|
|
- **Headers**: `AgentUI::RenderSectionHeader(icon, label, color)`
|
|
- **Indicators**: `AgentUI::RenderStatusIndicator()` (status dot), `AgentUI::StatusBadge()` (colored text badge).
|
|
- **Buttons**: `AgentUI::StyledButton()`, `AgentUI::IconButton()`.
|
|
- **Layout**: `AgentUI::VerticalSpacing()`, `AgentUI::HorizontalSpacing()`.
|
|
- **Benefit**: Creates a consistent visual language and makes the UI code far more readable and maintainable.
|
|
|
|
### 2.3. Toolbar Implementation (`CompactToolbar`)
|
|
|
|
- **Stretching**: To prevent ImGui from stretching the last item in a toolbar, do not use `ImGui::BeginGroup()`. Instead, manage layout with `ImGui::SameLine()` and end the toolbar with `ImGui::NewLine()`.
|
|
- **Separators**: Use `ImGui::SeparatorEx(ImGuiSeparatorFlags_Vertical)` for vertical separators that do not affect item layout.
|
|
- **Property Inputs**: Use the `toolbar.AddProperty()` method for consistent spacing and sizing of input fields within the toolbar.
|
|
|
|
## 3. Key System Implementations & Gotchas
|
|
|
|
### 3.1. Graphics Refresh Logic
|
|
|
|
- **Immediate vs. Deferred**: When a visual property changes, the texture must be updated on the GPU immediately. Use `Renderer::Get().RenderBitmap()` for an immediate, blocking update. `UpdateBitmap()` is deferred and should not be used for changes the user expects to see instantly.
|
|
- **Call Order is Critical**: When a property affecting graphics is changed, the correct sequence of operations is crucial:
|
|
1. Update the property in the data model.
|
|
2. Call the relevant `Load*()` method (e.g., `map.LoadAreaGraphics()`) to load the new data from the ROM into memory.
|
|
3. Force a redraw/re-render of the bitmap.
|
|
|
|
### 3.2. Multi-Area Map Configuration
|
|
|
|
- **Use the Helper**: When changing a map's area size (e.g., from `Small` to `Large`), you **must** use the `zelda3::Overworld::ConfigureMultiAreaMap()` method. Do not set the `area_size` property directly.
|
|
- **Why**: This method correctly handles the complex logic of assigning parent IDs to all sibling maps and updating the necessary ROM data for persistence. Failure to use it will result in inconsistent state and refresh bugs.
|
|
|
|
### 3.3. Version-Specific Feature Gating
|
|
|
|
- **Principle**: The UI must adapt to the features supported by the loaded ROM. Do not show UI for features that are not available.
|
|
- **Implementation**: Check the ROM's `asm_version` byte before rendering a UI component. If the feature is not supported, display a helpful message (e.g., "This feature requires ZSCustomOverworld v3+") instead of the UI.
|
|
|
|
### 3.4. Entity Visibility for Visual Testing
|
|
|
|
- **Standard**: All overworld entity markers (entrances, exits, items, sprites) should be rendered with a high-contrast color and an alpha of `0.85f` to ensure they are clearly visible against any background.
|
|
- **Entrances**: Bright yellow-gold
|
|
- **Exits**: Cyan-white
|
|
- **Items**: Bright red
|
|
- **Sprites**: Bright magenta
|