@cybermp-community/server-types 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CyberMP Community Developers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# CyberMP Server Types
+> By [CyberMP Community Developers](https://gitlab.com/cybermp).
+
+This repository contains the TypeScript type definitions for the **[CyberMP](https://cyber.mp) multiplayer server**, providing comprehensive type safety and IntelliSense support for server-side development.
+
+These types are designed to work seamlessly with the CyberMP server environment, offering full typing for server events, player management, world state synchronization, and all server-side APIs exposed by the CyberMP multiplayer modification.
+
+## 📦 Installation
+
+### 1. Install Package
+
+Using NPM:
+
+```bash
+npm install -D @cybermp-community/server-types
+```
+
+Using PNPM:
+
+```bash
+pnpm install -D @cybermp-community/server-types
+```
+
+Using Bun:
+
+```bash
+bun add -d @cybermp-community/server-types
+```
+
+### 2. Set types in tsconfig.json
+
+```json
+{
+   "compilerOptions": {
+        "types": [
+            "@cybermp-community/server-types"
+        ]
+    }
+}
+```
+
+## ⚖️ License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@cybermp-community/server-types",
+  "version": "1.0.0",
+  "description": "TypeScript type definitions for the CyberMP server-side environment.",
+  "license": "MIT",
+  "main": "./src/index.d.ts",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "bump": "npm version patch --no-git-tag-version",
+    "pub": "npm publish --access public"
+  },
+  "keywords": [
+    "cybermp",
+    "cyberpunk",
+    "multiplayer",
+    "mp",
+    "server",
+    "cp2077",
+    "types"
+  ],
+  "repository": {
+    "type": "gitlab",
+    "url": "https://gitlab.com/cybermp/types/server"
+  },
+  "author": {
+    "name": "An1by",
+    "url": "https://gitlab.com/an1by"
+  },
+  "contributors": [
+    "terminaate"
+  ]
+}

package/src/commands.d.ts

@@ -0,0 +1,13 @@
+import type { MpPlayer } from './entities/player';
+
+export interface MpCommands {
+  /**
+   * Register a command in the server scope.
+   * @param commandName Command name without "/".
+   * @param callback Callback with id and args.
+   */
+  add(
+    commandName: string,
+    callback: (player: MpPlayer, args: string[]) => void,
+  ): void;
+}

package/src/entities/entity.d.ts

@@ -0,0 +1,34 @@
+import type { MpPlayer } from './player';
+import type { Rotation, Vector3 } from '../shared';
+
+export enum EntityType {
+  Player = 1,
+  Vehicle = 2,
+  Object = 3,
+  Ped = 4,
+  Pickup = 5,
+  GameObject = 6,
+}
+
+export interface MpEntity {
+  readonly id: number;
+  readonly owner: MpPlayer;
+  readonly firstOwner: MpPlayer;
+  readonly position: Vector3;
+  readonly rotation: Rotation;
+  readonly yaw: number;
+  readonly type: EntityType;
+  readonly exist: boolean;
+
+  dimension: number;
+  streamingRadius: number;
+
+  getMeta<T = any>(key: string): T;
+  setMeta(key: string, value: any, sync?: boolean): void;
+}
+
+export interface MpEntities<T extends MpEntity = MpEntity> {
+  exists(entity: T | number): boolean;
+
+  at(entity: T | number): T;
+}

package/src/entities/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./entity";
+export * from "./player";

package/src/entities/player.d.ts

@@ -0,0 +1,26 @@
+import type { MpEntities, MpEntity } from './entity';
+import type { Vector3 } from '../shared';
+import type { MpVehicle } from '../vehicles';
+
+export type PlayerIdentifierType = 'steam' | 'ip';
+
+export interface MpPlayer extends MpEntity {
+  readonly velocity: Vector3;
+  readonly health: number;
+  readonly nickname: string;
+  readonly ping: number;
+  readonly vehicle: MpVehicle | null;
+  readonly lastVehicle: MpVehicle | null;
+
+  kick(reason?: string): void;
+  getIdentifier(type: PlayerIdentifierType): string;
+
+  emit(eventName: string, ...args: any[]): void;
+  mute(): void;
+}
+
+export interface MpPlayers extends MpEntities<MpPlayer> {
+  kick(player: MpPlayer | number, reason?: string): void;
+  getIdentifier(player: MpPlayer | number, type: PlayerIdentifierType): string;
+  toArray(): MpPlayer[];
+}

package/src/events/index.d.ts

