gtac-server-node

GTA Connected — Complete server toolkit for Node.js: JSON configuration, multi-resource build system, SpiderMonkey bundler, process manager, and standalone export.

Table of Contents

• Overview
• Installation
• Quick Start
• CLI Reference
  • init
  • build
  • start
  • dev
  • export
  • download
• Configuration
  • gtac.config.json
  • gtac.config.js
• Project Structure
• API Reference
  • createServer()
  • GtacServer
  • buildAll()
  • ensureServer()
  • scaffold()
  • generateServerConf()
  • generateMetaXml()
• Build System
  • Multi-Resource Build
  • Client Safety Wrapper
  • File Ordering
• Standalone Export
• Server Binary
  • Automatic Download
  • Manual Download
• Programmatic Usage
• Development
• Security
• License

Overview

gtac-server-node is a complete development toolkit for GTA Connected server resources targeting GTA III (gta:iii), Vice City (gta:vc), San Andreas (gta:sa), and GTA IV (gta:iv). It replaces the traditional XML + manual file management workflow with a modern TypeScript + JSON approach.

Key features:

• JSON → XML conversion — write gtac.config.json, get server.conf.xml + meta.xml automatically
• Multi-resource build system — build multiple resources from TypeScript sources in one command
• SpiderMonkey bundling — concatenates TypeScript files per meta.xml conventions using esbuild
• Client safety wrapper — automatically wraps client handlers with try/catch error reporting
• Server process manager — spawn, monitor, and stop the GTAC server binary
• Standalone export — produce a ready-to-copy folder for servers without Node.js
• Automatic binary download — downloads GTAC Server 1.7.3 on postinstall
• Dev mode — one command to scaffold, build, and start

Installation

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

Also install esbuild (required at build time):

npm install --save-dev esbuild

Type definitions for IntelliSense:

npm install --save-dev gtac-types

Quick Start

1. Scaffold a new project

npx gtac-server init my-server
cd my-server

This creates:

my-server/
├── gtac.config.json        # Server configuration
├── tsconfig.json           # TypeScript configuration
├── src/
│   └── my-resource/
│       ├── server/
│       │   └── main.ts     # Server-side entry
│       ├── client/
│       │   └── main.ts     # Client-side entry
│       └── shared/
│           └── index.ts    # Shared types/constants
└── resources/              # Built output (created by build)

2. Install dependencies

npm install --save-dev esbuild gtac-types

3. Build

npx gtac-server build

This produces:

resources/
├── my-resource/
│   ├── server.js           # Concatenated server-side JS
│   ├── client.js           # Concatenated client-side JS
│   └── meta.xml            # Auto-generated manifest
server.conf.xml             # Auto-generated server config

4. Start the server

npx gtac-server start

Or do everything in one command:

npx gtac-server dev

CLI Reference

npx gtac-server init [dir]

Scaffolds a new GTAC server project in the specified directory (default: current directory).

Creates:

• gtac.config.json — full server configuration
• tsconfig.json — TypeScript config targeting ES2015 with gtac-types
• src/<resource-name>/server/main.ts — example server code
• src/<resource-name>/client/main.ts — example client code
• src/<resource-name>/shared/index.ts — shared module

npx gtac-server build

Builds all resources defined in gtac.config.json:

1. Reads configuration from gtac.config.json or gtac.config.js
2. For each resource, collects .ts files from the specified source directories
3. Compiles and concatenates using esbuild (target: ES2015)
4. Generates meta.xml for each resource
5. Generates server.conf.xml at the project root

Output is placed in the resources/ directory and at the project root.

npx gtac-server start

Builds and starts the GTAC server:

1. Ensures the server binary is downloaded (cached in ~/.gtac-server/)
2. Generates server.xml from your configuration
3. Syncs built resources to the server directory
4. Spawns the Server binary
5. Watches stdout/stderr and the ServerLog.log file
6. Handles SIGINT/SIGTERM for graceful shutdown

npx gtac-server dev [dir]

One-command workflow: scaffold + build + start.

Use this for local development: it creates a project, builds it, and immediately launches the server.

npx gtac-server export [dir]

Exports a standalone server folder (no Node.js required):

1. Builds all resources (same as build)
2. Copies built resources to the output directory
3. Generates server.xml in the output
4. Output is a folder ready to copy alongside the GTAC Server binary

Default output directory: export/

npx gtac-server download

Manually downloads or updates the GTAC Server binary to ~/.gtac-server/server/.

Supports:

• Windows (x64, ARM64)
• Linux (x64, ARM64)
• macOS (via Linux binary compatibility)

Version: 1.7.3

Configuration

gtac.config.json

The primary configuration file for your GTAC server project.

