yaze/docs/networking.md

Networking and Collaboration

Version: 0.2.0-alpha Last Updated: October 5, 2025

1. Overview

This document provides a comprehensive overview of the networking, collaboration, and remote access features within the z3ed ecosystem. These systems are designed to enable everything from real-time collaborative ROM hacking to powerful AI-driven remote automation.

The architecture is composed of three main communication layers:

1. WebSocket Protocol: A real-time messaging layer for multi-user collaboration, managed by the yaze-server.
2. gRPC Service: A high-performance RPC layer for programmatic remote ROM manipulation, primarily used by the z3ed CLI and automated testing harnesses.
3. Collaboration Service: A high-level C++ API within the YAZE application that integrates version management with the networking protocols.

2. Architecture

2.1. System Diagram

┌─────────────┐         WebSocket          ┌──────────────┐
│  yaze app   │◄────────────────────────────►│ yaze-server  │
│  (GUI)      │                             │  (Node.js)   │
└─────────────┘                             └──────────────┘
       ▲                                            ▲
       │ gRPC (for GUI testing)                     │ WebSocket
       │                                            │
       └─────────────┐                              │
                     │                              │
              ┌──────▼──────┐                       │
              │  z3ed CLI   │◄──────────────────────┘
              │             │
              └─────────────┘

2.2. Core Components

The collaboration system is built on two key C++ components:

1. ROM Version Manager (app/net/rom_version_manager.h)

   • Purpose: Protects the ROM from corruption and unwanted changes.
   • Features:
     • Automatic periodic snapshots and manual checkpoints.
     • "Safe points" to mark host-verified versions.
     • Corruption detection and automatic recovery to the last safe point.
     • Ability to roll back to any previous version.

2. Proposal Approval Manager (app/net/rom_version_manager.h)

   • Purpose: Manages a collaborative voting system for applying changes.
   • Features:
     • Multiple approval modes: Host-Only (default), Majority, and Unanimous.
     • Automatically creates snapshots before and after a proposal is applied.
     • Handles the submission, voting, and application/rejection of proposals.

3. Collaboration Panel (app/gui/widgets/collaboration_panel.h)

   • Purpose: Provides a dedicated UI within the YAZE editor for managing collaboration.
   • Features:
     • Version history timeline with one-click restore.
     • ROM synchronization tracking.
     • Visual snapshot gallery.
     • A voting and approval interface for pending proposals.

3. Protocols

3.1. WebSocket Protocol (yaze-server v2.0)

Used for real-time, multi-user collaboration.

Connection:

const ws = new WebSocket('ws://localhost:8765');

Message Types:

Type	Sender	Payload Description
host_session	Client	Initiates a new session with a name, username, and optional ROM hash.
join_session	Client	Joins an existing session using a 6-character code.
rom_sync	Client	Broadcasts a base64-encoded ROM diff to all participants.
proposal_share	Client	Shares a new proposal (e.g., from an AI agent) with the group.
proposal_vote	Client	Submits a vote (approve/reject) for a specific proposal.
snapshot_share	Client	Shares a snapshot (e.g., a screenshot) with the group.
proposal_update	Server	Broadcasts the new status of a proposal (approved, rejected).
proposal_vote_received	Server	Confirms a vote was received and shows the current vote tally.
session_hosted	Server	Confirms a session was created and returns its code.
session_joined	Server	Confirms a user joined and provides session state (participants, history).

3.2. gRPC Service (Remote ROM Manipulation)

Provides a high-performance API for programmatic access to the ROM, used by the z3ed CLI and test harnesses.

Status: ✅ Designed and Implemented. Pending final build system integration.

Protocol Buffer (protos/rom_service.proto):