@@ -0,0 +1,52 @@
+import { MpPlayer } from "../entities";
+import { MpEventsMap } from "./map";
+
+export interface MpEvents {
+  /**
+   * Listen for a shared (server or client) custom event.
+   * @param eventName The name of the custom event.
+   * @param callback The callback to run when triggered.
+   */
+  on<E extends keyof MpEventsMap>(eventName: E, callback: MpEventsMap[E]): void;
+  on(eventName: string, callback: (...args: any[]) => void): void;
+
+  /**
+   * Listen for a client-side event on the server.
+   * @param eventName The name of the event.
+   * @param callback Function triggered when the event is received.
+   */
+  onClient(
+    eventName: string,
+    callback: (player: MpPlayer, ...args: any[]) => void,
+  ): void;
+
+  /**
+   * Unregister a custom event listener.
+   * @param eventName Name of the event.
+   * @param callback Callback function.
+   */
+  off<E extends keyof MpEventsMap>(
+    eventName: E,
+    callback: MpEventsMap[E],
+  ): void;
+  off(eventName: string, callback: (...args: any[]) => void): void;
+
+  /**
+   * Emit a shared custom event.
+   * @param eventName The event name to emit.
+   * @param args Arguments to pass to the handler.
+   */
+  emit(eventName: string, ...args: any[]): void;
+
+  /**
+   * Emit a client-side event from the server.
+   * @param eventName Resource name to emit from.
+   * @param playerId Target player entity/network ID.
+   * @param args Arguments to send with the event.
+   */
+  emitClient(
+    player: MpPlayer | number,
+    eventName: string,
+    ...args: any[]
+  ): void;
+}

package/src/events/map.d.ts

