From 640e0a78f246af377d77b6a6ef35a32cfe9c1a7c Mon Sep 17 00:00:00 2001 From: scawful Date: Sat, 4 Oct 2025 14:17:25 -0400 Subject: [PATCH] feat: Remove Asar integration documentation and update index references --- docs/03-asar-integration.md | 141 ------------------------------------ docs/04-api-reference.md | 44 +++++++++++ docs/index.md | 5 +- 3 files changed, 47 insertions(+), 143 deletions(-) delete mode 100644 docs/03-asar-integration.md diff --git a/docs/03-asar-integration.md b/docs/03-asar-integration.md deleted file mode 100644 index a021ade5..00000000 --- a/docs/03-asar-integration.md +++ /dev/null @@ -1,141 +0,0 @@ -# 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::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 ApplyPatch( - const std::string& patch_path, - std::vector& rom_data); - absl::StatusOr> 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 errors; // Error messages - std::vector 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** diff --git a/docs/04-api-reference.md b/docs/04-api-reference.md index 9b26b1bf..40b3c2ab 100644 --- a/docs/04-api-reference.md +++ b/docs/04-api-reference.md @@ -58,6 +58,40 @@ yaze_status yaze_save_message(zelda3_rom* rom, const zelda3_message* message); ## C++ API ### AsarWrapper (`src/app/core/asar_wrapper.h`) + +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::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; + } +} +``` + +#### AsarWrapper Class ```cpp namespace yaze::core { @@ -92,6 +126,16 @@ public: } ``` +#### 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 | + + ### Data Structures #### ROM Version Support diff --git a/docs/index.md b/docs/index.md index 8d4b4e14..e4227315 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,7 +6,6 @@ Yet Another Zelda3 Editor - A comprehensive ROM editor for The Legend of Zelda: - [Getting Started](01-getting-started.md) - Basic setup and usage - [Build Instructions](02-build-instructions.md) - Cross-platform build guide -- [Asar Integration](03-asar-integration.md) - 65816 assembler usage - [API Reference](04-api-reference.md) - C/C++ API documentation ## Development @@ -23,7 +22,7 @@ Yet Another Zelda3 Editor - A comprehensive ROM editor for The Legend of Zelda: - [Assembly Style Guide](E1-asm-style-guide.md) - 65816 assembly coding standards ### Editor Systems -- [Dungeon Editor Guide](dungeon_editor_master_guide.md) - Complete dungeon editing guide +- [Dungeon Editor Master Guide](dungeon_editor_master_guide.md) - Complete dungeon editing guide ### Overworld System - [Overworld Loading](F1-overworld-loading.md) - ZSCustomOverworld v3 implementation @@ -39,3 +38,5 @@ Yet Another Zelda3 Editor - A comprehensive ROM editor for The Legend of Zelda: - **CMake Compatibility**: Automatic handling of submodule compatibility issues (abseil-cpp, SDL) --- + +*Last updated: December 2025 - Version 0.3.2*