Add Comprehensive Guide for Yaze Dungeon Editor
- Introduced a new documentation file detailing the Yaze Dungeon Editor, covering its architecture, core components, coordinate system, object rendering system, user interface, and integration with ZScream. - Included sections on usage examples, testing and validation strategies, and future enhancements to provide a complete overview of the editor's capabilities. - Removed the outdated dungeon object rendering refactor documentation to streamline resources and focus on the comprehensive guide. - Enhanced clarity and organization of the documentation to support both novice and expert users in effectively utilizing the dungeon editing tools.
This commit is contained in:
scawful
360
docs/dungeon-editor-comprehensive-guide.md
Normal file
360
docs/dungeon-editor-comprehensive-guide.md
Normal file
@@ -0,0 +1,360 @@
|
||||
# Yaze Dungeon Editor - Comprehensive Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The Yaze Dungeon Editor is a comprehensive tool for editing Zelda 3: A Link to the Past dungeon rooms, objects, sprites, items, entrances, doors, and chests. It provides an integrated editing experience with real-time rendering, coordinate system management, and advanced features for dungeon modification.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Components
|
||||
|
||||
#### 1. DungeonEditorSystem
|
||||
- **Purpose**: Central coordinator for all dungeon editing operations
|
||||
- **Location**: `src/app/zelda3/dungeon/dungeon_editor_system.h/cc`
|
||||
- **Features**:
|
||||
- Room management (loading, saving, creating, deleting)
|
||||
- Sprite management (enemies, NPCs, interactive objects)
|
||||
- Item management (keys, hearts, rupees, etc.)
|
||||
- Entrance/exit management (room connections)
|
||||
- Door management (locked doors, key requirements)
|
||||
- Chest management (treasure placement)
|
||||
- Undo/redo system
|
||||
- Event callbacks for real-time updates
|
||||
|
||||
#### 2. DungeonObjectEditor
|
||||
- **Purpose**: Specialized editor for room objects (walls, floors, decorations)
|
||||
- **Location**: `src/app/zelda3/dungeon/dungeon_object_editor.h/cc`
|
||||
- **Features**:
|
||||
- Object placement and editing
|
||||
- Layer management (BG1, BG2, BG3)
|
||||
- Object size editing with scroll wheel
|
||||
- Collision detection and validation
|
||||
- Selection and multi-selection
|
||||
- Grid snapping
|
||||
- Real-time preview
|
||||
|
||||
#### 3. ObjectRenderer
|
||||
- **Purpose**: High-performance rendering system for dungeon objects
|
||||
- **Location**: `src/app/zelda3/dungeon/object_renderer.h/cc`
|
||||
- **Features**:
|
||||
- Graphics cache for performance optimization
|
||||
- Memory pool management
|
||||
- Performance monitoring and statistics
|
||||
- Object parsing from ROM data
|
||||
- Palette support and color management
|
||||
- Batch rendering for efficiency
|
||||
|
||||
#### 4. DungeonEditor (UI Layer)
|
||||
- **Purpose**: User interface and interaction handling
|
||||
- **Location**: `src/app/editor/dungeon/dungeon_editor.h/cc`
|
||||
- **Features**:
|
||||
- Integrated tabbed interface
|
||||
- Canvas-based room editing
|
||||
- Coordinate system management
|
||||
- Object preview system
|
||||
- Real-time rendering
|
||||
- Compact editing panels
|
||||
|
||||
## Coordinate System
|
||||
|
||||
### Room Coordinates vs Canvas Coordinates
|
||||
|
||||
The dungeon editor uses a two-tier coordinate system:
|
||||
|
||||
1. **Room Coordinates**: 16x16 tile units (as used in the ROM)
|
||||
2. **Canvas Coordinates**: Pixel coordinates for rendering
|
||||
|
||||
#### Conversion Functions
|
||||
|
||||
```cpp
|
||||
// Convert room coordinates to canvas coordinates
|
||||
std::pair<int, int> RoomToCanvasCoordinates(int room_x, int room_y) const {
|
||||
return {room_x * 16, room_y * 16};
|
||||
}
|
||||
|
||||
// Convert canvas coordinates to room coordinates
|
||||
std::pair<int, int> CanvasToRoomCoordinates(int canvas_x, int canvas_y) const {
|
||||
return {canvas_x / 16, canvas_y / 16};
|
||||
}
|
||||
|
||||
// Check if coordinates are within canvas bounds
|
||||
bool IsWithinCanvasBounds(int canvas_x, int canvas_y, int margin = 32) const;
|
||||
```
|
||||
|
||||
### Coordinate System Features
|
||||
|
||||
- **Automatic Bounds Checking**: Objects outside visible canvas area are culled
|
||||
- **Scrolling Support**: Canvas handles scrolling internally with proper coordinate transformation
|
||||
- **Grid Alignment**: 16x16 pixel grid for precise object placement
|
||||
- **Margin Support**: Configurable margins for partial object visibility
|
||||
|
||||
## Object Rendering System
|
||||
|
||||
### Object Types
|
||||
|
||||
The system supports three main object subtypes based on ROM structure:
|
||||
|
||||
1. **Subtype 1** (0x00-0xFF): Standard room objects (walls, floors, decorations)
|
||||
2. **Subtype 2** (0x100-0x1FF): Interactive objects (doors, switches, chests)
|
||||
3. **Subtype 3** (0x200+): Special objects (stairs, warps, bosses)
|
||||
|
||||
### Rendering Pipeline
|
||||
|
||||
1. **Object Loading**: Objects are loaded from ROM data using `LoadObjects()`
|
||||
2. **Tile Parsing**: Object tiles are parsed using `ObjectParser`
|
||||
3. **Graphics Caching**: Frequently used graphics are cached for performance
|
||||
4. **Palette Application**: SNES palettes are applied to object graphics
|
||||
5. **Canvas Rendering**: Objects are rendered to canvas with proper coordinate transformation
|
||||
|
||||
### Performance Optimizations
|
||||
|
||||
- **Graphics Cache**: Reduces redundant graphics sheet loading
|
||||
- **Memory Pool**: Efficient memory allocation for rendering
|
||||
- **Batch Rendering**: Multiple objects rendered in single pass
|
||||
- **Bounds Culling**: Objects outside visible area are skipped
|
||||
- **Cache Invalidation**: Smart cache management based on palette changes
|
||||
|
||||
## User Interface
|
||||
|
||||
### Integrated Editing Panels
|
||||
|
||||
The dungeon editor features a consolidated interface with:
|
||||
|
||||
#### Main Canvas
|
||||
- **Room Visualization**: Real-time room rendering with background layers
|
||||
- **Object Display**: Objects rendered with proper positioning and sizing
|
||||
- **Interactive Editing**: Click-to-select, drag-to-move, scroll-to-resize
|
||||
- **Grid Overlay**: Optional grid display for precise positioning
|
||||
- **Coordinate Display**: Real-time coordinate information
|
||||
|
||||
#### Compact Editing Panels
|
||||
|
||||
1. **Object Editor**
|
||||
- Mode selection (Select, Insert, Edit, Delete)
|
||||
- Layer management (BG1, BG2, BG3)
|
||||
- Object type selection
|
||||
- Size editing with scroll wheel
|
||||
- Configuration options (snap to grid, show grid)
|
||||
|
||||
2. **Sprite Editor**
|
||||
- Sprite placement and management
|
||||
- Enemy and NPC configuration
|
||||
- Layer assignment
|
||||
- Quick sprite addition
|
||||
|
||||
3. **Item Editor**
|
||||
- Item placement (keys, hearts, rupees)
|
||||
- Hidden item configuration
|
||||
- Item type selection
|
||||
- Room assignment
|
||||
|
||||
4. **Entrance Editor**
|
||||
- Room connection management
|
||||
- Bidirectional connection support
|
||||
- Position configuration
|
||||
- Connection validation
|
||||
|
||||
5. **Door Editor**
|
||||
- Door placement and configuration
|
||||
- Lock status management
|
||||
- Key requirement setup
|
||||
- Direction and target room assignment
|
||||
|
||||
6. **Chest Editor**
|
||||
- Treasure chest placement
|
||||
- Item and quantity configuration
|
||||
- Big chest support
|
||||
- Opened status tracking
|
||||
|
||||
7. **Properties Editor**
|
||||
- Room metadata management
|
||||
- Dungeon settings
|
||||
- Music and ambient sound configuration
|
||||
- Boss room and save room flags
|
||||
|
||||
### Object Preview System
|
||||
|
||||
- **Real-time Preview**: Objects are previewed in the canvas as they're selected
|
||||
- **Centered Display**: Preview objects are centered in the canvas for optimal viewing
|
||||
- **Palette Support**: Previews use current palette settings
|
||||
- **Information Display**: Object properties are shown in preview window
|
||||
|
||||
## Integration with ZScream
|
||||
|
||||
The dungeon editor is designed to be compatible with ZScream C# patterns:
|
||||
|
||||
### Room Loading
|
||||
- Uses same room loading patterns as ZScream
|
||||
- Compatible with ZScream room data structures
|
||||
- Supports ZScream room naming conventions
|
||||
|
||||
### Object Parsing
|
||||
- Follows ZScream object parsing logic
|
||||
- Compatible with ZScream object type definitions
|
||||
- Supports ZScream size encoding
|
||||
|
||||
### Coordinate System
|
||||
- Matches ZScream coordinate conventions
|
||||
- Uses same tile size calculations
|
||||
- Compatible with ZScream positioning logic
|
||||
|
||||
## Testing and Validation
|
||||
|
||||
### Integration Tests
|
||||
|
||||
The system includes comprehensive integration tests:
|
||||
|
||||
1. **Basic Object Rendering**: Tests fundamental object rendering functionality
|
||||
2. **Multi-Palette Rendering**: Tests rendering with different palettes
|
||||
3. **Real Room Object Rendering**: Tests with actual ROM room data
|
||||
4. **Disassembly Room Validation**: Tests specific rooms from disassembly
|
||||
5. **Performance Testing**: Measures rendering performance and memory usage
|
||||
6. **Cache Effectiveness**: Tests graphics cache performance
|
||||
7. **Error Handling**: Tests error conditions and edge cases
|
||||
|
||||
### Test Data
|
||||
|
||||
Tests use real ROM data from `build/bin/zelda3.sfc`:
|
||||
- **Room 0x0000**: Ganon's room (from disassembly)
|
||||
- **Room 0x0002, 0x0012**: Sewer rooms (from disassembly)
|
||||
- **Room 0x0020**: Agahnim's tower (from disassembly)
|
||||
- **Additional rooms**: 0x0001, 0x0010, 0x0033, 0x005A
|
||||
|
||||
### Performance Benchmarks
|
||||
|
||||
- **Rendering Time**: < 500ms for 100 objects
|
||||
- **Memory Usage**: < 100MB for large object sets
|
||||
- **Cache Hit Rate**: Optimized for frequent object access
|
||||
- **Coordinate Conversion**: O(1) coordinate transformation
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Object Editing
|
||||
|
||||
```cpp
|
||||
// Load a room
|
||||
auto room_result = dungeon_editor_system_->GetRoom(0x0000);
|
||||
|
||||
// Add an object
|
||||
auto status = object_editor_->InsertObject(5, 5, 0x10, 0x12, 0);
|
||||
// Parameters: x, y, object_type, size, layer
|
||||
|
||||
// Render objects
|
||||
auto result = object_renderer_->RenderObjects(objects, palette);
|
||||
```
|
||||
|
||||
### Coordinate Conversion
|
||||
|
||||
```cpp
|
||||
// Convert room coordinates to canvas coordinates
|
||||
auto [canvas_x, canvas_y] = RoomToCanvasCoordinates(room_x, room_y);
|
||||
|
||||
// Check if coordinates are within bounds
|
||||
if (IsWithinCanvasBounds(canvas_x, canvas_y)) {
|
||||
// Render object at this position
|
||||
}
|
||||
```
|
||||
|
||||
### Object Preview
|
||||
|
||||
```cpp
|
||||
// Create preview object
|
||||
auto preview_object = zelda3::RoomObject(id, 8, 8, 0x12, 0);
|
||||
preview_object.set_rom(rom_);
|
||||
preview_object.EnsureTilesLoaded();
|
||||
|
||||
// Render preview
|
||||
auto result = object_renderer_->RenderObject(preview_object, palette);
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### Editor Configuration
|
||||
|
||||
```cpp
|
||||
struct EditorConfig {
|
||||
bool snap_to_grid = true;
|
||||
int grid_size = 16;
|
||||
bool show_grid = true;
|
||||
bool show_preview = true;
|
||||
bool auto_save = false;
|
||||
int auto_save_interval = 300;
|
||||
bool validate_objects = true;
|
||||
bool show_collision_bounds = false;
|
||||
};
|
||||
```
|
||||
|
||||
### Performance Configuration
|
||||
|
||||
```cpp
|
||||
// Object renderer settings
|
||||
object_renderer_->SetCacheSize(100);
|
||||
object_renderer_->EnablePerformanceMonitoring(true);
|
||||
|
||||
// Canvas settings
|
||||
canvas_.SetCanvasSize(ImVec2(512, 512));
|
||||
canvas_.set_draggable(true);
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Objects Not Displaying**
|
||||
- Check if ROM is loaded
|
||||
- Verify object tiles are loaded with `EnsureTilesLoaded()`
|
||||
- Check coordinate bounds with `IsWithinCanvasBounds()`
|
||||
|
||||
2. **Coordinate Misalignment**
|
||||
- Use coordinate conversion functions
|
||||
- Check canvas scrolling settings
|
||||
- Verify grid alignment
|
||||
|
||||
3. **Performance Issues**
|
||||
- Enable graphics caching
|
||||
- Check memory usage with `GetMemoryUsage()`
|
||||
- Monitor performance stats with `GetPerformanceStats()`
|
||||
|
||||
4. **Preview Not Showing**
|
||||
- Verify object is within canvas bounds
|
||||
- Check palette is properly set
|
||||
- Ensure object has valid tiles
|
||||
|
||||
### Debug Information
|
||||
|
||||
The system provides comprehensive debug information:
|
||||
- Object count and statistics
|
||||
- Cache hit/miss rates
|
||||
- Memory usage tracking
|
||||
- Performance metrics
|
||||
- Coordinate system validation
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Planned Features
|
||||
|
||||
1. **Advanced Object Editing**
|
||||
- Multi-object selection and manipulation
|
||||
- Object grouping and layers
|
||||
- Advanced collision detection
|
||||
|
||||
2. **Enhanced Rendering**
|
||||
- Real-time lighting effects
|
||||
- Animation support
|
||||
- Advanced shader effects
|
||||
|
||||
3. **Improved UX**
|
||||
- Keyboard shortcuts
|
||||
- Context menus
|
||||
- Undo/redo visualization
|
||||
|
||||
4. **Integration Features**
|
||||
- ZScream project import/export
|
||||
- Collaborative editing
|
||||
- Version control integration
|
||||
|
||||
## Conclusion
|
||||
|
||||
The Yaze Dungeon Editor provides a comprehensive, high-performance solution for editing Zelda 3 dungeon rooms. With its integrated interface, robust coordinate system, and advanced rendering capabilities, it offers both novice and expert users the tools needed to create and modify dungeon content effectively.
|
||||
|
||||
The system's compatibility with ZScream patterns and comprehensive testing ensure reliability and consistency with existing tools, while its modern architecture provides a foundation for future enhancements and features.
|
||||
@@ -1,175 +0,0 @@
|
||||
# Dungeon Object Rendering Refactor
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes the comprehensive refactoring of the dungeon object rendering system in YAZE, replacing the SNES emulation approach with direct ROM parsing for better performance, reliability, and maintainability.
|
||||
|
||||
## Problem Statement
|
||||
|
||||
The original dungeon object rendering system had several issues:
|
||||
|
||||
1. **SNES Emulation Complexity**: Used full SNES CPU emulation to render objects, which was slow and error-prone
|
||||
2. **Poor Performance**: Emulating thousands of CPU instructions for simple object rendering
|
||||
3. **Maintenance Issues**: Complex emulation code was difficult to debug and maintain
|
||||
4. **Limited Testing**: Hard to test without real ROM files and complex emulation state
|
||||
5. **Architectural Problems**: Tight coupling between rendering and emulation systems
|
||||
|
||||
## Solution Architecture
|
||||
|
||||
### New Components
|
||||
|
||||
#### 1. ObjectParser (`src/app/zelda3/dungeon/object_parser.h/cc`)
|
||||
- **Purpose**: Direct ROM parsing for object data without emulation
|
||||
- **Features**:
|
||||
- Parses all three object subtypes (0x00-0xFF, 0x100-0x1FF, 0x200+)
|
||||
- Extracts tile data directly from ROM tables
|
||||
- Provides object size and orientation information
|
||||
- Handles object routine information
|
||||
|
||||
#### 2. ObjectRenderer (`src/app/zelda3/dungeon/object_renderer.h/cc`)
|
||||
- **Purpose**: High-performance object rendering using parsed data
|
||||
- **Features**:
|
||||
- Renders single objects or multiple objects
|
||||
- Supports size and orientation variations
|
||||
- Provides object previews for UI
|
||||
- Direct bitmap generation without emulation
|
||||
|
||||
#### 3. Enhanced RoomObject (`src/app/zelda3/dungeon/room_object.h/cc`)
|
||||
- **Purpose**: Improved object representation with better tile loading
|
||||
- **Features**:
|
||||
- Uses ObjectParser for tile loading
|
||||
- Fallback to legacy method for compatibility
|
||||
- Better error handling and validation
|
||||
|
||||
#### 4. Simplified Test Framework (`test/test_dungeon_objects.h/cc`)
|
||||
- **Purpose**: Comprehensive testing without real ROM files
|
||||
- **Features**:
|
||||
- Extended MockRom class for testing
|
||||
- Simplified test structure using test folder prefix
|
||||
- Performance benchmarks
|
||||
- Modular component testing
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Object Parsing
|
||||
|
||||
The new system directly parses object data from ROM tables:
|
||||
|
||||
```cpp
|
||||
// Old approach: SNES emulation
|
||||
snes_.cpu().ExecuteInstruction(opcode); // Thousands of instructions
|
||||
|
||||
// New approach: Direct parsing
|
||||
auto tiles = parser.ParseObject(object_id); // Direct ROM access
|
||||
```
|
||||
|
||||
### Object Rendering
|
||||
|
||||
Objects are now rendered directly to bitmaps:
|
||||
|
||||
```cpp
|
||||
// Create object with tiles
|
||||
auto object = RoomObject(id, x, y, size, layer);
|
||||
object.set_rom(rom);
|
||||
object.EnsureTilesLoaded(); // Uses ObjectParser
|
||||
|
||||
// Render to bitmap
|
||||
auto bitmap = renderer.RenderObject(object, palette);
|
||||
```
|
||||
|
||||
### Testing Strategy
|
||||
|
||||
The new system includes comprehensive testing:
|
||||
|
||||
1. **Unit Tests**: Individual component testing
|
||||
2. **Integration Tests**: End-to-end pipeline testing
|
||||
3. **Mock Data**: Testing without real ROM files
|
||||
4. **Performance Tests**: Benchmarking improvements
|
||||
|
||||
## Performance Improvements
|
||||
|
||||
### Before (SNES Emulation)
|
||||
- **Object Rendering**: ~1000+ CPU instructions per object
|
||||
- **Memory Usage**: Full SNES memory state (128KB+)
|
||||
- **Complexity**: O(n) where n = instruction count
|
||||
- **Debugging**: Difficult due to emulation state
|
||||
|
||||
### After (Direct Parsing)
|
||||
- **Object Rendering**: ~10-20 ROM reads per object
|
||||
- **Memory Usage**: Minimal (just parsed data)
|
||||
- **Complexity**: O(1) for most operations
|
||||
- **Debugging**: Simple, direct code paths
|
||||
|
||||
## API Changes
|
||||
|
||||
### DungeonEditor
|
||||
```cpp
|
||||
// Old
|
||||
// zelda3::DungeonObjectRenderer object_renderer_;
|
||||
|
||||
// New
|
||||
zelda3::ObjectRenderer object_renderer_;
|
||||
```
|
||||
|
||||
### RoomObject
|
||||
```cpp
|
||||
// New methods
|
||||
void EnsureTilesLoaded(); // Uses ObjectParser
|
||||
absl::Status LoadTilesWithParser(); // Direct parsing
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Running Tests
|
||||
```bash
|
||||
# Build and run all tests
|
||||
cd build
|
||||
make yaze_test
|
||||
./yaze_test
|
||||
|
||||
# Run specific test suites
|
||||
./yaze_test --gtest_filter="*ObjectParser*"
|
||||
./yaze_test --gtest_filter="*ObjectRenderer*"
|
||||
./yaze_test --gtest_filter="*TestDungeonObjects*"
|
||||
```
|
||||
|
||||
### Test Coverage
|
||||
- **ObjectParser**: 100% method coverage
|
||||
- **ObjectRenderer**: 100% method coverage
|
||||
- **Integration Tests**: Complete pipeline coverage
|
||||
- **Mock Data**: Realistic test scenarios
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### For Developers
|
||||
|
||||
1. **Replace Old Renderer**: Use `ObjectRenderer` instead of `DungeonObjectRenderer`
|
||||
2. **Update Object Loading**: Use `EnsureTilesLoaded()` for automatic tile loading
|
||||
3. **Add Error Handling**: Check return values from new methods
|
||||
4. **Update Tests**: Use new mock framework for testing
|
||||
|
||||
### For Users
|
||||
|
||||
- **No Breaking Changes**: All existing functionality preserved
|
||||
- **Better Performance**: Faster object rendering
|
||||
- **More Reliable**: Fewer emulation-related bugs
|
||||
- **Better UI**: Improved object previews
|
||||
|
||||
## Future Improvements
|
||||
|
||||
1. **Caching**: Add tile data caching for repeated objects
|
||||
2. **Batch Rendering**: Render multiple objects in single operation
|
||||
3. **GPU Acceleration**: Use GPU for large-scale rendering
|
||||
4. **Real-time Preview**: Live object preview in editor
|
||||
5. **Animation Support**: Animated object rendering
|
||||
|
||||
## Conclusion
|
||||
|
||||
The refactored dungeon object rendering system provides:
|
||||
|
||||
- **10x Performance Improvement**: Direct parsing vs emulation
|
||||
- **Better Maintainability**: Cleaner, more focused code
|
||||
- **Comprehensive Testing**: Full test coverage with mocks
|
||||
- **Future-Proof Architecture**: Extensible design for new features
|
||||
|
||||
This refactoring establishes a solid foundation for future dungeon editing features while maintaining backward compatibility and improving overall system reliability.
|
||||
Reference in New Issue
Block a user