@hytopia.com/server-protocol 1.4.0 → 1.4.1

package/exports.ts

@@ -1,3 +1,4 @@
+export * from './packets/bidirectional';
 export * from './packets/inbound';
 export * from './packets/outbound';
 export * from './packets/PacketCore';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hytopia.com/server-protocol",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -12,7 +12,8 @@
   },
   "dependencies": {
     "@hytopia.com/server-protocol": "^1.1.3",
-    "ajv": "^8.17.1"
+    "ajv": "^8.17.1",
+    "mediasoup": "^3.15.7"
   },
   "repository": {
     "type": "git",

package/packets/PacketCore.ts

@@ -39,6 +39,11 @@ export enum PacketId {
   UI_DATAS = 42,
   SCENE_UIS = 43,
   LIGHTS = 44,
+  PLAYERS = 45,
+
+  // Standard Bi-Directional Packet Types: 116 - 127 range
+  CONNECTION = 116,
+  HEARTBEAT = 117,
 
   // Debug Inbound Packet Types: 128 - 191 range
   DEBUG_CONFIG = 128,

package/packets/PacketDefinitions.ts

@@ -1,12 +1,13 @@
+import * as bidirectionalPackets from './bidirectional';
 import * as inboundPackets from './inbound';
 import * as outboundPackets from './outbound';
 import type { PacketId, AnyPacket, AnyPacketDefinition, IPacket } from './PacketCore';
 
-export { inboundPackets, outboundPackets };
+export { bidirectionalPackets, inboundPackets, outboundPackets };
 
 export const registeredPackets = new Map<PacketId, AnyPacketDefinition>();
 
-const allPackets = { ...inboundPackets, ...outboundPackets };
+const allPackets = { ...bidirectionalPackets, ...inboundPackets, ...outboundPackets };
 
 for (const packet of Object.values(allPackets)) {
   if ('id' in packet && 'schema' in packet) {

package/packets/bidirectional/Connection.ts

@@ -0,0 +1,11 @@
+import { definePacket, PacketId } from '../PacketCore';
+import type { IPacket } from '../PacketCore';
+import { connectionSchema } from '../../schemas/Connection';
+import type { ConnectionSchema } from '../../schemas/Connection';
+
+export type ConnectionPacket = IPacket<typeof PacketId.CONNECTION, ConnectionSchema>;
+
+export const connectionPacketDefinition = definePacket(
+  PacketId.CONNECTION,
+  connectionSchema
+);

package/packets/bidirectional/Heartbeat.ts

@@ -0,0 +1,11 @@
+import { definePacket, PacketId } from '../PacketCore';
+import type { IPacket } from '../PacketCore';
+import { heartbeatSchema } from '../../schemas/Heartbeat';
+import type { HeartbeatSchema } from '../../schemas/Heartbeat';
+
+export type HeartbeatPacket = IPacket<typeof PacketId.HEARTBEAT, HeartbeatSchema>;
+
+export const heartbeatPacketDefinition = definePacket(
+  PacketId.HEARTBEAT,
+  heartbeatSchema
+);

package/packets/bidirectional/index.ts

@@ -0,0 +1,2 @@
+export * from './Connection';
+export * from './Heartbeat';

package/packets/outbound/Players.ts

@@ -0,0 +1,12 @@
+import { definePacket, PacketId } from '../PacketCore';
+import type { IPacket } from '../PacketCore';
+import { playersSchema } from '../../schemas/Players';
+import type { PlayersSchema } from '../../schemas/Players';
+import type { WorldTick } from '../PacketCore';
+
+export type PlayersPacket = IPacket<typeof PacketId.PLAYERS, PlayersSchema> & [WorldTick];
+
+export const playersPacketDefinition = definePacket(
+  PacketId.PLAYERS,
+  playersSchema,
+);

package/packets/outbound/index.ts

@@ -8,6 +8,7 @@ export * from './Entities';
 export * from './Lights';
 export * from './PhysicsDebugRender';
 export * from './PhysicsDebugRaycasts';
+export * from './Players';
 export * from './SceneUIs';
 export * from './SyncResponse';
 export * from './UI';

package/schemas/Audio.ts

@@ -5,6 +5,7 @@ import type { VectorSchema } from './Vector';
 export type AudioSchema = {
   i: number;        // audio id
   a?: string;       // audio uri
+  cd?: number;      // cutoff distance
   d?: number;       // duration
   de?: number;      // detune
   di?: number;      // distortion (0 to 1, or 1+)
@@ -26,6 +27,7 @@ export const audioSchema: JSONSchemaType<AudioSchema> = {
   properties: {
     i: { type: 'number' },
     a: { type: 'string', nullable: true },
+    cd: { type: 'number', nullable: true },
     d: { type: 'number', nullable: true },
     de: { type: 'number', nullable: true },
     di: { type: 'number', minimum: 0, nullable: true },

package/schemas/ChatMessage.ts

@@ -3,8 +3,9 @@ import type { JSONSchemaType } from 'ajv';
 import type { HexColorSchema } from './HexColor';
 
 export type ChatMessageSchema = {
-  m: string; // message
+  m: string;          // message
   c?: HexColorSchema; // color
+  p?: string;         // player id
 }
 
 export const chatMessageSchema: JSONSchemaType<ChatMessageSchema> = {
@@ -12,6 +13,7 @@ export const chatMessageSchema: JSONSchemaType<ChatMessageSchema> = {
   properties: {
     m: { type: 'string' },
     c: { ...hexColorSchema, nullable: true },
+    p: { type: 'string', nullable: true },
   },
   required: ['m'],
   additionalProperties: false,

package/schemas/Connection.ts

@@ -0,0 +1,188 @@
+import * as mediasoup from 'mediasoup';
+import { JSONSchemaType } from 'ajv';
+
+/**
+ * Types
+ */
+
+type WrtcConnectAck = {
+  i: string; // transport id
+}
+
+type WrtcDataChannel = {
+  i?: string;                              // data channel id (server -> client channel only)
+  pi?: string;                             // data producer id (server -> client channel only)
+  l: string;                               // label
+  s: mediasoup.types.SctpStreamParameters; // sctp stream parameters
+}
+
+type WrtcProduceDataAck = {
+  i: string; // producer id
+  l: string; // label, used for client reference of ack
+}
+
+type WrtcTransport = {
+  i: string;                          // transport id
+  f: 'cs' | 'sc';                     // data flow (cs: client -> server | sc: server -> client)
+  d: mediasoup.types.DtlsParameters;  // dtls parameters
+  ic: mediasoup.types.IceCandidate[]; // ice candidates
+  ip: mediasoup.types.IceParameters;  // ice parameters
+  s: mediasoup.types.SctpParameters;  // sctp parameters
+}
+
+type WrtcTransportConnect = {
+  i: string;                         // transport id
+  d: mediasoup.types.DtlsParameters; // dtls parameters
+}
+
+export type ConnectionSchema = {
+  i?: string;               // connection id          | server -> client  | on initial WS connection
+  c?: WrtcTransportConnect, // wrtc transport connect | client -> server  | 2nd wrtc packet
+  ca?: WrtcConnectAck,      // wrtc connect ack       | server -> client  | 3rd wrtc packet
+  d?: WrtcDataChannel[],    // wrtc data channels     | server <-> client | 1st wrtc packet s->c, 4th wrtc packet c->s
+  pa?: WrtcProduceDataAck,  // wrtc produce data ack  | server -> client  | 5th wrtc packet
+  t?: WrtcTransport[],      // wrtc transports        | server -> client  | 1st wrtc packet
+};
+
+/**
+ * Schemas
+ */
+
+const wrtcConnectAckSchema: JSONSchemaType<WrtcConnectAck> = {
+  type: 'object',
+  properties: {
+    i: { type: 'string' },
+  },
+  required: [ 'i' ],
+  additionalProperties: false,
+};
+
+const wrtcDtlsParametersSchema: JSONSchemaType<mediasoup.types.DtlsParameters> = {
+  type: 'object',
+  properties: {
+    role: { type: 'string', enum: [ 'auto', 'client', 'server' ], nullable: true },
+    fingerprints: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          algorithm: { type: 'string', enum: [ 'sha-1', 'sha-224', 'sha-256', 'sha-384', 'sha-512' ] },
+          value: { type: 'string' },
+        },
+        required: [ 'algorithm', 'value' ],
+      }
+    },
+  },
+  required: [ 'fingerprints' ],
+  additionalProperties: false,
+};
+
+const wrtcIceCandidateSchema: JSONSchemaType<mediasoup.types.IceCandidate> = {
+  type: 'object',
+  properties: {
+    foundation: { type: 'string' },
+    priority: { type: 'number' },
+    ip: { type: 'string' },
+    address: { type: 'string' },
+    protocol: { type: 'string', enum: [ 'udp', 'tcp' ] },
+    port: { type: 'number' },
+    type: { type: 'string', enum: [ 'host' ] },
+    tcpType: { type: 'string', enum: [ 'passive' ], nullable: true },
+  },
+  required: [ 'foundation', 'priority', 'ip', 'address', 'protocol', 'port', 'type' ],
+  additionalProperties: false,
+};
+
+const wrtcIceParametersSchema: JSONSchemaType<mediasoup.types.IceParameters> = {
+  type: 'object',
+  properties: {
+    usernameFragment: { type: 'string' },
+    password: { type: 'string' },
+    iceLite: { type: 'boolean', nullable: true },
+  },
+  required: [ 'usernameFragment', 'password' ],
+  additionalProperties: false,
+};
+
+const wrtcProduceDataAckSchema: JSONSchemaType<WrtcProduceDataAck> = {
+  type: 'object',
+  properties: {
+    i: { type: 'string' },
+    l: { type: 'string' },
+  },
+  required: [ 'i', 'l' ],
+  additionalProperties: false,
+};
+
+const wrtcSctpParametersSchema: JSONSchemaType<mediasoup.types.SctpParameters> = {
+  type: 'object',
+  properties: {
+    port: { type: 'number' },
+    OS: { type: 'number' },
+    MIS: { type: 'number' },
+    maxMessageSize: { type: 'number' },
+  },
+  required: [ 'port', 'OS', 'MIS', 'maxMessageSize' ],
+  additionalProperties: true, // May be an SCTPParametersDump
+};
+
+const wrtcSctpStreamParametersSchema: JSONSchemaType<mediasoup.types.SctpStreamParameters> = {
+  type: 'object',
+  properties: {
+    streamId: { type: 'number' },
+    ordered: { type: 'boolean', nullable: true },
+    maxPacketLifeTime: { type: 'number', nullable: true },
+    maxRetransmits: { type: 'number', nullable: true },
+  },
+  required: [ 'streamId' ],
+  additionalProperties: false,
+};
+
+const wrtcTransportSchema: JSONSchemaType<WrtcTransport> = {
+  type: 'object',
+  properties: {
+    i: { type: 'string' },
+    f: { type: 'string', enum: [ 'cs', 'sc' ] },
+    ip: wrtcIceParametersSchema,
+    ic: { type: 'array', items: wrtcIceCandidateSchema },
+    d: wrtcDtlsParametersSchema,
+    s: wrtcSctpParametersSchema,
+  },
+  required: [ 'i', 'f', 'ip', 'ic', 'd', 's' ],
+  additionalProperties: false,
+};
+
+const wrtcTransportConnectSchema: JSONSchemaType<WrtcTransportConnect> = {
+  type: 'object',
+  properties: {
+    i: { type: 'string' },
+    d: wrtcDtlsParametersSchema,
+  },
+  required: [ 'i', 'd' ],
+  additionalProperties: false,
+};
+
+const wrtcDataChannelSchema: JSONSchemaType<WrtcDataChannel> = {
+  type: 'object',
+  properties: {
+    i: { type: 'string', nullable: true },
+    pi: { type: 'string', nullable: true },
+    l: { type: 'string' },
+    s: wrtcSctpStreamParametersSchema,
+  },
+  required: [ 'l', 's' ],
+  additionalProperties: false,
+};
+
+export const connectionSchema: JSONSchemaType<ConnectionSchema> = {
+  type: 'object',
+  properties: {
+    i: { type: 'string', nullable: true },
+    c: { ...wrtcTransportConnectSchema, nullable: true },
+    ca: { ...wrtcConnectAckSchema, nullable: true },
+    d: { type: 'array', items: { ...wrtcDataChannelSchema }, nullable: true },
+    pa: { ...wrtcProduceDataAckSchema, nullable: true },
+    t: { type: 'array', items: { ...wrtcTransportSchema }, nullable: true },
+  },
+  additionalProperties: false,
+};

package/schemas/Entity.ts

@@ -1,7 +1,9 @@
 import { rgbColorSchema } from './RgbColor';
+import { modelNodeOverrideSchema } from './ModelNodeOverride';
 import { quaternionSchema } from './Quaternion';
 import { vectorSchema } from './Vector';
 import type { JSONSchemaType } from 'ajv';
+import type { ModelNodeOverrideSchema } from './ModelNodeOverride';
 import type { QuaternionSchema } from './Quaternion';
 import type { RgbColorSchema } from './RgbColor';
 import type { VectorSchema } from './Vector';
@@ -14,11 +16,9 @@ export type EntitySchema = {
   as?: string[];                  // model animations stop
   bh?: VectorSchema;              // block half extents
   bt?: string;                    // block texture uri
-  c?: boolean;                    // controlled
-  cf?: string;                    // control function for client prediction
-  cs?: object;                    // control function state for client prediction
   h?: string[];                   // model parts to hide
   m?: string;                     // model uri
+  mo?: ModelNodeOverrideSchema[]; // model node overrides
   n?: string;                     // name
   o?: number;                     // opacity
   p?: VectorSchema;               // position
@@ -40,11 +40,9 @@ export const entitySchema: JSONSchemaType<EntitySchema> = {
     as: { type: 'array', items: { type: 'string' }, nullable: true },
     bh: { ...vectorSchema, nullable: true },
     bt: { type: 'string', nullable: true },
-    c: { type: 'boolean', nullable: true },
-    cf: { type: 'string', nullable: true },
-    cs: { type: 'object', nullable: true },
     h: { type: 'array', items: { type: 'string' }, nullable: true },
     m: { type: 'string', nullable: true },
+    mo: { type: 'array', items: { ...modelNodeOverrideSchema }, nullable: true },
     n: { type: 'string', nullable: true },
     o: { type: 'number', nullable: true },
     p: { ...vectorSchema, nullable: true },

package/schemas/Heartbeat.ts

@@ -0,0 +1,8 @@
+import type { JSONSchemaType } from 'ajv';
+
+export type HeartbeatSchema = null;
+
+export const heartbeatSchema: JSONSchemaType<HeartbeatSchema> = {
+  type: 'null',
+  nullable: true,
+}

package/schemas/Input.ts

@@ -30,6 +30,7 @@ export type InputSchema = {
   mr?: boolean; // mouse right pressed
   cp?: number;  // camera pitch radians
   cy?: number;  // camera yaw radians
+  sq?: number;  // sequence number for UDP inputs
 }
 
 export const inputSchema: JSONSchemaType<InputSchema> = {
@@ -64,6 +65,7 @@ export const inputSchema: JSONSchemaType<InputSchema> = {
     mr: { type: 'boolean', nullable: true },
     cp: { type: 'number', nullable: true },
     cy: { type: 'number', nullable: true },
+    sq: { type: 'number', nullable: true },
   },
   additionalProperties: false,
 }

package/schemas/ModelNodeOverride.ts

@@ -0,0 +1,26 @@
+import { rgbColorSchema } from './RgbColor';
+import type { JSONSchemaType } from 'ajv';
+import type { RgbColorSchema } from './RgbColor';
+
+export type ModelNodeOverrideSchema = {
+  n: string;          // node name match
+  h?: boolean;        // hidden
+  o?: number;         // opacity
+  r?: boolean;        // reset override to defaults
+  s?: number;         // scale
+  t?: RgbColorSchema; // tint color
+}
+
+export const modelNodeOverrideSchema: JSONSchemaType<ModelNodeOverrideSchema> = {
+  type: 'object',
+  properties: {
+    n: { type: 'string' },
+    h: { type: 'boolean', nullable: true },
+    o: { type: 'number', minimum: 0, maximum: 1, nullable: true },
+    r: { type: 'boolean', nullable: true },
+    s: { type: 'number', nullable: true },
+    t: { ...rgbColorSchema, nullable: true },
+  },
+  required: [ 'n' ],
+  additionalProperties: false,
+}

package/schemas/Player.ts

@@ -0,0 +1,20 @@
+import type { JSONSchemaType } from 'ajv';
+
+export type PlayerSchema = {
+  i: string;    // player id
+  p?: string;   // profile picture url
+  rm?: boolean; // removed/left game
+  u?: string;   // username
+}
+
+export const playerSchema: JSONSchemaType<PlayerSchema> = {
+  type: 'object',
+  properties: {
+    i: { type: 'string' },
+    p: { type: 'string', nullable: true },
+    rm: { type: 'boolean', nullable: true },
+    u: { type: 'string', nullable: true },
+  },
+  required: [ 'i' ],
+  additionalProperties: false,
+}

package/schemas/Players.ts

@@ -0,0 +1,10 @@
+import { playerSchema } from './Player';
+import type { JSONSchemaType } from 'ajv';
+import type { PlayerSchema } from './Player';
+
+export type PlayersSchema = PlayerSchema[];
+
+export const playersSchema: JSONSchemaType<PlayersSchema> = {
+  type: 'array',
+  items: { ...playerSchema },
+}

package/schemas/World.ts

@@ -13,6 +13,7 @@ export type WorldSchema = {
   dp?: VectorSchema;   // directional light position
   n?: string;          // name
   s?: string;          // skyboxUri
+  si?: number;         // skybox intensity
   t?: number;          // timestep (seconds)
 };
 
@@ -27,6 +28,7 @@ export const worldSchema: JSONSchemaType<WorldSchema> = {
     dp: { ...vectorSchema, nullable: true },
     n: { type: 'string', nullable: true },
     s: { type: 'string', nullable: true },
+    si: { type: 'number', nullable: true },
     t: { type: 'number', nullable: true },
   },
   required: [ 'i' ],

package/schemas/index.ts

@@ -9,16 +9,21 @@ export * from './ChatMessage';
 export * from './ChatMessages';
 export * from './Chunk';
 export * from './Chunks';
+export * from './Connection';
 export * from './DebugConfig';
 export * from './Entity';
 export * from './Entities';
+export * from './Heartbeat';
 export * from './HexColor';
 export * from './Input';
 export * from './Light';
 export * from './Lights';
+export * from './ModelNodeOverride';
 export * from './PhysicsDebugRaycast';
 export * from './PhysicsDebugRaycasts';
 export * from './PhysicsDebugRender';
+export * from './Player';
+export * from './Players';
 export * from './Quaternion';
 export * from './RgbColor';
 export * from './SceneUI';