@@ -0,0 +1,180 @@
+import type { EntityType } from '../entities';
+import type { GameHash, Vector3Object } from '../shared';
+
+export type DamageEventData = {
+  damageType: number;
+  weaponHash: GameHash;
+  totalDamage: number;
+  killerId: number;
+  victimId: number;
+  hitComponent: number;
+  hitPositionX: number;
+  hitPositionY: number;
+  hitPositionZ: number;
+  hitDirectionX: number;
+  hitDirectionY: number;
+  hitDirectionZ: number;
+  damageValues: number[];
+  flags: number[];
+  compName: string;
+  dismembermentParts: any[];
+  hitReactionZones: any[];
+  hitShapeTypes: any[];
+  hitShapeNames: string[];
+  physicsMaterials: string[];
+};
+
+export type DoorStateChangeEventData = Vector3Object & {
+  hashObject: GameHash;
+  state: boolean;
+};
+
+export type LiftStateChangeEventData = Vector3Object & {
+  hashObject: GameHash;
+  playerID: number;
+  targetFloor: number;
+  currentFloor: number;
+  maxFloor: number;
+};
+
+export type ExplosionEventData = Vector3Object & {
+  isVehicle: boolean;
+  vehicleID: number;
+  hashObject: GameHash;
+  objNetID: number;
+};
+
+export type AppearancePropertyData = {
+  meshType: number;
+  isEnabed: boolean;
+  pathToMesh: GameHash;
+  appearanceHash: GameHash;
+  chunkMask: GameHash;
+};
+
+export type AppearanceWeightPropertyData = {
+  targetHash: GameHash;
+  regionHash: GameHash;
+  weight: number;
+};
+
+export type PlayerAppearanceChangeEventData = {
+  skinneds: AppearancePropertyData[];
+  garments: AppearancePropertyData[];
+  morphs: AppearancePropertyData[];
+  weights: AppearanceWeightPropertyData[];
+};
+
+export type PlayerDeathEventData = {
+  killerId?: number;
+};
+
+export type VehicleCustomizationChangeEventData = {
+  isVehicleWasCustomized: boolean;
+  isEnabledVehCustomization: boolean;
+  isDisabledVehCustomizationByDamage: boolean;
+  lightsColorDefined: boolean;
+  lightsColorHue: number;
+  primaryColorR: number;
+  primaryColorG: number;
+  primaryColorB: number;
+  primaryColorDefined: boolean;
+  secondaryColorR: number;
+  secondaryColorG: number;
+  secondaryColorB: number;
+  secondaryColorDefined: boolean;
+  vehicleID: number;
+  hashAppearance: GameHash;
+};
+
+export type VehicleDestructionChangeEventData = {
+  vehicleID: number;
+  brokenGlass: number;
+  brokenLights: number;
+  flatTire: number;
+  windshieldShattered: boolean;
+};
+
+export type FireEventData = Vector3Object & {
+  hashObject: GameHash;
+  dirX: number;
+  dirY: number;
+  dirZ: number;
+};
+
+export type PickupChangeEventData = {
+  pickupNetId: number;
+  pickupHash: GameHash;
+  pickupHashes: GameHash[];
+};
+
+export type PickupDespawnEventData = {
+  pickupNetId: number;
+  pickupHash: GameHash;
+  isBag: boolean;
+};
+
+export type PickupCreateEventData = Vector3Object & {
+  pickupNetId: number;
+  pickupHash: GameHash;
+  pickupHashes: GameHash[];
+  isBag: boolean;
+};
+
+export interface MpEventsMap {
+  anyResourceStart(resourceName: string): void;
+  anyResourceStop(resourceName: string): void;
+  anyServerResourceStart(resourceName: string): void;
+  anyServerResourceStop(resourceName: string): void;
+  resourceStart(): void;
+  resourceStop(): void;
+  resourcesRefresh(): void;
+
+  playerConnecting(tempId: number, name: string): void;
+  playerConnected(playerId: number, tempId: string): void;
+  playerSpawn(playerId: number): void;
+  playerRespawn(playerId: number, data: Vector3Object): void;
+  playerDespawn(playerId: number): void;
+  playerDeath(playerId: number, data: PlayerDeathEventData): void;
+  playerDisconnected(playerId: number, reason: string): void;
+  playerAppearanceChange(
+    playerId: number,
+    data: PlayerAppearanceChangeEventData,
+  ): void;
+
+  damage(playerId: number, data: DamageEventData): void;
+  fire(playerId: number, data: FireEventData): void;
+  explosion(playerId: number, data: ExplosionEventData): void;
+
+  doorStateChange(playerId: number, data: DoorStateChangeEventData): void;
+  liftStateChange(playerId: number, data: LiftStateChangeEventData): void;
+
+  entitySpawn(id: number, type: EntityType): void;
+  entityDespawn(id: number, type: EntityType): void;
+
+  objectSpawn(id: number): void;
+  objectDespawn(id: number): void;
+
+  pedSpawn(id: number): void;
+  pedDespawn(id: number): void;
+
+  gameObjectSpawn(id: number): void;
+  gameObjectDespawn(id: number): void;
+
+  vehicleCustomizationChange(
+    playerId: number,
+    data: VehicleCustomizationChangeEventData,
+  ): void;
+  vehicleDestructionChange(
+    playerId: number,
+    data: VehicleDestructionChangeEventData,
+  ): void;
+  vehicleSpawn(id: number): void;
+  vehicleDespawn(id: number): void;
+
+  pickupChange(playerId: number, data: PickupChangeEventData): void;
+  pickupRaise(playerId: number, data: PickupDespawnEventData): void;
+  pickupDrop(playerId: number, data: PickupCreateEventData): void;
+  pickupSpawn(id: number): void;
+  pickupDespawn(id: number): void;
+}

package/src/exports.d.ts

@@ -0,0 +1,5 @@
+export interface MpExports {
+    [module: string]: {
+        [name: string]: (...args: unknown[]) => unknown;
+    };
+}

package/src/hashes.d.ts

@@ -0,0 +1,7 @@
+import type { CName, ResRef, TweakDBID } from './shared';
+
+export interface MpHashes {
+  tweakdbid(path: string): TweakDBID;
+  cname(path: string): CName;
+  resref(path: string): ResRef;
+}

package/src/index.d.ts

@@ -0,0 +1,13 @@
+export type * from './commands.d.ts';
+export type * from './entities';
+export type * from './events';
+export type * from './hashes.d.ts';
+export type * from './meta.d.ts';
+export type * from './mp';
+export type * from './objects.d.ts';
+export type * from './peds.d.ts';
+export type * from './pickups.d.ts';
+export type * from './resources.d.ts';
+export type * from './shared';
+export type * from './vehicles.d.ts';
+export type * from './voice-chat.d.ts';

package/src/meta.d.ts

