# csgogsi

> Parse Counter-Strike Game State Integration payloads into typed snapshots and match events.

Latest version **6.0.1** (published 2026-09-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install csgogsi
pnpm add csgogsi
yarn add csgogsi
bun add csgogsi
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 6.0.1 |
| Published | 2026-09-17 |
| First published | 2019-10-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=22.12.0 |
| Dependencies | 0 |
| Unpacked size | 48.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 50 |
| Author | Hubert Walczak |
| Maintainers | osztenkurden |

## Links

- npm: https://www.npmjs.com/package/csgogsi
- Repository: https://github.com/osztenkurden/csgogsi
- Homepage: https://github.com/osztenkurden/csgogsi#readme
- Issues: https://github.com/osztenkurden/csgogsi/issues
- npm.io page: https://npm.io/package/csgogsi

## Recent versions

- 6.0.1 (latest) — 2026-09-17
- 6.0.0 — 2026-09-17
- 5.3.0 — 2026-08-26
- 5.2.0 — 2026-08-26
- 5.1.3 — 2026-08-12
- 5.1.2 — 2026-08-12
- 5.1.1 — 2026-08-12
- 5.1.0 — 2026-08-06
- 5.0.1 — 2026-04-14
- 4.1.2 — 2026-04-13
- 4.1.0 — 2026-03-04
- 4.0.2 — 2025-10-03
- 4.0.1 — 2025-10-03
- 4.0.0 — 2025-10-03
- 3.0.7 — 2024-12-04
- … 68 more at https://npm.io/package/csgogsi/versions

## README

<div align="center">

# CS2 GSI Digest

**Turn Counter-Strike game state into typed snapshots and match events.**

[![npm version](https://img.shields.io/npm/v/csgogsi?color=cb6b26)](https://www.npmjs.com/package/csgogsi)
[![CI](https://github.com/osztenkurden/csgogsi/actions/workflows/main.yaml/badge.svg)](https://github.com/osztenkurden/csgogsi/actions/workflows/main.yaml)
[![Downloads](https://img.shields.io/npm/dm/csgogsi)](https://www.npmjs.com/package/csgogsi)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

[Quick start](#quick-start) · [API reference](docs/api.md) · [Integration guide](docs/integration.md) · [Migration from 5.3.0](docs/api.md#migration-from-530) · [Changelog](CHANGELOG.md)

</div>

`csgogsi` parses CS:GO / CS2 Game State Integration (GSI) payloads for spectator HUDs, broadcast overlays, and match tooling. Feed it game snapshots; receive normalized players, teams, weapons, grenades, and events such as `roundEnd`, `bombPlant`, and `phaseChange`.

| Game state                         | Match context                          | Integration                        |
| :--------------------------------- | :------------------------------------- | :--------------------------------- |
| Numeric positions and countdowns   | Round history with side swaps          | Round and observer events          |
| Player, weapon, and grenade arrays | MR12 by default; configurable overtime | Player and team metadata overrides |
| Bomb carrier and estimated site    | Accumulated damage and ADR             | Custom bombsite resolvers          |

```text
CS2 spectator ── HTTP JSON ──► your receiver ── digest() ──► snapshots + events
```

> **Before you start:** the parser needs `allplayers`, `map`, and `phase_countdowns`. Use a spectator/observer feed with the required data enabled. The package supplies the parser; your application supplies the HTTP receiver and game configuration.

## Quick start

### 1. Install

Requires **Node.js 22.12.0 or newer**. Version 5 is **ESM-only** and includes TypeScript declarations.

```sh
npm install csgogsi express
```

Express is used only by this example. The library itself has no declared runtime dependencies.

### 2. Receive game state

Save as `server.ts`:

```javascript
import express from 'express';
import { CSGOGSI } from 'csgogsi';

const app = express();
const gsi = new CSGOGSI();

app.use(express.json({ limit: '1mb' }));

gsi.on('data', data => {
	const { team_ct: ct, team_t: t } = data.map;
	console.log(`${ct.name} ${ct.score} : ${t.score} ${t.name}`);
});

gsi.on('roundEnd', ({ winner }) => {
	console.log(`${winner.name} won the round`);
});

gsi.on('bombPlant', player => {
	console.log(`${player?.name ?? 'Unknown player'} planted the bomb`);
});

app.post('/', (req, res, next) => {
	try {
		// null means the payload lacks the required spectator sections.
		gsi.digest(req.body);
		res.sendStatus(200);
	} catch (error) {
		next(error);
	}
});

app.listen(3000, '127.0.0.1', () => {
	console.log('GSI receiver: http://127.0.0.1:3000/');
});
```

```sh
node server.ts
```

### 3. Connect the game

Copy [gamestate_integration_csgogsi.cfg](examples/gamestate_integration_csgogsi.cfg) into your CS2 installation's `game/csgo/cfg` directory, then restart the game and spectate a match. Its receiver URL matches the example above.

See the [integration guide](docs/integration.md) for data requirements, authentication, browser applications, and troubleshooting.

## Work with parsed data

```typescript
import { CSGOGSI, type GameStateRaw } from 'csgogsi';

const gsi = new CSGOGSI();

function receive(raw: GameStateRaw) {
	const data = gsi.digest(raw);
	if (!data) return;

	for (const player of data.players) {
		const activeWeapon = player.weapons.find(weapon => weapon.state === 'active');
		console.log(player.name, player.state.health, activeWeapon?.name);
	}

	console.log(data.bomb?.site); // 'A', 'B', null, or undefined when there is no bomb
}
```

Callbacks are synchronous. Treat snapshots as read-only: the parser retains object references for its next comparison. Use one instance per game feed.

## Configure your match

```javascript
const gsi = new CSGOGSI();

gsi.regulationMR = 12; // Rounds per regulation half; default 12
gsi.overtimeMR = 3; // Rounds per overtime half; default 3

// For an MR15 match, set regulationMR = 15 before the first digest.
```

These values control round-history attribution and overtime detection; they do not configure the game server. See [metadata overrides](docs/integration.md#player-and-team-metadata).

## Drive your overlay

```javascript
gsi.on('roundStart', () => console.log(`Round ${gsi.current.map.round + 1} is live`));
gsi.on('observerTargetChange', (from, to) => {
	console.log(`${from?.name ?? 'Free camera'} → ${to?.name ?? 'Free camera'}`);
});
```

Use [custom bombsite resolvers](docs/integration.md#custom-bombsites-and-map-names) for new maps or your own site boundaries. Built-in map lookup accepts workshop paths, either slash direction, and `.bsp` / `.vpk` names.

## Documentation

| Read                                     | What you will find                                            |
| :--------------------------------------- | :------------------------------------------------------------ |
| [API reference](docs/api.md)             | Methods, state, all events, parsed types, and runtime caveats |
| [Integration guide](docs/integration.md) | GSI setup, metadata, UI integration, and troubleshooting      |
| [Contributing](CONTRIBUTING.md)          | Local checks, repository layout, and release workflow         |
| [Changelog](CHANGELOG.md)                | Released changes and migration history                        |

## Development

```sh
bun install --frozen-lockfile
bun run typecheck
bun run test
bun run build
```

See [Contributing](CONTRIBUTING.md) for runtime details and checks before opening a PR.

## License

[MIT](LICENSE)

---
_Source: https://npm.io/package/csgogsi · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._