gtac-types

GTA Connected — TypeScript type definitions & runtime utilities for GTA III / Vice City / San Andreas / IV server scripting (SpiderMonkey JS).

Table of Contents

• Overview
• Installation
• Quick Start
• Package Structure
• Type Definitions
  • Element Types
  • Server-Side Functions
  • Client-Side Functions
  • Events
  • Natives
  • Constants
• Runtime Utilities
  • Constants
  • Utility Functions
• Configuration
  • tsconfig.json
  • gtac.config.json
• CLI Usage
• Development
• Security
• License

Overview

gtac-types is the type definitions and runtime utility package for GTA Connected server resources targeting GTA III (gta:iii), Vice City (gta:vc), San Andreas (gta:sa), and GTA IV (gta:iv). It provides:

• 14 .d.ts type definition files covering the full GTAC API surface
  • Element hierarchy (Element, Entity, Physical, Ped, Player, Vehicle, etc.)
  • Server-side functions (addEventHandler, addCommandHandler, gta, http, etc.)
  • Client-side functions (gui, audio, font, bindKey, etc.)
  • Fully typed event handler overloads (server + client)
  • 300+ GTA Vice City native opcode signatures (natives-gtavc.) + 2500+ GTA IV natives (natives-gtaiv.)
  • 4000+ per-game enums across III, VC, SA, IV (missions, vehicles, weapons, ped skins, weather, icons)
  • 4700+ scripting defines across VC, SA, and IV (defines-gtavc, defines-gtasa, defines-gtaiv)
  • CVar definition interface
  • Vector math (Vec2, Vec3, Matrix4x4, NetFlags)
  • XML document manipulation API
  • Resource, Timer, Client interfaces
  • Predefined constants (colours, element types, cheats, controls, etc.)
• Runtime shared utilities for use in SpiderMonkey server scripts
• Build utilities shared with gtac-server-node

All declarations are global — no import/export required. Designed for the SpiderMonkey JS engine used by GTAC where scripts are concatenated via meta.xml.

Installation

npm install --save-dev gtac-types

Also install the build tool:

npm install --save-dev esbuild gtac-server-node

Quick Start

1. Create a project

npx gtac-server init my-server
cd my-server
npm init -y
npm install --save-dev gtac-types esbuild gtac-server-node

2. Configure TypeScript

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2015",
    "lib": ["ES2015"],
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true,
    "moduleResolution": "node",
    "types": ["gtac-types"]
  },
  "include": ["src/**/*.ts"]
}

3. Write server code

// src/my-resource/server/main.ts
addEventHandler("OnServerStart", () => {
  console.log("Server started!");
});

addEventHandler("OnPlayerJoin", (client: Client) => {
  message(client.name + " joined the server!", COLOUR_GREEN);

  // Spawn a vehicle for them
  const car = gta.createVehicle(141, 0, 0, 10, 0);
  message("Infernus spawned at " + car.position);
});

4. Write client code

// src/my-resource/client/main.ts
bindEventHandler("OnResourceStart", thisResource, () => {
  console.log("Client resource ready");

  bindKey("F2", (event: KeyEvent) => {
    if (!event.isUp()) {
      message("F2 pressed!");
    }
  });
});

5. Build & run

npx gtac-server build
npx gtac-server start

Package Structure

gtac-types/
├── src/
│   ├── index.d.ts              # Entry point — references all .d.ts files
│   ├── types/
│   │   ├── element.d.ts        # Element, Entity, Physical, Ped, Player, Vehicle, etc.
│   │   ├── event.d.ts          # Event, CancellableEvent, KeyEvent
│   │   ├── misc.d.ts           # Colour, element type, chat, camera constants
│   │   ├── resource.d.ts       # Resource, Timer, Stream, console
│   │   ├── vec.d.ts            # Vec2, Vec3, Matrix4x4, NetFlags
│   │   ├── xml.d.ts            # XmlDocument, XmlElement, FileObject
│   │   ├── client/
│   │   │   ├── animations.d.ts # AnimationGroup enum, cheat/control/corona defines
│   │   │   ├── events.d.ts     # Client-side event handler overloads
│   │   │   ├── functions.d.ts  # Client-side functions (gui, audio, font, etc.)
│   │   │   ├── gta.d.ts        # Client-side gta.* API (camera, AI, world, etc.)
│   │   │   └── natives.d.ts    # 300+ GTA VC native opcode signatures
│   │   └── server/
│   │       ├── client.d.ts     # Client interface (server-side)
│   │       ├── events.d.ts     # Server-side event handler overloads
│   │       └── functions.d.ts  # Server-side functions (gta, http, messaging, etc.)
│   └── runtime/
│       └── shared/
│           ├── constants.ts    # Runtime constant values for server scripts
│           └── utils.ts        # Runtime utility functions (dist3d, isAdmin, etc.)
├── lib/
│   └── build.js                # Build utilities (shared with gtac-server-node)
├── templates/
│   ├── meta.xml                # XML template for resources
│   └── tsconfig.json           # TypeScript config template
├── bin/
│   └── gtac.js                 # CLI delegates to gtac-server-node
├── index.js                    # Package entry point
├── LICENSE                     # Apache 2.0
└── README.md

