@myerscarpenter/cast2-protocol

Pure TypeScript implementation of the Meta Quest Cast 2.0 binary protocol — XRSP framing, MGIK sub-headers, MUD message builders/parsers, pose math, and resolution presets.

Zero runtime dependencies. Works in Node.js ≥ 18.

Install

npm install @myerscarpenter/cast2-protocol

Quick Start

import {
  packXrsp,
  packMgikSub,
  buildInit,
  buildPose,
  buildConfig,
  createPoseState,
  updatePose,
  CAST_PORT,
  RESOLUTIONS,
} from "@myerscarpenter/cast2-protocol";

// Build an INIT command
const subMagic = 0xdeadbeef; // learned from Quest's first message
const payload = buildInit(subMagic, /* seq */ 0);
const frame = packXrsp(/* seq */ 0, payload);

// Pose management
let pose = createPoseState();
pose = updatePose(pose, { dYaw: 0.5, dForward: 1.0 });
const posePayload = buildPose(subMagic, 1, pose);

API Overview

XRSP (framing layer)

• packXrsp(seq, payload, flags?, topic?) — pack an XRSP frame
• parseXrspHeader(data) — parse 8-byte XRSP header
• xrspPayloadSize(header) — compute payload size from header

MGIK (sub-header)

• packMgikSub(subMagic, msgSeq) — pack 24-byte MGIK sub-header
• parseMgikSub(data) — parse MGIK sub-header
• detectSubMagic(payload) — detect sub_magic from Quest's initial message
• isMgikMagic(payload) — check for "MGIK" magic bytes

MUD (message builders)

• buildInit, buildConfig, buildKeepalive, buildShortAck
• buildPose, buildDisplayConfig, buildDisconnect
• buildSetProperty, buildVirtualMouse
• buildInputForwardingState, buildStartInputForwarding, buildActivateLayer
• buildMud — arbitrary MUD message
• parseLayerConfiguration — parse LayerConfiguration responses
• packMudString / parseMudString — length-prefixed string encoding

Pose Math

• createPoseState() — identity pose at origin
• eulerToQuat(yaw, pitch) — euler angles to quaternion
• updatePose(state, delta) — apply incremental movement
• setPoseOffset(state, offset) — set absolute offset
• screenToYawPitch(x, y, ...) — screen coordinates to yaw/pitch

Resolutions

• RESOLUTIONS — preset map (720p, 1080p, native)
• resolveResolution(name?, width?, height?) — resolve to width/height

Constants

All protocol constants are exported: CAST_PORT, QUEST_CAST_PORT, XRSP_HEADER_SIZE, MGIK_MAGIC, command IDs (CMD_POSE, CMD_INIT, etc.), eye selectors (EYE_LEFT, EYE_RIGHT, EYE_STEREO), layer types, and more.

Types

• XrspHeader, MgikSubHeader, LayerInfo
• PoseState, PoseDelta, PoseOffset
• Resolution

Documentation

Full protocol documentation is available at myers.github.io/quest-dev.

License

MIT