Networked Shared
Sessions

What this system is designed to solve

Today, an emulator usually assumes its input devices and display are attached to the same computer. Networked Shared Sessions extends Phlegmulator so people on other computers can see the running emulated machine, hear its audio, and operate assigned controls over a local network or the internet.

The host runs the emulator. Guests do not run an independent copy of the emulated hardware; instead, their keyboards, gamepads, joysticks, and other devices are converted into authorized virtual input signals at the host.

Because there is only one emulated machine, all users interact with the same memory contents, running program, and game or application. A guest may experience slightly more video delay than another guest because of network conditions, but the underlying machine state is shared and authoritative.

How the pieces connect

A session is tied to a running emulator instance, not merely to a downloadable machine definition. The existing Hosted Definitions feature remains separate: it discovers or downloads machine definitions, while Network Sessions finds and joins active emulation sessions.

Multiple physical devices, one virtual hardware interface

Clients can attach keyboards, mice, digital/analog joysticks, modern gamepads, touch controls, and machine-specific peripherals where the selected machine supports them. One client may contribute more than one device. Devices receive session-scoped identifiers, so two guests with identical controllers are not confused.

Controller capacity depends on the emulated machine and its configured peripherals, not on the number of people allowed to connect. For instance, two standard SNES controller ports do not automatically become four ports because four guests joined. A data-defined multitap can legitimately expand hardware capacity.

Keep machine behavior in .phlegm definitions

The network layer should be generic. It must not include special cases for the Commodore keyboard, NES controller shift registers, or SNES ports. Instead, the machine's existing or extended .phlegm files describe the input hardware, while a separate mapping layer translates remote physical devices into those hardware interfaces.

Illustrative design schema — NOT existing .phlegm syntax

machine.input_interfaces:
  keyboard:
    type: matrix
    source: <machine-defined matrix and scan rules>
  controller_port_1:
    compatible_devices: <defined controller types>
    source: <machine-defined electrical/register behavior>
  controller_port_2:
    compatible_devices: <defined controller types>
    source: <machine-defined electrical/register behavior>

session.assignments:
  guest-A/gamepad-0: controller_port_1
  guest-B/gamepad-0: controller_port_2
  guest-C/keyboard-0: keyboard

The example expresses the division of responsibility. The actual serialization must match PHLEGM v10's real definition grammar and compiler/runtime interfaces.

What happens when two people control the same device?

For each emulated input device, the host maintains an authoritative current state. Inputs may be assigned exclusively to one user, shared among several users, or not assigned at all for spectators.

Button presses should be tracked per contributing device. If Guest A holds a key and Guest B releases the same key, the combined key should remain held until A also releases it. On disconnect, revocation, or device reassignment, the host removes only that contributor's held states—preventing stuck keys without erasing another user's input.

Live display visible to every shared user

The host captures the emulator's completed framebuffer or equivalent final video surface after emulated video hardware has produced a frame. That image is sent to a media encoder, distributed to connected clients, and displayed in their viewing windows.

This is not desktop screen sharing. Remote users should not see the host's unrelated windows, notifications, other monitors, or private applications. They see only the designated emulated display.

• Same content: everyone views output from the same host machine state. Individual playback delay may differ by client.
• Native image behavior: retain the machine's aspect ratio, refresh characteristics, pixel geometry, and display timing. Do not stretch a 4:3 framebuffer into 16:9 by default.
• Client scaling: each guest independently chooses windowed/fullscreen and nearest-neighbor or other supported scaling.
• Spectators included: a guest without an input assignment still receives video and, if enabled, audio.
• Adaptive quality: lower the transmitted resolution, bitrate, or streamed frame rate for poor connections without altering emulated CPU/PPU timing.
• No stale backlog: if a viewer falls behind, skip old network video frames instead of delaying the host machine.

Share the APU output alongside video

The completed mixed audio from the emulated APU is routed to local playback as usual and, independently, into a network audio encoder. Opus is a sensible candidate for interactive network playback; the exact codec and integration should follow the selected native media stack.

Each guest should have a local volume/mute control. Host-generated audio/video presentation timestamps keep sound aligned with the corresponding emulated display. A small bounded client jitter buffer can smooth network variation, with a user-selectable tradeoff between delay and stability.

For systems with no audio device or when sound sharing is disabled, the rest of the shared session continues to work. Remote audio must not block the emulated APU or change its timing.

Different traffic needs different handling

Recommended transport: evaluate a native WebRTC implementation for encrypted media, data channels, and NAT traversal. WebRTC is a design recommendation, not a claim that PHLEGM already includes this functionality. Other native transports are possible if they satisfy the latency and security requirements.

