yaze/docs/internal/rom-service-phase5-summary.md

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