scawful/yaze
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Remove Asar integration documentation and update index references

Browse Source
This commit is contained in:
scawful
2025-10-04 14:17:25 -04:00
parent 820e4577df
commit 640e0a78f2
3 changed files with 47 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files

141
docs/03-asar-integration.md
View File

@@ -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<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**

44
docs/04-api-reference.md
View File

@@ -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

5
docs/index.md
View File

@@ -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*