@@ -0,0 +1,23 @@
+import type { MpEntity } from './entities';
+import type { MpPlayer } from './entities/player';
+
+export interface MpMeta {
+  setGlobalMeta(key: string, value: any, sync?: boolean): void;
+  getGlobalMeta<T = any>(key: string): T;
+
+  setPlayerMeta(
+    player: MpPlayer | number,
+    key: string,
+    value: any,
+    sync?: boolean,
+  ): void;
+  getPlayerMeta<T = any>(player: MpPlayer | number, key: string): T;
+
+  setEntityMeta(
+    entity: MpEntity | number,
+    key: string,
+    value: any,
+    sync?: boolean,
+  ): void;
+  getEntityMeta<T = any>(entity: MpEntity | number, key: string): T;
+}

package/src/mp/config.d.ts

@@ -0,0 +1,38 @@
+export namespace MpServer {
+    export type CoreOverrides = {
+        change_player_on_death_logic?: boolean;
+        disable_side_quests_notifications?: boolean;
+        change_vehicles_logic?: boolean;
+        disable_player_inventory_encumbrance?: boolean;
+        player_extended_customization?: boolean;
+        disable_time_skip?: boolean;
+        disable_turrets?: boolean;
+        disable_surveillance_cameras?: boolean;
+        disable_vending_machines?: boolean;
+        disable_generic_devices?: boolean;
+        disable_no_combat?: boolean;
+    };
+
+    export type CoreConfig = {
+        nametags?: boolean;
+        disable_switch_seats?: boolean;
+        delete_map_objects?: boolean;
+        default_gameplay_restrictions?: boolean;
+        disable_drop_points?: boolean;
+        disable_location_dependent_quests?: boolean;
+        disable_garage?: boolean;
+        overrides?: CoreOverrides;
+        files?: string[];
+    };
+
+    export type ServerConfig = {
+        tcp_host: string;
+        udp_host: string;
+        connection_host_addr: string;
+        max_players: number;
+        secret_token: string;
+        resources: string[];
+        disable_VoIP_server: boolean;
+        core?: CoreConfig;
+    };
+}

package/src/mp/index.d.ts

@@ -0,0 +1,40 @@
+import type { MpCommands } from '../commands';
+import type { MpEntities } from '../entities';
+import type { MpEvents } from '../events';
+import type { MpHashes } from '../hashes';
+import type { MpMeta } from '../meta';
+import type { MpObjects } from '../objects';
+import type { MpPeds } from '../peds';
+import type { MpPickups } from '../pickups';
+import type { MpPlayers } from '../entities/player';
+import type { MpResources } from '../resources';
+import type { MpVehicles } from '../vehicles';
+import type { MpServer as MpServ } from './config';
+import type { MpExports } from '../exports';
+
+export interface MpServer {
+  events: MpEvents;
+  exports: MpExports;
+  meta: MpMeta;
+  resources: MpResources;
+  commands: MpCommands;
+  entities: MpEntities;
+  vehicles: MpVehicles;
+  players: MpPlayers;
+  objects: MpObjects;
+  pickups: MpPickups;
+  peds: MpPeds;
+  hashes: MpHashes;
+
+  /**
+   * Checks if the code is running on the server.
+   * @returns True if running on server, false otherwise.
+   */
+  isServer(): boolean;
+
+  config: MpServ.ServerConfig;
+}
+
+declare global {
+  var mp: MpServer;
+}

package/src/objects.d.ts

@@ -0,0 +1,22 @@
+import type { MpEntities, MpEntity } from './entities';
+import type { TweakDBID, Vector3 } from './shared';
+
+export interface MpObject extends MpEntity {
+  readonly model: TweakDBID;
+
+  destroy(): void;
+}
+
+export type CreateObjectOptions = {
+  model: TweakDBID;
+  position: Vector3;
+  yaw?: number;
+  dynamic?: boolean;
+  dimension?: number;
+};
+
+export interface MpObjects extends MpEntities<MpObject> {
+  create(options: CreateObjectOptions): MpObject;
+  destroy(entity: MpObject | number): void;
+  toArray(): MpObject[];
+}

package/src/peds.d.ts

@@ -0,0 +1,27 @@
+import type { MpEntities, MpEntity } from './entities';
+import type { CName, TweakDBID, Vector3 } from './shared';
+
+export interface MpPed extends MpEntity {
+  readonly health: number;
+  readonly model: TweakDBID;
+  readonly appearance: CName;
+
+  destroy(): void;
+}
+
+export type CreatePedOptions = {
+  model: TweakDBID;
+  appearance: CName;
+  position: Vector3;
+  health?: number;
+  yaw?: number;
+  dimension?: number;
+};
+
+export interface MpPeds extends MpEntities<MpPed> {
+  create(options: CreatePedOptions): MpPed;
+
+  destroy(ped: MpPed | number): void;
+
+  toArray(): MpPed[];
+}