{
  "server": {
    "name": "My Vice City Server",
    "port": 23000,
    "httpport": 23000,
    "httpserver": true,
    "game": "gta:vc",
    "maxPlayers": 32,
    "password": "",
    "minclientversion": "1.7.0",
    "announce": true,
    "streaminterval": 1000,
    "syncinterval": 30,
    "syncmethod": "interval",
    "synclocalentities": true,
    "streamindistance": 999999,
    "streamoutdistance": 999999,
    "pickupstreamindistance": 30,
    "pickupstreamoutdistance": 50,
    "logpath": "logs",
    "logtimestamp": "[%d/%m/%Y - %X]",
    "modules": [],
    "cvars": [
      { "name": "nametags", "value": "0" },
      { "name": "traffic", "value": "1" },
      { "name": "civilians", "value": "1" }
    ],
    "rules": [
      { "name": "Owner", "value": "MyName" },
      { "name": "Website", "value": "mywebsite.com" }
    ]
  },
  "resourcesDir": "resources",
  "resources": [
    {
      "name": "my-resource",
      "server": ["server", "shared"],
      "client": ["client", "shared"],
      "serverOrder": {
        "server": ["main", "events", "commands"],
        "shared": ["enums", "constants"]
      },
      "clientOrder": {
        "client": ["main"],
        "shared": ["enums"]
      }
    },
    {
      "name": "another-resource",
      "server": ["server"],
      "client": ["client"]
    }
  ],
  "confFile": "server.conf.xml"
}

server options — Networking

| Field | Type | Default | Description | |-------|------|---------|-------------| | name | string | "GTAC Server" | Server display name | | port | number | 23000 | Game server port | | httpport | number | — | HTTP server port (separate from game port) | | httpserver | boolean | true | Enable HTTP server for downloads | | game | string | "gta:vc" | Game identifier ("gta:iii", "gta:vc", "gta:sa", or "gta:iv") | | gamemode | string | "Free Roam" | Game mode (displayed in server browser) | | maxPlayers | number | 32 | Max player count | | password | string | "" | Server password (empty = none) | | minclientversion | string | "1.7.0" | Minimum client version required | | announce | boolean | — | Show in server browser | | duplicatenames | boolean | false | Allow duplicate player names | | streaminterval | number | — | Element stream interval in ms | | syncinterval | number | — | Network sync interval in ms | | syncmethod | string | — | Sync method ("interval" or "adaptive") | | synclocalentities | boolean | — | Sync entities created by local client |

server options — Element Streaming

| Field | Type | Default | Description | |-------|------|---------|-------------| | streamindistance | number | — | Default stream-in distance | | streamoutdistance | number | — | Default stream-out distance | | pickupstreamindistance | number | — | Pickup stream-in distance | | pickupstreamoutdistance | number | — | Pickup stream-out distance |

server options — Logging

| Field | Type | Default | Description | |-------|------|---------|-------------| | logpath | string | — | Log file directory (relative to server) | | logtimestamp | string | — | Timestamp format (e.g. [%d/%m/%Y - %X]) |

server options — GTA IV

| Field | Type | Default | Description | |-------|------|---------|-------------| | iv_gamemode | number | — | GTA IV game mode (VC: leave unset) | | iv_episode | number | — | GTA IV episode (VC: leave unset) |

server options — Modules

| Field | Type | Default | Description | |-------|------|---------|-------------| | modules | string[] | [] | Module source paths |

server options — CVars

| Field | Type | Default | Description | |-------|------|---------|-------------| | cvars | object[] | defaults below | Global server CVars |

Default CVars when none specified (per-game):

GTA III: nametags, gunslinger, trains, maximumwantedlevel, defaultparkedcars, ambulances, traffic, civilians, defaultpickups, singleplayer, bigmap

GTA Vice City: nametags, gunshops, uniquestuntjumps, stuntjumps, stauntontoiletcamera, gates, trains, planes, maximumwantedlevel, defaultparkedcars, ambulances, traffic, civilians, defaultpickups, singleplayer, bigmap

GTA San Andreas: Same as VC, plus jetpack