Type Definitions

Element Types

The GTAC element hierarchy is fully typed with all properties and methods:

| Interface | Extends | Key Properties | |-----------|---------|---------------| | Element | — | id, type, name, position, rotation, dimension, parent, children | | Entity | Element | heading, interior, matrix, alpha, bounding*, collisions* | | Building | Entity | modelIndex | | Physical | Entity | gravity, mass, velocity, turnVelocity | | Object | Physical | modelIndex | | Ped | Physical | armour, health, frozen, modelIndex, occupiedVehicle | | Player | Ped | skin, team, money, weapons, vehicle, wantedLevel | | Vehicle | Physical | colour, health, engineState, doorStates, isLocked | | Train | Vehicle | isTrain, carriage, track | | Blip | Element | — | | Marker | Element | color, type, targetPosition, visible | | Pickup | Element | amount, type, quantity, respawns | | Sphere | Element | — |

Server-Side Functions

Typed in types/server/functions.d.ts:

• Network Events: addNetworkHandler(), triggerNetworkEvent()
• Commands: addCommandHandler(), removeCommandHandler()
• Client Queries: getClient(), getClients(), getClientFromPlayerElement()
• Element Queries: getElementsByType(), getElementFromId(), destroyElement()
• Entity Counts: getPlayerCount(), getVehicleCount(), getBlips(), etc.
• Messaging: message(), messageClient(), messageAllExcept()
• Key Binding: bindKey(), unbindKey()
• Server Info: getServerPort(), getServerName(), setServerPassword()
• HTTP: http.get(), http.post(), http.createRequest()
• File I/O: fileOpen(), fileRead(), fileWrite(), fileDelete()
• Timing: platform.ticks
• Player Control: spawnPlayer(), fadeCamera()

Client-Side Functions

Typed in types/client/functions.d.ts:

• Player References: localPlayer, localClient
• GUI: gui.createElement(), gui.createWindow(), gui.createPage()
• Audio: audio.createSound(), audio.createSoundFromURL()
• Font: font.create(), lucasFont.createFont()
• Screen: screen.width, screen.height, getScreenResolution()
• Events: addNetworkHandler(), bindEventHandler(), removeEventHandler()
• Commands: addCommandHandler()
• Chat: chatInputEnabled(), chatWindowEnabled()
• Messaging: message()
• File I/O: openFile(), fileOpen(), fileRead()
• Keys: bindKey(), unbindKey()
• Colours: toColour()

Events

Both server and client events are fully typed with per-event overloads:

Server events (types/server/events.d.ts): OnElementDestroy, OnElementStreamIn, OnElementStreamOut, OnPedCrouch, OnPedEnterVehicle, OnPedExitVehicle, OnPedFall, OnPedJump, OnPedSpawn, OnPedUncrouch, OnPedWasted, OnPickupCollected, OnPlayerChat, OnPlayerCommand, OnPlayerConnect, OnPlayerJoin, OnPlayerJoined, OnPlayerQuit, OnProcess, OnResourceStart, OnResourceStop, OnServerStart

Client events (types/client/events.d.ts): OnBeforeProcessCamera, OnCameraProcess, OnChatOutput, OnCursorDown, OnCursorMove, OnCursorUp, OnElementDestroy, OnElementStreamIn, OnElementStreamOut, OnEntityProcess, OnFocus, OnLostFocus, OnGUIAnchorClick, OnGUIClick, OnBeforeDrawHUD, OnDrawHUD, OnDrawnHUD, OnCharacter, OnKeyDown, OnKeyUp, OnMouseConnected, OnMouseDisconnected, OnMouseDown, OnMouseUp, OnMouseMove, OnMouseLeave, OnMouseWheel, OnDisconnect, OnPed* (18 events), OnPickupCollected, OnProcess, OnPostRender2D, OnPreRender, OnRender, OnRender2D, OnRenderEffects, OnResourceReady, OnResourceStart, OnResourceStop, OnVehicleExplode

Natives

types/client/natives.d.ts contains 300+ typed GTA Vice City native opcodes organized in the Natives interface:

CREATE_CAR, CREATE_CHAR, CREATE_OBJECT, CREATE_PICKUP, CREATE_PLAYER
DELETE_CAR, DELETE_CHAR, DELETE_OBJECT
SET_CAR_HEALTH, SET_CHAR_HEALTH, SET_PLAYER_HEALTH
GIVE_WEAPON_TO_CHAR, GIVE_WEAPON_TO_PLAYER
TASK_GO_TO_COORD, TASK_KILL_CHAR, TASK_PLAY_ANIM
PLAY_SOUND, ADD_EXPLOSION, ADD_BLIP_FOR_COORD
SET_WEATHER, SET_TIME_OF_DAY, SET_GRAVITY
SET_CAMERA_POSITION, POINT_CAMERA_AT_PLAYER
DISPLAY_TEXT, PRINT, PRINT_HELP
... and 280+ more

