134 lines
4.8 KiB
Markdown
134 lines
4.8 KiB
Markdown
# ROM Service Phase 5 Implementation Summary
|
|
|
|
## Overview
|
|
Phase 5 of the AI infrastructure plan focused on implementing and enhancing ROM Domain RPCs for the RomService. This service provides remote access to ROM data for AI agents and external tools.
|
|
|
|
## Current Status: COMPLETE ✅
|
|
|
|
## What Was Already Implemented
|
|
Before starting Phase 5, the following RPCs were already functional:
|
|
|
|
### Basic Operations
|
|
- **ReadBytes**: Read raw bytes from ROM at specified offset
|
|
- **WriteBytes**: Write bytes to ROM with optional approval workflow
|
|
|
|
### Version Management
|
|
- **CreateSnapshot**: Create ROM snapshots before changes
|
|
- **RestoreSnapshot**: Restore ROM to previous snapshot
|
|
- **ListSnapshots**: List available snapshots with metadata
|
|
|
|
### Proposal System
|
|
- **SubmitRomProposal**: Submit write operations for approval
|
|
- **GetProposalStatus**: Check approval status of proposals
|
|
|
|
## What Was Enhanced in Phase 5
|
|
|
|
### 1. GetRomInfo RPC ✅
|
|
**Previous State**: Returned basic title and size only
|
|
|
|
**Enhanced Implementation**:
|
|
- Calculates simple checksum (sum of all bytes)
|
|
- Detects if ROM is expanded (>2MB)
|
|
- Determines ROM version (JP/US/EU) from header byte at 0x7FDB
|
|
- Returns comprehensive metadata for ROM identification
|
|
|
|
### 2. ReadOverworldMap RPC ✅
|
|
**Previous State**: Stub returning "not yet implemented"
|
|
|
|
**Enhanced Implementation**:
|
|
- Validates map ID (0-159 range for ALTTP)
|
|
- Reads map pointer from table at 0x1794D
|
|
- Fetches compressed map data from calculated address
|
|
- Returns raw compressed data (LC-LZ2 format)
|
|
- Proper error handling with detailed messages
|
|
|
|
**Future Enhancement Needed**: Decompress LC-LZ2 data to provide tile16_data array
|
|
|
|
### 3. ReadDungeonRoom RPC ✅
|
|
**Previous State**: Stub returning "not yet implemented"
|
|
|
|
**Enhanced Implementation**:
|
|
- Validates room ID (0-295 range for ALTTP)
|
|
- Reads room header (14 bytes) from 0x7E00 + (room_id * 0x0E)
|
|
- Extracts layout pointer from header
|
|
- Fetches room object data from calculated address
|
|
- Returns raw compressed object data
|
|
- Comprehensive error handling
|
|
|
|
**Future Enhancement Needed**: Parse objects and build tile map
|
|
|
|
### 4. ReadSprite RPC ✅
|
|
**Previous State**: Stub returning "not yet implemented"
|
|
|
|
**Enhanced Implementation**:
|
|
- Validates sprite ID (0-255 range for ALTTP)
|
|
- Reads sprite HP from table at 0x6B173
|
|
- Reads damage value from table at 0x6B266
|
|
- Reads palette index from table at 0x6B35B
|
|
- Reads additional properties (4 bytes) from 0x6B450
|
|
- Returns consolidated sprite property data
|
|
|
|
**Future Enhancement Needed**: Extract actual graphics tiles and animations
|
|
|
|
## Not Yet Implemented RPCs
|
|
The following RPCs still return "not yet implemented":
|
|
- **WriteOverworldTile**: Modify single tile in overworld map
|
|
- **WriteDungeonTile**: Modify single tile in dungeon room
|
|
|
|
These require complex tile map rebuilding and were left for future implementation.
|
|
|
|
## Technical Details
|
|
|
|
### Error Handling
|
|
All RPCs follow consistent error handling pattern:
|
|
1. Check if ROM is loaded
|
|
2. Validate input parameters
|
|
3. Return detailed error messages in response
|
|
4. Use grpc::Status::OK even for errors (error details in response)
|
|
|
|
### ROM Address Constants
|
|
The implementation uses well-known ALTTP ROM addresses:
|
|
- Overworld map pointers: 0x1794D
|
|
- Dungeon room headers: 0x7E00
|
|
- Sprite property tables: 0x6B173, 0x6B266, 0x6B35B, 0x6B450
|
|
|
|
### Data Format
|
|
- Overworld maps: Compressed LC-LZ2 format
|
|
- Dungeon rooms: Custom object format requiring parsing
|
|
- Sprites: Direct property bytes from various tables
|
|
|
|
## Files Modified
|
|
- `/Users/scawful/Code/yaze/src/app/net/rom_service_impl.cc`
|
|
- Enhanced GetRomInfo with checksum and version detection
|
|
- Implemented ReadOverworldMap with pointer table lookup
|
|
- Implemented ReadDungeonRoom with header parsing
|
|
- Implemented ReadSprite with property table reads
|
|
|
|
## Testing Recommendations
|
|
To test the enhanced RPCs:
|
|
|
|
1. **GetRomInfo**: Call and verify checksum, expansion status, version
|
|
2. **ReadOverworldMap**: Test with map IDs 0-159, verify raw data returned
|
|
3. **ReadDungeonRoom**: Test with room IDs 0-295, verify header + object data
|
|
4. **ReadSprite**: Test with sprite IDs 0-255, verify property bytes
|
|
|
|
## Future Work
|
|
1. Implement LC-LZ2 decompression for map/room data
|
|
2. Parse dungeon objects to build actual tile maps
|
|
3. Extract sprite graphics and animation data
|
|
4. Implement write operations for tiles
|
|
5. Add caching layer for frequently accessed data
|
|
6. Implement batch operations for efficiency
|
|
|
|
## Integration Points
|
|
The enhanced RomService can now be used by:
|
|
- AI agents for ROM analysis
|
|
- z3ed CLI tool for remote ROM access
|
|
- Testing frameworks for ROM validation
|
|
- External tools via gRPC client libraries
|
|
|
|
## Performance Considerations
|
|
- Current implementation reads data on each request
|
|
- Consider adding caching for frequently accessed data
|
|
- Batch operations would reduce RPC overhead
|
|
- Decompression should be done server-side to reduce network traffic |