GTA IV: nametags, iv_gamemode, `iv_episode

server options — Rules

| Field | Type | Default | Description | |-------|------|---------|-------------| | rules | object[] | defaults below | Server rules displayed in browser |

Default rules when none specified:

• Owner: Roxas
• Website: roxasytb on Discord

resource options

| Field | Type | Description | |-------|------|-------------| | name | string | Resource name (directory name) | | server | string[] | Source subdirectories for server-side code | | client | string[] | Source subdirectories for client-side code | | serverOrder | object | File ordering per directory (server-side) | | clientOrder | object | File ordering per directory (client-side) | | files | object[] | Additional files to include in meta.xml |

gtac.config.js

Alternative JavaScript configuration (auto-detected if gtac.config.json doesn't exist):

module.exports = {
  server: {
    name: "My Server",
    port: 23000,
    game: "gta:vc",
  },
  resources: [
    {
      name: "my-resource",
      server: ["server"],
      client: ["client"],
    },
  ],
};

Project Structure

A typical GTAC project using gtac-server-node:

my-server/
├── gtac.config.json              # Server & build config
├── tsconfig.json                 # TypeScript config
├── server.conf.xml               # Generated server config (after build)
├── src/
│   ├── my-resource/
│   │   ├── server/
│   │   │   ├── main.ts           # Server entry point
│   │   │   ├── events.ts         # Event handlers
│   │   │   ├── commands.ts       # Command handlers
│   │   │   └── vehicles.ts       # Vehicle management
│   │   ├── client/
│   │   │   ├── main.ts           # Client entry point
│   │   │   ├── hud.ts            # HUD rendering
│   │   │   └── gui.ts            # GUI windows
│   │   └── shared/
│   │       ├── enums.ts          # Enums and constants
│   │       ├── types.ts          # Shared interfaces
│   │       └── positions.ts      # Coordinate definitions
│   └── another-resource/
│       ├── server/
│       └── client/
└── resources/                    # Built output
    ├── my-resource/
    │   ├── server.js             # Compiled server script
    │   ├── client.js             # Compiled client script
    │   └── meta.xml              # Resource manifest
    └── another-resource/
        └── ...

API Reference

createServer(opts)

Creates a new managed GTAC server instance.

const { createServer } = require("gtac-server-node");

const server = createServer({
  name: "My Server",
  port: 23000,
  game: "gta:vc",
  maxPlayers: 32,
  resources: [{ name: "my-resource" }],
  resourcesDir: "./resources",
});

server.on("ready", () => console.log("Server ready!"));
server.on("log", (text) => console.log("[log]", text));
server.on("close", (code) => console.log("Exited with", code));

await server.start();

GtacServer

Server process manager class (extends EventEmitter). Handles resource syncing, server.xml generation, and binary lifecycle.

Constructor Options

All options are passed as a single object to new GtacServer(opts):

| Option | Type | Default | Description | |--------|------|---------|-------------| | cwd | string | process.cwd() | Project root directory | | serverDir | string | ~/.gtac-server/server | Directory containing the Server binary | | config | object | — | Full server config passed to generateServerConf() for server.xml | | resources | object[] | — | Resource configs to sync into ~/.gtac-server/server/resources/ | | resourcesDir | string | "resources" | Resources subdirectory relative to cwd |

The config object supports the same fields as gtac.config.json's server section: name, game, gamemode, port, httpport, httpserver, maxPlayers, password, minclientversion, announce, streaminterval, syncinterval, syncmethod, synclocalentities, streamindistance, streamoutdistance, pickupstreamindistance, pickupstreamoutdistance, logpath, logtimestamp, iv_gamemode, iv_episode, modules, cvars, rules.

Usage

const { readFileSync, existsSync } = require("fs");
const { join } = require("path");
const { GtacServer } = require("gtac-server-node");

// Load from gtac.config.json (same pattern as index.cjs)
const cfgPath = join(__dirname, "gtac.config.json");
const cfg = existsSync(cfgPath) ? JSON.parse(readFileSync(cfgPath, "utf-8")) : {};

const server = new GtacServer({
  cwd: __dirname,
  config: cfg.server || {},          // server.xml content
  resources: cfg.resources || [],    // resources to sync
  resourcesDir: cfg.resourcesDir || "resources",
});

server.on("ready", () => console.log("Server ready!"));
server.on("close", (code) => console.log("Exited with", code));
server.on("error", (e) => console.error(e));
await server.start();

Events

| Event | Payload | Description | |-------|---------|-------------| | ready | — | Server binary started (emitted 2s after spawn) | | close | code (number) | Server process exited | | error | error (Error) | Process spawn error |

Properties

| Property | Type | Description | |----------|------|-------------| | running | boolean | Whether the server process is alive |

Methods

async start() — Syncs resources, generates server.xml, spawns the Server binary with inherit stdio. Emits ready after 2s. stop(signal?) — Sends SIGTERM (or custom signal), then SIGKILL after 5s if still alive.

buildAll(cfg, baseDir)

Builds all resources from a configuration object.

const { buildAll } = require("gtac-server-node");
const cfg = require("./gtac.config.json");
buildAll(cfg, __dirname);

ensureServer(destDir)

Downloads the GTAC Server binary if not present.

const { ensureServer } = require("gtac-server-node");
await ensureServer("~/.gtac-server/server");

scaffold(targetDir)

Creates a new project structure.

const { scaffold } = require("gtac-server-node");
scaffold("./my-server");

generateServerConf(cfg)

Generates server.conf.xml string from a configuration object.

const { generateServerConf } = require("gtac-server-node");
const xml = generateServerConf({
  name: "My Server",
  port: 23000,
  game: "gta:vc",
  maxPlayers: 32,
  resources: [{ name: "my-resource" }],
});

generateMetaXml(res)

Generates meta.xml string for a resource configuration.

const { generateMetaXml } = require("gtac-server-node");
const xml = generateMetaXml({
  name: "my-resource",
  server: ["server"],
  client: ["client"],
});

Build System

Multi-Resource Build

The build system supports multiple resources in a single project. Each resource is configured in gtac.config.json with its own source directories and file ordering.

{
  "resources": [
    { "name": "core",   "server": ["server"],          "client": ["client"] },
    { "name": "admin",  "server": ["server", "shared"] },
    { "name": "chat",   "client": ["client"] }
  ]
}

Running npx gtac-server build processes all resources in parallel-friendly sequence, generating server.js, client.js, and meta.xml for each.

Client Safety Wrapper

When building client-side code (client array), the build system automatically wraps handlers with error reporting:

• addNetworkHandler(...) → safeAddNetworkHandler(...)
• addEventHandler(...) → safeAddEventHandler(...)
• addCommandHandler(...) → safeAddCommandHandler(...)
• console.log(...) → enhanced version that also sends triggerNetworkEvent("clientLog", ...)

Errors are reported via triggerNetworkEvent("clientError", ...) so the server can capture client-side crashes.

File Ordering

Control script concatenation order with the serverOrder and clientOrder fields:

{
  "serverOrder": {
    "server": ["main", "events", "commands"],
    "shared": ["enums", "constants", "types"]
  }
}

Files not listed in the order array are appended alphabetically after ordered files. Directories are processed in the order specified in the server/client arrays.

Standalone Export

Export a server folder that works without Node.js:

npx gtac-server export ./release

This creates:

release/
├── server.xml           # Server config
└── resources/
    ├── my-resource/
    │   ├── server.js
    │   ├── client.js
    │   └── meta.xml
    └── ...

Copy the release/ folder next to the Server binary and run ./Server.

Useful for:

• Deploying to machines without Node.js
• Sharing compiled resources with other server operators
• Creating reproducible builds

Server Binary

Automatic Download

On npm install, the postinstall.js script automatically downloads the GTAC Server 1.7.3 binary to ~/.gtac-server/server/.

Download URL: https://gtaconnected.com/downloads/server/GTAC-Server-<Platform>-<Arch>-1.7.3.tar.gz

Manual Download

npx gtac-server download

Or download directly:

• Linux x64
• Linux ARM64
• Windows x64
• Windows ARM64

Cache location can be overridden via GTAC_CACHE environment variable:

export GTAC_CACHE=/opt/gtac
npx gtac-server start

Programmatic Usage

Use gtac-server-node programmatically in your own Node.js scripts:

const {
  createServer,
  buildAll,
  ensureServer,
  scaffold,
  generateServerConf,
  generateMetaXml,
} = require("gtac-server-node");

// Scaffold a project
scaffold("./my-server");

// Load and build
const cfg = require("./my-server/gtac.config.json");
buildAll(cfg, "./my-server");

// Ensure server binary
await ensureServer("~/.gtac-server/server");

// Create and start server
const server = createServer({
  ...cfg.server,
  cwd: "./my-server",
  resourcesDir: "./my-server/resources",
});
server.on("ready", () => console.log("Server ready!"));
server.on("close", (code) => process.exit(code));
process.on("SIGINT", () => server.stop());
await server.start();

Development

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

# Install
npm install

# Test locally
cd /tmp/test-server
npm init -y
npm install /path/to/gtac-server-node
npx gtac-server init

Publishing

# Verify package contents
npm pack --dry-run

# Bump version
npm version patch

# Publish
npm publish --access public

Security

• No credentials, tokens, or secrets are included in the package
• The files field in package.json explicitly whitelists only necessary files
• The postinstall.js script downloads the GTAC Server binary from the official source (gtaconnected.com) over HTTPS
• Binary downloads go to ~/.gtac-server/ (user-local cache, never world-readable)
• No telemetry, analytics, or external network calls beyond binary download
• The server process manager handles signals gracefully (SIGTERM → 5s timeout → SIGKILL)

License

Apache 2.0 — see LICENSE.

Copyright 2025-2026 RoxasYTB.