@hytopia.com/server-protocol 1.0.0

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@hytopia.com/server-protocol",
+  "version": "1.0.0",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "quicktype": "^23.0.170"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hytopiagg/server-protocol.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hytopiagg/server-protocol/issues"
+  },
+  "homepage": "https://github.com/hytopiagg/server-protocol#readme",
+  "description": ""
+}

package/packets/PacketTypes.ts

@@ -0,0 +1,67 @@
+import Ajv from '../shared/Ajv';
+import type { JSONSchemaType, ValidateFunction } from 'ajv';
+
+/*
+ * Packet types are numerically ordered relative to their use.
+ *
+ * Standard inbound/outbound packets must be within the id
+ * range of 0-127 to allow their numerical representation in
+ * msgpack'd format to be 1 byte - these packets are the most
+ * frequent and thus should be optimized for the smallest 
+ * representation.
+ * 
+ * Debug packets must be within the id range of 128-255 to
+ * allow their msgpack'd format to be 2 bytes - these packets
+ * are not packets used in typical or frequent gameplay and
+ * are acceptable to be represented with an additional byte
+ * in encoded format.
+ */
+
+export enum PacketType {
+  // Standard Inbound Packet Types: 0 - 31 range
+  HEARTBEAT = 0,
+  INPUT = 1,
+
+  // Standard Outbound Packet Types: 32 - 127 range
+  BLOCK = 32,
+  BLOCK_REGISTRY = 33,
+  BLOCK_TYPE = 34,
+  CHUNK = 35,
+  ENTITY = 36,
+
+  // Debug Inbound Packet Types: 128 - 191 range
+  // NONE atm, start at 128
+
+  // Debug Outbound Packet Types: 192 - 255 range
+  PHYSICS_DEBUG_RENDER = 192
+}
+
+/*
+ * Generators for packet definitions and validators.
+ */
+
+export interface IPacketDefinition<TId extends PacketType, TPayload> {
+  id: TId;
+  schema: JSONSchemaType<TPayload>;
+  validate: ValidateFunction<TPayload>;
+}
+
+export interface IPacket<TId extends PacketType, TPayload> {
+  id: TId;
+  payload: TPayload;
+}
+
+export const definePacket = <TId extends PacketType, TPayload>(
+  id: TId,
+  schema: JSONSchemaType<TPayload>,
+): IPacketDefinition<TId, TPayload> => ({
+  id,
+  schema,
+  validate: Ajv.instance.compile(schema),
+});
+
+// Represents any packet type
+export type AnyPacket = IPacket<PacketType, unknown>;
+
+// Represents any packet definition type
+export type AnyPacketDefinition = IPacketDefinition<number, unknown>;

package/packets/inbound/Heartbeat.ts

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

package/packets/inbound/Input.ts

@@ -0,0 +1,11 @@
+import { definePacket, PacketType } from '../PacketTypes';
+import type { IPacket } from '../PacketTypes';
+import { inputSchema } from '../../schemas/Input';
+import type { Input } from '../../schemas/Input';
+
+export type InputPacket = IPacket<typeof PacketType.INPUT, Input>;
+
+export const inputPacketDefinition = definePacket(
+  PacketType.INPUT,
+  inputSchema
+);

package/packets/index.ts

@@ -0,0 +1,26 @@
+import fs from 'fs';
+import path from 'path';
+
+const inboundPackets: Record<string, any> = {};
+const outboundPackets: Record<string, any> = {};
+
+const importPackets = async () => {
+  for (const directory of ['inbound', 'outbound']) {
+    const directoryPath = path.join(__dirname, directory);
+    const files = fs.readdirSync(directoryPath);
+
+    for (const file of files) {
+      if (file.endsWith('.ts')) {
+        const name = path.basename(file, '.ts');
+        const module = await import(`./${directory}/${name}`);
+        const typePackets = directory === 'inbound' ? inboundPackets : outboundPackets;
+        const lcfName = name.charAt(0).toLowerCase() + name.slice(1);
+        typePackets[`${lcfName}PacketDefinition`] = module[`${lcfName}PacketDefinition`];
+      }
+    }
+  }
+};
+
+await importPackets();
+
+export default { inboundPackets, outboundPackets };

package/packets/outbound/Block.ts