service RomService {
  // Core
  rpc ReadBytes(ReadBytesRequest) returns (ReadBytesResponse);
  rpc WriteBytes(WriteBytesRequest) returns (WriteBytesResponse);
  rpc GetRomInfo(GetRomInfoRequest) returns (GetRomInfoResponse);

  // Overworld
  rpc ReadOverworldMap(ReadOverworldMapRequest) returns (ReadOverworldMapResponse);
  rpc WriteOverworldTile(WriteOverworldTileRequest) returns (WriteOverworldTileResponse);

  // Dungeon
  rpc ReadDungeonRoom(ReadDungeonRoomRequest) returns (ReadDungeonRoomResponse);
  rpc WriteDungeonTile(WriteDungeonTileRequest) returns (WriteDungeonTileResponse);

  // Proposals
  rpc SubmitRomProposal(SubmitRomProposalRequest) returns (SubmitRomProposalResponse);
  rpc GetProposalStatus(GetProposalStatusRequest) returns (GetProposalStatusResponse);

  // Version Management
  rpc CreateSnapshot(CreateSnapshotRequest) returns (CreateSnapshotResponse);
  rpc RestoreSnapshot(RestoreSnapshotRequest) returns (RestoreSnapshotResponse);
  rpc ListSnapshots(ListSnapshotsRequest) returns (ListSnapshotsResponse);
}

Use Case: Write with Approval via z3ed The z3ed CLI can submit a change as a proposal via gRPC and wait for a host to approve it in the YAZE GUI.

# 1. CLI connects and submits a proposal via gRPC
z3ed net connect --host server.example.com --port 50051
z3ed agent run --prompt "Make dungeon 5 harder" --submit-grpc-proposal

# 2. The YAZE GUI receives the proposal and the host approves it.

# 3. The z3ed CLI polls for the status and receives the approval.

4. Client Integration

4.1. YAZE App Integration

The CollaborationService provides a high-level API that integrates the version manager, approval manager, and WebSocket client.

#include "app/net/collaboration_service.h"

// High-level service that integrates everything
auto collab_service = std::make_unique<net::CollaborationService>(rom);

// Initialize with managers
collab_service->Initialize(config, version_mgr, approval_mgr);

// Connect and host
collab_service->Connect("localhost", 8765);
collab_service->HostSession("My Hack", "username");

// Submit local changes as a proposal to the group
collab_service->SubmitChangesAsProposal("Modified dungeon room 5", "username");

4.2. z3ed CLI Integration

The CLI provides net commands for interacting with the collaboration server.

# Connect to a collaboration server
z3ed net connect --host localhost --port 8765

# Join an existing session
z3ed net join --code ABC123 --username myname

# Submit an AI-generated change as a proposal and wait for it to be approved
z3ed agent run --prompt "Make boss room more challenging" --submit-proposal --wait-approval

# Manually check a proposal's status
z3ed net proposal status --id prop_123

5. Best Practices & Troubleshooting

Best Practices

• For Hosts: Enable auto-backups, mark safe points after playtesting, and use Host-Only approval mode for maximum control.
• For Participants: Submit all changes as proposals, wait for approval, and use descriptive names.
• For Everyone: Test changes in an emulator before submitting, make small atomic changes, and communicate with the team.

Troubleshooting

• "Failed to connect": Check that the yaze-server is running and the port is not blocked by a firewall.
• "Corruption detected": Use version_mgr->AutoRecover() or manually restore the last known safe point from the Collaboration Panel.
• "Snapshot not found": Verify the snapshot ID is correct and wasn't deleted due to storage limits.
• "SSL handshake failed": Ensure you are using a wss:// URL and that a valid SSL certificate is configured on the server.

6. Security Considerations

• Transport Security: Production environments should use WebSocket Secure (wss://) with a valid SSL/TLS certificate.
• Approval Security: Host-Only mode is the safest. For more open collaboration, consider a token-based authentication system.
• ROM Protection: The RomVersionManager is the primary defense. Always create snapshots before applying proposals and mark safe points often.
  • Rate Limiting: The yaze-server enforces a rate limit (default: 100 messages/minute) to prevent abuse.

7. Future Enhancements

• Encrypted WebSocket (WSS) support
• Diff visualization in UI
• Merge conflict resolution
• Branch/fork support for experimental changes
• AI-assisted proposal review
• Cloud snapshot backup
• Multi-host sessions
• Access control lists (ACLs)
• WebRTC for peer-to-peer connections
• Binary protocol for faster ROM syncs
• Automatic reconnection with exponential backoff
• Connection pooling for multiple sessions
• NAT traversal for home networks
• End-to-end encryption for proposals