ccmp-types

TypeScript types for the ccmp JavaScript scripting API. Install as a dev dependency in your server-script or client-script project to get autocomplete and tsc-based checking.

Install

npm install -D @classic-mp/types

Usage — server scripts

// tsconfig.json
{
  "compilerOptions": {
    "types": ["@classic-mp/types/server"],
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noEmit": true,
    "allowJs": true,
    "checkJs": true
  },
  "include": ["**/*.js", "**/*.ts"]
}

Scripts use the ccmp global directly — no import needed, because the runtime provides globalThis.ccmp:

ccmp.on('playerConnected', (player) => {
  player.teleport(90.79, -1951.33, 20.74, 307.23);
  player.giveWeapon(0x1B06D571, 200);
});

ccmp.on('playerDisconnected', (player) => {
  console.log(`${player.name} (${player.id}) disconnected`);
});

Usage — client scripts

Same as above but with "@classic-mp/types/client" in compilerOptions.types. This pulls in typings for ccmp.natives.* (the full GTA V native surface) as well as ccmp.browsers, key events, and the CEF bridge.

const browser = ccmp.browsers.create('index.html');

ccmp.on('keyUp', (key) => {
  if (key === 0x50) ccmp.notify('P pressed');
});

ccmp.on('ui:ping', (data) => {
  console.log('CEF ping payload:', data);
});

ccmp.natives.player.setPlayerModel(playerId, 0x39DA2754);

Typing custom events

Built-in events (playerConnected, keyUp, ...) are typed out of the box. Your own events go through declaration merging.

Server (events that clients send to the server):

// src/types.d.ts in your server project
declare module '@classic-mp/types/server' {
  interface CcmpServerEvents {
    teleportRequest: { x: number; y: number; z: number; name: string };
    spawnVehicleRequest: { model: number };
  }
  interface CcmpClientInboundEvents {
    chatMessage: {
      authorId: number;
      authorName: string;
      text: string;
      timestamp: number;
    };
  }
}

Now ccmp.on('teleportRequest', (player, data) => ...) has data typed as { x, y, z, name }, and ccmp.emitAllClients('chatMessage', payload) checks the payload shape.

Client (named events the runtime emits to the client script, and events the client sends back):

declare module '@classic-mp/types/client' {
  interface CcmpClientEvents {
    chatMessage: {
      authorId: number;
      authorName: string;
      text: string;
      timestamp: number;
    };
    'ui:ping': { ts: number };
  }
  interface CcmpServerInboundEvents {
    teleportRequest: { x: number; y: number; z: number; name: string };
  }
}

Then ccmp.on('ui:ping', (data) => ...) and ccmp.on('chatMessage', (data) => ...) are typed from CcmpClientEvents.

Subpath exports

| Import | Provides | | ------------------------------ | --------------------------------------------------- | | @classic-mp/types/server | ccmp global for server scripts, Player, events | | @classic-mp/types/client | ccmp global for client scripts, Browser, events, ccmp.natives | | @classic-mp/types/ui | Minimal CEF bridge payload types for standalone UI bundles | | @classic-mp/types/natives | Standalone access to the natives interfaces (rarely needed directly) |

A single script project should pick one of /server or /client in its tsconfig.types, not both — the two define the same ccmp global with different shapes.

Versioning

@classic-mp/[email protected] is pinned to runtime API compatibility with the ccmp release of the same major.minor. Patches (Z) fix typing bugs without runtime changes.

Contributing

Commit conventions

This repo uses Conventional Commits. A commit-msg hook (powered by commitlint + @commitlint/config-conventional) rejects non-conforming messages. Examples:

• feat: add vehicle spawn natives
• fix(server): correct player event payload type
• chore: bump typescript to 5.5

Pre-commit

A pre-commit hook runs npm run check (tsc on server + client) whenever *.ts, *.d.ts, or *.json files are staged. Skip with --no-verify only when absolutely necessary.

Release flow

Releases are automated:

1. On dev, bump the version in package.json (npm version patch | minor | major --no-git-tag-version).
2. Open a PR from dev → stable.
3. Merge the PR. The release.yml workflow will:
   • Check if the version is already on npm (skip if so).
   • Type-check, publish with --provenance as @classic-mp/types, create a v<version> git tag and a GitHub Release.

Do not run npm publish manually. Do not bump the version directly on stable.

License

MIT