@@ -0,0 +1,11 @@
+import { definePacket, PacketType } from '../PacketTypes';
+import type { IPacket } from '../PacketTypes';
+import { blockSchema } from '../../schemas/Block';
+import type { Block } from '../../schemas/Block';
+
+export type BlockPacket = IPacket<typeof PacketType.BLOCK, Block>;
+
+export const blockPacketDefinition = definePacket(
+  PacketType.BLOCK,
+  blockSchema,
+);

package/packets/outbound/BlockRegistry.ts

@@ -0,0 +1,11 @@
+import { definePacket, PacketType } from '../PacketTypes';
+import type { IPacket } from '../PacketTypes';
+import { blockRegistrySchema } from '../../schemas/BlockRegistry';
+import type { BlockRegistry } from '../../schemas/BlockRegistry';
+
+export type BlockRegistryPacket = IPacket<typeof PacketType.BLOCK_REGISTRY, BlockRegistry>;
+
+export const blockRegistryPacketDefinition = definePacket(
+  PacketType.BLOCK_REGISTRY,
+  blockRegistrySchema,
+);

package/packets/outbound/BlockType.ts

@@ -0,0 +1,11 @@
+import { definePacket, PacketType } from '../PacketTypes';
+import type { IPacket } from '../PacketTypes';
+import { blockTypeSchema } from '../../schemas/BlockType';
+import type { BlockType } from '../../schemas/BlockType';
+
+export type BlockTypePacket = IPacket<typeof PacketType.BLOCK_TYPE, BlockType>;
+
+export const blockTypePacketDefinition = definePacket(
+  PacketType.BLOCK_TYPE,
+  blockTypeSchema,
+);

package/packets/outbound/Chunk.ts

@@ -0,0 +1,11 @@
+import { definePacket, PacketType } from '../PacketTypes';
+import type { IPacket } from '../PacketTypes';
+import { chunkSchema } from '../../schemas/Chunk';
+import type { Chunk } from '../../schemas/Chunk';
+
+export type ChunkPacket = IPacket<typeof PacketType.CHUNK, Chunk>;
+
+export const chunkPacketDefinition = definePacket(
+  PacketType.CHUNK,
+  chunkSchema,
+);

package/packets/outbound/Entity.ts

@@ -0,0 +1,11 @@
+import { definePacket, PacketType } from '../PacketTypes';
+import type { IPacket } from '../PacketTypes';
+import { entitySchema } from '../../schemas/Entity';
+import type { Entity } from '../../schemas/Entity';
+
+export type EntityPacket = IPacket<typeof PacketType.ENTITY, Entity>;
+
+export const entityPacketDefinition = definePacket(
+  PacketType.ENTITY,
+  entitySchema,
+);

package/packets/outbound/PhysicsDebugRender.ts

@@ -0,0 +1,11 @@
+import { definePacket, PacketType } from '../PacketTypes';
+import type { IPacket } from '../PacketTypes';
+import { physicsDebugRenderSchema } from '../../schemas/PhysicsDebugRender';
+import type { PhysicsDebugRender } from '../../schemas/PhysicsDebugRender';
+
+export type PhysicsDebugRenderPacket = IPacket<typeof PacketType.PHYSICS_DEBUG_RENDER, PhysicsDebugRender>;
+
+export const physicsDebugRenderPacketDefinition = definePacket(
+  PacketType.PHYSICS_DEBUG_RENDER,
+  physicsDebugRenderSchema,
+);

package/schemas/Block.ts

@@ -0,0 +1,20 @@
+import { vectorSchema } from './Vector';
+import type { JSONSchemaType } from 'ajv';
+import type { Vector } from './Vector';
+
+export type Block = {
+  wi: string; // world id
+  i: number;  // block id
+  c: Vector;  // coordinate
+};
+
+export const blockSchema: JSONSchemaType<Block> = {
+  type: 'object',
+  properties: {
+    wi: { type: 'string' },
+    i: { type: 'number' },
+    c: vectorSchema,
+  },
+  required: [ 'wi', 'i', 'c' ],
+  additionalProperties: false,
+}

package/schemas/BlockRegistry.ts

@@ -0,0 +1,21 @@
+import { blockTypeSchema } from './BlockType';
+import type { JSONSchemaType } from 'ajv';
+import type { BlockType } from './BlockType';
+
+export type BlockRegistry = {
+  wi: string;     // world id
+  b: BlockType[]; // block types
+}
+
+export const blockRegistrySchema: JSONSchemaType<BlockRegistry> = {
+  type: 'object',
+  properties: {
+    wi: { type: 'string' },
+    b: {
+      type: 'array',
+      items: blockTypeSchema,
+    }
+  },
+  required: [ 'wi', 'b' ],
+  additionalProperties: false,
+}

