Update README and documentation for YAZE v0.3.0 release
- Revamped README to reflect the new branding and major features of YAZE, including complete Asar 65816 assembler integration and enhanced CLI tools. - Added new documentation files for getting started, build instructions, Asar integration, and comprehensive testing guides. - Removed outdated documentation and streamlined the structure for better navigation. - Introduced a changelog to track version history and significant updates. - Updated API reference and added detailed guides for dungeon and overworld editing functionalities.
This commit is contained in:
scawful
56
docs/01-getting-started.md
Normal file
56
docs/01-getting-started.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# Getting Started
|
||||
|
||||
This software allows you to modify "The Legend of Zelda: A Link to the Past" (US or JP) ROMs. Built for compatibility with ZScream projects and designed to be cross-platform.
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. **Download** the latest release for your platform
|
||||
2. **Load ROM** via File > Open ROM
|
||||
3. **Select Editor** from the toolbar (Overworld, Dungeon, Graphics, etc.)
|
||||
4. **Make Changes** and save your project
|
||||
|
||||
## General Tips
|
||||
|
||||
- **Experiment Flags**: Enable/disable features in File > Options > Experiment Flags
|
||||
- **Backup Files**: Enabled by default - each save creates a timestamped backup
|
||||
- **Extensions**: Load custom tools via the Extensions menu (C library and Python module support)
|
||||
|
||||
## Supported Features
|
||||
|
||||
| Feature | Status | Details |
|
||||
|---------|--------|---------|
|
||||
| Overworld Maps | ✅ Complete | Edit and save tile32 data |
|
||||
| OW Map Properties | ✅ Complete | Edit and save map properties |
|
||||
| OW Entrances | ✅ Complete | Edit and save entrance data |
|
||||
| OW Exits | ✅ Complete | Edit and save exit data |
|
||||
| OW Sprites | 🔄 In Progress | Edit sprite positions, add/remove sprites |
|
||||
| Dungeon Editor | 🔄 In Progress | View room metadata and edit room data |
|
||||
| Palette Editor | 🔄 In Progress | Edit and save palettes, palette groups |
|
||||
| Graphics Sheets | 🔄 In Progress | Edit and save graphics sheets |
|
||||
| Graphics Groups | ✅ Complete | Edit and save graphics groups |
|
||||
| Hex Editor | ✅ Complete | View and edit ROM data in hex |
|
||||
| Asar Patching | ✅ Complete | Apply Asar 65816 assembly patches to ROM |
|
||||
|
||||
## Command Line Interface
|
||||
|
||||
The `z3ed` CLI tool provides ROM operations:
|
||||
|
||||
```bash
|
||||
# Apply Asar assembly patch
|
||||
z3ed asar patch.asm --rom=zelda3.sfc
|
||||
|
||||
# Extract symbols from assembly
|
||||
z3ed extract patch.asm
|
||||
|
||||
# Validate assembly syntax
|
||||
z3ed validate patch.asm
|
||||
|
||||
# Launch interactive TUI
|
||||
z3ed --tui
|
||||
```
|
||||
|
||||
## Extending Functionality
|
||||
|
||||
YAZE provides a pure C library interface and Python module for building extensions and custom sprites without assembly. Load these under the Extensions menu.
|
||||
|
||||
This feature is still in development and not fully documented yet.
|
||||
65
docs/02-build-instructions.md
Normal file
65
docs/02-build-instructions.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# Build Instructions
|
||||
|
||||
YAZE uses CMake 3.16+ with modern target-based configuration. For VSCode users, install the CMake extensions:
|
||||
- https://marketplace.visualstudio.com/items?itemName=twxs.cmake
|
||||
- https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
|
||||
|
||||
## Quick Build
|
||||
|
||||
```bash
|
||||
# Development build
|
||||
cmake --preset dev
|
||||
cmake --build --preset dev
|
||||
|
||||
# CI build (minimal dependencies)
|
||||
cmake --preset ci
|
||||
cmake --build --preset ci
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Core Dependencies
|
||||
- **SDL2**: Graphics and input library
|
||||
- **ImGui**: Immediate mode GUI library with docking support
|
||||
- **Abseil**: Modern C++ utilities library
|
||||
- **libpng**: Image processing library
|
||||
|
||||
### v0.3.0 Additions
|
||||
- **Asar**: 65816 assembler for ROM patching
|
||||
- **ftxui**: Terminal UI library for CLI
|
||||
- **GoogleTest**: Comprehensive testing framework
|
||||
|
||||
## Platform-Specific Setup
|
||||
|
||||
### Windows
|
||||
|
||||
#### vcpkg (Recommended)
|
||||
```json
|
||||
{
|
||||
"dependencies": [
|
||||
"abseil", "sdl2", "libpng"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### msys2 (Advanced)
|
||||
Install packages: `mingw-w64-x86_64-gcc`, `mingw-w64-x86_64-cmake`, `mingw-w64-x86_64-sdl2`, `mingw-w64-x86_64-libpng`, `mingw-w64-x86_64-abseil-cpp`
|
||||
|
||||
### macOS
|
||||
```bash
|
||||
brew install cmake sdl2 zlib libpng abseil boost-python3
|
||||
```
|
||||
|
||||
### Linux
|
||||
Use your package manager to install the same dependencies as macOS.
|
||||
|
||||
### iOS
|
||||
Xcode required. The xcodeproject file is in the `ios` directory. Link `SDL2.framework` and `libpng.a`.
|
||||
|
||||
## Build Targets
|
||||
|
||||
- **yaze**: Desktop GUI application
|
||||
- **z3ed**: Enhanced CLI tool
|
||||
- **yaze_c**: C library for extensions
|
||||
- **yaze_test**: Test suite executable
|
||||
- **yaze_emu**: Standalone SNES emulator
|
||||
141
docs/03-asar-integration.md
Normal file
141
docs/03-asar-integration.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# Asar 65816 Assembler Integration
|
||||
|
||||
Complete cross-platform ROM patching with assembly code support, symbol extraction, and validation.
|
||||
|
||||
## Quick Examples
|
||||
|
||||
### Command Line
|
||||
```bash
|
||||
# Apply assembly patch to ROM
|
||||
z3ed asar my_patch.asm --rom=zelda3.sfc
|
||||
|
||||
# Extract symbols without patching
|
||||
z3ed extract my_patch.asm
|
||||
|
||||
# Validate assembly syntax
|
||||
z3ed validate my_patch.asm
|
||||
```
|
||||
|
||||
### C++ API
|
||||
```cpp
|
||||
#include "app/core/asar_wrapper.h"
|
||||
|
||||
yaze::app::core::AsarWrapper wrapper;
|
||||
wrapper.Initialize();
|
||||
|
||||
// Apply patch to ROM
|
||||
auto result = wrapper.ApplyPatch("patch.asm", rom_data);
|
||||
if (result.ok() && result->success) {
|
||||
for (const auto& symbol : result->symbols) {
|
||||
std::cout << symbol.name << " @ $" << std::hex << symbol.address << std::endl;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Assembly Patch Examples
|
||||
|
||||
### Basic Hook
|
||||
```assembly
|
||||
org $008000
|
||||
custom_hook:
|
||||
sei ; Disable interrupts
|
||||
rep #$30 ; 16-bit A and X/Y
|
||||
|
||||
; Your custom code
|
||||
lda #$1234
|
||||
sta $7E0000
|
||||
|
||||
rts
|
||||
|
||||
custom_data:
|
||||
db "YAZE", $00
|
||||
dw $1234, $5678
|
||||
```
|
||||
|
||||
### Advanced Features
|
||||
```assembly
|
||||
!player_health = $7EF36C
|
||||
!custom_ram = $7E2000
|
||||
|
||||
macro save_context()
|
||||
pha : phx : phy
|
||||
endmacro
|
||||
|
||||
org $008000
|
||||
advanced_hook:
|
||||
%save_context()
|
||||
|
||||
sep #$20
|
||||
lda #$A0 ; Full health
|
||||
sta !player_health
|
||||
|
||||
%save_context()
|
||||
rtl
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### AsarWrapper Class
|
||||
```cpp
|
||||
class AsarWrapper {
|
||||
public:
|
||||
absl::Status Initialize();
|
||||
absl::StatusOr<AsarPatchResult> ApplyPatch(
|
||||
const std::string& patch_path,
|
||||
std::vector<uint8_t>& rom_data);
|
||||
absl::StatusOr<std::vector<AsarSymbol>> ExtractSymbols(
|
||||
const std::string& asm_path);
|
||||
absl::Status ValidateAssembly(const std::string& asm_path);
|
||||
};
|
||||
```
|
||||
|
||||
### Data Structures
|
||||
```cpp
|
||||
struct AsarSymbol {
|
||||
std::string name; // Symbol name
|
||||
uint32_t address; // Memory address
|
||||
std::string opcode; // Associated opcode
|
||||
std::string file; // Source file
|
||||
int line; // Line number
|
||||
};
|
||||
|
||||
struct AsarPatchResult {
|
||||
bool success; // Whether patch succeeded
|
||||
std::vector<std::string> errors; // Error messages
|
||||
std::vector<AsarSymbol> symbols; // Extracted symbols
|
||||
uint32_t rom_size; // Final ROM size
|
||||
};
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### ROM-Dependent Tests
|
||||
```cpp
|
||||
YAZE_ROM_TEST(AsarIntegration, RealRomPatching) {
|
||||
auto rom_data = TestRomManager::LoadTestRom();
|
||||
AsarWrapper wrapper;
|
||||
wrapper.Initialize();
|
||||
|
||||
auto result = wrapper.ApplyPatch("test.asm", rom_data);
|
||||
EXPECT_TRUE(result.ok());
|
||||
}
|
||||
```
|
||||
|
||||
ROM tests are automatically skipped in CI with `--label-exclude ROM_DEPENDENT`.
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Cause | Solution |
|
||||
|-------|-------|----------|
|
||||
| `Unknown command` | Invalid opcode | Check 65816 instruction reference |
|
||||
| `Label not found` | Undefined label | Define the label or check spelling |
|
||||
| `Invalid hex value` | Bad hex format | Use `$1234` format |
|
||||
| `Buffer too small` | ROM needs expansion | Check if ROM needs to be larger |
|
||||
|
||||
## Development Workflow
|
||||
|
||||
1. **Write assembly patch**
|
||||
2. **Validate syntax**: `z3ed validate patch.asm`
|
||||
3. **Extract symbols**: `z3ed extract patch.asm`
|
||||
4. **Apply to test ROM**: `z3ed asar patch.asm --rom=test.sfc`
|
||||
5. **Test in emulator**
|
||||
208
docs/04-api-reference.md
Normal file
208
docs/04-api-reference.md
Normal file
@@ -0,0 +1,208 @@
|
||||
# API Reference
|
||||
|
||||
Comprehensive reference for the YAZE C API and C++ interfaces.
|
||||
|
||||
## C API (`incl/yaze.h`, `incl/zelda.h`)
|
||||
|
||||
### Core Library Functions
|
||||
```c
|
||||
// Initialization
|
||||
yaze_status yaze_library_init(void);
|
||||
void yaze_library_shutdown(void);
|
||||
|
||||
// Version management
|
||||
const char* yaze_get_version_string(void);
|
||||
int yaze_get_version_number(void);
|
||||
bool yaze_check_version_compatibility(const char* expected_version);
|
||||
|
||||
// Status utilities
|
||||
const char* yaze_status_to_string(yaze_status status);
|
||||
```
|
||||
|
||||
### ROM Operations
|
||||
```c
|
||||
// ROM loading and management
|
||||
zelda3_rom* yaze_load_rom(const char* filename);
|
||||
void yaze_unload_rom(zelda3_rom* rom);
|
||||
yaze_status yaze_save_rom(zelda3_rom* rom, const char* filename);
|
||||
bool yaze_is_rom_modified(const zelda3_rom* rom);
|
||||
```
|
||||
|
||||
### Graphics Operations
|
||||
```c
|
||||
// SNES color management
|
||||
snes_color yaze_rgb_to_snes_color(uint8_t r, uint8_t g, uint8_t b);
|
||||
void yaze_snes_color_to_rgb(snes_color color, uint8_t* r, uint8_t* g, uint8_t* b);
|
||||
|
||||
// Bitmap operations
|
||||
yaze_bitmap* yaze_create_bitmap(int width, int height, uint8_t bpp);
|
||||
void yaze_free_bitmap(yaze_bitmap* bitmap);
|
||||
```
|
||||
|
||||
### Palette System
|
||||
```c
|
||||
// Palette creation and management
|
||||
snes_palette* yaze_create_palette(uint8_t id, uint8_t size);
|
||||
void yaze_free_palette(snes_palette* palette);
|
||||
snes_palette* yaze_load_palette_from_rom(const zelda3_rom* rom, uint8_t palette_id);
|
||||
```
|
||||
|
||||
### Message System
|
||||
```c
|
||||
// Message handling
|
||||
zelda3_message* yaze_load_message(const zelda3_rom* rom, uint16_t message_id);
|
||||
void yaze_free_message(zelda3_message* message);
|
||||
yaze_status yaze_save_message(zelda3_rom* rom, const zelda3_message* message);
|
||||
```
|
||||
|
||||
## C++ API
|
||||
|
||||
### AsarWrapper (`src/app/core/asar_wrapper.h`)
|
||||
```cpp
|
||||
namespace yaze::app::core {
|
||||
|
||||
class AsarWrapper {
|
||||
public:
|
||||
// Initialization
|
||||
absl::Status Initialize();
|
||||
void Shutdown();
|
||||
bool IsInitialized() const;
|
||||
|
||||
// Core functionality
|
||||
absl::StatusOr<AsarPatchResult> ApplyPatch(
|
||||
const std::string& patch_path,
|
||||
std::vector<uint8_t>& rom_data,
|
||||
const std::vector<std::string>& include_paths = {});
|
||||
|
||||
absl::StatusOr<std::vector<AsarSymbol>> ExtractSymbols(
|
||||
const std::string& asm_path,
|
||||
const std::vector<std::string>& include_paths = {});
|
||||
|
||||
// Symbol management
|
||||
std::optional<AsarSymbol> FindSymbol(const std::string& name);
|
||||
std::vector<AsarSymbol> GetSymbolsAtAddress(uint32_t address);
|
||||
std::map<std::string, AsarSymbol> GetSymbolTable();
|
||||
|
||||
// Utility functions
|
||||
absl::Status ValidateAssembly(const std::string& asm_path);
|
||||
std::string GetVersion();
|
||||
void Reset();
|
||||
};
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
### Data Structures
|
||||
|
||||
#### ROM Version Support
|
||||
```c
|
||||
typedef enum zelda3_version {
|
||||
ZELDA3_VERSION_US = 1,
|
||||
ZELDA3_VERSION_JP = 2,
|
||||
ZELDA3_VERSION_SD = 3,
|
||||
ZELDA3_VERSION_RANDO = 4,
|
||||
// Legacy aliases maintained for compatibility
|
||||
US = ZELDA3_VERSION_US,
|
||||
JP = ZELDA3_VERSION_JP,
|
||||
SD = ZELDA3_VERSION_SD,
|
||||
RANDO = ZELDA3_VERSION_RANDO,
|
||||
} zelda3_version;
|
||||
```
|
||||
|
||||
#### SNES Graphics
|
||||
```c
|
||||
typedef struct snes_color {
|
||||
uint16_t raw; // Raw 15-bit SNES color
|
||||
uint8_t red; // Red component (0-31)
|
||||
uint8_t green; // Green component (0-31)
|
||||
uint8_t blue; // Blue component (0-31)
|
||||
} snes_color;
|
||||
|
||||
typedef struct snes_palette {
|
||||
uint8_t id; // Palette ID
|
||||
uint8_t size; // Number of colors
|
||||
snes_color* colors; // Color array
|
||||
} snes_palette;
|
||||
```
|
||||
|
||||
#### Message System
|
||||
```c
|
||||
typedef struct zelda3_message {
|
||||
uint16_t id; // Message ID (0-65535)
|
||||
uint32_t rom_address; // Address in ROM
|
||||
uint16_t length; // Length in bytes
|
||||
uint8_t* raw_data; // Raw ROM data
|
||||
char* parsed_text; // Decoded UTF-8 text
|
||||
bool is_compressed; // Compression flag
|
||||
uint8_t encoding_type; // Encoding type
|
||||
} zelda3_message;
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Status Codes
|
||||
```c
|
||||
typedef enum yaze_status {
|
||||
YAZE_OK = 0, // Success
|
||||
YAZE_ERROR_UNKNOWN = -1, // Unknown error
|
||||
YAZE_ERROR_INVALID_ARG = 1, // Invalid argument
|
||||
YAZE_ERROR_FILE_NOT_FOUND = 2, // File not found
|
||||
YAZE_ERROR_MEMORY = 3, // Memory allocation failed
|
||||
YAZE_ERROR_IO = 4, // I/O operation failed
|
||||
YAZE_ERROR_CORRUPTION = 5, // Data corruption detected
|
||||
YAZE_ERROR_NOT_INITIALIZED = 6, // Component not initialized
|
||||
} yaze_status;
|
||||
```
|
||||
|
||||
### Error Handling Pattern
|
||||
```c
|
||||
yaze_status status = yaze_library_init();
|
||||
if (status != YAZE_OK) {
|
||||
printf("Failed to initialize YAZE: %s\n", yaze_status_to_string(status));
|
||||
return 1;
|
||||
}
|
||||
|
||||
zelda3_rom* rom = yaze_load_rom("zelda3.sfc");
|
||||
if (rom == nullptr) {
|
||||
printf("Failed to load ROM file\n");
|
||||
return 1;
|
||||
}
|
||||
|
||||
// Use ROM...
|
||||
yaze_unload_rom(rom);
|
||||
yaze_library_shutdown();
|
||||
```
|
||||
|
||||
## Extension System
|
||||
|
||||
### Plugin Architecture
|
||||
```c
|
||||
typedef struct yaze_extension {
|
||||
const char* name; // Extension name
|
||||
const char* version; // Version string
|
||||
const char* description; // Description
|
||||
const char* author; // Author
|
||||
int api_version; // Required API version
|
||||
|
||||
yaze_status (*initialize)(yaze_editor_context* context);
|
||||
void (*cleanup)(void);
|
||||
uint32_t (*get_capabilities)(void);
|
||||
} yaze_extension;
|
||||
```
|
||||
|
||||
### Capability Flags
|
||||
```c
|
||||
#define YAZE_EXT_CAP_ROM_EDITING 0x0001 // ROM modification
|
||||
#define YAZE_EXT_CAP_GRAPHICS 0x0002 // Graphics operations
|
||||
#define YAZE_EXT_CAP_AUDIO 0x0004 // Audio processing
|
||||
#define YAZE_EXT_CAP_SCRIPTING 0x0008 // Scripting support
|
||||
#define YAZE_EXT_CAP_IMPORT_EXPORT 0x0010 // Data import/export
|
||||
```
|
||||
|
||||
## Backward Compatibility
|
||||
|
||||
All existing code continues to work without modification due to:
|
||||
- Legacy enum aliases (`US`, `JP`, `SD`, `RANDO`)
|
||||
- Original struct field names maintained
|
||||
- Duplicate field definitions for old/new naming conventions
|
||||
- Typedef aliases for renamed types
|
||||
@@ -1,14 +1,14 @@
|
||||
# Testing Strategy for Yaze v0.3.0
|
||||
# Testing Guide
|
||||
|
||||
Comprehensive testing framework with efficient CI/CD integration and ROM-dependent test separation.
|
||||
|
||||
## Test Categories
|
||||
|
||||
Yaze uses a comprehensive testing strategy with different categories of tests to ensure quality while maintaining efficient CI/CD pipelines.
|
||||
|
||||
### Stable Tests (STABLE)
|
||||
**Always run in CI/CD - Required for releases**
|
||||
|
||||
- **AsarWrapperTest**: Core Asar functionality tests
|
||||
- **SnesTileTest**: SNES tile format handling
|
||||
- **SnesTileTest**: SNES tile format handling
|
||||
- **CompressionTest**: Data compression/decompression
|
||||
- **SnesPaletteTest**: SNES palette operations
|
||||
- **HexTest**: Hexadecimal utilities
|
||||
@@ -18,7 +18,6 @@ Yaze uses a comprehensive testing strategy with different categories of tests to
|
||||
- Fast execution (< 30 seconds total)
|
||||
- No external dependencies (ROMs, complex setup)
|
||||
- High reliability and deterministic results
|
||||
- Core functionality testing
|
||||
|
||||
### ROM-Dependent Tests (ROM_DEPENDENT)
|
||||
**Only run in development with available ROM files**
|
||||
@@ -29,68 +28,22 @@ Yaze uses a comprehensive testing strategy with different categories of tests to
|
||||
**Characteristics:**
|
||||
- Require specific ROM files to be present
|
||||
- Test real-world functionality
|
||||
- May be slower due to large file operations
|
||||
- Automatically skipped in CI if ROM files unavailable
|
||||
|
||||
### Experimental Tests (EXPERIMENTAL)
|
||||
### Experimental Tests (EXPERIMENTAL)
|
||||
**Run separately, allowed to fail**
|
||||
|
||||
- **CpuTest**: 65816 CPU emulation tests (complex, may have timing issues)
|
||||
- **CpuTest**: 65816 CPU emulation tests
|
||||
- **Spc700Test**: SPC700 audio processor tests
|
||||
- **ApuTest**: Audio Processing Unit tests
|
||||
- **PpuTest**: Picture Processing Unit tests
|
||||
- **Complex Integration Tests**: Multi-component integration tests
|
||||
|
||||
**Characteristics:**
|
||||
- May be unstable due to emulation complexity
|
||||
- Test advanced/experimental features
|
||||
- Allowed to fail without blocking releases
|
||||
- Run in separate CI job with `continue-on-error: true`
|
||||
|
||||
### GUI Tests (GUI_TEST)
|
||||
**Tests requiring graphical components**
|
||||
|
||||
- **DungeonEditorIntegrationTest**: GUI-based dungeon editing
|
||||
- **Editor Integration Tests**: Tests requiring ImGui components
|
||||
|
||||
**Characteristics:**
|
||||
- Require display/graphics context
|
||||
- May not work in headless CI environments
|
||||
- Focus on user interface functionality
|
||||
|
||||
## CI/CD Strategy
|
||||
|
||||
### Main CI Pipeline
|
||||
```yaml
|
||||
# Always run - required for merge
|
||||
- Run Stable Tests: --label-regex "STABLE"
|
||||
|
||||
# Optional - allowed to fail
|
||||
- Run Experimental Tests: --label-regex "EXPERIMENTAL" (continue-on-error: true)
|
||||
```
|
||||
|
||||
### Development Testing
|
||||
```bash
|
||||
# Quick development testing
|
||||
ctest --preset stable
|
||||
|
||||
# Full development testing with ROM
|
||||
ctest --preset dev
|
||||
|
||||
# Test specific functionality
|
||||
ctest --preset asar-only
|
||||
```
|
||||
|
||||
### Release Testing
|
||||
```bash
|
||||
# Release candidate testing
|
||||
ctest --preset stable --parallel
|
||||
ctest --preset ci
|
||||
```
|
||||
|
||||
## Test Execution Examples
|
||||
|
||||
### Command Line Usage
|
||||
## Command Line Usage
|
||||
|
||||
```bash
|
||||
# Run only stable tests (release-ready)
|
||||
@@ -110,7 +63,7 @@ ctest --preset stable
|
||||
ctest --preset experimental
|
||||
```
|
||||
|
||||
### CMake Preset Usage
|
||||
## CMake Presets
|
||||
|
||||
```bash
|
||||
# Development workflow
|
||||
@@ -129,6 +82,62 @@ cmake --build --preset release
|
||||
ctest --preset stable
|
||||
```
|
||||
|
||||
## Writing Tests
|
||||
|
||||
### Stable Tests
|
||||
```cpp
|
||||
TEST(SnesTileTest, UnpackBppTile) {
|
||||
std::vector<uint8_t> tile_data = {0xAA, 0x55, 0xAA, 0x55};
|
||||
std::vector<uint8_t> result = UnpackBppTile(tile_data, 2);
|
||||
EXPECT_EQ(result.size(), 64);
|
||||
// Test specific pixel values...
|
||||
}
|
||||
```
|
||||
|
||||
### ROM-Dependent Tests
|
||||
```cpp
|
||||
YAZE_ROM_TEST(AsarIntegration, RealRomPatching) {
|
||||
auto rom_data = TestRomManager::LoadTestRom();
|
||||
if (!rom_data.has_value()) {
|
||||
GTEST_SKIP() << "ROM file not available";
|
||||
}
|
||||
|
||||
AsarWrapper wrapper;
|
||||
wrapper.Initialize();
|
||||
|
||||
auto result = wrapper.ApplyPatch("test.asm", *rom_data);
|
||||
EXPECT_TRUE(result.ok());
|
||||
}
|
||||
```
|
||||
|
||||
### Experimental Tests
|
||||
```cpp
|
||||
TEST(CpuTest, InstructionExecution) {
|
||||
// Complex emulation tests
|
||||
// May be timing-sensitive or platform-dependent
|
||||
}
|
||||
```
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions
|
||||
```yaml
|
||||
# Main CI pipeline
|
||||
- name: Run Stable Tests
|
||||
run: ctest --label-regex "STABLE"
|
||||
|
||||
# Experimental tests (allowed to fail)
|
||||
- name: Run Experimental Tests
|
||||
run: ctest --label-regex "EXPERIMENTAL"
|
||||
continue-on-error: true
|
||||
```
|
||||
|
||||
### Test Execution Strategy
|
||||
1. **Stable tests run first** - Quick feedback for developers
|
||||
2. **Experimental tests run in parallel** - Don't block on unstable tests
|
||||
3. **ROM tests skipped** - No dependency on external files
|
||||
4. **Selective test execution** - Only run relevant tests for changes
|
||||
|
||||
## Test Development Guidelines
|
||||
|
||||
### Writing Stable Tests
|
||||
@@ -137,33 +146,19 @@ ctest --preset stable
|
||||
- **Deterministic**: Same results every run
|
||||
- **Core functionality**: Test essential features only
|
||||
|
||||
### Writing Experimental Tests
|
||||
- **Complex scenarios**: Multi-component integration
|
||||
- **Advanced features**: Emulation, complex algorithms
|
||||
- **Performance tests**: May vary by system
|
||||
- **GUI components**: May require display context
|
||||
|
||||
### Writing ROM-Dependent Tests
|
||||
- **Use TestRomManager**: Proper ROM file handling
|
||||
- **Graceful skipping**: Skip if ROM not available
|
||||
- **Real-world scenarios**: Test with actual game data
|
||||
- **Label appropriately**: Always include ROM_DEPENDENT label
|
||||
|
||||
## CI/CD Efficiency
|
||||
### Writing Experimental Tests
|
||||
- **Complex scenarios**: Multi-component integration
|
||||
- **Advanced features**: Emulation, complex algorithms
|
||||
- **Performance tests**: May vary by system
|
||||
- **GUI components**: May require display context
|
||||
|
||||
### Fast Feedback Loop
|
||||
1. **Stable tests run first** - Quick feedback for developers
|
||||
2. **Experimental tests run in parallel** - Don't block on unstable tests
|
||||
3. **ROM tests skipped** - No dependency on external files
|
||||
4. **Selective test execution** - Only run relevant tests for changes
|
||||
|
||||
### Release Quality Gates
|
||||
1. **All stable tests must pass** - No exceptions
|
||||
2. **Experimental tests informational only** - Don't block releases
|
||||
3. **ROM tests run manually** - When ROM files available
|
||||
4. **Performance benchmarks** - Track regression trends
|
||||
|
||||
## Maintenance Strategy
|
||||
## Performance and Maintenance
|
||||
|
||||
### Regular Review
|
||||
- **Monthly review** of experimental test failures
|
||||
@@ -176,27 +171,3 @@ ctest --preset stable
|
||||
- **Identify slow tests** for optimization or recategorization
|
||||
- **Monitor CI resource usage** and adjust parallelism
|
||||
- **Benchmark critical path tests** for performance regression
|
||||
|
||||
## Test Categories by Feature
|
||||
|
||||
### Asar Integration
|
||||
- **Stable**: AsarWrapperTest, AsarIntegrationTest
|
||||
- **ROM-Dependent**: AsarRomIntegrationTest
|
||||
- **Focus**: Core assembly patching and symbol extraction
|
||||
|
||||
### Graphics System
|
||||
- **Stable**: SnesTileTest, SnesPaletteTest, CompressionTest
|
||||
- **Experimental**: Complex rendering tests
|
||||
- **Focus**: SNES graphics format handling
|
||||
|
||||
### Emulation
|
||||
- **Experimental**: CpuTest, Spc700Test, ApuTest, PpuTest
|
||||
- **Focus**: Hardware emulation accuracy
|
||||
- **Note**: Complex timing-sensitive tests
|
||||
|
||||
### Editor Components
|
||||
- **GUI**: DungeonEditorIntegrationTest, Editor integration tests
|
||||
- **Experimental**: Complex editor workflow tests
|
||||
- **Focus**: User interface functionality
|
||||
|
||||
This strategy ensures efficient CI/CD while maintaining comprehensive test coverage for quality assurance.
|
||||
239
docs/B1-contributing.md
Normal file
239
docs/B1-contributing.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# Contributing
|
||||
|
||||
Guidelines for contributing to the YAZE project.
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Prerequisites
|
||||
- **CMake 3.16+**: Modern build system
|
||||
- **C++23 Compiler**: GCC 13+, Clang 16+, MSVC 2022 17.8+
|
||||
- **Git**: Version control with submodules
|
||||
|
||||
### Quick Start
|
||||
```bash
|
||||
# Clone with submodules
|
||||
git clone --recursive https://github.com/scawful/yaze.git
|
||||
cd yaze
|
||||
|
||||
# Build with presets
|
||||
cmake --preset dev
|
||||
cmake --build --preset dev
|
||||
|
||||
# Run tests
|
||||
ctest --preset stable
|
||||
```
|
||||
|
||||
## Code Style
|
||||
|
||||
### C++ Standards
|
||||
- **C++23**: Use modern language features
|
||||
- **Google C++ Style**: Follow Google C++ style guide
|
||||
- **Naming**: Use descriptive names, avoid abbreviations
|
||||
|
||||
### File Organization
|
||||
```cpp
|
||||
// Header guards
|
||||
#pragma once
|
||||
|
||||
// Includes (system, third-party, local)
|
||||
#include <vector>
|
||||
#include "absl/status/status.h"
|
||||
#include "app/core/asar_wrapper.h"
|
||||
|
||||
// Namespace usage
|
||||
namespace yaze::app::editor {
|
||||
|
||||
class ExampleClass {
|
||||
public:
|
||||
// Public interface
|
||||
absl::Status Initialize();
|
||||
|
||||
private:
|
||||
// Private implementation
|
||||
std::vector<uint8_t> data_;
|
||||
};
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
```cpp
|
||||
// Use absl::Status for error handling
|
||||
absl::Status LoadRom(const std::string& filename) {
|
||||
if (filename.empty()) {
|
||||
return absl::InvalidArgumentError("Filename cannot be empty");
|
||||
}
|
||||
|
||||
// ... implementation
|
||||
|
||||
return absl::OkStatus();
|
||||
}
|
||||
|
||||
// Use absl::StatusOr for operations that return values
|
||||
absl::StatusOr<std::vector<uint8_t>> ReadFile(const std::string& filename);
|
||||
```
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
### Test Categories
|
||||
- **Stable Tests**: Fast, reliable, no external dependencies
|
||||
- **ROM-Dependent Tests**: Require ROM files, skip in CI
|
||||
- **Experimental Tests**: Complex, may be unstable
|
||||
|
||||
### Writing Tests
|
||||
```cpp
|
||||
// Stable test example
|
||||
TEST(SnesTileTest, UnpackBppTile) {
|
||||
std::vector<uint8_t> tile_data = {0xAA, 0x55};
|
||||
auto result = UnpackBppTile(tile_data, 2);
|
||||
EXPECT_TRUE(result.ok());
|
||||
EXPECT_EQ(result->size(), 64);
|
||||
}
|
||||
|
||||
// ROM-dependent test example
|
||||
YAZE_ROM_TEST(AsarIntegration, RealRomPatching) {
|
||||
auto rom_data = TestRomManager::LoadTestRom();
|
||||
if (!rom_data.has_value()) {
|
||||
GTEST_SKIP() << "ROM file not available";
|
||||
}
|
||||
// ... test implementation
|
||||
}
|
||||
```
|
||||
|
||||
### Test Execution
|
||||
```bash
|
||||
# Run stable tests (required)
|
||||
ctest --label-regex "STABLE"
|
||||
|
||||
# Run experimental tests (optional)
|
||||
ctest --label-regex "EXPERIMENTAL"
|
||||
|
||||
# Run specific test
|
||||
ctest -R "AsarWrapperTest"
|
||||
```
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
### Before Submitting
|
||||
1. **Run tests**: Ensure all stable tests pass
|
||||
2. **Check formatting**: Use clang-format
|
||||
3. **Update documentation**: Update relevant docs if needed
|
||||
4. **Test on multiple platforms**: Verify cross-platform compatibility
|
||||
|
||||
### Pull Request Template
|
||||
```markdown
|
||||
## Description
|
||||
Brief description of changes
|
||||
|
||||
## Type of Change
|
||||
- [ ] Bug fix
|
||||
- [ ] New feature
|
||||
- [ ] Breaking change
|
||||
- [ ] Documentation update
|
||||
|
||||
## Testing
|
||||
- [ ] Stable tests pass
|
||||
- [ ] Manual testing completed
|
||||
- [ ] Cross-platform testing (if applicable)
|
||||
|
||||
## Checklist
|
||||
- [ ] Code follows project style guidelines
|
||||
- [ ] Self-review completed
|
||||
- [ ] Documentation updated
|
||||
- [ ] Tests added/updated
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Branch Strategy
|
||||
- **main**: Stable, release-ready code
|
||||
- **feature/**: New features and enhancements
|
||||
- **fix/**: Bug fixes
|
||||
- **docs/**: Documentation updates
|
||||
|
||||
### Commit Messages
|
||||
```
|
||||
type(scope): brief description
|
||||
|
||||
Detailed explanation of changes, including:
|
||||
- What was changed
|
||||
- Why it was changed
|
||||
- Any breaking changes
|
||||
|
||||
Fixes #issue_number
|
||||
```
|
||||
|
||||
### Types
|
||||
- **feat**: New features
|
||||
- **fix**: Bug fixes
|
||||
- **docs**: Documentation changes
|
||||
- **style**: Code style changes
|
||||
- **refactor**: Code refactoring
|
||||
- **test**: Test additions/changes
|
||||
- **chore**: Build/tooling changes
|
||||
|
||||
## Architecture Guidelines
|
||||
|
||||
### Component Design
|
||||
- **Single Responsibility**: Each class should have one clear purpose
|
||||
- **Dependency Injection**: Use dependency injection for testability
|
||||
- **Interface Segregation**: Keep interfaces focused and minimal
|
||||
|
||||
### Memory Management
|
||||
- **RAII**: Use RAII for resource management
|
||||
- **Smart Pointers**: Prefer unique_ptr and shared_ptr
|
||||
- **Avoid Raw Pointers**: Use smart pointers or references
|
||||
|
||||
### Performance
|
||||
- **Profile Before Optimizing**: Measure before optimizing
|
||||
- **Use Modern C++**: Leverage C++23 features for performance
|
||||
- **Avoid Premature Optimization**: Focus on correctness first
|
||||
|
||||
## Documentation
|
||||
|
||||
### Code Documentation
|
||||
- **Doxygen Comments**: Use Doxygen format for public APIs
|
||||
- **Inline Comments**: Explain complex logic
|
||||
- **README Updates**: Update relevant README files
|
||||
|
||||
### API Documentation
|
||||
```cpp
|
||||
/**
|
||||
* @brief Applies an assembly patch to ROM data
|
||||
* @param patch_path Path to the assembly patch file
|
||||
* @param rom_data ROM data to patch (modified in place)
|
||||
* @param include_paths Optional include paths for assembly
|
||||
* @return Result containing success status and extracted symbols
|
||||
* @throws std::invalid_argument if patch_path is empty
|
||||
*/
|
||||
absl::StatusOr<AsarPatchResult> ApplyPatch(
|
||||
const std::string& patch_path,
|
||||
std::vector<uint8_t>& rom_data,
|
||||
const std::vector<std::string>& include_paths = {});
|
||||
```
|
||||
|
||||
## Community Guidelines
|
||||
|
||||
### Communication
|
||||
- **Be Respectful**: Treat all contributors with respect
|
||||
- **Be Constructive**: Provide helpful feedback
|
||||
- **Be Patient**: Remember that everyone is learning
|
||||
|
||||
### Getting Help
|
||||
- **GitHub Issues**: Report bugs and request features
|
||||
- **Discussions**: Ask questions and discuss ideas
|
||||
- **Discord**: [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk)
|
||||
|
||||
## Release Process
|
||||
|
||||
### Version Numbering
|
||||
- **Semantic Versioning**: MAJOR.MINOR.PATCH
|
||||
- **v0.3.0**: Current stable release
|
||||
- **Pre-release**: v0.4.0-alpha, v0.4.0-beta
|
||||
|
||||
### Release Checklist
|
||||
- [ ] All stable tests pass
|
||||
- [ ] Documentation updated
|
||||
- [ ] Changelog updated
|
||||
- [ ] Cross-platform builds verified
|
||||
- [ ] Release notes prepared
|
||||
@@ -1,12 +1,16 @@
|
||||
# Changelog
|
||||
|
||||
## 0.3.0 (01-2025)
|
||||
- **Asar 65816 Assembler Integration**: Complete cross-platform support for ROM patching with assembly code
|
||||
## 0.3.0 (January 2025)
|
||||
|
||||
### Major Features
|
||||
- **Asar 65816 Assembler Integration**: Complete cross-platform ROM patching with assembly code
|
||||
- **ZSCustomOverworld v3**: Full integration with enhanced overworld editing capabilities
|
||||
- **Advanced Message Editing**: Enhanced text editing interface with improved parsing and real-time preview
|
||||
- **GUI Docking System**: Improved docking and workspace management for better user workflow
|
||||
- **Symbol Extraction**: Extract symbol names and opcodes from assembly files
|
||||
- **Symbol Extraction**: Extract symbol names and opcodes from assembly files
|
||||
- **Modernized Build System**: Upgraded to CMake 3.16+ with target-based configuration
|
||||
|
||||
### Enhancements
|
||||
- **Enhanced CLI Tools**: Improved z3ed with modern command line interface and TUI
|
||||
- **CMakePresets**: Added development workflow presets for better productivity
|
||||
- **Cross-Platform CI/CD**: Multi-platform automated builds and testing
|
||||
@@ -14,90 +18,71 @@
|
||||
- **ROM-Dependent Testing**: Separated testing infrastructure for CI compatibility
|
||||
- **Comprehensive Documentation**: Updated guides and API documentation
|
||||
|
||||
## 0.2.2 (12-31-2024)
|
||||
### Technical Improvements
|
||||
- **Modern C++23**: Latest language features for performance and safety
|
||||
- **Memory Safety**: Enhanced memory management with RAII and smart pointers
|
||||
- **Error Handling**: Improved error handling using absl::Status throughout
|
||||
- **Cross-Platform**: Consistent experience across Windows, macOS, and Linux
|
||||
- **Performance**: Optimized rendering and data processing
|
||||
|
||||
### Bug Fixes
|
||||
- **Graphics Arena Crash**: Fixed double-free error during Arena singleton destruction
|
||||
- **SNES Tile Format**: Corrected tile unpacking algorithm based on SnesLab documentation
|
||||
- **Palette System**: Fixed color conversion functions (ImVec4 float to uint8_t conversion)
|
||||
- **CI/CD**: Fixed missing cstring include for Ubuntu compilation
|
||||
- **ROM Loading**: Fixed file path issues in tests
|
||||
|
||||
## 0.2.2 (December 2024)
|
||||
- DungeonMap editing improvements
|
||||
- ZSCustomOverworld support
|
||||
- Cross platform file handling
|
||||
|
||||
## 0.2.1 (08-20-2024)
|
||||
## 0.2.1 (August 2024)
|
||||
- Improved MessageEditor parsing
|
||||
- Added integration test window
|
||||
- Bitmap bug fixes
|
||||
|
||||
## 0.2.0 (07-20-2024)
|
||||
## 0.2.0 (July 2024)
|
||||
- iOS app support
|
||||
- Graphics Sheet Browser
|
||||
- Project Files
|
||||
|
||||
## 0.1.0 (05-11-2024)
|
||||
## 0.1.0 (May 2024)
|
||||
- Bitmap bug fixes
|
||||
- Error handling improvements
|
||||
|
||||
## 0.0.9 (04-14-2024)
|
||||
## 0.0.9 (April 2024)
|
||||
- Documentation updates
|
||||
- Entrance tile types
|
||||
- Emulator subsystem overhaul
|
||||
|
||||
## 0.0.8 (02-08-2024)
|
||||
## 0.0.8 (February 2024)
|
||||
- Hyrule Magic Compression
|
||||
- Dungeon Room Entrances
|
||||
- Png Export
|
||||
- PNG Export
|
||||
|
||||
## 0.0.7 (01-27-2024)
|
||||
## 0.0.7 (January 2024)
|
||||
- OverworldEntities
|
||||
- Entrances
|
||||
- Exits
|
||||
- Items
|
||||
- Sprites
|
||||
|
||||
## 0.0.6 (11-22-2023)
|
||||
## 0.0.6 (November 2023)
|
||||
- ScreenEditor DungeonMap
|
||||
- Tile16 Editor
|
||||
- Canvas updates
|
||||
|
||||
## 0.0.5 (11-21-2023)
|
||||
## 0.0.5 (November 2023)
|
||||
- DungeonEditor
|
||||
- DungeonObjectRenderer
|
||||
|
||||
## 0.0.4 (11-11-2023)
|
||||
## 0.0.4 (November 2023)
|
||||
- Tile16Editor
|
||||
- GfxGroupEditor
|
||||
- Add GfxGroups fns to Rom
|
||||
- Add GfxGroups functions to Rom
|
||||
- Add Tile16Editor and GfxGroupEditor to OverworldEditor
|
||||
|
||||
## 0.0.3 (10-26-2023)
|
||||
## 0.0.3 (October 2023)
|
||||
- Emulator subsystem
|
||||
- Snes Ppu and PpuRegisters
|
||||
- Direct Memory Access
|
||||
- Cpu Tests
|
||||
- Read/Write Tile16 functions
|
||||
- CompressionV3
|
||||
- Rom::LoadLinkGraphics
|
||||
|
||||
|
||||
## 0.0.2 (08-26-2023)
|
||||
- Emulator subsystem
|
||||
- Spc700
|
||||
- Emulator loop
|
||||
- Clock and MockClock
|
||||
- Ppu and Apu cycling
|
||||
- Setup Snes initialization
|
||||
- 65816 Cpu opcodes
|
||||
- JP Font support
|
||||
- SCAD Format support for CGX, COL, OBJ files
|
||||
- Overworld Save
|
||||
- Overworld Map Tile Editing
|
||||
|
||||
## 0.0.1 (07-22-2023)
|
||||
- GraphicsEditor
|
||||
- Palette management
|
||||
- lc_lz2 Compression
|
||||
- SnesTo8bppSheet
|
||||
- Bitmap Canvas
|
||||
|
||||
## 0.0.0 (06-08-2022)
|
||||
|
||||
- Started project
|
||||
- Added ImGui
|
||||
- Added SDL2
|
||||
- Added yaze_test target with gtest
|
||||
- SNES PPU and PPURegisters
|
||||
62
docs/D1-roadmap.md
Normal file
62
docs/D1-roadmap.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# Roadmap
|
||||
|
||||
## 0.4.X (Next Major Release)
|
||||
|
||||
### Core Features
|
||||
- **Overworld Sprites**: Complete sprite editing with add/remove functionality
|
||||
- **Enhanced Dungeon Editing**: Advanced room object editing and manipulation
|
||||
- **Tile16 Editing**: Enhanced editor for creating and modifying tile16 data
|
||||
- **Plugin Architecture**: Framework for community extensions and custom tools
|
||||
- **Graphics Sheets**: Complete editing, saving, and re-importing of sheets
|
||||
- **Project Refactoring**: Clean up resource loading and memory usage
|
||||
|
||||
### Technical Improvements
|
||||
- **Sprite Property Editor**: Add support for changing sprite behavior and attributes
|
||||
- **Custom Sprites**: Support creating and editing custom sprites
|
||||
- **Asar Patching**: Stabilize existing patching system for advanced modifications
|
||||
|
||||
## 0.5.X
|
||||
|
||||
### Advanced Features
|
||||
- **SCAD Format**: Polish and finalize the scad file integration
|
||||
- **Hex Editing Improvements**: Enhance user interface for direct ROM manipulation
|
||||
- **Music Editing**: Add an interface to edit and manage music data
|
||||
|
||||
## 0.6.X
|
||||
|
||||
### Platform & Integration
|
||||
- **Cross-Platform Stability**: Test and refine builds across Windows, macOS, iOS, and Linux
|
||||
- **Plugin/Integration Framework**: Provide hooks or scripting for community add-ons
|
||||
|
||||
## 0.7.X
|
||||
|
||||
### Performance & Polish
|
||||
- **Performance Optimizations**: Remove bottlenecks in rendering and data processing
|
||||
- **Documentation Overhaul**: Update manuals, guides, and in-app tooltips
|
||||
|
||||
## 0.8.X
|
||||
|
||||
### Beta Preparation
|
||||
- **Beta Release**: Code freeze on major features, focus on bug fixes and polish
|
||||
- **User Interface Refinements**: Improve UI consistency, iconography, and layout
|
||||
- **Internal Cleanup**: Remove deprecated code, finalize API calls
|
||||
|
||||
## 1.0.0
|
||||
|
||||
### Stable Release
|
||||
- **Stable Release**: Final, production-ready version
|
||||
- **Changelog**: Comprehensive summary of all changes since 0.0.0
|
||||
|
||||
## Current Focus Areas
|
||||
|
||||
### Immediate Priorities (v0.4.X)
|
||||
1. **Dungeon Editor Refactoring**: Complete component-based architecture
|
||||
2. **Sprite System**: Implement comprehensive sprite editing
|
||||
3. **Graphics Pipeline**: Enhance graphics editing capabilities
|
||||
4. **Plugin System**: Enable community extensions
|
||||
|
||||
### Long-term Vision
|
||||
- **Community-Driven**: Robust plugin system for community contributions
|
||||
- **Cross-Platform Excellence**: Seamless experience across all platforms
|
||||
- **Performance**: Optimized for large ROMs and complex modifications
|
||||
- **Accessibility**: User-friendly interface for both beginners and experts
|
||||
248
docs/E4-dungeon-editor-refactoring.md
Normal file
248
docs/E4-dungeon-editor-refactoring.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# DungeonEditor Refactoring Plan
|
||||
|
||||
## Overview
|
||||
This document outlines the comprehensive refactoring of the 1444-line `dungeon_editor.cc` file into focused, single-responsibility components.
|
||||
|
||||
## Component Structure
|
||||
|
||||
### ✅ Created Components
|
||||
|
||||
#### 1. DungeonToolset (`dungeon_toolset.h/cc`)
|
||||
**Responsibility**: Toolbar UI management
|
||||
- Background layer selection (All/BG1/BG2/BG3)
|
||||
- Placement mode selection (Object/Sprite/Item/etc.)
|
||||
- Undo/Redo buttons with callbacks
|
||||
- **Replaces**: `DrawToolset()` method (~70 lines)
|
||||
|
||||
#### 2. DungeonObjectInteraction (`dungeon_object_interaction.h/cc`)
|
||||
**Responsibility**: Object selection and placement
|
||||
- Mouse interaction handling
|
||||
- Object selection rectangle (like OverworldEditor)
|
||||
- Drag and drop operations
|
||||
- Coordinate conversion utilities
|
||||
- **Replaces**: All mouse/selection methods (~400 lines)
|
||||
|
||||
#### 3. DungeonRenderer (`dungeon_renderer.h/cc`)
|
||||
**Responsibility**: All rendering operations
|
||||
- Object rendering with caching
|
||||
- Background layer composition
|
||||
- Layout object visualization
|
||||
- Render cache management
|
||||
- **Replaces**: All rendering methods (~200 lines)
|
||||
|
||||
#### 4. DungeonRoomLoader (`dungeon_room_loader.h/cc`)
|
||||
**Responsibility**: ROM data loading
|
||||
- Room loading from ROM
|
||||
- Room size calculation
|
||||
- Entrance loading
|
||||
- Graphics loading coordination
|
||||
- **Replaces**: Room loading methods (~150 lines)
|
||||
|
||||
#### 5. DungeonUsageTracker (`dungeon_usage_tracker.h/cc`)
|
||||
**Responsibility**: Resource usage analysis
|
||||
- Blockset/spriteset/palette usage tracking
|
||||
- Usage statistics display
|
||||
- Resource optimization insights
|
||||
- **Replaces**: Usage statistics methods (~100 lines)
|
||||
|
||||
## Refactored DungeonEditor Structure
|
||||
|
||||
### Before Refactoring: 1444 lines
|
||||
```cpp
|
||||
class DungeonEditor {
|
||||
// 30+ methods handling everything
|
||||
// Mixed responsibilities
|
||||
// Large data structures
|
||||
// Complex dependencies
|
||||
};
|
||||
```
|
||||
|
||||
### After Refactoring: ~400 lines
|
||||
```cpp
|
||||
class DungeonEditor {
|
||||
// Core editor interface (unchanged)
|
||||
void Initialize() override;
|
||||
absl::Status Load() override;
|
||||
absl::Status Update() override;
|
||||
absl::Status Save() override;
|
||||
|
||||
// High-level UI orchestration
|
||||
absl::Status UpdateDungeonRoomView();
|
||||
void DrawCanvasAndPropertiesPanel();
|
||||
void DrawRoomPropertiesDebugPopup();
|
||||
|
||||
// Component coordination
|
||||
void OnRoomSelected(int room_id);
|
||||
|
||||
private:
|
||||
// Focused components
|
||||
DungeonToolset toolset_;
|
||||
DungeonObjectInteraction object_interaction_;
|
||||
DungeonRenderer renderer_;
|
||||
DungeonRoomLoader room_loader_;
|
||||
DungeonUsageTracker usage_tracker_;
|
||||
|
||||
// Existing UI components
|
||||
DungeonRoomSelector room_selector_;
|
||||
DungeonCanvasViewer canvas_viewer_;
|
||||
DungeonObjectSelector object_selector_;
|
||||
|
||||
// Core data and state
|
||||
std::array<zelda3::Room, 0x128> rooms_;
|
||||
bool is_loaded_ = false;
|
||||
// etc.
|
||||
};
|
||||
```
|
||||
|
||||
## Method Migration Map
|
||||
|
||||
### Core Editor Methods (Keep in main file)
|
||||
- ✅ `Initialize()` - Component initialization
|
||||
- ✅ `Load()` - Delegates to room_loader_
|
||||
- ✅ `Update()` - High-level update coordination
|
||||
- ✅ `Save()`, `Undo()`, `Redo()` - Editor interface
|
||||
- ✅ `UpdateDungeonRoomView()` - UI orchestration
|
||||
|
||||
### UI Methods (Keep for coordination)
|
||||
- ✅ `DrawCanvasAndPropertiesPanel()` - Tab management
|
||||
- ✅ `DrawRoomPropertiesDebugPopup()` - Debug popup
|
||||
- ✅ `DrawDungeonTabView()` - Room tab management
|
||||
- ✅ `DrawDungeonCanvas()` - Canvas coordination
|
||||
- ✅ `OnRoomSelected()` - Room selection handling
|
||||
|
||||
### Methods Moved to Components
|
||||
|
||||
#### → DungeonToolset
|
||||
- ❌ `DrawToolset()` - Toolbar rendering
|
||||
|
||||
#### → DungeonObjectInteraction
|
||||
- ❌ `HandleCanvasMouseInput()` - Mouse handling
|
||||
- ❌ `CheckForObjectSelection()` - Selection rectangle
|
||||
- ❌ `DrawObjectSelectRect()` - Selection drawing
|
||||
- ❌ `SelectObjectsInRect()` - Selection logic
|
||||
- ❌ `PlaceObjectAtPosition()` - Object placement
|
||||
- ❌ `DrawSelectBox()` - Selection visualization
|
||||
- ❌ `DrawDragPreview()` - Drag preview
|
||||
- ❌ `UpdateSelectedObjects()` - Selection updates
|
||||
- ❌ `IsObjectInSelectBox()` - Selection testing
|
||||
- ❌ Coordinate conversion helpers
|
||||
|
||||
#### → DungeonRenderer
|
||||
- ❌ `RenderObjectInCanvas()` - Object rendering
|
||||
- ❌ `DisplayObjectInfo()` - Object info overlay
|
||||
- ❌ `RenderLayoutObjects()` - Layout rendering
|
||||
- ❌ `RenderRoomBackgroundLayers()` - Background rendering
|
||||
- ❌ `RefreshGraphics()` - Graphics refresh
|
||||
- ❌ Object cache management
|
||||
|
||||
#### → DungeonRoomLoader
|
||||
- ❌ `LoadDungeonRoomSize()` - Room size calculation
|
||||
- ❌ `LoadAndRenderRoomGraphics()` - Graphics loading
|
||||
- ❌ `ReloadAllRoomGraphics()` - Bulk reload
|
||||
- ❌ Room size and address management
|
||||
|
||||
#### → DungeonUsageTracker
|
||||
- ❌ `CalculateUsageStats()` - Usage calculation
|
||||
- ❌ `DrawUsageStats()` - Usage display
|
||||
- ❌ `DrawUsageGrid()` - Usage visualization
|
||||
- ❌ `RenderSetUsage()` - Set usage rendering
|
||||
|
||||
## Component Communication
|
||||
|
||||
### Callback System
|
||||
```cpp
|
||||
// Object placement callback
|
||||
object_interaction_.SetObjectPlacedCallback([this](const auto& object) {
|
||||
renderer_.ClearObjectCache();
|
||||
});
|
||||
|
||||
// Toolset callbacks
|
||||
toolset_.SetUndoCallback([this]() { Undo(); });
|
||||
toolset_.SetPaletteToggleCallback([this]() { palette_showing_ = !palette_showing_; });
|
||||
|
||||
// Object selection callback
|
||||
object_selector_.SetObjectSelectedCallback([this](const auto& object) {
|
||||
object_interaction_.SetPreviewObject(object, true);
|
||||
toolset_.set_placement_type(DungeonToolset::kObject);
|
||||
});
|
||||
```
|
||||
|
||||
### Data Sharing
|
||||
```cpp
|
||||
// Update components with current room
|
||||
void OnRoomSelected(int room_id) {
|
||||
current_room_id_ = room_id;
|
||||
object_interaction_.SetCurrentRoom(&rooms_, room_id);
|
||||
// etc.
|
||||
}
|
||||
```
|
||||
|
||||
## Benefits of Refactoring
|
||||
|
||||
### 1. **Reduced Complexity**
|
||||
- Main file: 1444 → ~400 lines (72% reduction)
|
||||
- Single responsibility per component
|
||||
- Clear separation of concerns
|
||||
|
||||
### 2. **Improved Testability**
|
||||
- Individual components can be unit tested
|
||||
- Mocking becomes easier
|
||||
- Isolated functionality testing
|
||||
|
||||
### 3. **Better Maintainability**
|
||||
- Changes isolated to relevant components
|
||||
- Easier to locate and fix bugs
|
||||
- Cleaner code reviews
|
||||
|
||||
### 4. **Enhanced Extensibility**
|
||||
- New features added to appropriate components
|
||||
- Component interfaces allow easy replacement
|
||||
- Plugin-style architecture possible
|
||||
|
||||
### 5. **Cleaner Dependencies**
|
||||
- UI separate from data manipulation
|
||||
- Rendering separate from business logic
|
||||
- Clear component boundaries
|
||||
|
||||
## Implementation Status
|
||||
|
||||
### ✅ Completed
|
||||
- Created all component header files
|
||||
- Created component implementation stubs
|
||||
- Updated DungeonEditor header with components
|
||||
- Basic component integration
|
||||
|
||||
### 🔄 In Progress
|
||||
- Method migration from main file to components
|
||||
- Component callback setup
|
||||
- Legacy method removal
|
||||
|
||||
### ⏳ Pending
|
||||
- Full method implementation in components
|
||||
- Complete integration testing
|
||||
- Documentation updates
|
||||
- Build system updates
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
### Phase 1: Create Components ✅
|
||||
- Define component interfaces
|
||||
- Create header and implementation files
|
||||
- Set up basic structure
|
||||
|
||||
### Phase 2: Integrate Components 🔄
|
||||
- Add components to DungeonEditor
|
||||
- Set up callback systems
|
||||
- Begin method delegation
|
||||
|
||||
### Phase 3: Move Methods
|
||||
- Systematically move methods to components
|
||||
- Update method calls to use components
|
||||
- Remove old implementations
|
||||
|
||||
### Phase 4: Cleanup
|
||||
- Remove unused member variables
|
||||
- Clean up includes
|
||||
- Update documentation
|
||||
|
||||
This refactoring transforms the monolithic DungeonEditor into a well-organized, component-based architecture that's easier to maintain, test, and extend.
|
||||
32
docs/F2-overworld-expansion.md
Normal file
32
docs/F2-overworld-expansion.md
Normal file
@@ -0,0 +1,32 @@
|
||||
|
||||
Module09_21
|
||||
Module08_02_LoadAndAdvance
|
||||
Credits_LoadScene_Overworld_LoadMap
|
||||
|
||||
Overworld_LoadAndBuildScreen:
|
||||
#_02ED59:
|
||||
|
||||
Overworld_DrawQuadrantsAndOverlays:
|
||||
#_02EEC5:
|
||||
|
||||
Overworld_DecompressAndDrawAllQuadrants:
|
||||
#_02F54A:
|
||||
|
||||
OverworldLoad_Map32HPointers/LPointers:
|
||||
#_02F94D
|
||||
OverworldMap32_Screens
|
||||
Banks $0B and $0C
|
||||
|
||||
|
||||
public void fill(int x, int y, byte indextoreplace)
|
||||
{
|
||||
if (indextoreplace == (byte)colorIndex) { return; }
|
||||
if (sheetPtr[x, y] == indextoreplace)
|
||||
{
|
||||
sheetPtr[x, y] = (byte)colorIndex;
|
||||
fill(x - 1, y, indextoreplace);
|
||||
fill(x + 1, y, indextoreplace);
|
||||
fill(x, y - 1, indextoreplace);
|
||||
fill(x, y + 1, indextoreplace);
|
||||
}
|
||||
}
|
||||
@@ -1,404 +0,0 @@
|
||||
# Asar 65816 Assembler Integration Guide
|
||||
|
||||
Yaze v0.3.0 includes complete integration with the Asar 65816 assembler, enabling cross-platform ROM patching, symbol extraction, and assembly validation for SNES development.
|
||||
|
||||
## Overview
|
||||
|
||||
The Asar integration provides:
|
||||
- **ROM Patching**: Apply 65816 assembly patches directly to SNES ROMs
|
||||
- **Symbol Extraction**: Extract labels, addresses, and opcodes from assembly files
|
||||
- **Assembly Validation**: Comprehensive syntax checking and error reporting
|
||||
- **Cross-Platform**: Full support for Windows, macOS, and Linux
|
||||
- **Modern APIs**: Both CLI tools and C++ programming interface
|
||||
|
||||
## Quick Examples
|
||||
|
||||
### Command Line Usage
|
||||
|
||||
```bash
|
||||
# Apply assembly patch to ROM
|
||||
z3ed asar my_patch.asm --rom=zelda3.sfc
|
||||
✅ Asar patch applied successfully!
|
||||
📁 Output: zelda3_patched.sfc
|
||||
🏷️ Extracted 6 symbols:
|
||||
main_routine @ $008000
|
||||
data_table @ $008020
|
||||
|
||||
# Extract symbols without patching
|
||||
z3ed extract my_patch.asm
|
||||
|
||||
# Validate assembly syntax
|
||||
z3ed validate my_patch.asm
|
||||
✅ Assembly file is valid
|
||||
|
||||
# Launch interactive TUI
|
||||
z3ed --tui
|
||||
```
|
||||
|
||||
### C++ API Usage
|
||||
|
||||
```cpp
|
||||
#include "app/core/asar_wrapper.h"
|
||||
|
||||
// Initialize Asar
|
||||
yaze::app::core::AsarWrapper wrapper;
|
||||
wrapper.Initialize();
|
||||
|
||||
// Apply patch to ROM
|
||||
std::vector<uint8_t> rom_data = LoadRom("zelda3.sfc");
|
||||
auto result = wrapper.ApplyPatch("patch.asm", rom_data);
|
||||
|
||||
if (result.ok() && result->success) {
|
||||
std::cout << "Found " << result->symbols.size() << " symbols:" << std::endl;
|
||||
for (const auto& symbol : result->symbols) {
|
||||
std::cout << " " << symbol.name << " @ $"
|
||||
<< std::hex << symbol.address << std::endl;
|
||||
}
|
||||
}
|
||||
|
||||
// Extract symbols independently
|
||||
auto symbols = wrapper.ExtractSymbols("source.asm");
|
||||
auto main_symbol = wrapper.FindSymbol("main_routine");
|
||||
```
|
||||
|
||||
## Assembly Patch Examples
|
||||
|
||||
### Basic Hook
|
||||
|
||||
```assembly
|
||||
; Simple code hook
|
||||
org $008000
|
||||
custom_hook:
|
||||
sei ; Disable interrupts
|
||||
rep #$30 ; 16-bit A and X/Y
|
||||
|
||||
; Your custom code
|
||||
lda #$1234
|
||||
sta $7E0000
|
||||
|
||||
rts
|
||||
|
||||
; Data section
|
||||
custom_data:
|
||||
db "YAZE", $00
|
||||
dw $1234, $5678
|
||||
```
|
||||
|
||||
### Advanced Features
|
||||
|
||||
```assembly
|
||||
; Constants and macros
|
||||
!player_health = $7EF36C
|
||||
!custom_ram = $7E2000
|
||||
|
||||
macro save_context()
|
||||
pha : phx : phy
|
||||
endmacro
|
||||
|
||||
macro restore_context()
|
||||
ply : plx : pla
|
||||
endmacro
|
||||
|
||||
; Main code
|
||||
org $008000
|
||||
advanced_hook:
|
||||
%save_context()
|
||||
|
||||
; Modify gameplay
|
||||
sep #$20
|
||||
lda #$A0 ; Full health
|
||||
sta !player_health
|
||||
|
||||
%restore_context()
|
||||
rtl
|
||||
```
|
||||
|
||||
## Testing Infrastructure
|
||||
|
||||
### ROM-Dependent Tests
|
||||
|
||||
Yaze includes comprehensive testing that handles ROM files properly:
|
||||
|
||||
```cpp
|
||||
// ROM tests are automatically skipped in CI
|
||||
YAZE_ROM_TEST(AsarIntegration, RealRomPatching) {
|
||||
auto rom_data = TestRomManager::LoadTestRom();
|
||||
AsarWrapper wrapper;
|
||||
wrapper.Initialize();
|
||||
|
||||
auto result = wrapper.ApplyPatch("test.asm", rom_data);
|
||||
EXPECT_TRUE(result.ok());
|
||||
}
|
||||
```
|
||||
|
||||
### CI/CD Compatibility
|
||||
|
||||
- ROM-dependent tests are labeled with `ROM_DEPENDENT`
|
||||
- CI automatically excludes these tests: `--label-exclude ROM_DEPENDENT`
|
||||
- Development builds can enable ROM testing with `YAZE_ENABLE_ROM_TESTS=ON`
|
||||
|
||||
## Cross-Platform Support
|
||||
|
||||
### Build Configuration
|
||||
|
||||
The Asar integration works across all supported platforms:
|
||||
|
||||
```cmake
|
||||
# Modern CMake target
|
||||
target_link_libraries(my_target PRIVATE yaze::asar)
|
||||
|
||||
# Cross-platform definitions automatically handled
|
||||
# Windows: _CRT_SECURE_NO_WARNINGS, strcasecmp=_stricmp
|
||||
# Linux: linux, stricmp=strcasecmp
|
||||
# macOS: MACOS, stricmp=strcasecmp
|
||||
```
|
||||
|
||||
### Platform-Specific Notes
|
||||
|
||||
- **Windows**: Uses static linking with proper MSVC runtime
|
||||
- **macOS**: Universal binaries support both Intel and Apple Silicon
|
||||
- **Linux**: Compatible with both GCC and Clang compilers
|
||||
|
||||
## API Reference
|
||||
|
||||
### AsarWrapper Class
|
||||
|
||||
```cpp
|
||||
namespace yaze::app::core {
|
||||
|
||||
class AsarWrapper {
|
||||
public:
|
||||
// Initialization
|
||||
absl::Status Initialize();
|
||||
void Shutdown();
|
||||
bool IsInitialized() const;
|
||||
|
||||
// Core functionality
|
||||
absl::StatusOr<AsarPatchResult> ApplyPatch(
|
||||
const std::string& patch_path,
|
||||
std::vector<uint8_t>& rom_data,
|
||||
const std::vector<std::string>& include_paths = {});
|
||||
|
||||
absl::StatusOr<std::vector<AsarSymbol>> ExtractSymbols(
|
||||
const std::string& asm_path,
|
||||
const std::vector<std::string>& include_paths = {});
|
||||
|
||||
// Symbol management
|
||||
std::optional<AsarSymbol> FindSymbol(const std::string& name);
|
||||
std::vector<AsarSymbol> GetSymbolsAtAddress(uint32_t address);
|
||||
std::map<std::string, AsarSymbol> GetSymbolTable();
|
||||
|
||||
// Utility functions
|
||||
absl::Status ValidateAssembly(const std::string& asm_path);
|
||||
std::string GetVersion();
|
||||
void Reset();
|
||||
};
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
### Data Structures
|
||||
|
||||
```cpp
|
||||
struct AsarSymbol {
|
||||
std::string name; // Symbol name
|
||||
uint32_t address; // Memory address
|
||||
std::string opcode; // Associated opcode
|
||||
std::string file; // Source file
|
||||
int line; // Line number
|
||||
std::string comment; // Optional comment
|
||||
};
|
||||
|
||||
struct AsarPatchResult {
|
||||
bool success; // Whether patch succeeded
|
||||
std::vector<std::string> errors; // Error messages
|
||||
std::vector<std::string> warnings; // Warning messages
|
||||
std::vector<AsarSymbol> symbols; // Extracted symbols
|
||||
uint32_t rom_size; // Final ROM size
|
||||
uint32_t crc32; // CRC32 checksum
|
||||
};
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors and Solutions
|
||||
|
||||
| Error | Cause | Solution |
|
||||
|-------|-------|----------|
|
||||
| `Unknown command` | Invalid opcode | Check 65816 instruction reference |
|
||||
| `Label not found` | Undefined label | Define the label or check spelling |
|
||||
| `Invalid hex value` | Bad hex format | Use `$1234` format, not `$GOOD` |
|
||||
| `Buffer too small` | ROM needs expansion | Check if ROM needs to be larger |
|
||||
|
||||
### Error Handling Pattern
|
||||
|
||||
```cpp
|
||||
auto result = wrapper.ApplyPatch("patch.asm", rom_data);
|
||||
if (!result.ok()) {
|
||||
std::cerr << "Patch failed: " << result.status().message() << std::endl;
|
||||
return;
|
||||
}
|
||||
|
||||
if (!result->success) {
|
||||
std::cerr << "Assembly errors:" << std::endl;
|
||||
for (const auto& error : result->errors) {
|
||||
std::cerr << " " << error << std::endl;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### CMake Presets
|
||||
|
||||
```bash
|
||||
# Development build with ROM testing
|
||||
cmake --preset dev
|
||||
cmake --build --preset dev
|
||||
ctest --preset dev
|
||||
|
||||
# CI-compatible build (no ROM tests)
|
||||
cmake --preset ci
|
||||
cmake --build --preset ci
|
||||
ctest --preset ci
|
||||
|
||||
# Release build with packaging
|
||||
cmake --preset macos-release
|
||||
cmake --build --preset macos-release
|
||||
cmake --build --preset macos-release --target package
|
||||
```
|
||||
|
||||
### Testing Workflow
|
||||
|
||||
1. **Write assembly patch**
|
||||
2. **Validate syntax**: `z3ed validate patch.asm`
|
||||
3. **Extract symbols**: `z3ed extract patch.asm`
|
||||
4. **Apply to test ROM**: `z3ed asar patch.asm --rom=test.sfc`
|
||||
5. **Test in emulator**
|
||||
|
||||
## Integration with Yaze Editor
|
||||
|
||||
The Asar integration is built into the main yaze editor:
|
||||
|
||||
- **Assembly Editor**: Real-time syntax validation
|
||||
- **Project System**: Save/load assembly patches with projects
|
||||
- **Symbol Browser**: Navigate symbols with address lookup
|
||||
- **Patch Management**: Apply and manage multiple patches
|
||||
|
||||
## Performance and Memory
|
||||
|
||||
- **Large ROM Support**: Handles ROMs up to 16MB
|
||||
- **Efficient Symbol Storage**: Hash-based symbol lookup
|
||||
- **Memory Safety**: RAII and smart pointer usage
|
||||
- **Cross-Platform Optimization**: Platform-specific optimizations
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Planned improvements for future versions:
|
||||
|
||||
- **Real-time Assembly**: Live compilation and testing
|
||||
- **Visual Debugging**: Assembly debugging tools
|
||||
- **Patch Management**: GUI for managing multiple patches
|
||||
- **Symbol Navigation**: Enhanced symbol browser with search
|
||||
|
||||
## Assembly Patch Templates
|
||||
|
||||
### Basic Assembly Structure
|
||||
|
||||
```assembly
|
||||
; Header comment explaining the patch
|
||||
; Author: Your Name
|
||||
; Purpose: Brief description
|
||||
|
||||
; Constants section
|
||||
!player_health = $7EF36C
|
||||
!custom_ram = $7E2000
|
||||
|
||||
; Code section
|
||||
org $008000
|
||||
main_hook:
|
||||
; Save context
|
||||
pha : phx : phy
|
||||
|
||||
; Your custom code here
|
||||
sep #$20 ; 8-bit A
|
||||
lda #$A0 ; Full health
|
||||
sta !player_health
|
||||
|
||||
; Restore context
|
||||
ply : plx : pla
|
||||
rts
|
||||
|
||||
; Data section
|
||||
data_table:
|
||||
dw $1234, $5678, $9ABC
|
||||
```
|
||||
|
||||
### Advanced Features
|
||||
|
||||
```assembly
|
||||
; Macro definitions
|
||||
macro save_registers()
|
||||
pha : phx : phy
|
||||
endmacro
|
||||
|
||||
macro restore_registers()
|
||||
ply : plx : pla
|
||||
endmacro
|
||||
|
||||
; Conditional assembly
|
||||
if !version == 3
|
||||
; ZSCustomOverworld v3 specific code
|
||||
org $C08000
|
||||
else
|
||||
; Vanilla ROM code
|
||||
org $008000
|
||||
endif
|
||||
|
||||
advanced_routine:
|
||||
%save_registers()
|
||||
|
||||
; Complex logic here
|
||||
|
||||
%restore_registers()
|
||||
rtl
|
||||
```
|
||||
|
||||
## Testing Your Patches
|
||||
|
||||
### Development Workflow
|
||||
|
||||
1. **Write Assembly**: Create your `.asm` patch file
|
||||
2. **Validate**: `z3ed validate patch.asm`
|
||||
3. **Extract Symbols**: `z3ed extract patch.asm`
|
||||
4. **Apply Patch**: `z3ed asar patch.asm --rom=test.sfc`
|
||||
5. **Test in Emulator**: Verify functionality
|
||||
|
||||
### Best Practices
|
||||
|
||||
- Always backup ROMs before patching
|
||||
- Use test ROMs for development
|
||||
- Validate assembly before applying
|
||||
- Start with simple patches and build complexity
|
||||
- Document your patches with clear comments
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| "Unknown command" | Check 65816 instruction reference |
|
||||
| "Label not found" | Define the label or check spelling |
|
||||
| "Invalid hex value" | Use `$1234` format, not `$GOOD` |
|
||||
| "Buffer too small" | ROM may need expansion |
|
||||
|
||||
### Getting Help
|
||||
|
||||
- **CLI Help**: `z3ed help asar`
|
||||
- **Community**: [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk)
|
||||
- **Documentation**: [Complete guide](docs/index.md)
|
||||
|
||||
---
|
||||
|
||||
For complete API reference and advanced usage, see the [documentation index](index.md).
|
||||
@@ -1,94 +0,0 @@
|
||||
# Build Instructions
|
||||
|
||||
For VSCode users, use the following CMake extensions
|
||||
|
||||
- https://marketplace.visualstudio.com/items?itemName=twxs.cmake
|
||||
- https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
|
||||
|
||||
Yaze uses CMake to build the project. If you are unexperienced with CMake, please refer to the [CMake documentation](https://cmake.org/documentation/).
|
||||
|
||||
The gui editor is built using SDL2 and ImGui. For reference on how to use ImGui, see the [Getting Started](https://github.com/ocornut/imgui/wiki/Getting-Started) guide. For SDL2, see the [SDL2 documentation](https://wiki.libsdl.org/).
|
||||
|
||||
For those who want to reduce compile times, consider installing the dependencies on your system.
|
||||
|
||||
## Windows
|
||||
|
||||
### vcpkg
|
||||
|
||||
For Visual Studio users, follow the [Install and use packages with CMake](https://learn.microsoft.com/en-us/vcpkg/get_started/get-started) tutorial from Microsoft.
|
||||
|
||||
Define the following dependencies in `vcpkg.json`
|
||||
|
||||
```
|
||||
{
|
||||
"dependencies": [
|
||||
"abseil",
|
||||
"sdl2",
|
||||
"libpng"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Target the architecture in `CMakePresets.json`
|
||||
|
||||
```
|
||||
{
|
||||
"name": "vcpkg",
|
||||
"generator": "Ninja",
|
||||
"binaryDir": "${sourceDir}/build",
|
||||
"architecture": {
|
||||
"value": "arm64/x64",
|
||||
"strategy": "external"
|
||||
},
|
||||
"cacheVariables": {
|
||||
"CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
|
||||
"CMAKE_SYSTEM_PROCESSOR": "arm64/x64"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### msys2
|
||||
|
||||
[msys2](https://www.msys2.org/) is an alternative you may use for a Unix-like environment on Windows. Beware that this is for more experienced developers who know how to manage their system PATH.
|
||||
|
||||
Add to environment variables `C:\msys64\mingw64\bin`
|
||||
|
||||
Install the following packages using `pacman -S <package-name>`
|
||||
|
||||
- `mingw-w64-x86_64-gcc`
|
||||
- `mingw-w64-x86_64-gcc-libs`
|
||||
- `mingw-w64-x86_64-cmake`
|
||||
- `mingw-w64-x86_64-sdl2`
|
||||
- `mingw-w64-x86_64-libpng`
|
||||
- `mingw-w64-x86_64-abseil-cpp`
|
||||
|
||||
For `yaze_py` you will need Boost Python
|
||||
|
||||
- `mingw-w64-x86_64-boost`
|
||||
|
||||
# macOS
|
||||
|
||||
Prefer to use clang provided with XCode command line tools over gcc.
|
||||
|
||||
Install the following packages using `brew install <package-name>`
|
||||
|
||||
- `cmake`
|
||||
- `sdl2`
|
||||
- `zlib`
|
||||
- `libpng`
|
||||
- `abseil`
|
||||
- `boost-python3`
|
||||
|
||||
# iOS
|
||||
|
||||
Xcode is required to build for iOS. Currently testing with iOS 18 on iPad Pro.
|
||||
|
||||
The xcodeproject file is located in the `ios` directory.
|
||||
|
||||
You will need to link `SDL2.framework` and `libpng.a` to the project.
|
||||
|
||||
# GNU/Linux
|
||||
|
||||
You can use your package manager to install the same dependencies as macOS.
|
||||
|
||||
I trust you know how to use your package manager.
|
||||
@@ -1,190 +0,0 @@
|
||||
# CI/CD Testing Strategy - Efficient Workflows
|
||||
|
||||
## Overview
|
||||
|
||||
Yaze v0.3.0 implements a sophisticated testing strategy designed for efficient CI/CD pipelines while maintaining comprehensive quality assurance.
|
||||
|
||||
## Test Categories & Execution Strategy
|
||||
|
||||
### 🟢 STABLE Tests (CI Required)
|
||||
**These tests MUST pass for releases**
|
||||
|
||||
- **AsarWrapperTest** (11/12 tests passing): Core Asar functionality
|
||||
- **SnesTileTest**: SNES graphics format handling
|
||||
- **CompressionTest**: Data compression utilities
|
||||
- **SnesPaletteTest**: SNES palette operations
|
||||
- **Basic ROM operations**: Core file handling
|
||||
|
||||
**Execution Time**: < 30 seconds total
|
||||
**CI Strategy**: Run on every commit, block merge if failing
|
||||
|
||||
### 🟡 EXPERIMENTAL Tests (CI Informational)
|
||||
**These tests can fail without blocking releases**
|
||||
|
||||
- **CpuTest** (400+ tests): 65816 CPU emulation - complex timing issues
|
||||
- **Spc700Test**: SPC700 audio processor - emulation accuracy
|
||||
- **Complex Integration Tests**: Multi-component scenarios
|
||||
- **MessageTest**: Text parsing - may have encoding issues
|
||||
- **DungeonIntegrationTest**: Complex editor workflows
|
||||
|
||||
**Execution Time**: 5-10 minutes
|
||||
**CI Strategy**: Run separately with `continue-on-error: true`
|
||||
|
||||
### 🔴 ROM_DEPENDENT Tests (Development Only)
|
||||
**These tests require actual ROM files**
|
||||
|
||||
- **AsarRomIntegrationTest**: Real ROM patching tests
|
||||
- **ROM-based validation**: Tests with actual game data
|
||||
|
||||
**Execution**: Only in development environment
|
||||
**CI Strategy**: Automatically skipped in CI (`--label-exclude ROM_DEPENDENT`)
|
||||
|
||||
## Dependency Management
|
||||
|
||||
### NFD (Native File Dialog) - Optional
|
||||
```cmake
|
||||
# Conditional inclusion for CI efficiency
|
||||
option(YAZE_MINIMAL_BUILD "Minimal build for CI" OFF)
|
||||
|
||||
if(NOT YAZE_MINIMAL_BUILD)
|
||||
add_subdirectory(lib/nativefiledialog-extended) # Requires GTK on Linux
|
||||
else()
|
||||
# Skip NFD to avoid GTK dependency in CI
|
||||
endif()
|
||||
```
|
||||
|
||||
### Linux Dependencies for Full Build
|
||||
```bash
|
||||
# Required for NFD on Linux
|
||||
sudo apt-get install libgtk-3-dev libdbus-1-dev
|
||||
|
||||
# Core dependencies (always required)
|
||||
sudo apt-get install libglew-dev libxext-dev libwavpack-dev libpng-dev
|
||||
```
|
||||
|
||||
## CI Configuration Examples
|
||||
|
||||
### Fast CI Pipeline (< 5 minutes)
|
||||
```yaml
|
||||
- name: Configure (Minimal)
|
||||
run: cmake -B build -DYAZE_MINIMAL_BUILD=ON -DYAZE_ENABLE_EXPERIMENTAL_TESTS=OFF
|
||||
|
||||
- name: Build
|
||||
run: cmake --build build --parallel
|
||||
|
||||
- name: Test (Stable Only)
|
||||
run: ctest --test-dir build --label-regex "STABLE" --parallel
|
||||
```
|
||||
|
||||
### Development Pipeline (Complete)
|
||||
```yaml
|
||||
- name: Configure (Full)
|
||||
run: cmake -B build -DYAZE_ENABLE_ROM_TESTS=ON -DYAZE_ENABLE_EXPERIMENTAL_TESTS=ON
|
||||
|
||||
- name: Build
|
||||
run: cmake --build build --parallel
|
||||
|
||||
- name: Test (All)
|
||||
run: ctest --test-dir build --output-on-failure
|
||||
```
|
||||
|
||||
## Local Development Workflows
|
||||
|
||||
### Quick Development Testing
|
||||
```bash
|
||||
# Test only Asar functionality (< 30 seconds)
|
||||
ctest --test-dir build -R "*AsarWrapper*" --parallel
|
||||
|
||||
# Test stable features only
|
||||
ctest --test-dir build --label-regex "STABLE" --parallel
|
||||
|
||||
# Full development testing
|
||||
cmake --preset dev
|
||||
cmake --build --preset dev
|
||||
ctest --preset dev
|
||||
```
|
||||
|
||||
### Release Validation
|
||||
```bash
|
||||
# Release candidate testing (stable tests only)
|
||||
cmake --preset release
|
||||
cmake --build --preset release
|
||||
ctest --test-dir build --label-regex "STABLE" --stop-on-failure
|
||||
|
||||
# Performance validation
|
||||
ctest --test-dir build --label-regex "STABLE" --repeat until-pass:3
|
||||
```
|
||||
|
||||
## Test Maintenance Strategy
|
||||
|
||||
### Weekly Review Process
|
||||
1. **Check experimental test results** - identify tests ready for promotion
|
||||
2. **Update test categorization** - move stable experimental tests to STABLE
|
||||
3. **Performance monitoring** - track test execution times
|
||||
4. **Failure analysis** - investigate patterns in experimental test failures
|
||||
|
||||
### Promotion Criteria (Experimental → Stable)
|
||||
- **Consistent passing** for 2+ weeks
|
||||
- **Fast execution** (< 10 seconds per test)
|
||||
- **No external dependencies** (ROM files, GUI, complex setup)
|
||||
- **Deterministic results** across platforms
|
||||
|
||||
### Test Categories by Stability
|
||||
|
||||
#### Currently Stable (22/24 tests passing)
|
||||
- AsarWrapperTest.InitializationAndShutdown ✅
|
||||
- AsarWrapperTest.ValidPatchApplication ✅
|
||||
- AsarWrapperTest.SymbolExtraction ✅
|
||||
- AsarWrapperTest.PatchFromString ✅
|
||||
- AsarWrapperTest.ResetFunctionality ✅
|
||||
|
||||
#### Needs Attention (2/24 tests failing)
|
||||
- AsarWrapperTest.AssemblyValidation ⚠️ (Error message format mismatch)
|
||||
|
||||
#### Experimental (Many failing but expected)
|
||||
- CpuTest.* (400+ tests) - Complex 65816 emulation
|
||||
- MessageTest.* - Text parsing edge cases
|
||||
- Complex integration tests - Multi-component scenarios
|
||||
|
||||
## Efficiency Metrics
|
||||
|
||||
### Target CI Times
|
||||
- **Stable Test Suite**: < 30 seconds
|
||||
- **Full Build**: < 5 minutes
|
||||
- **Total CI Pipeline**: < 10 minutes per platform
|
||||
|
||||
### Resource Optimization
|
||||
- **Parallel Testing**: Use all available CPU cores
|
||||
- **Selective Dependencies**: Skip optional dependencies in CI
|
||||
- **Test Categorization**: Run only relevant tests for changes
|
||||
- **Artifact Caching**: Cache build dependencies between runs
|
||||
|
||||
## Error Handling Strategy
|
||||
|
||||
### Build Failures
|
||||
- **NFD/GTK Issues**: Use YAZE_MINIMAL_BUILD=ON to skip
|
||||
- **Dependency Problems**: Clear dependency installation in CI
|
||||
- **Platform-Specific**: Use matrix builds with proper toolchains
|
||||
|
||||
### Test Failures
|
||||
- **Stable Tests**: Must be fixed before merge
|
||||
- **Experimental Tests**: Log for review, don't block pipeline
|
||||
- **ROM Tests**: Skip gracefully when ROM unavailable
|
||||
- **GUI Tests**: May need headless display configuration
|
||||
|
||||
## Monitoring & Metrics
|
||||
|
||||
### Success Metrics
|
||||
- **Stable Test Pass Rate**: 95%+ required
|
||||
- **CI Pipeline Duration**: < 10 minutes target
|
||||
- **Build Success Rate**: 98%+ across all platforms
|
||||
- **Release Cadence**: Monthly releases with high confidence
|
||||
|
||||
### Quality Gates
|
||||
1. All stable tests pass
|
||||
2. Build succeeds on all platforms
|
||||
3. No critical security issues
|
||||
4. Performance regression check
|
||||
5. Documentation updated
|
||||
|
||||
This strategy ensures efficient CI/CD while maintaining high quality standards for the yaze project.
|
||||
@@ -1,95 +0,0 @@
|
||||
# Contributing
|
||||
|
||||
This project is looking for contributors to help improve the software and enhance the user experience. If you are interested in contributing, please read the following guidelines and suggestions for areas where you can make a difference.
|
||||
|
||||
Discussion on the editor and its development can be found on the [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk) server.
|
||||
|
||||
## Style Guide
|
||||
|
||||
When contributing to the project, please follow these guidelines to ensure consistency and readability across the codebase:
|
||||
|
||||
C++ Code should follow the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) with the following exceptions:
|
||||
|
||||
- Boost libraries are allowed, but require cross platform compatibility.
|
||||
|
||||
Objective-C Code should follow the [Google Objective-C Style Guide](https://google.github.io/styleguide/objcguide.html).
|
||||
|
||||
Python Code should follow the [PEP 8 Style Guide](https://pep8.org/).
|
||||
|
||||
Assembly code should follow the [65816 Style Guide](docs/asm-style-guide.md).
|
||||
|
||||
## Testing Facilities
|
||||
|
||||
The project includes the `yaze_test` target which defines unit tests and an integration test window. The unit tests make use of GoogleTest and GoogleMock. The integration test window is an ImGui window build out of the yaze::core::Controller and yaze::test::integration::TestEditor. The integration test window can be accessed by passing the argument `integration` to the target.
|
||||
|
||||
New modules should define unit tests in the `src/test` directory and integration tests in the `src/test/integration` directory. The `yaze_test` target will automatically include all tests in these directories.
|
||||
|
||||
## Key Areas of Contribution
|
||||
|
||||
### 1. Sprite Builder System
|
||||
|
||||
The sprite builder system in yaze is based on the [ZSpriteMaker](https://github.com/Zarby89/ZSpriteMaker/) project and allows users to create custom sprites for use in ROM hacks. The goal is to support ZSM files and provide an intuitive interface for editing sprites without the need for writing assembly code. Contributions to the sprite builder system might include:
|
||||
|
||||
- Implementing new features for sprite editing, such as palette management, animation preview, or tileset manipulation.
|
||||
- Extending the sprite builder interface by writing assembly code for sprite behavior.
|
||||
|
||||
### 2. Emulator Subsystem
|
||||
|
||||
yaze includes an emulator subsystem that allows developers to test their modifications directly within the editor. The emulator can currently run certain test ROMs but lacks the ability to play any complex games with audio because of timing issues with the APU and Spc700. Contributions to the emulator subsystem might include:
|
||||
|
||||
- Improving the accuracy and performance of the emulator to support more games and features.
|
||||
- Implementing new debugging tools, such as memory viewers, breakpoints, or trace logs.
|
||||
- Extending the emulator to support additional features, such as save states, cheat codes, or multiplayer modes.
|
||||
|
||||
## Building the Project
|
||||
|
||||
For detailed instructions on building YAZE, including its dependencies and supported platforms, refer to [build-instructions.md](docs/build-instructions.md).
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. Clone the Repository:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/yaze.git
|
||||
cd yaze
|
||||
```
|
||||
|
||||
2. Initialize the Submodules:
|
||||
|
||||
```bash
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
3. Build the Project:
|
||||
|
||||
Follow the instructions in the [build-instructions.md](docs/build-instructions.md). file to configure and build the project on your target platform.
|
||||
|
||||
4. Run the Application:
|
||||
|
||||
After building, you can run the application on your chosen platform and start exploring the existing features.
|
||||
|
||||
## Contributing your Changes
|
||||
|
||||
1. Fork the Repository:
|
||||
|
||||
Create a fork of the project on GitHub and clone your fork to your local machine.
|
||||
|
||||
2. Create a Branch:
|
||||
|
||||
Create a new branch for your feature or bugfix.
|
||||
|
||||
```bash
|
||||
git checkout -b feature/my-new-feature
|
||||
```
|
||||
|
||||
3. Implement Your Changes:
|
||||
|
||||
Follow the guidelines above to implement new features, extensions, or improvements.
|
||||
|
||||
4. Test Your Changes:
|
||||
|
||||
Ensure your changes don’t introduce new bugs or regressions. Write unit tests where applicable.
|
||||
|
||||
5. Submit a Pull Request:
|
||||
|
||||
Push your changes to your fork and submit a pull request to the main repository. Provide a clear description of your changes and why they are beneficial.
|
||||
@@ -1,61 +0,0 @@
|
||||
# Getting Started
|
||||
|
||||
This software allows you to modify "The Legend of Zelda: A Link to the Past" (US or JP) ROMs.
|
||||
|
||||
This editor is built to be compatible with ZScream projects and is designed to be cross platform.
|
||||
|
||||
Please note that this project is currently a work in progress, and some features may not be fully implemented or may be subject to change.
|
||||
|
||||
## General Tips
|
||||
|
||||
- Experiment flags determine whether certain features are enabled or not. To change your flags, go to `File` > `Options` > `Experiment Flags` or in the Settings tab.
|
||||
- Backup files are enabled by default. Each save will produce a timestamped copy of your ROM before you last saved. You can disable this feature in the settings.
|
||||
|
||||
## Extending Functionality
|
||||
|
||||
In addition to the built-in features, this software provides a pure C library interface and a Python module that can be used for building extensions and custom sprites without assembly. In the editor these can be loaded under the `Extensions` menu.
|
||||
|
||||
This feature is still in development and is not yet fully documented.
|
||||
|
||||
## Supported Features
|
||||
|
||||
| Feature | Status | Details |
|
||||
|-------------------|-------------|------------------------------------------------|
|
||||
| Overworld Maps | Done | Edit and save tile32 data. |
|
||||
| OW Map Properties | Done | Edit and save map properties. |
|
||||
| OW Entrances | Done | Edit and save entrance data. |
|
||||
| OW Exits | Done | Edit and save exit data. |
|
||||
| OW Sprites | In Progress | Edit sprite positions, add and remove sprites. |
|
||||
| Tile16 Editing | Todo | Edit and save tile16 data. |
|
||||
| Dungeon | In Progress | View dungeon room metadata and edit room data. |
|
||||
| Palette | In Progress | Edit and save palettes, palette groups. |
|
||||
| Graphics Sheets | In Progress | Edit and save graphics sheets. |
|
||||
| Graphics Groups | Done | Edit and save graphics groups. |
|
||||
| Sprite | Todo | View-only sprite data. |
|
||||
| Custom Sprites | Todo | Edit and create custom sprite data. |
|
||||
| Music | Todo | Edit music data. |
|
||||
| Dungeon Maps | Todo | Edit dungeon maps. |
|
||||
| Scad Format | Done-ish | Open and view scad files (SCR, CGX, COL) |
|
||||
| Hex Editing | Done | View and edit ROM data in hex. |
|
||||
| Asar Patching | Complete | Apply Asar 65816 assembly patches to ROM. |
|
||||
|
||||
## Command Line Interface
|
||||
|
||||
Included with the editor is a command line interface (CLI) that allows you to perform various operations on your ROMs from the command line. This aims to reduce the need for multiple tools in zelda3 hacking like Zcompress, LunarExpand, LunarAddress, Asar, and others.
|
||||
|
||||
| Command | Arg | Params | Status |
|
||||
|--------------------|-------|--------------------------------------|-------------|
|
||||
| Apply Asar Patch | asar | patch.asm [--rom=file] | Complete |
|
||||
| Extract Symbols | extract | patch.asm | Complete |
|
||||
| Validate Assembly | validate | patch.asm | Complete |
|
||||
| Apply BPS Patch | patch | patch.bps [--rom=file] | Complete |
|
||||
| Create BPS Patch | create | src_file modified_file | In progress |
|
||||
| Asar Patch (legacy) | -asar | asm_file rom_file | Complete |
|
||||
| Open ROM | -o | rom_file | Complete |
|
||||
| Backup ROM | -b | rom_file [new_file] | In progress |
|
||||
| Expand ROM | -x | rom_file file_size | Not started |
|
||||
| Transfer Tile16 | -t | src_rom dest_rom tile32_id_list(csv) | Complete |
|
||||
| Export Graphics | -e | rom_file bin_file | In progress |
|
||||
| Import Graphics | -i | bin_file rom_file | Not started |
|
||||
| SNES to PC Address | -s | address | Complete |
|
||||
| PC to SNES Address | -p | address | Complete |
|
||||
@@ -1,46 +1,39 @@
|
||||
# Yaze Documentation
|
||||
# YAZE Documentation
|
||||
|
||||
Welcome to the Yaze documentation. This cross-platform Zelda 3 ROM editor is built with modern C++23, SDL2, ImGui, and integrated Asar 65816 assembler support.
|
||||
Cross-platform Zelda 3 ROM editor built with modern C++23, SDL2, ImGui, and integrated Asar 65816 assembler support.
|
||||
|
||||
## Quick Start
|
||||
|
||||
- [Getting Started](getting-started.md) - Basic setup and usage
|
||||
- [Build Instructions](build-instructions.md) - How to build yaze from source
|
||||
- [Contributing](contributing.md) - How to contribute to the project
|
||||
- [Getting Started](01-getting-started.md) - Basic setup and usage
|
||||
- [Build Instructions](02-build-instructions.md) - How to build from source
|
||||
- [Asar Integration](03-asar-integration.md) - Complete 65816 assembler guide
|
||||
- [API Reference](04-api-reference.md) - C/C++ API documentation
|
||||
|
||||
## New in v0.3.0
|
||||
## Development
|
||||
|
||||
- [Asar Integration Guide](asar-integration.md) - Complete 65816 assembler integration
|
||||
- [Roadmap](roadmap.md) - Updated development plans and release timeline
|
||||
- [Changelog](changelog.md) - Complete version history and changes
|
||||
- [Testing Guide](A1-testing-guide.md) - Comprehensive testing framework
|
||||
- [Contributing](B1-contributing.md) - Development guidelines and standards
|
||||
- [Changelog](C1-changelog.md) - Version history and changes
|
||||
- [Roadmap](D1-roadmap.md) - Development plans and timeline
|
||||
|
||||
## Core Documentation
|
||||
## Technical Documentation
|
||||
|
||||
### Architecture & Infrastructure
|
||||
- [Infrastructure](infrastructure.md) - Project structure and modern build system
|
||||
- [Assembly Style Guide](asm-style-guide.md) - 65816 assembly coding standards
|
||||
### Assembly & Code
|
||||
- [Assembly Style Guide](E1-asm-style-guide.md) - 65816 assembly coding standards
|
||||
|
||||
### Editors
|
||||
### Editor Systems
|
||||
- [Dungeon Editor Guide](E2-dungeon-editor-guide.md) - Complete dungeon editing guide
|
||||
- [Dungeon Editor Design](E3-dungeon-editor-design.md) - Architecture and development guide
|
||||
- [Dungeon Editor Refactoring](E4-dungeon-editor-refactoring.md) - Component-based architecture plan
|
||||
- [Dungeon Object System](E5-dungeon-object-system.md) - Object management framework
|
||||
|
||||
#### Overworld Editor
|
||||
- [Overworld Loading Guide](overworld_loading_guide.md) - ZSCustomOverworld v3 implementation
|
||||
- [Overworld Expansion](overworld-expansion.md) - Advanced overworld features
|
||||
|
||||
#### Dungeon Editor
|
||||
- [Dungeon Editor Guide](dungeon-editor-comprehensive-guide.md) - Complete dungeon editing guide
|
||||
- [Dungeon Editor Design Plan](dungeon-editor-design-plan.md) - Architecture and development guide
|
||||
- [Dungeon Integration Tests](dungeon-integration-tests.md) - Testing framework
|
||||
|
||||
### Graphics & UI
|
||||
- [Canvas Interface Refactoring](canvas-refactor-summary.md) - Canvas system architecture
|
||||
- [Canvas Migration](canvas-migration.md) - Migration guide for canvas changes
|
||||
|
||||
### Testing & Development
|
||||
- [Integration Test Guide](integration_test_guide.md) - Comprehensive testing framework
|
||||
### Overworld System
|
||||
- [Overworld Loading](F1-overworld-loading.md) - ZSCustomOverworld v3 implementation
|
||||
- [Overworld Expansion](F2-overworld-expansion.md) - Advanced overworld features
|
||||
|
||||
## Current Version: 0.3.0 (January 2025)
|
||||
|
||||
### ✅ Major New Features
|
||||
### ✅ Major Features
|
||||
|
||||
#### Asar 65816 Assembler Integration
|
||||
- **Cross-platform ROM patching** with assembly code support
|
||||
@@ -129,7 +122,7 @@ Welcome to the Yaze documentation. This cross-platform Zelda 3 ROM editor is bui
|
||||
- **Comprehensive Testing**: Unit tests, integration tests, and ROM validation
|
||||
|
||||
### Contributing
|
||||
See [Contributing](contributing.md) for guidelines on:
|
||||
See [Contributing](B1-contributing.md) for guidelines on:
|
||||
- Code style and C++23 standards
|
||||
- Testing requirements and ROM handling
|
||||
- Pull request process and review
|
||||
@@ -137,7 +130,7 @@ See [Contributing](contributing.md) for guidelines on:
|
||||
|
||||
### Community
|
||||
- **Discord**: [Oracle of Secrets Discord](https://discord.gg/MBFkMTPEmk)
|
||||
- **GitHub**: [Yaze Repository](https://github.com/scawful/yaze)
|
||||
- **GitHub**: [YAZE Repository](https://github.com/scawful/yaze)
|
||||
- **Issues**: Report bugs and request features on GitHub
|
||||
- **Discussions**: Community discussions and support
|
||||
|
||||
|
||||
@@ -1,92 +0,0 @@
|
||||
# Infrastructure Overview
|
||||
|
||||
For developers to reference.
|
||||
|
||||
The goal of yaze is to build a cross platform editor for the Legend of Zelda: A Link to the Past. The project is built using C++23, SDL2, ImGui, and Asar 65816 assembler. The project uses modern CMake 3.16+ and is designed to be modular and extensible. The project supports Windows, macOS, and Linux with professional packaging and CI/CD.
|
||||
|
||||
## Targets
|
||||
|
||||
- **yaze**: Desktop application with GUI docking system (Windows/macOS/Linux)
|
||||
- **z3ed**: Enhanced command line interface with Asar integration and TUI
|
||||
- **yaze_c**: C Library for custom tools and extensions
|
||||
- **yaze_test**: Comprehensive unit test executable with ROM-dependent test separation
|
||||
- **yaze_emu**: Standalone SNES emulator application
|
||||
- **yaze_ios**: iOS application (coming in future release)
|
||||
|
||||
## Directory Structure
|
||||
|
||||
- **assets**: Hosts assets like fonts, icons, assembly source, etc.
|
||||
- **cmake**: Contains CMake configurations.
|
||||
- **docs**: Contains documentation for users and developers.
|
||||
- **incl**: Contains the public headers for `yaze_c`
|
||||
- **src**: Contains source files.
|
||||
- **app**: Contains the GUI editor `yaze`
|
||||
- **app/emu**: Contains a standalone Snes emulator application `yaze_emu`
|
||||
- **cli**: Contains the command line interface `z3ed`
|
||||
- **ios**: Contains the iOS application `yaze_ios`
|
||||
- **lib**: Contains the dependencies as git submodules
|
||||
- **test**: Contains testing interface `yaze_test`
|
||||
- **win32**: Contains Windows resource file and icon
|
||||
|
||||
## Dependencies
|
||||
|
||||
See [build-instructions.md](docs/build-instructions.md) for more information.
|
||||
|
||||
### Core Dependencies
|
||||
- **SDL2**: Graphics and input library
|
||||
- **ImGui**: Immediate mode GUI library with docking support
|
||||
- **Abseil**: Modern C++ utilities library
|
||||
- **libpng**: Image processing library
|
||||
|
||||
### New in v0.3.0
|
||||
- **Asar**: 65816 assembler for ROM patching and symbol extraction
|
||||
- **ftxui**: Terminal UI library for enhanced CLI experience
|
||||
- **GoogleTest/GoogleMock**: Comprehensive testing framework
|
||||
|
||||
### Build System
|
||||
- **CMake 3.16+**: Modern build system with target-based configuration
|
||||
- **CMakePresets**: Development workflow presets
|
||||
- **Cross-platform CI/CD**: GitHub Actions for automated builds and testing
|
||||
|
||||
## Flow of Control
|
||||
|
||||
- app/main.cc
|
||||
- Initializes `absl::FailureSignalHandler` for stack tracing.
|
||||
- Runs the `core::Controller` loop.
|
||||
- app/core/controller.cc
|
||||
- Initializes SDLRenderer and SDLWindow
|
||||
- Initializes ImGui, fonts, themes, and clipboard.
|
||||
- Handles user input from keyboard and mouse.
|
||||
- Renders the output to the screen.
|
||||
- Handles the teardown of SDL and ImGui resources.
|
||||
- app/editor/editor_manager.cc
|
||||
- Handles the main menu bar
|
||||
- Handles `absl::Status` errors as popups delivered to the user.
|
||||
- Dispatches messages to the various editors.
|
||||
- Update all the editors in a tab view.
|
||||
- app/editor/code/assembly_editor.cc
|
||||
- app/editor/dungeon/dungeon_editor.cc
|
||||
- app/editor/graphics/graphics_editor.cc
|
||||
- app/editor/graphics/gfx_group_editor.cc
|
||||
- app/editor/graphics/palette_editor.cc
|
||||
- app/editor/graphics/tile16_editor.cc
|
||||
- app/editor/message/message_editor.cc
|
||||
- app/editor/music/music_editor.cc
|
||||
- app/editor/overworld/overworld_editor.cc
|
||||
- app/editor/graphics/screen_editor.cc
|
||||
- app/editor/sprite/sprite_editor.cc
|
||||
- app/editor/system/settings_editor.cc
|
||||
|
||||
## Rom
|
||||
|
||||
- app/rom.cc
|
||||
- app/rom.h
|
||||
|
||||
The Rom class provides methods to manipulate and access data from a ROM.
|
||||
|
||||
## Bitmap
|
||||
|
||||
- app/gfx/bitmap.cc
|
||||
- app/gfx/bitmap.h
|
||||
|
||||
This class is responsible for creating, managing, and manipulating bitmap data, which can be displayed on the screen using SDL2 Textures and the ImGui draw list. It also provides functions for exporting these bitmaps to the clipboard in PNG format using libpng.
|
||||
@@ -1,480 +0,0 @@
|
||||
# Integration Test Guide
|
||||
|
||||
This guide explains how to use yaze's integration test suite to validate ROM loading, overworld functionality, and ensure compatibility between vanilla and ZSCustomOverworld ROMs.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Overview](#overview)
|
||||
2. [Test Structure](#test-structure)
|
||||
3. [Running Tests](#running-tests)
|
||||
4. [Understanding Results](#understanding-results)
|
||||
5. [Adding New Tests](#adding-new-tests)
|
||||
6. [Debugging Failed Tests](#debugging-failed-tests)
|
||||
7. [Best Practices](#best-practices)
|
||||
|
||||
## Overview
|
||||
|
||||
The integration test suite validates that yaze correctly loads and processes ROM data by comparing against known values from vanilla ROMs and ensuring that ZSCustomOverworld features work as expected.
|
||||
|
||||
### Key Components
|
||||
|
||||
- **Vanilla ROM Tests**: Validate loading of original Zelda 3 ROMs
|
||||
- **ZSCustomOverworld Tests**: Validate v2/v3 feature compatibility
|
||||
- **Sprite Position Tests**: Verify sprite coordinate systems
|
||||
- **Overworld Map Tests**: Test map loading and property access
|
||||
|
||||
## Test Structure
|
||||
|
||||
### Test Files
|
||||
|
||||
```
|
||||
test/zelda3/
|
||||
├── overworld_integration_test.cc # Integration tests with real ROMs
|
||||
├── comprehensive_integration_test.cc # Full ROM validation
|
||||
├── dungeon_integration_test.cc # Dungeon system integration tests
|
||||
├── dungeon_editor_system_integration_test.cc # Dungeon editor system tests
|
||||
└── extract_vanilla_values.cc # Utility to extract test values
|
||||
|
||||
test/integration/
|
||||
├── editor_integration_test.h/cc # Base editor integration test framework
|
||||
├── dungeon_editor_test.h # Dungeon editor integration tests
|
||||
└── test_editor.h/cc # Test editor framework
|
||||
```
|
||||
|
||||
### Test Categories
|
||||
|
||||
#### 1. Integration Tests (`overworld_integration_test.cc`)
|
||||
|
||||
Test with real ROM files and validate overworld functionality:
|
||||
|
||||
```cpp
|
||||
TEST_F(OverworldIntegrationTest, VanillaROMLoading) {
|
||||
// Load vanilla ROM
|
||||
auto rom = LoadVanillaROM();
|
||||
Overworld overworld(rom.get());
|
||||
|
||||
// Test specific map properties
|
||||
auto* map = overworld.overworld_map(0);
|
||||
EXPECT_EQ(map->area_graphics(), expected_graphics);
|
||||
EXPECT_EQ(map->area_palette(), expected_palette);
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Comprehensive Integration Tests (`comprehensive_integration_test.cc`)
|
||||
|
||||
Full ROM validation with multiple ROM types:
|
||||
|
||||
```cpp
|
||||
TEST_F(ComprehensiveIntegrationTest, VanillaVsV3Comparison) {
|
||||
// Compare vanilla and v3 ROM features
|
||||
EXPECT_NE(vanilla_overworld_, nullptr);
|
||||
EXPECT_NE(v3_overworld_, nullptr);
|
||||
|
||||
// Test feature differences
|
||||
TestFeatureDifferences();
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. Dungeon Integration Tests (`dungeon_integration_test.cc`)
|
||||
|
||||
Test dungeon system functionality:
|
||||
|
||||
```cpp
|
||||
TEST_F(DungeonIntegrationTest, DungeonRoomLoading) {
|
||||
// Test loading dungeon rooms
|
||||
for (int i = 0; i < kNumTestRooms; i++) {
|
||||
// Test room loading and properties
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 4. Dungeon Editor System Tests (`dungeon_editor_system_integration_test.cc`)
|
||||
|
||||
Test the complete dungeon editor system:
|
||||
|
||||
```cpp
|
||||
TEST_F(DungeonEditorSystemIntegrationTest, BasicInitialization) {
|
||||
EXPECT_NE(dungeon_editor_system_, nullptr);
|
||||
EXPECT_EQ(dungeon_editor_system_->GetROM(), rom_.get());
|
||||
EXPECT_FALSE(dungeon_editor_system_->IsDirty());
|
||||
}
|
||||
```
|
||||
|
||||
## Running Tests
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. **Build yaze**: Ensure yaze is built with test support
|
||||
2. **ROM Files**: Have test ROM files available
|
||||
3. **Test Data**: Generated test values from vanilla ROMs
|
||||
|
||||
### Basic Test Execution
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
cd /Users/scawful/Code/yaze/build
|
||||
./bin/yaze_test
|
||||
|
||||
# Run specific test suite
|
||||
./bin/yaze_test --gtest_filter="OverworldTest.*"
|
||||
|
||||
# Run specific test
|
||||
./bin/yaze_test --gtest_filter="SpritePositionTest.SpriteCoordinateSystem"
|
||||
|
||||
# Run with verbose output
|
||||
./bin/yaze_test --gtest_filter="OverworldIntegrationTest.*" --gtest_output=xml:test_results.xml
|
||||
```
|
||||
|
||||
### Test Filtering
|
||||
|
||||
Use Google Test filters to run specific tests:
|
||||
|
||||
```bash
|
||||
# Run only overworld tests
|
||||
./bin/yaze_test --gtest_filter="Overworld*"
|
||||
|
||||
# Run only integration tests
|
||||
./bin/yaze_test --gtest_filter="*Integration*"
|
||||
|
||||
# Run tests matching pattern
|
||||
./bin/yaze_test --gtest_filter="*Sprite*"
|
||||
|
||||
# Exclude specific tests
|
||||
./bin/yaze_test --gtest_filter="OverworldTest.*:-OverworldTest.OverworldMapDestroy"
|
||||
```
|
||||
|
||||
### Parallel Execution
|
||||
|
||||
```bash
|
||||
# Run tests in parallel (faster)
|
||||
./bin/yaze_test --gtest_parallel=4
|
||||
|
||||
# Run with specific number of workers
|
||||
./bin/yaze_test --gtest_workers=8
|
||||
```
|
||||
|
||||
## Understanding Results
|
||||
|
||||
### Test Output Format
|
||||
|
||||
```
|
||||
[==========] Running 3 tests from 1 test suite.
|
||||
[----------] Global test environment set-up.
|
||||
[----------] 3 tests from OverworldTest
|
||||
[ RUN ] OverworldTest.OverworldMapInitialization
|
||||
[ OK ] OverworldTest.OverworldMapInitialization (2 ms)
|
||||
[ RUN ] OverworldTest.AreaSizeEnumValues
|
||||
[ OK ] OverworldTest.AreaSizeEnumValues (1 ms)
|
||||
[ RUN ] OverworldTest.OverworldMapDestroy
|
||||
[ OK ] OverworldTest.OverworldMapDestroy (1 ms)
|
||||
[----------] 3 tests from OverworldTest (4 ms total)
|
||||
[----------] Global test environment tear-down.
|
||||
[==========] 3 tests from 1 test suite ran. (4 ms total)
|
||||
[ PASSED ] 3 tests.
|
||||
```
|
||||
|
||||
### Success Indicators
|
||||
|
||||
- `[ OK ]`: Test passed
|
||||
- `[ PASSED ]`: All tests in suite passed
|
||||
- No error messages or stack traces
|
||||
|
||||
### Failure Indicators
|
||||
|
||||
- `[ FAILED ]`: Test failed
|
||||
- Error messages with expected vs actual values
|
||||
- Stack traces showing failure location
|
||||
|
||||
### Example Failure Output
|
||||
|
||||
```
|
||||
[ RUN ] OverworldTest.OverworldMapInitialization
|
||||
test/zelda3/overworld_test.cc:45: Failure
|
||||
Expected equality of these values:
|
||||
map.area_graphics()
|
||||
Which is: 5
|
||||
0
|
||||
[ FAILED ] OverworldTest.OverworldMapInitialization (2 ms)
|
||||
```
|
||||
|
||||
## Adding New Tests
|
||||
|
||||
### 1. Unit Test Example
|
||||
|
||||
```cpp
|
||||
// Add to overworld_test.cc
|
||||
TEST_F(OverworldTest, VanillaOverlayLoading) {
|
||||
OverworldMap map(0, rom_.get());
|
||||
|
||||
// Test vanilla overlay loading
|
||||
RETURN_IF_ERROR(map.LoadVanillaOverlay());
|
||||
|
||||
// Verify overlay data
|
||||
EXPECT_TRUE(map.has_vanilla_overlay());
|
||||
EXPECT_GT(map.vanilla_overlay_data().size(), 0);
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Integration Test Example
|
||||
|
||||
```cpp
|
||||
// Add to overworld_integration_test.cc
|
||||
TEST_F(OverworldIntegrationTest, ZSCustomOverworldV3Features) {
|
||||
// Load ZSCustomOverworld v3 ROM
|
||||
auto rom = LoadZSCustomOverworldV3ROM();
|
||||
Overworld overworld(rom.get());
|
||||
|
||||
// Test v3 features
|
||||
auto* map = overworld.overworld_map(0);
|
||||
EXPECT_GT(map->subscreen_overlay(), 0);
|
||||
EXPECT_GT(map->animated_gfx(), 0);
|
||||
|
||||
// Test custom tile graphics
|
||||
for (int i = 0; i < 8; i++) {
|
||||
EXPECT_GE(map->custom_tileset(i), 0);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Performance Test Example
|
||||
|
||||
```cpp
|
||||
TEST_F(OverworldPerformanceTest, LargeMapLoading) {
|
||||
auto start = std::chrono::high_resolution_clock::now();
|
||||
|
||||
// Load large number of maps
|
||||
for (int i = 0; i < 100; i++) {
|
||||
OverworldMap map(i % 160, rom_.get());
|
||||
}
|
||||
|
||||
auto end = std::chrono::high_resolution_clock::now();
|
||||
auto duration = std::chrono::duration_cast<std::chrono::milliseconds>(end - start);
|
||||
|
||||
// Ensure loading is reasonably fast
|
||||
EXPECT_LT(duration.count(), 1000); // Less than 1 second
|
||||
}
|
||||
```
|
||||
|
||||
## Debugging Failed Tests
|
||||
|
||||
### 1. Enable Debug Output
|
||||
|
||||
```cpp
|
||||
// Add debug output to tests
|
||||
TEST_F(OverworldTest, DebugTest) {
|
||||
OverworldMap map(0, rom_.get());
|
||||
|
||||
// Print debug information
|
||||
std::cout << "Map index: " << map.index() << std::endl;
|
||||
std::cout << "Area graphics: " << static_cast<int>(map.area_graphics()) << std::endl;
|
||||
std::cout << "Area palette: " << static_cast<int>(map.area_palette()) << std::endl;
|
||||
|
||||
// Your assertions here
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Use GDB for Debugging
|
||||
|
||||
```bash
|
||||
# Run test with GDB
|
||||
gdb --args ./bin/yaze_test --gtest_filter="OverworldTest.DebugTest"
|
||||
|
||||
# Set breakpoints
|
||||
(gdb) break overworld_test.cc:45
|
||||
(gdb) run
|
||||
|
||||
# Inspect variables
|
||||
(gdb) print map.area_graphics()
|
||||
(gdb) print map.area_palette()
|
||||
```
|
||||
|
||||
### 3. Memory Debugging
|
||||
|
||||
```bash
|
||||
# Run with Valgrind (Linux)
|
||||
valgrind --leak-check=full ./bin/yaze_test --gtest_filter="OverworldTest.*"
|
||||
|
||||
# Run with AddressSanitizer
|
||||
export ASAN_OPTIONS=detect_leaks=1
|
||||
./bin/yaze_test --gtest_filter="OverworldTest.*"
|
||||
```
|
||||
|
||||
### 4. Common Debugging Scenarios
|
||||
|
||||
#### ROM Loading Issues
|
||||
|
||||
```cpp
|
||||
// Check ROM version detection
|
||||
uint8_t asm_version = (*rom_)[zelda3::OverworldCustomASMHasBeenApplied];
|
||||
std::cout << "ASM Version: 0x" << std::hex << static_cast<int>(asm_version) << std::endl;
|
||||
|
||||
// Verify ROM size
|
||||
std::cout << "ROM Size: " << rom_->size() << " bytes" << std::endl;
|
||||
```
|
||||
|
||||
#### Map Property Issues
|
||||
|
||||
```cpp
|
||||
// Check map loading
|
||||
auto* map = overworld.overworld_map(current_map_);
|
||||
std::cout << "Map " << current_map_ << " properties:" << std::endl;
|
||||
std::cout << " Area Graphics: 0x" << std::hex << static_cast<int>(map->area_graphics()) << std::endl;
|
||||
std::cout << " Area Palette: 0x" << std::hex << static_cast<int>(map->area_palette()) << std::endl;
|
||||
std::cout << " Main Palette: 0x" << std::hex << static_cast<int>(map->main_palette()) << std::endl;
|
||||
```
|
||||
|
||||
#### Sprite Issues
|
||||
|
||||
```cpp
|
||||
// Check sprite loading
|
||||
for (int game_state = 0; game_state < 3; game_state++) {
|
||||
auto& sprites = *overworld.mutable_sprites(game_state);
|
||||
std::cout << "Game State " << game_state << ": " << sprites.size() << " sprites" << std::endl;
|
||||
|
||||
for (size_t i = 0; i < std::min(sprites.size(), size_t(5)); i++) {
|
||||
auto& sprite = sprites[i];
|
||||
std::cout << " Sprite " << i << ": Map=" << sprite.map_id()
|
||||
<< ", X=" << sprite.x_ << ", Y=" << sprite.y_ << std::endl;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Test Organization
|
||||
|
||||
- **Group related tests**: Use descriptive test suite names
|
||||
- **One concept per test**: Each test should verify one specific behavior
|
||||
- **Descriptive names**: Test names should clearly indicate what they're testing
|
||||
|
||||
```cpp
|
||||
// Good
|
||||
TEST_F(OverworldTest, VanillaOverlayLoadingForMap00) {
|
||||
// Test specific map's overlay loading
|
||||
}
|
||||
|
||||
// Bad
|
||||
TEST_F(OverworldTest, Test1) {
|
||||
// Unclear what this tests
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Test Data Management
|
||||
|
||||
```cpp
|
||||
class OverworldTest : public ::testing::Test {
|
||||
protected:
|
||||
void SetUp() override {
|
||||
// Initialize test data once
|
||||
rom_ = std::make_unique<Rom>();
|
||||
// ... setup code
|
||||
}
|
||||
|
||||
void TearDown() override {
|
||||
// Clean up after each test
|
||||
rom_.reset();
|
||||
}
|
||||
|
||||
std::unique_ptr<Rom> rom_;
|
||||
};
|
||||
```
|
||||
|
||||
### 3. Error Handling in Tests
|
||||
|
||||
```cpp
|
||||
TEST_F(OverworldTest, ErrorHandling) {
|
||||
// Test error conditions
|
||||
OverworldMap map(999, rom_.get()); // Invalid map index
|
||||
|
||||
// Verify error handling
|
||||
EXPECT_FALSE(map.is_initialized());
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Performance Considerations
|
||||
|
||||
```cpp
|
||||
// Use fixtures for expensive setup
|
||||
class ExpensiveTest : public ::testing::Test {
|
||||
protected:
|
||||
void SetUp() override {
|
||||
// Expensive setup here
|
||||
LoadLargeROM();
|
||||
ProcessAllMaps();
|
||||
}
|
||||
};
|
||||
|
||||
// Run expensive tests separately
|
||||
TEST_F(ExpensiveTest, FullOverworldProcessing) {
|
||||
// Test that requires expensive setup
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Continuous Integration
|
||||
|
||||
Add tests to CI pipeline:
|
||||
|
||||
```yaml
|
||||
# .github/workflows/tests.yml
|
||||
name: Tests
|
||||
on: [push, pull_request]
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- name: Build and Test
|
||||
run: |
|
||||
cd build
|
||||
make -j4 yaze_test
|
||||
./bin/yaze_test --gtest_output=xml:test_results.xml
|
||||
- name: Upload Test Results
|
||||
uses: actions/upload-artifact@v2
|
||||
with:
|
||||
name: test-results
|
||||
path: build/test_results.xml
|
||||
```
|
||||
|
||||
## Test Results Interpretation
|
||||
|
||||
### Viewing Results
|
||||
|
||||
Test results are typically displayed in the terminal, but you can also generate XML reports:
|
||||
|
||||
```bash
|
||||
# Generate XML report
|
||||
./bin/yaze_test --gtest_output=xml:test_results.xml
|
||||
|
||||
# View in browser (if you have a test result viewer)
|
||||
open test_results.xml
|
||||
```
|
||||
|
||||
### Key Metrics
|
||||
|
||||
- **Test Count**: Number of tests run
|
||||
- **Pass Rate**: Percentage of tests that passed
|
||||
- **Execution Time**: How long tests took to run
|
||||
- **Memory Usage**: Peak memory consumption during tests
|
||||
|
||||
### Performance Benchmarks
|
||||
|
||||
Track performance over time:
|
||||
|
||||
```bash
|
||||
# Run with timing
|
||||
time ./bin/yaze_test --gtest_filter="OverworldPerformanceTest.*"
|
||||
|
||||
# Profile with gprof
|
||||
gprof ./bin/yaze_test gmon.out > profile.txt
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
The integration test suite is essential for maintaining yaze's reliability and ensuring compatibility with different ROM types. By following this guide, you can effectively run tests, debug issues, and add new test cases to improve the overall quality of the codebase.
|
||||
|
||||
Remember to:
|
||||
- Run tests regularly during development
|
||||
- Add tests for new features
|
||||
- Debug failures promptly
|
||||
- Keep tests fast and focused
|
||||
- Use appropriate test data and fixtures
|
||||
@@ -1,51 +0,0 @@
|
||||
# Roadmap
|
||||
|
||||
## 0.3.0 (Current - Released January 2025)
|
||||
- **Asar 65816 Assembler Integration**: Complete cross-platform ROM patching with assembly code
|
||||
- **ZSCustomOverworld v3**: Complete integration with enhanced overworld editing capabilities
|
||||
- **Advanced Message Editing**: Enhanced text editing interface with improved parsing
|
||||
- **GUI Docking System**: Improved docking and workspace management for better workflow
|
||||
- **Symbol Extraction**: Extract and analyze assembly symbols with addresses
|
||||
- **Enhanced CLI Tools**: Modern z3ed command-line interface with improved UX
|
||||
- **Modernized Build System**: CMake 3.16+ with professional packaging and CI/CD
|
||||
- **Testing Infrastructure**: Comprehensive test suite with ROM-dependent test separation
|
||||
|
||||
## 0.4.X (Next Major Release)
|
||||
- **Overworld Sprites**: Complete sprite editing, add/remove functionality
|
||||
- **Enhanced Dungeon Editing**: Advanced room object draw and edit functionality
|
||||
- **Tile16 Editing**: Enhanced editor for creating and modifying tile16 data
|
||||
- **Plugin Architecture**: Framework for community extensions and custom tools
|
||||
- **Graphics Sheets**: Complete editing, saving, and re-importing of sheets
|
||||
- **Project Refactoring**: Clean up resource loading and memory usage
|
||||
|
||||
## 0.4.X
|
||||
- Dungeon: Implement room object draw and edit functionality.
|
||||
- Graphics Sheets: Complete editing, saving, and re-importing of sheets.
|
||||
- Project Refactoring: Clean up resource loading and memory usage.
|
||||
|
||||
## 0.5.X
|
||||
- Sprite Property Editor: Add support for changing sprite behavior and attributes.
|
||||
- Custom Sprites: Support creating and editing custom sprites.
|
||||
- Asar Patching: Stabilize existing patching system for advanced modifications.
|
||||
|
||||
## 0.6.X
|
||||
- SCAD Format: Polish and finalize the scad file integration.
|
||||
- Hex Editing Improvements: Enhance user interface for direct ROM manipulation.
|
||||
- Music Editing: Add an interface to edit and manage music data.
|
||||
|
||||
## 0.7.X
|
||||
- Cross-Platform Stability: Test and refine builds across Windows, macOS, iOS, and Linux.
|
||||
- Plugin/Integration Framework: Provide hooks or scripting for community add-ons.
|
||||
|
||||
## 0.8.X
|
||||
- Performance Optimizations: Remove bottlenecks in rendering and data processing.
|
||||
- Documentation Overhaul: Update manuals, guides, and in-app tooltips.
|
||||
|
||||
## 0.9.X
|
||||
- Beta Release: Code freeze on major features, focus on bug fixes and polish.
|
||||
- User Interface Refinements: Improve UI consistency, iconography, and layout.
|
||||
- Internal Cleanup: Remove deprecated code, finalize API calls.
|
||||
|
||||
## 1.0.0
|
||||
- Stable Release: Final, production-ready version.
|
||||
- Changelog: Comprehensive summary of all changes since 0.0.0.
|
||||
Reference in New Issue
Block a user