EC Gaming

EC Gaming turns live ECG and chest-motion signals into browser games. The first game, Heartbeat Flight, is a low-poly airplane experience that runs as a normal 3D web app and can enter immersive WebXR on a compatible headset.

Play Heartbeat Flight · Protocol · Hardware validation

How it works

The primary station is one page with two views and one continuous runtime:

1. Ground Control view selects exactly one cardiac-signal authority, configures metric mappings and personal-range normalization, shows signal readiness, and grants or withholds runway clearance.
2. Cockpit view runs the airplane in the same page and can enter immersive WebXR. Switching views does not create a second acquisition or mapping owner: Cockpit receives the normalized FlightFrame produced by Ground Control.

Ground Control can use either a worn Polar H10 connected directly to that browser or a recognized Ground Control beacon from another browser. The direct source owns Bluetooth, local ECG and 200 Hz accelerometer processing, derived heart/breathing metrics, and beat detection. The beacon source carries derived metrics and beat timing over a data-only VDO.Ninja/WebRTC channel so the receiving Ground Control can apply its own mappings. The two sources are mutually exclusive and are never blended.

Two additional paths remain available:

• Smartphone Flight combines Polar acquisition and the touch-friendly game in one browser tab. A compatible Android browser connects directly to a worn Polar H10; raw ECG and derived controls stay on that phone. The main unified Ground Control/Cockpit route is responsive on the same browsers as well.
• Standalone Flight Deck is the compatibility receiver for normalized ecgflightv1 commands. It works in a normal browser, iPhone/iPad, or Meta Quest Browser and never requests Bluetooth, camera, or microphone access.

Unified local: Polar H10 ──Bluetooth──▶ Ground Control ⇄ Cockpit
                raw ECG stays local       map + play in one page

Beacon:       Polar H10 ──Bluetooth──▶ Ground Control A ──WebRTC data──▶ Ground Control B ⇄ Cockpit
                                           derived metrics + beats only    map + play locally

Commands:     Polar H10 ──Bluetooth──▶ Ground Control ──WebRTC data──▶ Standalone Flight Deck
                                           normalized commands             flat 3D / WebXR

Direct phone pairing is feature-detected, requires HTTPS, and must begin with the Connect Polar H10 tap. Chrome for Android and compatible Chromium-based Android browsers are the supported path. Safari/WebKit does not expose native Web Bluetooth, so iPhone and iPad use Flight Deck with Ground Control running on another supported device. The deterministic simulator remains available on every browser and is always labelled simulated.

All direct-capable front ends use one central browser connector module and its versioned ecgaming-polar-hub-v1 ownership protocol. Only that hub may instantiate the raw H10 adapter. It prevents duplicate sessions within a page, announces a fresh owner across ECGaming tabs, and uses an exclusive Web Lock as the race-proof authority. The protocol shares low-rate health/readiness status, never raw ECG or accelerometer samples.

The fixed discovery room is ecgaming_flight_v1. It is public and unauthenticated. Anonymous random source IDs and the signal-beacon session token fence accidental cross-session packets, but they are not authentication or access control. Do not transmit sensitive data or use a source you do not recognize. A remote physicalPolar flag is an unauthenticated source claim, not proof of device identity.

Ground Control and Cockpit views

The view switch changes presentation, not authority. Ground Control remains the owner of source selection, calibration, mappings, smoothing, readiness, transport, and optional logging. Cockpit owns the game lifecycle and presentation only. Returning to Ground Control pauses the visible cockpit while preserving the selected signal session; starting or resuming flight never creates a hidden simulator or manual fallback.

Start Cockpit Flight is fail-closed. Runway clearance requires a live selected source, a physical Polar ECG sample no more than two seconds old (or an equally fresh validated beacon), physical-Polar provenance, a fresh and ready selected heart or breathing metric, completed adaptive calibration when enabled, the selected beat source when used, and a valid aircraft. A derived-metric remote source additionally needs a validated signal-beacon configuration; the legacy command-only path requires a validated flight configuration and sender readiness. Simulation can preview mappings and interface behavior, but it cannot grant production flight clearance.

When Direct Polar is selected, the avionics display is a real rolling ECG waveform from local PMD samples. When a beacon is selected, no waveform samples exist on the receiver; the display is explicitly labelled Remote Beacon / Derived Telemetry and plots a command/telemetry trace instead of claiming to show ECG.

Controls and signal mapping

Phone / tablet tilt controller: click the dedicated Phone steering widget in Ground Control and scan its QR code. The phone connects automatically with tilt selected and centres on its first valid reading. Hold it sideways with both hands. A scalable, text-free SVG yoke has a live attitude instrument and a heart-rate connection icon. If motion permission needs a gesture, a hand symbol prompts a tap on the instrument. Tap it again to recenter. Tilt left/right to steer the airplane on the other screen; tip forward/back to trim speed. Ground Control can disable phone speed control. Heart/breathing still controls altitude. Dragging the grips steers in touch fallback when motion is unavailable. The same pairing action is under Flight options in the standalone and mobile game views. For a shared flight session, pair from Ground Control: Flight settings → Pair separate cockpit opens a third browser, and ECG source selects Ground Control, phone, or cockpit. The yoke and session cockpit each have Connect Polar H10. The selected H10 browser computes the tower's mappings locally; only normalized flight controls and readiness are relayed. Direct H10 access requires a browser with Web Bluetooth; other browsers can still steer or display the cockpit. Source/mapping changes revoke old controls, and signal loss holds flight until recovery. Both devices need Internet; no installation is needed. See Phone tilt controller for pairing, lifecycle, and validation.