package/schemas/BlockType.ts

@@ -0,0 +1,28 @@
+import { colliderDescSchema } from './ColliderDesc';
+import type { JSONSchemaType } from 'ajv';
+import type { ColliderDesc } from './ColliderDesc';
+
+export type BlockType = {
+  wi: string;       // world id
+  i: number;        // block type id
+  d: boolean;       // delta
+  t?: string;       // textureUri
+  n?: string;       // name
+  c?: ColliderDesc; // collider desc
+  s?: boolean;      // is solid
+}
+
+export const blockTypeSchema: JSONSchemaType<BlockType> = {
+  type: 'object',
+  properties: {
+    wi: { type: 'string' },
+    i: { type: 'number' },
+    d: { type: 'boolean' },
+    t: { type: 'string', nullable: true },
+    n: { type: 'string', nullable: true },
+    c: { ...colliderDescSchema, nullable: true },
+    s: { type: 'boolean', nullable: true },
+  },
+  required: [ 'wi', 'i', 'd' ],
+  additionalProperties: false,
+}

package/schemas/Chunk.ts

@@ -0,0 +1,29 @@
+import { vectorSchema } from './Vector';
+import type { JSONSchemaType } from 'ajv';
+import type { Vector } from './Vector';
+
+export type Chunk = {
+  wi: string; // world id
+  c: Vector; // chunk coordinate [ 16n, 16n, 16n ]
+  b: Uint8Array | number[]; // block ids in chunk, 16^3 entries, registry block ids 1-255, 0 = none
+};
+
+export const chunkSchema: JSONSchemaType<Chunk> = {
+  type: 'object',
+  properties: {
+    wi: { type: 'string' },
+    c: vectorSchema,
+    b: {
+      type: 'array',
+      items: {
+        type: 'number',
+        minimum: 0,
+        maximum: 255
+      },
+      minItems: 4096,
+      maxItems: 4096
+    }
+  },
+  required: [ 'wi', 'c', 'b' ],
+  additionalProperties: false,
+}

package/schemas/Collider.ts

@@ -0,0 +1,16 @@
+import { colliderDescSchema } from './ColliderDesc';
+import type { JSONSchemaType } from 'ajv';
+import type { ColliderDesc } from './ColliderDesc';
+
+export type Collider = {
+  h?: number; // collider handle for rapier
+} & ColliderDesc;
+
+export const colliderSchema: JSONSchemaType<Collider> = {
+  type: 'object',
+  properties: {
+    h: { type: 'number', nullable: true },
+    ...colliderDescSchema.properties
+  },
+  additionalProperties: false,
+}

package/schemas/ColliderDesc.ts

@@ -0,0 +1,47 @@
+import { shapeSchema } from './Shape';
+import { quaternionSchema } from './Quaternion';
+import { vectorSchema } from './Vector';
+import type { JSONSchemaType } from 'ajv';
+import type { Shape } from './Shape';
+import type { Quaternion } from './Quaternion';
+import type { Vector } from './Vector';
+
+export type ColliderDesc = {
+  at?: number;    // active collision types
+  cg?: number;    // collision groups
+  cs?: number;    // contact skin
+  d?: number;     // density
+  f?: number;     // friction
+  fr?: number;    // friction combine rule
+  en?: boolean;   // enabled
+  sn?: boolean;   // sensor
+  m?: number;     // mass
+  re?: number;    // restitution
+  rer?: number;   // restitution combine rule
+  r?: Quaternion; // rotation
+  s?: Shape;      // shape
+  sg?: number;    // solver groups
+  t?: Vector;     // translation
+}
+
+export const colliderDescSchema: JSONSchemaType<ColliderDesc> = {
+  type: 'object',
+  properties: {
+    at: { type: 'number', nullable: true },
+    cg: { type: 'number', nullable: true },
+    cs: { type: 'number', nullable: true },
+    d: { type: 'number', nullable: true },
+    f: { type: 'number', nullable: true },
+    fr: { type: 'number', nullable: true },
+    en: { type: 'boolean', nullable: true },
+    sn: { type: 'boolean', nullable: true },
+    m: { type: 'number', nullable: true },
+    re: { type: 'number', nullable: true },
+    rer: { type: 'number', nullable: true },
+    r: { ...quaternionSchema, nullable: true },
+    s: { ...shapeSchema, nullable: true },
+    sg: { type: 'number', nullable: true },
+    t: { ...vectorSchema, nullable: true },
+  },
+  additionalProperties: false,
+}