package/src/pickups.d.ts

@@ -0,0 +1,27 @@
+import type { MpEntities, MpEntity } from './entities';
+import type { TweakDBID, Vector3 } from './shared';
+
+export enum PickupType {
+  Clothes = 1,
+  Weapon = 2,
+  Other = 3,
+}
+
+export interface MpPickup extends MpEntity {
+  readonly model: TweakDBID;
+  readonly pickupType: PickupType;
+
+  destroy(): void;
+}
+
+export type CreatePickupOptions = {
+  model: TweakDBID;
+  type: PickupType;
+  position: Vector3;
+  yaw?: number;
+  dimension?: number;
+};
+
+export interface MpPickups extends MpEntities<MpPickup> {
+  create(options: CreatePickupOptions): MpPickup;
+}

package/src/resources.d.ts

@@ -0,0 +1,45 @@
+export interface MpResources {
+  /**
+   * Gets the current state of a resource.
+   * @param resourceName The resource to check.
+   * @returns Resource state as string.
+   */
+  getState(resourceName: string): string;
+
+  /**
+   * Starts a specific resource by name.
+   * @param resourceName Name of the resource to start.
+   */
+  start(resourceName: string): void;
+
+  /**
+   * Stops a specific resource by name.
+   * @param resourceName Name of the resource to stop.
+   */
+  stop(resourceName: string): void;
+
+  restart(resourceName: string): void;
+
+  /**
+   * Gets the current resource's name.
+   * @returns Resource name.
+   */
+  getCurrentName(): string;
+
+  /**
+   * Gets metadata from a resource manifest.
+   * @param resourceName Resource name.
+   * @param keyName Metadata key.
+   * @param index Index (if multiple values exist).
+   * @returns Metadata string.
+   */
+  getMetadata(resourceName: string, keyName: string, index: number): string;
+
+  /**
+   * Reads a file inside a resource and returns its contents.
+   * @param resourceName Name of the resource.
+   * @param pathToResource Path to the file.
+   * @returns File content as string.
+   */
+  loadFile(resourceName: string, pathToResource: string): string;
+}

package/src/shared/hash.d.ts

@@ -0,0 +1,4 @@
+export type GameHash = bigint | number;
+export type TweakDBID = GameHash;
+export type CName = GameHash;
+export type ResRef = GameHash;

package/src/shared/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./transform"
+export * from "./hash"

package/src/shared/transform.d.ts

@@ -0,0 +1,9 @@
+export type Vector3 = [x: number, y: number, z: number];
+export type Vector4 = [x: number, y: number, z: number, w: number];
+export type Rotation = [pitch: number, roll: number, yaw: number];
+
+export type Vector3Object = {
+    posX: number;
+    posY: number;
+    posZ: number;
+};

package/src/vehicles.d.ts

@@ -0,0 +1,37 @@
+import type { MpPlayer, MpEntities, MpEntity } from './entities';
+import type { CName, TweakDBID, Vector3 } from './shared';
+
+export enum VehicleSeat {
+  Driver = 0,
+  Passenger = 1,
+  RearLeft = 2,
+  RearRight = 3,
+}
+
+export interface MpVehicle extends MpEntity {
+  readonly model: TweakDBID;
+  readonly appearance: CName;
+  readonly health: number;
+  readonly velocity: Vector3;
+  readonly angularVelocity: Vector3;
+
+  getPlayerInSeat(seat: VehicleSeat): MpPlayer | null;
+  getLastPlayerInSeat(seat: VehicleSeat): MpPlayer | null;
+
+  destroy(): void;
+}
+
+export type CreateVehicleOptions = {
+  model: TweakDBID;
+  appearance: CName;
+  position: Vector3;
+  yaw?: number;
+  health?: number;
+  dimension?: number;
+};
+
+export interface MpVehicles extends MpEntities<MpVehicle> {
+  create(options: CreateVehicleOptions): MpVehicle;
+  destroy(vehicle: MpVehicle | number): void;
+  toArray(): MpVehicle[];
+}

package/src/voice-chat.d.ts

@@ -0,0 +1,9 @@
+import type { MpPlayer } from './entities';
+
+export interface MpVoiceChat {
+  mutePlayer(player: MpPlayer | number): void;
+
+  createChannel(voiceId: number): void;
+
+  isPlayerMuted(player: MpPlayer | number): boolean;
+}