LAN: permit directly joined hosts and optional local discovery. Internet: use signaling plus ICE/STUN/TURN where needed for connections across routers and firewalls. A relay may be required on restrictive networks. Session discovery services do not need to execute the emulated machine.

A native client should require no JavaScript in the emulator's runtime path. An optional browser client would naturally use browser technologies for media and controller access, but must not dictate the native implementation.

Handling latency without breaking emulation

Client inputs arrive later than local inputs; that delay cannot be eliminated entirely over the internet. The design goal is to minimize it, avoid stale input, and preserve hardware-accurate polling on the host.

1. Client detects a change. Button, axis, keyboard, or pointer state changes are converted using the active device mapping.
2. Client sends a numbered state update. Include session/device identity, assignment generation, sequence number, and input values; client timestamp is useful for diagnostics but not trusted as authoritative host time.
3. Host checks permission and freshness. Reject invalid, obsolete, duplicate, oversize, or unauthorized data before it reaches the emulated machine.
4. Host applies input at a defined boundary. Update the virtual device state at the normal point where the emulated hardware reads or latches control signals, without waiting for an acknowledgment.
5. Host streams the result. The next relevant video/audio output is captured and sent to viewers with presentation timestamps.

Conceptual input-state message
{
  protocol_version: 1,
  session_id:   <opaque session ID>,
  device_id:    <connection-scoped ID>,
  assignment_revision: <number>,
  sequence:     <increasing number>,
  buttons:      <bitset>,
  axes:         <normalized values>,
  pointer:      <optional motion/position>,
  client_time:  <diagnostic monotonic timestamp>
}

Authentication: established secure connection, NOT claimed fields.

Send immediate state changes plus periodic snapshots for loss recovery. When a connection ends or an input lease expires, the host releases that participant's contributions. Keep jitter/input queues bounded. Avoid rollback or speculative emulation in the first version; those techniques introduce complexity and can be assessed later if measurements justify them.

New Network Sessions interface

Add a Network Sessions area to Phlegmulator, clearly separate from Hosted Definitions. The host can start a session, generate an invitation, view participants, grant input access, assign controller ports, toggle audio/video sharing, and end the session. Guests can discover or join a session, inspect device mappings, adjust their own viewer settings, and leave.

Access rule: a client given input permissions should automatically receive the session's live display. Otherwise, they would be operating a machine whose response they cannot see. A policy that deliberately disables display sharing should also disable remote interactive control or clearly reject the configuration.

Let guests control hardware, not the host computer

The host is always the authority for joining, device assignment, role changes, resets, and other privileged operations. Each connection has an authenticated session identity with an explicit role. Invitations should be unguessable, revocable and preferably time-limited.

• Encrypt traffic; verify authenticated peers and message integrity.
• Allow spectators without implicitly granting input.
• Require explicit host authorization before enabling any remote device control.
• Validate input payload lengths, device types, assignment revisions, and update rates.
• Reject remote commands that attempt filesystem access, script execution, arbitrary memory changes, or compiler control.
• Do not send ROMs, cartridge/program images, machine files, or unrelated host data just to enable viewing.
• Expose only the emulated framebuffer and optional audio—not the entire desktop.

Keep network work off the emulation hot path

PHLEGM's interpreter, microcode execution, and hardware timing should not wait on internet traffic. Network functions should be connected by bounded, nonblocking queues and independently scheduled workers. The following responsibilities are logical partitions, not a requirement to create exactly six operating-system threads.

For small groups, encode one suitable common stream and fan it out rather than encoding identical output separately for each user. If guests have vastly different bandwidth, add a small number of quality tiers or adaptive layers. Large spectator audiences could later use a relay/SFU rather than multiplying the host's upload load indefinitely.

Build it in measurable phases

Phases are a proposed development sequence, not a statement that these components are already implemented.

What would prove the design works?

Representative machine tests should include a Commodore PET keyboard matrix, Commodore 64 keyboard/joystick, NES dual controllers, and SNES controllers with and without a data-defined multitap. These test targets must use real machine definitions rather than hand-built networking shortcuts.

One machine. Many operators. A shared view.

The architecture separates emulated hardware behavior from remote device transport and audiovisual distribution. That separation is what keeps the feature scalable, reusable, and consistent with PHLEGM v10's data-driven design.

Remote users connect to a session, watch the host's actual emulated display, hear its audio if enabled, and provide inputs that the host maps to ordinary virtual hardware ports. The host remains authoritative, handles conflicts and permissions, and never lets media encoding or networking interrupt execution.

Status: design explanation only. This document does not modify PHLEGM v10 source code, define final wire protocols, or claim networking support already exists.