package/schemas/Entity.ts

@@ -0,0 +1,30 @@
+import { rigidBodySchema } from './RigidBody';
+import type { JSONSchemaType } from 'ajv';
+import type { RigidBody } from './RigidBody';
+
+export type Entity = {
+  wi: string;    // world id
+  i: number;     // entity id
+  d: boolean;    // delta
+  f?: boolean;   // focused
+  n?: string;    // name
+  m?: string;    // model uri
+  t?: string;    // texture uri
+  r?: RigidBody; // rigid body
+}
+
+export const entitySchema: JSONSchemaType<Entity> = {
+  type: 'object',
+  properties: {
+    wi: { type: 'string' },
+    i: { type: 'number' },
+    d: { type: 'boolean' },
+    f: { type: 'boolean', nullable: true },
+    n: { type: 'string', nullable: true },
+    m: { type: 'string', nullable: true },
+    t: { type: 'string', nullable: true },
+    r: { ...rigidBodySchema, nullable: true },
+  },
+  required: [ 'wi', 'i', 'd' ],
+  additionalProperties: false,
+}

package/schemas/Heartbeat.ts

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

package/schemas/Input.ts

@@ -0,0 +1,35 @@
+import { JSONSchemaType } from 'ajv';
+
+export type Input = {
+  w?: boolean;  // w key pressed
+  a?: boolean;  // a key pressed
+  s?: boolean;  // s key pressed
+  d?: boolean;  // d key pressed
+  sp?: boolean; // space key pressed
+  sh?: boolean; // shift key pressed
+  ct?: boolean; // ctrl key pressed
+  tb?: boolean; // tab key pressed
+  ml?: boolean; // mouse left pressed
+  mr?: boolean; // mouse right pressed
+  cp?: number;  // camera pitch radians
+  cy?: number;  // camera yaw radians
+}
+
+export const inputSchema: JSONSchemaType<Input> = {
+  type: 'object',
+  properties: {
+    w: { type: 'boolean', nullable: true },
+    a: { type: 'boolean', nullable: true },
+    s: { type: 'boolean', nullable: true },
+    d: { type: 'boolean', nullable: true },
+    sp: { type: 'boolean', nullable: true },
+    sh: { type: 'boolean', nullable: true },
+    ct: { type: 'boolean', nullable: true },
+    tb: { type: 'boolean', nullable: true },
+    ml: { type: 'boolean', nullable: true },
+    mr: { type: 'boolean', nullable: true },
+    cp: { type: 'number', nullable: true },
+    cy: { type: 'number', nullable: true },
+  },
+  additionalProperties: false,
+}

package/schemas/PhysicsDebugRender.ts

@@ -0,0 +1,18 @@
+import { JSONSchemaType } from 'ajv';
+
+export type PhysicsDebugRender = {
+  wi: number;  // world id
+  v: number[]; // rapier debug render vertices
+  c: number[]; // rapier debug render colors
+}
+
+export const physicsDebugRenderSchema: JSONSchemaType<PhysicsDebugRender> = {
+  type: 'object',
+  properties: {
+    wi: { type: 'number' },
+    v: { type: 'array', items: { type: 'number' } },
+    c: { type: 'array', items: { type: 'number' } },
+  },
+  required: [ 'wi', 'v', 'c' ],
+  additionalProperties: false,
+}

package/schemas/Quaternion.ts

@@ -0,0 +1,20 @@
+import type { JSONSchemaType } from 'ajv';
+
+export type Quaternion = [
+  number, // x
+  number, // y
+  number, // z
+  number, // w
+];
+
+export const quaternionSchema: JSONSchemaType<Quaternion> = {
+  type: 'array',
+  items: [
+    { type: 'number' },
+    { type: 'number' },
+    { type: 'number' },
+    { type: 'number' }
+  ],
+  minItems: 4,
+  maxItems: 4
+}

package/schemas/RigidBody.ts

@@ -0,0 +1,16 @@
+import { rigidBodyDescSchema } from './RigidBodyDesc';
+import type { JSONSchemaType } from 'ajv';
+import { RigidBodyDesc } from './RigidBodyDesc';
+
+export type RigidBody = {
+  h?: number; // rigid body handle for rapier
+} & RigidBodyDesc;
+
+export const rigidBodySchema: JSONSchemaType<RigidBody> = {
+  type: 'object',
+  properties: {
+    handle: { type: 'number', nullable: true },
+    ...rigidBodyDescSchema.properties,
+  },
+  additionalProperties: false,
+}

