🎯 CS2-GSI-Z

A modern, modular, and event-driven Game State Integration (GSI) handler for Counter-Strike 2, built with Node.js.

📖 Project Overview

cs2-gsi-z is an advanced event processing library for Counter-Strike 2 Game State Integration (GSI) data. It transforms raw GSI JSON updates into high-level, context-aware events, enabling developers to easily build real-time HUDs, dashboards, analytics systems, bots, or esports tools.

Unlike traditional GSI listeners that emit low-level or noisy data, cs2-gsi-z structures and simplifies information, significantly reducing client-side complexity.

✨ Why CS2-GSI-Z?

“There are other GSI tools... why use this one?”

Whether you're building a companion HUD, tournament backend, stream overlay, or an esports analytics dashboard — this is the toolkit designed for you.

🚀 Key Features

• 🌟 Structured, Context-Aware Events

  Problem Solved: No need to manually parse complex GSI dumps. Benefit: Focus immediately on meaningful gameplay changes.

• 🧩 Modular Differ System

  Problem Solved: Avoids tangled monolithic update handlers. Benefit: Easier maintenance, faster extension, safer upgrades.

• ✨ Delta-Aware Processing

  Problem Solved: Deep-cloning and manual patching are error-prone. Benefit: Fast, reliable diff calculation with minimal memory footprint.

• 🔀 Dynamic Diff Manager

  Problem Solved: Hardcoding all diffs upfront limits flexibility. Benefit: Extend or replace behaviors easily at runtime.

• 🎯 Flexible Event Subscription

  Problem Solved: Handling noisy events on the client. Benefit: Listen only to what matters, improving performance.

• 💪 Optimized for Real-Time Systems

  Problem Solved: Raw GSI processing can cause lags or instability. Benefit: Low-latency, high-frequency event handling.

🚀 Quick Start

Prerequisites

To receive data from CS2, you must set up a Game State Integration (GSI) configuration file. Reference: Valve Developer Wiki — Game State Integration

Or you can simply generate a valid GSI configuration file automatically using the included helper in this library:

import { GSIConfigWriter } from 'cs2-gsi-z';

// Generate the config file on your desktop
const configPath = GSIConfigWriter.generate({
  name: 'cs2-gsi-z',
  uri: 'http://localhost:3000'
});

console.log(`Config file created at: ${configPath}`);

Remember to move the generated .cfg file to your CS2 cfg directory

Installation

npm install cs2-gsi-z

⚠️ Note: This package is not yet published on npm. You can install it directly from GitHub for now.

Basic Usage

import { GsiService, EVENTS } from 'cs2-gsi-z';

const gsi = new GsiService({
  httpPort: 3000
});

gsi.start();

gsi.on(EVENTS.player.weaponChanged, (payload) => {
  console.log(`weapon changed:`, payload);
});

📈 Event Model

When a new GSI payload is received, cs2-gsi-z:

1. 🔄 Applies delta changes efficiently.
2. 🔀 Detects relevant modifications via differs.
3. 💪 Emits structured, context-aware events.

Each emitted event includes:

{
  previous: <previous value>,
  current: <current value>,
  previouslyBlock: <raw previous GSI block>,
  addedBlock: <raw new GSI block>
}

🔖 Supported Events

Player: hpChanged, armorChanged, teamChanged, weaponChanged, activityChanged, helmetChanged, flashedChanged, smokedChanged, burningChanged, killsChanged, deathsChanged, assistsChanged, scoreChanged

Round: phaseChanged, started, ended, won

Map: nameChanged, phaseChanged, roundChanged, teamCTScoreChanged, teamTScoreChanged

(Some of them are not yet implemented, but you can easily do it)

🔢 Differs and Diff Manager

Each differ handles one domain: player, round, map, etc.

The DifferManager:

• Manages active differs
• Calls them on each GSI update
• Emits clean events when changes are detected

Extend or replace differs without touching core functionality.

🎯 Extending with Custom Differs

Register your own differ easily:

const customDiffer = {
  diff(prev, curr, emitter) {
    const p = prev?.map?.team_t;
    const c = curr.map?.team_t;
    if (p && c && p.score !== c.score) {
      emitter.emit('map:teamTScoreChanged', { previous: p.score, current: c.score });
    }
  }
};

gsi.differManager.registerDiffer(customDiffer);

🔍 Advanced Event Subscription

Subscribe to:

• Specific event (player:hpChanged)
• Whole namespace (player:*)

gsi.on('player:*', (eventName, payload) => {
  console.log(`[Player Event] ${eventName}:`, payload);
});

🔹 Examples

Log Health Changes

gsi.on('player:hpChanged', ({ previous, current }) => {
  console.log(`HP: ${previous} → ${current}`);
});

Log Map Changes

gsi.on('map:nameChanged', ({ previous, current }) => {
  console.log(`Map: ${previous} → ${current}`);
});

🌐 Use Cases

• 🏋️ Live HUDs for players and spectators
• 🌍 Stream overlays with real-time updates
• 📊 Tournament backends and dashboards
• 👾 Automated bots reacting to events
• 📘 Esports analytics and match reviews
• 💪 Coaching and training tools

🔹 Requirements

• Node.js v18+
• Support for async/await, optional chaining (?.), and ES Modules.

🧳 Contributing

Pull requests, ideas, and feedback are welcome! If you are using cs2-gsi-z for your tools, streams, or projects, feel free to share and contribute back.

🙏 Acknowledgments

• Valve Corporation for the CS Game State Integration API

• CS community for inspiration and feedback

🔒 License

Distributed under the MIT License. See LICENSE for full text.

Made with ❤️ for the CS2 community