Also provides an index signature [key: string] for dynamic native calls.

Constants

types/misc.d.ts and types/client/animations.d.ts provide GTAC engine constants:

• Colours: COLOUR_RED, COLOUR_GREEN, COLOUR_BLUE, COLOUR_WHITE, etc.
• Element Types: ELEMENT_PLAYER, ELEMENT_VEHICLE, ELEMENT_BLIP, etc.
• GTA Entity Types: ENTITYTYPE_BUILDING, ENTITYTYPE_VEHICLE, etc.
• Chat Types: CHAT_TYPE_CHAT, CHAT_TYPE_INFO, CHAT_TYPE_DEBUG
• Camera Fade: FADE_IN, FADE_OUT
• Animation Groups: AnimationGroup enum (PED, VAN, BIKE, SNIPER, etc.)
• Radar Sprites: RADAR_SPRITE_TOMMY, RADAR_SPRITE_GUN, etc.
• Cheats: CHEAT_FASTTIME, CHEAT_ALLDODOS, CHEAT_GREENLIGHTS, etc.
• Controls: CONTROL_INCAR_HANDBRAKE, CONTROL_ONFOOT_JUMP, etc.
• Cop Types: COPTYPE_COP, COPTYPE_FBI, COPTYPE_SWAT, COPTYPE_ARMY
• Explosion Types: EXPLOSION_GRENADE, EXPLOSION_ROCKET, EXPLOSION_CAR
• Vehicle Doors: AUTOMOBILEDOOR_DOOR_FRONT_LEFT, etc.
• Vehicle Panels: AUTOMOBILEPANEL_FRONT_LEFT, etc.
• Corona Textures: CORONATEXTURE_CORONA, CORONATEXTURE_CORONASTAR, etc.
• Flight Modes: FLIGHTMODE_HELICOPTER, FLIGHTMODE_HOVERCAR, etc.

Runtime Utilities

Runtime Constants

src/runtime/shared/constants.ts provides runtime values for use in server scripts:

var STREAM_INFINITE = 999999;
var BLIP_VISIBILITY_DIST = 300;
var FADE_MS = 300;
var DEATH_SEQUENCE_DELAY = 11000;
var RESPAWN_DELAY = 1500;
var IV_100 = 100;
var IV_1000 = 1000;
var SKIN_TOMMY_MIN = 161;
var SKIN_TOMMY_MAX = 171;
var CHEAT_SPAWN_DIST = 4;
var MISSION_TRIGGER_DIST = 2;
var PROGRESS_BG_COLOUR = 0xff1b5982;
var PROGRESS_FG_COLOUR = 0xff61c2f7;
var EXPLOSION_TYPE_CHEAT = 3;
// ... 100+ constants total

Utility Functions

src/runtime/shared/utils.ts provides:

function dist3d(ax, ay, az, bx, by, bz): number
function setInfiniteStream(blip): void
function formatJSON(obj): string
function isAdmin(c): boolean
function isRoxasName(c): boolean

These are compiled directly into your SpiderMonkey bundle — no import required.

Configuration

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2015",
    "lib": ["ES2015"],
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true,
    "moduleResolution": "node",
    "types": ["gtac-types"]
  },
  "include": ["src/**/*.ts"]
}

gtac.config.json

The gtac-server-node package uses this JSON configuration file:

{
  "server": {
    "name": "My GTAC Server",
    "port": 23000,
    "game": "gta:vc",
    "maxPlayers": 32,
    "password": ""
  },
  "resourcesDir": "resources",
  "resources": [
    {
      "name": "my-resource",
      "server": ["server", "shared"],
      "client": ["client", "shared"],
      "serverOrder": { "server": ["main"] },
      "clientOrder": { "client": ["main"] }
    }
  ]
}

CLI Usage

gtac-types provides a CLI that delegates to gtac-server-node:

npx gtac-types        # Show help
npx gtac-types build  # → tells you to use npx gtac-server build
npx gtac-server init  # Scaffold a new project
npx gtac-server build # Build TypeScript → SpiderMonkey JS
npx gtac-server start # Launch the GTAC server
npx gtac-server dev   # Init + build + start

Development

# Clone
git clone https://github.com/RoxasYTB/gtac-types.git
cd gtac-types

# Install dependencies
npm install

# The .d.ts files are the source — no build step for types
# Edit src/runtime/ or lib/ as needed

Publishing

# Ensure clean files
npm pack --dry-run  # Verify what will be published

# Bump version
npm version patch   # or minor, major

# Publish
npm publish

Security

• No credentials, tokens, or secrets are included in the package
• The files field in package.json explicitly whitelists only necessary files
• .gitignore excludes node_modules/
• All type definitions are read-only declarations — no executable code that accesses external services
• The package is published publicly on npmjs under Apache 2.0

License

Apache 2.0 — see LICENSE.

Copyright 2025-2026 RoxasYTB.