package/schemas/RigidBodyDesc.ts

@@ -0,0 +1,47 @@
+import { colliderSchema } from './Collider';
+import { vectorSchema } from './Vector';
+import { vectorBooleanSchema } from './VectorBoolean'
+import type { JSONSchemaType } from 'ajv';
+import type { Collider } from './Collider';
+import type { Vector } from './Vector';
+import type { VectorBoolean } from './VectorBoolean';
+
+export type RigidBodyDesc = {
+  ad?: number;        // angular dampening
+  av?: Vector;        // angular velocity
+  b?: number;         // body type
+  c?: Collider[];     // colliders
+  d?: number;         // dominance group
+  ce?: boolean;       // ccd enabled
+  en?: boolean;       // enabled
+  er?: VectorBoolean; // enabled rotations
+  et?: VectorBoolean; // enabled translations
+  g?: number;         // gravity scaling
+  ld?: number;        // linear damping
+  lv?: Vector;        // linear velocity
+  sl?: boolean;       // sleeping
+  scp?: number;       // soft ccd prediction
+  t?: Vector;         // translation
+}
+
+export const rigidBodyDescSchema: JSONSchemaType<RigidBodyDesc> = {
+  type: 'object',
+  properties: {
+    ad: { type: 'number', nullable: true },
+    av: { ...vectorSchema, nullable: true },
+    b: { type: 'number', nullable: true },
+    c: { type: 'array', items: colliderSchema, nullable: true },
+    d: { type: 'number', nullable: true },
+    ce: { type: 'boolean', nullable: true },
+    en: { type: 'boolean', nullable: true },
+    er: { ...vectorBooleanSchema, nullable: true },
+    et: { ...vectorBooleanSchema, nullable: true },
+    g: { type: 'number', nullable: true },
+    ld: { type: 'number', nullable: true },
+    lv: { ...vectorSchema, nullable: true },
+    sl: { type: 'boolean', nullable: true },
+    scp: { type: 'number', nullable: true },
+    t: { ...vectorSchema, nullable: true },
+  },
+  additionalProperties: false,
+}

package/schemas/Shape.ts

@@ -0,0 +1,23 @@
+import { JSONSchemaType } from 'ajv';
+import { vectorSchema } from './Vector';
+import type { Vector } from './Vector';
+
+export type Shape = {
+  t?: number;  // type
+  b?: number;  // border radius
+  r?: number;  // radius
+  hx?: Vector; // half extends
+  hh?: number; // half height
+}
+
+export const shapeSchema: JSONSchemaType<Shape> = {
+  type: 'object',
+  properties: {
+    t: { type: 'number', nullable: true },
+    b: { type: 'number', nullable: true },
+    r: { type: 'number', nullable: true },
+    hx: { ...vectorSchema, nullable: true },
+    hh: { type: 'number', nullable: true },
+  },
+  additionalProperties: false,
+}

package/schemas/Vector.ts

@@ -0,0 +1,18 @@
+import type { JSONSchemaType } from 'ajv';
+
+export type Vector = [
+  number, // x
+  number, // y
+  number, // z
+];
+
+export const vectorSchema: JSONSchemaType<Vector> = {
+  type: 'array',
+  items: [
+    { type: 'number' },
+    { type: 'number' },
+    { type: 'number' }
+  ],
+  minItems: 3,
+  maxItems: 3
+}

package/schemas/VectorBoolean.ts

@@ -0,0 +1,18 @@
+import { JSONSchemaType } from 'ajv';
+
+export type VectorBoolean = [
+  boolean, // x
+  boolean, // y
+  boolean, // z
+];
+
+export const vectorBooleanSchema: JSONSchemaType<VectorBoolean> = {
+  type: 'array',
+  items: [
+    { type: 'boolean' },
+    { type: 'boolean' },
+    { type: 'boolean' }
+  ],
+  minItems: 3,
+  maxItems: 3
+}

package/shared/Ajv.ts

@@ -0,0 +1,8 @@
+import Ajv from "ajv";
+
+export default class extends Ajv {
+  // shared instance for the entire application
+  // per ajv docs, this is for performance around
+  // compiled validate function caching & more.
+  public static readonly instance = new Ajv();  
+}