{"id":31041701,"url":"https://github.com/rpdevjesco/retrogameanalysis","last_synced_at":"2025-09-14T10:39:16.554Z","repository":{"id":303734475,"uuid":"1016502909","full_name":"RPDevJesco/RetroGameAnalysis","owner":"RPDevJesco","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-09T05:44:53.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-09T06:38:59.245Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RPDevJesco.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-09T05:41:22.000Z","updated_at":"2025-07-09T05:44:56.000Z","dependencies_parsed_at":"2025-07-09T06:49:00.394Z","dependency_job_id":null,"html_url":"https://github.com/RPDevJesco/RetroGameAnalysis","commit_stats":null,"previous_names":["rpdevjesco/retrogameanalysis"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/RPDevJesco/RetroGameAnalysis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RPDevJesco%2FRetroGameAnalysis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RPDevJesco%2FRetroGameAnalysis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RPDevJesco%2FRetroGameAnalysis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RPDevJesco%2FRetroGameAnalysis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RPDevJesco","download_url":"https://codeload.github.com/RPDevJesco/RetroGameAnalysis/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RPDevJesco%2FRetroGameAnalysis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275094398,"owners_count":25404446,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-14T02:00:10.474Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-14T10:39:12.780Z","updated_at":"2025-09-14T10:39:16.544Z","avatar_url":"https://github.com/RPDevJesco.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RetroGameAnalysis\n\n🎮 **Modern retro game memory manipulation with advanced property management**\n\nRetroGameAnalysis is a powerful, next-generation tool for interacting with retro game memory in real-time. Built in Go, it provides a sophisticated web-based interface for monitoring, modifying, and analyzing game state with unprecedented detail and control.\n\n## ✨ What Makes RetroGameAnalysis Special\n\nUnlike traditional memory editors that work with raw bytes and addresses, RetroGameAnalysis operates at a **property level**, treating game data as structured, typed information with rich metadata and validation rules.\n\n### 🚀 Key Features\n\n- **🔄 Real-time Monitoring** - 60fps property change detection and streaming\n- **🧊 Property Freezing** - Lock values to prevent changes from the game\n- **📊 Advanced Property Types** - Enums, flags, coordinates, colors, percentages, and more\n- **⚡ Batch Operations** - Update multiple properties atomically\n- **✅ Property Validation** - Enforce constraints and data integrity\n- **📈 State Tracking** - Monitor read/write counts, history, and statistics\n- **🎨 Rich UI Hints** - Enhanced metadata for beautiful interfaces\n- **🔗 Reference Types** - Structured data definitions and lookups\n- **📡 WebSocket API** - Real-time bidirectional communication\n- **🎯 Event System** - Trigger-based automation and alerts\n\n## 🎯 How It Works\n\n### Architecture Overview\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   Web Browser   │    │RetroGameAnalysis Server│    │   RetroArch     │\n│                 │    │                  │    │                 │\n│ ┌─────────────┐ │    │ ┌──────────────┐ │    │ ┌─────────────┐ │\n│ │ Enhanced UI │ │◄──►│ │ REST API     │ │    │ │ Game Core   │ │\n│ └─────────────┘ │    │ └──────────────┘ │    │ └─────────────┘ │\n│                 │    │ ┌──────────────┐ │    │       ▲         │\n│ ┌─────────────┐ │    │ │ WebSocket    │ │    │       │         │\n│ │ Real-time   │ │◄──►│ │ Streaming    │ │    │ ┌─────▼─────┐   │\n│ │ Updates     │ │    │ └──────────────┘ │    │ │ Memory    │   │\n│ └─────────────┘ │    │ ┌──────────────┐ │◄──►│ │ Interface │   │\n└─────────────────┘    │ │ Adaptive     │ │    │ └───────────┘   │\n                       │ │ RetroArch    │ │    └─────────────────┘\n                       │ │ Driver       │ │\n                       │ └──────────────┘ │\n                       │ ┌──────────────┐ │\n                       │ │ Enhanced     │ │\n                       │ │ Memory       │ │\n                       │ │ Manager      │ │\n                       │ └──────────────┘ │\n                       └──────────────────┘\n```\n\n### Core Components\n\n1. **Adaptive RetroArch Driver** - Optimized UDP communication with automatic chunking\n2. **Enhanced Memory Manager** - Advanced caching, state tracking, and property management\n3. **CUE-based Mappers** - Declarative game memory definitions with rich typing\n4. **Property Engine** - Real-time monitoring, validation, and transformation\n5. **WebSocket Streaming** - 60fps real-time updates to connected clients\n6. **REST API** - Comprehensive HTTP API for all operations\n\n## 🔧 Setup \u0026 Installation\n\n### Prerequisites\n\n- **RetroArch** with network commands enabled\n- **Go 1.19+** for building from source\n\n### RetroArch Configuration\n\n1. Enable network commands in RetroArch:\n   ```\n   Settings → Network → Network Commands: ON\n   Settings → Network → Network Command Port: 55355\n   ```\n\n2. Load a compatible game and core (Game Boy games work best)\n\n### Building \u0026 Running\n\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd gamehook-enhanced\n\n# Build the application\ngo build -o gamehook-enhanced ./cmd/gamehook\n\n# Run with default settings\n./gamehook-enhanced\n\n# Or specify custom configuration\n./gamehook-enhanced --port 8080 --retroarch-host 127.0.0.1\n```\n\n### Configuration Options\n\n```bash\n# Server configuration\n--port 8080                    # Web server port\n--host 0.0.0.0                # Server host\n\n# RetroArch connection\n--retroarch-host 127.0.0.1    # RetroArch host\n--retroarch-port 55355        # RetroArch UDP port\n\n# Performance tuning\n--update-interval 16ms        # Property monitoring rate (60fps)\n--request-timeout 64ms        # RetroArch request timeout\n\n# Directories\n--mappers-dir ./mappers       # Mapper definitions directory\n--uis-dir ./uis               # Web UI directory\n```\n\n## 📝 Mapper System\n\nRetroGameAnalysis uses **CUE** (Configure, Unify, Execute) for defining game memory layouts. This provides type safety, validation, and powerful expressions.\n\n### Simple Property Example\n\n```cue\nproperties: {\n    playerName: {\n        type: \"string\"\n        address: \"0xD158\"\n        length: 11\n        description: \"Player character name\"\n        charMap: characterMaps.pokemon\n        validation: {\n            pattern: \"^[A-Za-z0-9 ]*$\"\n        }\n        uiHints: {\n            icon: \"👤\"\n            editable: true\n        }\n    }\n}\n```\n\n### Advanced Property with Freezing\n\n```cue\nproperties: {\n    playerMoney: {\n        type: \"bcd\"\n        address: \"0xD347\"\n        length: 3\n        description: \"Player's money in BCD format\"\n        freezable: true\n        transform: {\n            expression: \"bcdToDecimal(value)\"\n        }\n        validation: {\n            minValue: 0\n            maxValue: 999999\n        }\n        uiHints: {\n            displayFormat: \"currency\"\n            unit: \"₽\"\n            icon: \"💰\"\n        }\n    }\n}\n```\n\n### Computed Properties\n\n```cue\ncomputed: {\n    teamTotalLevel: {\n        expression: \"\"\"\n            properties.pokemon1Level + \n            properties.pokemon2Level + \n            properties.pokemon3Level\n        \"\"\"\n        dependencies: [\"pokemon1Level\", \"pokemon2Level\", \"pokemon3Level\"]\n        type: \"uint16\"\n    }\n}\n```\n\n## 🌐 API Reference\n\n### Enhanced REST Endpoints\n\n#### Property Management\n```http\nGET    /api/properties                    # List all properties\nGET    /api/properties/{name}             # Get specific property\nPUT    /api/properties/{name}/value       # Set property value\nPUT    /api/properties/{name}/bytes       # Set raw bytes\nPOST   /api/properties/{name}/freeze      # Freeze/unfreeze property\nPUT    /api/properties/batch              # Batch property updates\n```\n\n#### Enhanced Features\n```http\nGET    /api/properties/states             # Get all property states\nGET    /api/properties/{name}/metadata    # Get property metadata\nGET    /api/properties/{name}/ui-hints    # Get UI presentation hints\nGET    /api/properties/by-group/{group}   # Get properties by group\n```\n\n#### Reference System\n```http\nGET    /api/references                    # Get reference types\nGET    /api/references/{type}             # Get specific reference\n```\n\n#### Event System\n```http\nGET    /api/events                        # Get events\nPOST   /api/events/{name}/trigger         # Trigger event\n```\n\n#### Validation \u0026 UI\n```http\nGET    /api/validation/rules              # Get validation rules\nGET    /api/validation/errors             # Get validation errors\nGET    /api/ui/themes                     # Get UI themes\nGET    /api/ui/layout                     # Get UI layout\n```\n\n### WebSocket Streaming\n\nConnect to `/api/stream` for real-time updates:\n\n```javascript\nconst ws = new WebSocket('ws://localhost:8080/api/stream');\n\nws.onmessage = (event) =\u003e {\n    const data = JSON.parse(event.data);\n    \n    switch(data.type) {\n        case 'property_changed':\n            console.log(`${data.property} = ${data.value}`);\n            break;\n        case 'property_freeze_changed':\n            console.log(`${data.property} freeze: ${data.frozen}`);\n            break;\n        case 'event_triggered':\n            console.log(`Event ${data.event_name} triggered`);\n            break;\n    }\n};\n```\n\n## 🎮 Use Cases\n\n### 🕹️ Game Development \u0026 Testing\n- **Save State Analysis** - Examine save data structure and validation\n- **Balancing \u0026 Tuning** - Real-time parameter adjustment during gameplay\n- **Bug Investigation** - Monitor memory corruption and unexpected changes\n- **Feature Testing** - Verify game logic responds correctly to state changes\n\n### 📚 Game Research \u0026 Reverse Engineering\n- **Memory Layout Discovery** - Map unknown game structures\n- **Data Format Analysis** - Understand encoding and compression\n- **Behavior Study** - Observe how games respond to different inputs\n- **Documentation** - Create comprehensive memory maps\n\n### 🎯 Speedrunning \u0026 Competition\n- **Route Optimization** - Analyze RNG and optimal strategies\n- **Practice Tools** - Set up specific game states for practice\n- **Record Analysis** - Verify runs and analyze techniques\n- **Training Aids** - Practice difficult sequences repeatedly\n\n### 🔬 Educational \u0026 Academic\n- **Computer Science Education** - Demonstrate memory management concepts\n- **Game Studies** - Research game design and player behavior\n- **Preservation** - Document game internals for future preservation\n\n## 🚀 What Makes It Different\n\n### vs. Traditional Memory Editors (Cheat Engine, etc.)\n\n| Feature | Traditional | RetroGameAnalysis |\n|---------|-------------|-------------------|\n| **Approach** | Raw memory addresses | Structured properties |\n| **Type Safety** | Manual casting | Rich type system |\n| **Real-time** | Polling-based | 60fps streaming |\n| **Validation** | None | Built-in constraints |\n| **UI** | Basic tables | Rich metadata-driven |\n| **API** | None/Limited | Full REST + WebSocket |\n| **Automation** | Scripts | Event system |\n| **Collaboration** | File sharing | Web-based, multi-user |\n\n### vs. Save Editors\n\n| Feature | Save Editors | RetroGameAnalysis |\n|---------|--------------|-------------------|\n| **Timing** | Save file only | Real-time during gameplay |\n| **Scope** | Save data only | All game memory |\n| **Interaction** | Static | Dynamic with game running |\n| **Development** | Game-specific tools | Universal framework |\n\n### vs. Basic RAM Watchers\n\n| Feature | RAM Watchers | RetroGameAnalysis |\n|---------|--------------|-------------------|\n| **Property Types** | Numbers only | Rich types (enums, colors, etc.) |\n| **Validation** | None | Comprehensive |\n| **Freezing** | Basic | Advanced with conditions |\n| **API** | None | Full REST + WebSocket |\n| **UI** | Simple lists | Rich, customizable interface |\n\n## 🏗️ Advanced Features\n\n### Property Freezing\nLock values to prevent the game from changing them:\n\n```bash\n# Freeze player health at current value\ncurl -X POST http://localhost:8080/api/properties/playerHP/freeze \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"freeze\": true}'\n```\n\n### Batch Operations\nUpdate multiple properties atomically:\n\n```bash\ncurl -X PUT http://localhost:8080/api/properties/batch \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"atomic\": true,\n    \"properties\": [\n      {\"name\": \"playerHP\", \"value\": 999},\n      {\"name\": \"playerMP\", \"value\": 999},\n      {\"name\": \"playerLevel\", \"value\": 50}\n    ]\n  }'\n```\n\n### Event Triggers\nAutomate responses to game state changes:\n\n```cue\nevents: {\n    custom: {\n        lowHealth: {\n            trigger: \"properties.playerHP \u003c 20\"\n            action: \"log('Warning: Low health!')\"\n            dependencies: [\"playerHP\"]\n        }\n    }\n}\n```\n\n## 🤝 Contributing\n\nRetroGameAnalysis is designed to be extensible and community-driven:\n\n1. **Mapper Development** - Create mappers for new games\n2. **Feature Enhancement** - Add new property types and transformations\n3. **UI Improvements** - Build better interfaces and visualizations\n4. **Driver Support** - Add support for other emulators\n5. **Documentation** - Improve guides and examples\n\n## 🙏 Acknowledgments\n\n- **RetroArch Team** - For the excellent emulation platform\n- **CUE Language** - For the powerful configuration system\n- **Go Community** - For the robust ecosystem\n\n---\n\n**Ready to enhance your retro gaming experience?** 🎮✨\n\nVisit the web interface at `http://localhost:8080` after starting the server to explore your game's memory in real-time!\n\n## Known Bugs\n\n- Not all values are correct in Pokemon Red and Blue Version (WIP)\n- Pokemon Stadium is a proof of concept that this works with Mugen-Plus Core, all data is incorrect.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frpdevjesco%2Fretrogameanalysis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frpdevjesco%2Fretrogameanalysis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frpdevjesco%2Fretrogameanalysis/lists"}