backend-infra-engineer: Release v0.3.9-hotfix7 snapshot
This commit is contained in:
scawful
134
docs/internal/rom-service-phase5-summary.md
Normal file
134
docs/internal/rom-service-phase5-summary.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user