Ground Control exposes one-open-at-a-time aviation panels for the direct Polar or beacon source, flight commands, broadcast tower, and test simulator. Smartphone Flight exposes the core choices in a touch-friendly side drawer. Each continuous command can use a derived metric or a manual value, with input range, reversal, and attack/release smoothing.

The altitude card starts with large heart and breath instrument buttons. Heart control exposes all ECG, HR, RR, HRV, and excitement metrics; breath control selects Polar Stream's source-timed breathing_volume compatibility metric. That metric uses 200 Hz H10 chest acceleration, a 12-second X+Z PCA calibration, causal filtering, explicit freshness/readiness, and a bounded 0…1 output. It is an experimental respiratory-motion/effort surrogate—not lung volume, airflow, respiratory rate, or a clinical measure. Strap mounting and movement can change its polarity or quality.

Each metric binding has a normalization mode. Fixed mode uses the configured low/high bounds. Adaptive mode learns a separate observed minimum and maximum for that metric and source session, then maps the learned range to 0…1; altitude converts that result to -1…1. Adaptive output remains unavailable until its minimum sample count, warmup time, and metric-specific minimum span are all satisfied. Learned ranges reset when the source session or policy changes and can be reset explicitly, so one wearer or beacon never silently inherits another session's calibration. The current personal-range control applies to the selected altitude metric; the binding contract keeps normalization per metric for future games and controls.

Command	Default	Game range
Altitude	Excite-O-Meter excitement score	-1…1
Throttle	Manual 0.5	8–14 world units/second
Traffic	Manual 0.5	one ring every 10–3 seconds
Heartbeat	Experimental ECG R-peak	visual and engine pulse

The optional heartbeat lift action replaces the continuous altitude target; the two vertical-control modes are mutually exclusive. Horizontal steering remains local. On desktop, use A/D, the arrow keys, touch drag, or a thumbstick. On Smartphone Flight and the phone-sized unified Cockpit, hold the large left or right button in the corresponding bottom corner. In immersive WebXR, continuous headset tilt is the primary steering input: tilt left or right to move and bank in that direction. Heartbeat Flight is an endless forward course, so steering moves the airplane laterally through the rings while the model banks and briefly yaws into the input; it does not change to an unrestricted compass heading.

Choose the airplane from Ground Control, the standalone Flight Deck, or the Smartphone Flight start menu. Ground Control presents the full catalog as a rotating 3D hangar carousel with previous/next controls, persistent selection, and a unique cardiac-themed callsign and tagline for every plane. On desktop, its fixed-width rail reserves explicit percentage zones for source controls, the hangar, and runway clearance; Pretext fits key labels to those cells instead of letting copy resize or push the panels around. Its primary actions use large, labelled ECG, radar, control-tower, and runway widgets so the control room remains playful and legible for younger pilots without hiding what a button does. The catalog contains the original ECGaming airplane plus redistributable models from OpenGameArt, Tiny Plane Asset Pack, Poly Pizza, and Magic Games, including all 15 Tiny Plane variants. Every selection is centered in a rotation-safe preview volume and uniformly scaled at runtime to stay within the ring's safe opening. ECGaming adds an animated project propeller where needed. SA Node Stinger instead animates the asset's correctly placed source rotor and removes its duplicate source node, avoiding the extra nose propeller.

Polar Heart Rate Service RR notifications are available as an alternate beat source. They can contain multiple intervals in one notification, so they are useful interval data but not guaranteed exact beat-arrival timing. The ECG R-peak path reconstructs the 130 Hz sample timestamps and applies a causal adaptive detector with a 250 ms refractory period and RR cross-check. It is experimental and not a medical detector.

Game rules

• Fly through a ring: +1 point.
• A successful pass triggers a bright score celebration in Cockpit and Smartphone Flight.
• Miss a ring: keep flying. There are no lives, penalties, or game-over interruption.
• If the selected local or network cardiac signal is absent for two seconds, play pauses instead of silently falling back to manual altitude or simulation.
• Integrated Cockpit requires three continuous ready seconds before resuming after a loss. The standalone Flight Deck first requires three fresh command frames, then shows its three-second resume countdown.
• Heartbeat events older than 250 ms are never replayed as late or stacked actions.

Optional Game Adapters

The app root opens the EC Games menu. Use Ground Control for the unified Heartbeat Flight hangar/cockpit flow, or choose an optional browser-game adapter directly while keeping signal ownership, upstream attribution, and licences visible:

• Pixel Hop Twins ECG edition is a vendored static snapshot of stm1978/retro-platformer at commit 9835295888c7cb8afa795ca2a31707a65167c2ea. Its MIT code and CC0 procedural sprites, audio, and levels are retained under games/pixel-hop/ and public/games/pixel-hop/. A fresh selected beat queues the game's normal buffered jump.
• MOTH heartbeat + dive trial is built from the user's English-only MOTH adaptation branch at commit a56fa97e7f8e2a6abb75634799e963d54ce4c750, based on ahmedallam222/moth-game. All five chapters are immediately selectable, and the repaired title moth keeps both wings attached throughout its flap animation. Fresh R-peaks jump on land. Underwater R-peak paddles are accepted only while fresh physical Polar ACC breathing input is at a stable calibrated upper crest. Keyboard, touch, and gamepad remain available as a safety fallback.

Open Ground Control, Smartphone Flight, or Flight Deck in one same-origin tab and the selected game in another. The acquisition tab publishes only a versioned beat event containing timing, confidence, readiness, and simulated/physical labels. It never publishes raw ECG or a Polar identifier. Keyboard controls remain available.

The source forks are GeorgeFejer91/retro-platformer and GeorgeFejer91/moth-game. See Game integrations for the adapter contract and limitations.

Run locally

Requirements: Node.js 22 or newer and a Chromium browser. Web Bluetooth needs HTTPS or localhost.

npm install
npm run dev

Then open the printed /ECGaming/ URL. Open Ground Control for the unified Ground Control/Cockpit flow, use Smartphone Flight for the dedicated phone flow, or use two tabs/devices with a broadcasting Ground Control first and either a receiving Ground Control or standalone Flight Deck second.

npm test          # codecs, mapping, detector, transport, rules, privacy
npm run test:browser
npm run build
npm run build:hosted # stage the hosted MOTH browser build

Use ?remote-force-turn=1 on both pages to request a TURN-relayed WebRTC path for qualification.

Data and privacy

• Raw ECG samples stay inside the browser connected to the Polar and are used only for the rolling preview and detector.
• In Smartphone Flight, raw ECG likewise stays in the current phone tab and is never sent to a relay room.
• The 32-byte realtime frame contains normalized altitude, throttle, traffic, beat counter/age, quality, and readiness flags.
• The current 92-byte ecgsignalv1 beacon contains only finite derived heart/breathing metrics, separate ECG/RR beat counters and ages, quality, and readiness/provenance flags. Receivers also accept the legacy 88-byte heart-only frame. Neither contains a raw sample array, device name, Bluetooth identifier, or participant identity.
• A versioned configuration snapshot is sent separately on a reliable ordered data channel.
• Session CSV logging is off by default, bounded in memory, and exported only by an explicit local download.
• Ground Control CSV contains derived metrics, bindings, commands, and beat events—not raw ECG.
• There is no backend, account, cloud upload, camera stream, microphone stream, or analytics service.

See the wire protocol for the exact contract.

Project structure

ground-control/        unified signal control and flat/WebXR cockpit views
flight/                standalone normalized-command compatibility receiver
mobile/                direct Polar + touch flight UI for phones
src/mobile.ts           local signal-to-game orchestration (no VDO.Ninja)
src/signals/           mappings, adaptive ranges, readiness, R-peak detector
src/protocol/          command/signal frames and VDO.Ninja transport
src/game/              reusable game module and Heartbeat Flight
src/logging/           opt-in bounded derived CSV
src/vendor/            BSD Affect Tracker signal code
public/assets/aircraft/ redistributable aircraft models in runtime GLB form
public/vendor/         MPL VDO.Ninja SDK and its notices
public/games/          attributed third-party game adapters and launchers
games/                 Vite entry points and adapted browser-game source
scripts/                reproducible aircraft conversion and preview helpers

EcgGameModule is the small game boundary intended for future ECG games, including a heartbeat-synchronized runner. Heartbeat Flight is v1; the runner is not included yet.

Status and scientific disclaimer

The software implementation and deterministic tests are complete. Physical Polar/Quest qualification requires the explicit gates in docs/HARDWARE-VALIDATION.md; this repository does not claim those hardware gates have passed until evidence is recorded there.

EC Gaming is for games, education, and research prototyping. It is not a medical device, does not diagnose or treat any condition, and must not be used for safety-critical control.

License and provenance

EC Gaming's original code and procedural assets are released under the BSD 3-Clause License. The optional aircraft catalog also includes redistributable CC0 and Creative Commons Attribution models. Those aircraft retain their own licenses and author credits; ECGaming's normalization and animated-propeller additions do not replace the source licenses. No Unity Asset Store/Synty assets or old unlicensed Unity game code are redistributed.

The Polar browser signal layer is reused from Affect Tracker under BSD-3-Clause. The vendored VDO.Ninja SDK remains MPL-2.0. Three.js is MIT. Self-hosted Inter and Barlow Condensed fonts are OFL-1.1. Full notices are in THIRD_PARTY_NOTICES.md.