feat: Remove Asar integration documentation and update index references
This commit is contained in:
@@ -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**
|
|
||||||
@@ -58,6 +58,40 @@ yaze_status yaze_save_message(zelda3_rom* rom, const zelda3_message* message);
|
|||||||
## C++ API
|
## C++ API
|
||||||
|
|
||||||
### AsarWrapper (`src/app/core/asar_wrapper.h`)
|
### 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
|
```cpp
|
||||||
namespace yaze::core {
|
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
|
### Data Structures
|
||||||
|
|
||||||
#### ROM Version Support
|
#### ROM Version Support
|
||||||
|
|||||||
@@ -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
|
- [Getting Started](01-getting-started.md) - Basic setup and usage
|
||||||
- [Build Instructions](02-build-instructions.md) - Cross-platform build guide
|
- [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
|
- [API Reference](04-api-reference.md) - C/C++ API documentation
|
||||||
|
|
||||||
## Development
|
## 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
|
- [Assembly Style Guide](E1-asm-style-guide.md) - 65816 assembly coding standards
|
||||||
|
|
||||||
### Editor Systems
|
### 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 System
|
||||||
- [Overworld Loading](F1-overworld-loading.md) - ZSCustomOverworld v3 implementation
|
- [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)
|
- **CMake Compatibility**: Automatic handling of submodule compatibility issues (abseil-cpp, SDL)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
*Last updated: December 2025 - Version 0.3.2*
|
||||||
|
|||||||
Reference in New Issue
Block a user