### Basic Server Setup with Java

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/configuration.md

Demonstrates creating a basic GSI configuration, writing it to the game directory, and starting a server with a simple listener.

```java
GSIConfig config = new GSIConfig(1337)
    .withDataComponents(
        DataComponent.PROVIDER,
        DataComponent.PLAYER_STATE,
        DataComponent.PLAYER_MATCH_STATS
    );

config.writeFile("my_service");

GSIListener listener = (state, context) -> {
    state.getPlayer().ifPresent(player -> {
        System.out.println("Player: " + player.getName());
    });
};

GSIServer server = new GSIServer.Builder(1337)
    .registerListener(listener)
    .build();

server.start();
```

--------------------------------

### Basic Setup and Listening in Java

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/README.md

Set up the GSI configuration, write it to the game directory, and start a listener for game state updates. Ensure the correct port is used and handle potential exceptions during file writing and server startup.

```java
GSIConfig config = new GSIConfig(1337)
    .withDataComponents(
        DataComponent.PROVIDER,
        DataComponent.PLAYER_STATE,
        DataComponent.ROUND
    );

try {
    config.writeFile("my_app");
} catch (GameNotFoundException | IOException e) {
    System.err.println("Error: " + e.getMessage());
}

GSIListener listener = (state, context) -> {
    state.getPlayer().ifPresent(player -> {
        System.out.println("Player: " + player.getName());
    });
};

GSIServer server = new GSIServer.Builder(1337)
    .registerListener(listener)
    .build();

try {
    server.start();
} catch (IOException e) {
    System.err.println("Cannot start server: " + e.getMessage());
}
```

--------------------------------

### Minimal Server Setup (Java)

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/QUICK_START.md

Set up a basic CSGO GSI server in Java. This involves creating a configuration file, writing it to the CSGO game directory, and starting a listener for game state updates.

```java
import uk.oczadly.karl.csgsi.*;
import uk.oczadly.karl.csgsi.config.*;
import uk.oczadly.karl.csgsi.state.*;

// 1. Create configuration
GSIConfig config = new GSIConfig(1337)
    .withDataComponents(
        DataComponent.PROVIDER,
        DataComponent.PLAYER_STATE,
        DataComponent.ROUND,
        DataComponent.MAP
    );

// 2. Write to game directory
try {
    config.writeFile("my_app");
    System.out.println("Config file created!");
} catch (GameNotFoundException e) {
    System.out.println("CSGO not found - see configuration.md");
}

// 3. Create listener
GSIListener listener = (state, context) -> {
    state.getPlayer().ifPresent(player -> {
        System.out.println("Player: " + player.getName());
    });
    
    state.getMap().ifPresent(map -> {
        System.out.println("Map: " + map.getName());
    });
};

// 4. Create and start server
GSIServer server = new GSIServer.Builder(1337)
    .registerListener(listener)
    .build();

try {
    server.start();
    System.out.println("Server running on port 1337");
} catch (IOException e) {
    System.out.println("Failed to start server");
}
```

--------------------------------

### start()

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-server.md

Starts the HTTP server on a new thread, enabling it to listen for game state updates. Throws an IllegalStateException if the server is already running or an IOException if the port cannot be bound.

```APIDOC
## start()

### Description
Starts the HTTP server on a new thread and begins listening for game state updates.

### Method
```java
public void start() throws IOException
```

### Throws
- `IllegalStateException`: if the server is already running
- `IOException`: if the port cannot be bound

### Example
```java
try {
    server.start();
    System.out.println("Server started on port " + server.getPort());
} catch (IOException e) {
    System.err.println("Failed to start server: " + e.getMessage());
}
```
```

--------------------------------

### Complete Game State Analysis Example

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/game-state.md

This example demonstrates how to implement a GSIListener to analyze various aspects of the game state, including provider information, map details, player statistics, and round events. It logs detailed information to the console.

```java
GSIListener analyzer = (state, context) -> {
    System.out.println("\n=== Game State Analysis #" + context.getSequentialCounter() + " ===");
    
    // Analyze provider information
    state.getProvider().ifPresent(provider -> {
        System.out.println("Client: " + provider.getClientSteamId().getAsID64());
    });
    
    // Analyze map state
    state.getMap().ifPresent(map -> {
        System.out.println("Map: " + map.getName());
        System.out.println("Round: " + map.getRound());
        System.out.println("Score - CT: " + map.getCounterTerroristStats().getScore() +
                          ", T: " + map.getTerroristStats().getScore());
    });
    
    // Analyze current player
    state.getPlayer().ifPresent(player -> {
        System.out.println("You: " + player.getName());
        player.getState().ifPresent(playerState -> {
            System.out.println("  Health: " + playerState.getHealth());
            System.out.println("  Armor: " + playerState.getArmor());
            System.out.println("  Money: $" + playerState.getMoney());
        });
        player.getStatistics().ifPresent(stats -> {
            System.out.println("  Kills: " + stats.getKills());
            System.out.println("  Deaths: " + stats.getDeaths());
            System.out.println("  Assists: " + stats.getAssists());
        });
    });
    
    // Analyze all players (spectator view)
    state.getAllPlayers().ifPresent(players -> {
        System.out.println("All players (" + players.size() + "):");
        players.forEach((steamId, player) -> {
            System.out.println("  " + player.getName() + ": " +
                             player.getStatistics().map(s -> 
                                 s.getKills() + "K/" + s.getDeaths() + "D"
                             ).orElse("N/A"));
        });
    });
    
    // Analyze round state
    state.getRound().ifPresent(round -> {
        System.out.println("Round Phase: " + round.getPhase().getValue());
        round.getWinningTeam().ifPresent(team ->
            System.out.println("Round Winner: " + team.getValue())
        );
    });
    
    // Analyze grenades (spectator view)
    state.getGrenades().ifPresent(grenades -> {
        System.out.println("Active grenades: " + grenades.getAllGrenades().size());
    });
};

```

--------------------------------

### Complete Game State Listener Example

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/game-state-context.md

An example of a GSIListener implementation that logs detailed information about each game state update, including timing, network details, and player name changes.

```java
GSIListener diagnosticListener = (state, context) -> {
    // Print timing information
    System.out.println("\n=== Game State Update #" + context.getSequentialCounter() + " ===");
    System.out.println("Received at: " + context.getTimestamp());
    
    // Print network information
    System.out.println("From address: " + context.getAddress().getHostAddress());
    System.out.println("URI path: " + context.getUriPath());
    
    // Print timing delta
    context.getMillisSinceLastState().ifPresentOrElse(
        delta -> System.out.println("Time since last state: " + delta + "ms"),
        () -> System.out.println("(First state received)")
    );
    
    // Compare with previous state
    context.getPreviousState().ifPresent(prevState -> {
        System.out.println("\nState comparison:");
        prevState.getPlayer().ifPresent(prev -> {
            state.getPlayer().ifPresent(current -> {
                if (!prev.getName().equals(current.getName())) {
                    System.out.println("Player changed: " + prev.getName() + 
                                       " -> " + current.getName());
                }
            });
        });
    });
};

```

--------------------------------

### Complete Player State Usage Example in Java

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/player-state.md

A comprehensive example demonstrating how to use the GSIListener to access and print various player and match statistics. This includes basic info, current health, armor, money, status effects, round performance, match statistics, and equipment.

```java
GSIListener playerAnalyzer = (state, context) -> {
    state.getPlayer().ifPresent(player -> {
        // Basic info
        System.out.println("\n=== Player Status ===");
        System.out.println("Name: " + player.getName());
        System.out.println("Team: " + player.getTeam());
        System.out.println("Activity: " + player.getActivity());
        
        // Current state
        player.getState().ifPresent(state_ -> {
            System.out.println("\n=== Condition ===");
            System.out.println("Health: " + state_.getHealth());
            System.out.println("Armor: " + state_.getArmor() +
                             (state_.hasHelmet() ? " (with helmet)" : ""));
            System.out.println("Money: $" + state_.getMoney());
            
            // Status effects
            if (state_.isFlashed()) System.out.println("🔆 FLASHED");
            if (state_.isSmoked()) System.out.println("💨 IN SMOKE");
            if (state_.isBurning()) System.out.println("🔥 BURNING");
            
            // Round performance
            System.out.println("\n=== Round Stats ===");
            System.out.println("Kills: " + state_.getRoundKills());
            System.out.println("Damage: " + state_.getRoundTotalDamage());
            System.out.println("Equipment value: $" + state_.getEquipmentValue());
        });
        
        // Match statistics
        player.getStatistics().ifPresent(stats -> {
            System.out.println("\n=== Match Stats ===");
            System.out.println("K/D/A: " + stats.getKills() + "/" + 
                             stats.getDeaths() + "/" + stats.getAssists());
        });
        
        // Equipment
        player.getInventory().ifPresent(inv -> {
            System.out.println("\n=== Equipment ===");
            inv.getPrimaryWeapon().ifPresent(w ->
                System.out.println("Primary: " + w.getName() +
                                 " (" + w.getAmmoClip() + "/" + w.getAmmoReserve() + ")")
            );
            inv.getSecondaryWeapon().ifPresent(w ->
                System.out.println("Secondary: " + w.getName())
            );
        });
    });
};
```

--------------------------------

### Start the GSI Server

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-server.md

Starts the HTTP server on a new thread. Use this to begin listening for game state updates. Ensure to handle potential IOExceptions during port binding.

```java
try {
    server.start();
    System.out.println("Server started on port " + server.getPort());
} catch (IOException e) {
    System.err.println("Failed to start server: " + e.getMessage());
}
```

--------------------------------

### Register Listener Before Starting Server

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/QUICK_START.md

Register listeners with the GSI server during its initialization before starting it. This is the standard way to set up listeners.

```java
GSIServer server = new GSIServer.Builder(1337)
    .registerListener(listener1)
    .registerListener(listener2)
    .build();

server.start();
```

--------------------------------

### Start and Stop GSIServer

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/README.md

Methods to start and stop the GSI server. Ensure proper shutdown to release resources.

```java
server.start();
// ... later ...
server.stop();
```

--------------------------------

### Handle SteamNotFoundException with Fallbacks

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/errors.md

Provides an example of handling SteamNotFoundException by attempting to locate the Steam directory and falling back to common installation paths if the initial attempt fails.

```java
Path steamPath;
try {
    steamPath = SteamUtils.locateSteamDirectory();
} catch (SteamNotFoundException e) {
    // Try common paths
    List<Path> commonPaths = Arrays.asList(
        Paths.get("C:\\Program Files\\Steam"),
        Paths.get("C:\\Program Files (x86)\\Steam"),
        Paths.get(System.getProperty("user.home"), ".steam")
    );
    
    steamPath = commonPaths.stream()
        .filter(p -> Files.exists(p))
        .findFirst()
        .orElseThrow(() -> new RuntimeException("Steam not found"));
}
```

--------------------------------

### Complete Map State Listener Example

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/map-state.md

Implement a listener to process and display detailed map state information, including game details, scores, economy, and round history. This example requires the `GSIListener` interface and relevant classes like `GameState`, `TeamStats`, `GameMode`, `GamePhase`, and `RoundOutcome`.

```java
GSIListener mapAnalyzer = (state, context) -> {
    state.getMap().ifPresent(map -> {
        System.out.println("\n=== Map Information ===");
        System.out.println("Map: " + map.getName());
        System.out.println("Mode: " + map.getMode());
        System.out.println("Phase: " + map.getPhase());
        System.out.println("Round: " + (map.getRound() + 1));
        
        // Team scores
        System.out.println("\n=== Score ===");
        System.out.println("CT: " + map.getCounterTerroristStats().getScore());
        System.out.println("T:  " + map.getTerroristStats().getScore());
        
        // Team economy
        System.out.println("\n=== Economy ===");
        System.out.println("CT Money: $" + map.getCounterTerroristStats().getMoney());
        System.out.println("T Money:  $" + map.getTerroristStats().getMoney());
        
        // Match info
        if (map.getSeriesMatchesToWin() > 0) {
            System.out.println("\nSeries: Best of " + (map.getSeriesMatchesToWin() * 2 - 1));
        }
        
        System.out.println("Spectators: " + map.getCurrentSpectators());
        
        // Round history
        System.out.println("\nRound History: ");
        map.getRoundResults().forEach(outcome -> {
            System.out.print(outcome.getValue() == RoundOutcome.TERRORIST_WIN ? "T" : "CT");
            System.out.print(" ");
        });
        System.out.println();
    });
};
```

--------------------------------

### Register Listener After Starting Server

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/QUICK_START.md

Listeners can be registered dynamically even after the GSI server has started. This allows for on-the-fly listener management.

```java
server.registerListener(listener3);  // Works while running
```

--------------------------------

### Register Listener

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/QUICK_START.md

Demonstrates how to register listeners with the GSIServer, both during initialization and after the server has started.

```APIDOC
## Register Listener

### Register Listener Before Starting
```java
GSIServer server = new GSIServer.Builder(1337)
    .registerListener(listener1)
    .registerListener(listener2)
    .build();

server.start();
```

### Register After Starting
```java
server.registerListener(listener3);  // Works while running
```
```

--------------------------------

### Complete GSI Configuration Example

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-config.md

Demonstrates how to create and configure a GSIConfig object, write it to the game directory, and export it as a string. Ensure the correct port and authentication details are used.

```java
GSIConfig config = new GSIConfig(1337)
    .setURI("http://localhost:1337")
    .setTimeoutPeriod(1.0)
    .setBufferPeriod(0.5)
    .disableThrottling()
    .setHeartbeatPeriod(10.0)
    .withAuthToken("password", "Q79v5tcxVQ8u")
    .withDataComponents(
        DataComponent.PROVIDER,
        DataComponent.MAP,
        DataComponent.ROUND,
        DataComponent.PLAYER_ID,
        DataComponent.PLAYER_STATE,
        DataComponent.PLAYER_WEAPONS,
        DataComponent.PLAYER_MATCH_STATS
    )
    .setDescription("My GSI Service");

// Write to game directory
try {
    Path configFile = config.writeFile("my_service");
    System.out.println("Configuration written to: " + configFile);
} catch (GameNotFoundException e) {
    System.err.println("Could not locate CSGO installation");
} catch (IOException e) {
    System.err.println("Could not write configuration file");
}

// Or export as string
String configContent = config.export();
System.out.println(configContent);
```

--------------------------------

### Create and Start GSIServer

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-server.md

Instantiates a GSIServer to listen on a specified port. Ensure the port is within the valid range (1-65535).

```java
GSIServer server = new GSIServer(1337);
server.start();
```

--------------------------------

### Registering and Managing GSIListeners with GSIServer

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-listener.md

Demonstrates how to register multiple GSIListeners with a GSIServer instance during its build process or after it has started. Also shows how to remove a listener.

```java
// Register before server starts
GSIServer server = new GSIServer.Builder(1337)
    .registerListener(listener1)
    .registerListener(listener2)
    .build();

// Or register after server starts
server.registerListener(listener3);

// Remove a listener
server.removeListener(listener1);
```

--------------------------------

### Handle Server Startup Errors

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/QUICK_START.md

Catch IOExceptions during server startup, potentially due to a port conflict. If an error occurs, a new server instance is built with a different port and started.

```java
try {
    server.start();
} catch (IOException e) {
    // Port already in use? Try different port
    int port = 8080;
    server = new GSIServer.Builder(port).build();
    server.start();
}
```

--------------------------------

### Example Player State Usage

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/player-state.md

Demonstrates how to access and display various player state details like health, armor, flash status, money, and round performance.

```java
player.getState().ifPresent(state -> {
    System.out.println("Status: " + state.getHealth() + "HP, " + 
                      state.getArmor() + " armor");
    if (state.isFlashed()) System.out.println("Player is flashed!");
    if (state.isBurning()) System.out.println("Player is on fire!");
    System.out.println("Money: $" + state.getMoney());
    System.out.println("Round kills: " + state.getRoundKills() + 
                      " (HS: " + state.getRoundKillsHeadshot() + ")");
});
```

--------------------------------

### Stop Server

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/QUICK_START.md

Provides an example of how to safely stop the GSIServer if it is currently running.

```APIDOC
## Stop Server
```java
if (server.isRunning()) {
    server.stop();
}
```
```

--------------------------------

### Configure Network Streaming Parameters

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/QUICK_START.md

Configure network streaming settings including buffer period, heartbeat interval, and timeout. This example buffers data for 500ms and sets a 10-second heartbeat.

```java
config.setBufferPeriod(0.5)      // Buffer for 500ms
    .setHeartbeatPeriod(10.0)    // Heartbeat every 10 seconds
    .setTimeoutPeriod(2.0)       // 2 second timeout
    .withDataComponents(...);
```

--------------------------------

### Add Multiple Data Components - Java

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-config.md

Adds multiple specific data components to the configuration. This example demonstrates adding player state and weapon information.

```java
config.withDataComponents(
    DataComponent.PROVIDER,
    DataComponent.PLAYER_STATE,
    DataComponent.PLAYER_WEAPONS
);
```

--------------------------------

### Get Sequential State Counter

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/game-state-context.md

Obtain the sequential counter value, which increments by one for each new state, starting from 1. This helps in tracking the order of state updates.

```java
listener = (state, context) -> {
    int stateNumber = context.getSequentialCounter();
    System.out.println("This is state #" + stateNumber);
};
```

--------------------------------

### Handle Server Already Running Exception

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/errors.md

Prevent `IllegalStateException` by checking if the server is already running before calling `start()`.

```java
GSIServer server = new GSIServer(1337);
server.start();
server.start(); // throws IllegalStateException
```

```java
if (!server.isRunning()) {
    server.start();
}
```

--------------------------------

### Handling GameNotFoundException with Fallback

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/errors.md

Provides an example of handling GameNotFoundException by falling back to user interaction or a file chooser dialog.

```java
try {
    Path configFile = config.writeFile("my_service");
} catch (GameNotFoundException e) {
    // Fallback: ask user for path
    System.out.println("Could not automatically locate CS:GO directory.");
    System.out.println("Please navigate to: .../steamapps/common/Counter-Strike Global Offensive/csgo/cfg/");
    
    // Or use a file chooser dialog
    Path customPath = showFileChooserDialog();
    config.writeFile("my_service", customPath);
}
```

--------------------------------

### getAllPlayers()

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/game-state.md

Gets state information for all players currently on the server. This information is only available if the client is spectating.

```APIDOC
## getAllPlayers()

### Description
Gets state information for all players currently on the server. This information is only available if the client is spectating.

### Method
```java
public Optional<Map<PlayerSteamID, PlayerState>> getAllPlayers()
```

### Returns
Optional containing map of PlayerSteamID to PlayerState, or empty if not available.

### Required Data Components
- `DataComponent.PLAYERS_ID` (spectator only)
- `DataComponent.PLAYERS_MATCH_STATS` (spectator only)
- `DataComponent.PLAYERS_POSITION` (spectator only)
- `DataComponent.PLAYERS_STATE` (spectator only)
- `DataComponent.PLAYERS_WEAPONS` (spectator only)

### Example
```java
state.getAllPlayers().ifPresent(playersMap -> {
    playersMap.forEach((steamId, playerState) -> {
        System.out.println("Player: " + playerState.getName());
        System.out.println("SteamID: " + steamId.getAsID64());
        System.out.println("Team: " + playerState.getTeam());
        System.out.println("Kills: " + playerState.getStatistics().getKills());
        System.out.println("Deaths: " + playerState.getStatistics().getDeaths());
    });
});
```
```

--------------------------------

### Find Available Port with IOException Handling

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/errors.md

Iteratively attempt to start the GSI server on incrementing ports until a free port is found or all ports are exhausted.

```java
int port = 1337;
while (true) {
    try {
        GSIServer server = new GSIServer(port);
        server.start();
        System.out.println("Started on port " + port);
        break;
    } catch (IOException e) {
        port++;
        if (port > 65535) throw new RuntimeException("No available ports");
    }
}
```

--------------------------------

### Get DataComponent Name

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/data-component.md

Returns the native name used in the game client configuration file.

```java
public String getConfigName()
```

```java
DataComponent.PLAYER_STATE.getConfigName() // Returns "player_state"
```

--------------------------------

### Generate CSGO Game State Configuration

Source: https://github.com/koczadly/csgo-gsi/blob/master/README.md

Use GSIConfig to automatically create the gamestate_integration configuration file for CSGO. Ensure the game and Steam installations are discoverable.

```java
// Build the configuration for our service
GSIConfig config = new GSIConfig()
        .setLocalURI(1337)  // Server on localhost:1337
        .setTimeoutPeriod(1.0)
        .setBufferPeriod(0.5)
        .withAuthToken("password", "Q79v5tcxVQ8u")
        .withAllDataComponents();  // Or specify which using withDataComponents(...)

try {
    // Automatically locates the game directory and creates the configuration file
    Path output = config.writeFile("test_service");
    System.out.println("Written config file: " + output);
} catch (GameNotFoundException e) {
    // Either CSGO or Steam installation directory could not be located
    System.err.println("Couldn't locate CSGO installation: " + e.getMessage());
} catch (IOException e) {
    System.err.println("Couldn't write to configuration file.");
}
```

```text
"Sample test service" {
    "uri"     "http://localhost:1337"
    "timeout" "1.0"
    "buffer"  "0.5"
    "auth" {
        "password" "Q79v5tcxVQ8u"
    }
    "data" {
        "map_round_wins"         "1"
        "map"                    "1"
        "player_id"              "1"
        "player_match_stats"     "1"
        "player_state"           "1"
        "player_weapons"         "1"
        "player_position"        "1"
        "provider"               "1"
        "round"                  "1"
        "allgrenades"            "1"
        "allplayers_id"          "1"
        "allplayers_match_stats" "1"
        "allplayers_position"    "1"
        "allplayers_state"       "1"
        "allplayers_weapons"     "1"
        "bomb"                   "1"
        "phase_countdowns"       "1"
    }
}
```

--------------------------------

### Get GameStateContext Millis Since Last State

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/README.md

Get the time elapsed in milliseconds since the last GameState update.

```java
OptionalInt millisSinceLastState = gameStateContext.getMillisSinceLastState();
```

--------------------------------

### Handle Server Startup Errors

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/errors.md

Catch IOExceptions during server startup. Solutions include using an alternative port if the current one is in use, or running with administrator privileges if port binding permissions are insufficient.

```java
try {
    server.start();
} catch (IOException e) {
    // Likely causes and solutions:
    // 1. Port already in use
    //    Solution: Use a different port
    GSIServer altServer = new GSIServer(8080);
    altServer.start();
    
    // 2. No permission to bind to port
    //    Solution: Use port >= 1024, or run as admin
    
    // 3. System error
    //    Solution: Check system logs, restart application
}
```

--------------------------------

### getProvider()

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/game-state.md

Gets information about the game client which reported the state. Returns an Optional containing ProviderState, or empty if not available.

```APIDOC
## getProvider()

### Description
Gets information about the game client which reported the state.

### Method
```java
public Optional<ProviderState> getProvider()
```

### Returns
Optional containing ProviderState, or empty if not available

### Required Data Component
`DataComponent.PROVIDER`

### Example
```java
state.getProvider().ifPresent(provider -> {
    System.out.println("Game: " + provider.getName());
    System.out.println("Version: " + provider.getVersion());
    System.out.println("Client SteamID: " + provider.getClientSteamId().getAsID64());
    System.out.println("Timestamp: " + provider.getTimestamp());
});
```
```

--------------------------------

### Initialize GSIServer with Port Binding (Java)

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/configuration.md

Instantiate the GSIServer, binding it to a specific port. Binding to all interfaces (0.0.0.0) is recommended if the CS:GO client is on the same machine.

```java
// All interfaces (recommended for client on same machine)
new GSIServer.Builder(1337).build();
```

```java
// Specific interface
InetAddress localAddr = InetAddress.getByName("192.168.1.100");
new GSIServer.Builder(localAddr, 1337).build();
```

--------------------------------

### Get State Update Timestamp

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/game-state-context.md

Get the local server timestamp when the state update was received. Useful for tracking the timing of updates.

```java
listener = (state, context) -> {
    Instant updateTime = context.getTimestamp();
    System.out.println("State received at: " + updateTime);
};
```

--------------------------------

### GSIServer.Builder.build

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-server.md

Constructs a new GSIServer instance with the configured parameters.

```APIDOC
## build()

### Description
Constructs a new `GSIServer` instance with the configured parameters.

### Returns
A new GSIServer instance

### Example
```java
GSIServer server = new GSIServer.Builder(1337)
    .requireAuthToken("password", "secure_token")
    .disableDiagnosticsPage()
    .build();
```
```

--------------------------------

### Get Player Steam ID

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/player-state.md

Retrieves the player's Steam ID. Use getAsID64(), getAsID2(), or getAsID3() to get the ID in different formats.

```java
player.getSteamId(); // Returns PlayerSteamID object
// Get in various formats:
player.getSteamId().getAsID64();    // "76561198050830377"
player.getSteamId().getAsID2();     // "STEAM_1:1:45282324"
player.getSteamId().getAsID3();     // "[U:1:90564649]"
```

--------------------------------

### Create GSIConfig with URI

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-config.md

Initialize GSIConfig using a complete URI string, which includes the protocol, host, and port. This is a convenient way to set all connection details at once.

```java
public GSIConfig(String uri)
```

```java
GSIConfig config = new GSIConfig("http://example.com:9000");
```

--------------------------------

### GameNotFoundException Class

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/types.md

Thrown when the CS:GO game installation directory cannot be located on the system. This exception is part of the `uk.oczadly.karl.csgsi.config` package.

```java
public class GameNotFoundException extends Exception
```

--------------------------------

### Spectator View with All Data

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/configuration.md

Sets up a server to capture all available game data for spectator analysis, with buffering and heartbeat configured.

```java
GSIConfig config = new GSIConfig(1337)
    .setBufferPeriod(0.5)      // Buffer for 500ms
    .setHeartbeatPeriod(15.0)  // Heartbeat every 15 seconds
    .withAllDataComponents()   // Get all available data
    .setDescription("Spectator Analysis Tool");

config.writeFile("spectator_tool");

GSIServer server = new GSIServer.Builder(1337)
    .registerListener(spectatorAnalyzer)
    .build();

server.start();
```

--------------------------------

### Get PlayerState Name

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/README.md

Retrieve the name of the player.

```java
String name = playerState.getName();
```

--------------------------------

### Get PlayerState Steam ID

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/README.md

Retrieve the SteamID of the player.

```java
PlayerSteamID steamId = playerState.getSteamId();
```

--------------------------------

### GSIConfig(String host, int port) Constructor

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-config.md

Creates a GSI configuration with the server on the specified host and port.

```APIDOC
## GSIConfig(String host, int port)

### Description
Creates a GSI configuration with the server on the specified host and port.

### Method
Constructor

### Parameters
#### Path Parameters
- **host** (String) - Required - Hostname or IP address
- **port** (int) - Required - Port number (1-65535)

### Request Example
```java
GSIConfig config = new GSIConfig("192.168.1.100", 8080);
```
```

--------------------------------

### Get GameStateContext Timestamp

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/README.md

Retrieve the timestamp of when the GameState was generated.

```java
Instant timestamp = gameStateContext.getTimestamp();
```

--------------------------------

### Build GSIServer with Builder Pattern

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-server.md

Recommended approach to create a GSIServer. Allows for configuration of authentication tokens, listeners, and disabling the diagnostics page before building the server instance.

```java
GSIServer server = new GSIServer.Builder(1337)
    .requireAuthToken("password", "Q79v5tcxVQ8u")
    .registerListener(listener)
    .build();
```

```java
GSIServer server = new GSIServer.Builder(1337)
    .requireAuthToken("password", "secure_token")
    .disableDiagnosticsPage()
    .build();
```

--------------------------------

### Get Player Match Statistics

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/player-state.md

Retrieves match statistics for the player, including kills, deaths, and assists. Requires player match statistics data components.

```java
public MatchStats getStatistics()
```

```java
player.getStatistics().ifPresent(stats -> {
    System.out.println("Kills: " + stats.getKills());
    System.out.println("Deaths: " + stats.getDeaths());
    System.out.println("Assists: " + stats.getAssists());
    System.out.println("KD Ratio: " + 
        (stats.getDeaths() > 0 ? 
         stats.getKills() / (double)stats.getDeaths() : 
         stats.getKills()));
});
```

--------------------------------

### Get PlayerState Inventory

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/README.md

Retrieve the player's current inventory.

```java
PlayerInventory inventory = playerState.getInventory();
```

--------------------------------

### GSIConfig(String uri) Constructor

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-config.md

Creates a GSI configuration with a complete URI including protocol and port.

```APIDOC
## GSIConfig(String uri)

### Description
Creates a GSI configuration with a complete URI including protocol and port.

### Method
Constructor

### Parameters
#### Path Parameters
- **uri** (String) - Required - Full URI (e.g., "http://localhost:1337")

### Request Example
```java
GSIConfig config = new GSIConfig("http://example.com:9000");
```
```

--------------------------------

### Get PlayerState Team

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/README.md

Retrieve the team the player is on, represented by an EnumValue.

```java
EnumValue<Team> team = playerState.getTeam();
```

--------------------------------

### GSIConfig(int port) Constructor

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-config.md

Creates a GSI configuration with the server listening on localhost on the specified port.

```APIDOC
## GSIConfig(int port)

### Description
Creates a GSI configuration with the server listening on localhost on the specified port.

### Method
Constructor

### Parameters
#### Path Parameters
- **port** (int) - Required - Port number (1-65535)

### Request Example
```java
GSIConfig config = new GSIConfig(1337);
```
```

--------------------------------

### Get GameStateContext Address

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/README.md

Retrieve the network address from which the GameState was received.

```java
InetAddress address = gameStateContext.getAddress();
```

--------------------------------

### DataComponent Enumeration

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/types.md

Enumerates all available game state information components that can be configured in the GSI profile. Use `getConfigName()` to get the config name for the GSI profile and `isObserverOnly()` to check if data is observer-only.

```java
public enum DataComponent
```

--------------------------------

### Configure All Data Components for Spectator Mode

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/QUICK_START.md

This is a shortcut to enable all available data components, suitable for spectator modes where comprehensive data is required.

```java
config.withAllDataComponents();
```

--------------------------------

### GSIConfig() Constructor

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-config.md

Creates an empty GSI configuration object with no parameters set.

```APIDOC
## GSIConfig()

### Description
Creates an empty GSI configuration object with no parameters set.

### Method
Constructor

### Parameters
None
```

--------------------------------

### Get PlayerState Position

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/README.md

Retrieve the player's current position on the map.

```java
Coordinate position = playerState.getPosition();
```

--------------------------------

### GSIServer.Builder Constructor (bindAddr, bindPort)

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-server.md

Creates a builder with a specific bind address and port.

```APIDOC
## GSIServer.Builder(InetAddress bindAddr, int bindPort)

### Description
Creates a builder with a specific bind address and port.

### Parameters
#### Path Parameters
- **bindAddr** (InetAddress) - Optional - IP address to bind to, or null to bind to all
- **bindPort** (int) - Required - Socket port to bind to (1-65535)
```

--------------------------------

### getBomb()

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/game-state.md

Gets state information about the bomb. This information is only available if the client is spectating.

```APIDOC
## getBomb()

### Description
Gets state information about the bomb. This information is only available if the client is spectating.

### Method
```java
public Optional<BombState> getBomb()
```

### Returns
Optional containing BombState, or empty if not available.

### Required Data Component
- `DataComponent.BOMB` (spectator only)

### Example
```java
state.getBomb().ifPresent(bomb -> {
    System.out.println("Bomb state: " + bomb.getState());
    System.out.println("Position: " + bomb.getPosition());
    bomb.getPlanter().ifPresent(planter -> 
        System.out.println("Planted by: " + planter)
    );
});
```
```

--------------------------------

### Get GameStateContext Auth Tokens

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/README.md

Retrieve the authentication tokens associated with this GameState update.

```java
Map<String, String> authTokens = gameStateContext.getAuthTokens();
```

--------------------------------

### Get Latest GameState

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/README.md

Retrieve the most recent GameState object. This can be useful for polling or debugging.

```java
GameState latestState = server.getLatestGameState();
```

--------------------------------

### GSIServer Constructor

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-server.md

Constructs a new GSIServer that listens on the specified port, binding to all network interfaces.

```APIDOC
## GSIServer(int port)

### Description
Constructs a new GSIServer that listens on the specified port, binding to all network interfaces.

### Parameters
#### Path Parameters
- **port** (int) - Required - Network port to listen on (1-65535)

### Throws
- `IllegalArgumentException` if port is outside the range 1-65535

### Example
```java
GSIServer server = new GSIServer(1337);
server.start();
```
```

--------------------------------

### getRound()

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/map-state.md

Retrieves the current round number, starting from 0. Requires the DataComponent.MAP data component.

```APIDOC
## getRound()

### Description
Gets the current round number (0-based).

### Method
```java
public short getRound()
```

### Returns
Round number

### Required Data Component
`DataComponent.MAP`

### Example
```java
System.out.println("Round: " + (map.getRound() + 1)); // 1-based display
```
```

--------------------------------

### Get Vector Precision

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-config.md

Retrieves the currently configured number of decimal places for vector values.

```java
public Integer getPrecisionVector()
```

--------------------------------

### Configure GSIServer with Auth Tokens

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/configuration.md

Use `requireAuthToken` to set a single authentication token or `requireAuthTokens` for multiple tokens. This is useful when your game server requires specific credentials for GSI communication.

```java
GSIServer server = new GSIServer.Builder(1337)
    .requireAuthToken("password", "Q79v5tcxVQ8u")
    .requireAuthToken("api_key", "secret123")
    .build();
```

--------------------------------

### Add All Data Components - Java

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-config.md

Adds all available data components to the configuration. This is a shortcut to include every possible data component.

```java
public GSIConfig withAllDataComponents()
```

--------------------------------

### Get Position Precision

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-config.md

Retrieves the currently configured number of decimal places for position values.

```java
public Integer getPrecisionPosition()
```

--------------------------------

### Get Time Precision

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-config.md

Retrieves the currently configured number of decimal places for time values.

```java
public Integer getPrecisionTime()
```

--------------------------------

### Basic Player Tracking Configuration

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/data-component.md

Configure GSIClient to track basic player information.

```java
GSIConfig config = new GSIConfig(1337)
    .withDataComponents(
        DataComponent.PROVIDER,
        DataComponent.PLAYER_ID,
        DataComponent.PLAYER_STATE,
        DataComponent.PLAYER_MATCH_STATS
    );
```

--------------------------------

### Full Player Information Configuration

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/data-component.md

Configure GSIClient to retrieve comprehensive player data.

```java
GSIConfig config = new GSIConfig(1337)
    .withDataComponents(
        DataComponent.PROVIDER,
        DataComponent.MAP,
        DataComponent.ROUND,
        DataComponent.PLAYER_ID,
        DataComponent.PLAYER_STATE,
        DataComponent.PLAYER_WEAPONS,
        DataComponent.PLAYER_MATCH_STATS,
        DataComponent.PLAYER_POSITION
    );
```

--------------------------------

### Get Heartbeat Period

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-config.md

Retrieves the configured heartbeat period in seconds. Returns null if not set.

```java
public Double getHeartbeatPeriod()
```

--------------------------------

### Configure and Require Authentication Tokens

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/QUICK_START.md

Set up authentication tokens for your CS:GO GSI configuration. This includes including a password in the config and requiring a password for server connections.

```java
String password = "secure_key_123";

// Config: include password
config.withAuthToken("password", password);

// Server: require password
server = new GSIServer.Builder(1337)
    .requireAuthToken("password", password)
    .build();
```

--------------------------------

### Get Throttle Period

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-config.md

Retrieves the configured throttle period in seconds. Returns null if not set.

```java
public Double getThrottlePeriod()
```

--------------------------------

### Get Buffer Period

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-config.md

Retrieves the configured buffer period in seconds. Returns null if not set.

```java
public Double getBufferPeriod()
```

--------------------------------

### writeFile(String serviceName)

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-config.md

Creates or replaces a GSI configuration file in the automatically detected CSGO game directory.

```APIDOC
## writeFile(String serviceName)

### Description
Creates or replaces a configuration file in the automatically-located CSGO game directory.

### Parameters
#### Path Parameters
- **serviceName** (String) - Required - Service name (3-32 alphanumeric/underscore chars)

### Returns
Path to the created config file

### Throws
- `GameNotFoundException` if CSGO installation directory cannot be found
- `IOException` if the file cannot be written
- `IllegalStateException` if required configuration values are not set
- `SecurityException` if file system access is denied

### Example
```java
try {
    Path configFile = config.writeFile("my_service");
    System.out.println("Config written to: " + configFile);
} catch (GameNotFoundException e) {
    System.err.println("CSGO not found");
} catch (IOException e) {
    System.err.println("Cannot write config file");
}
```
```

--------------------------------

### Set Application Description

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/configuration.md

Use `setDescription` to provide a custom description for your CS:GO application configuration. This is optional.

```java
config.setDescription("My CS:GO Application");
```

--------------------------------

### Get Player Round Kills

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/player-state.md

Retrieves the number of kills the player has achieved in the current round.

```java
public short getRoundKills()
```

--------------------------------

### Get Player Money

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/player-state.md

Retrieves the player's current in-game money amount in dollars.

```java
public int getMoney()
```

--------------------------------

### Get PlayerState Statistics

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/README.md

Retrieve the player's match statistics, such as kills, deaths, and assists.

```java
MatchStats stats = playerState.getStatistics();
```

--------------------------------

### Configure Basic Player Tracking

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/QUICK_START.md

Use this configuration to track essential player and game state information. It includes provider, player ID, player state, match statistics, map, and round data.

```java
config.withDataComponents(
    DataComponent.PROVIDER,
    DataComponent.PLAYER_ID,
    DataComponent.PLAYER_STATE,
    DataComponent.PLAYER_MATCH_STATS,
    DataComponent.MAP,
    DataComponent.ROUND
);
```

--------------------------------

### Get PlayerState Details

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/README.md

Retrieve the detailed player state, including health, armor, and equipment.

```java
PlayerStateDetails details = playerState.getState();
```

--------------------------------

### writeFile(String serviceName, Path dir)

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-config.md

Creates or replaces a GSI configuration file in a specified directory.

```APIDOC
## writeFile(String serviceName, Path dir)

### Description
Creates or replaces a configuration file in the specified directory.

### Parameters
#### Path Parameters
- **serviceName** (String) - Required - Service name (3-32 alphanumeric/underscore chars)
- **dir** (Path) - Required - Directory to write to

### Returns
Path to the created config file

### Throws
- `IOException` if the file cannot be written
- `IllegalStateException` if required configuration values are not set
```

--------------------------------

### Get Required Auth Tokens

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/README.md

Retrieve the map of required authentication tokens configured for the server.

```java
Map<String, String> tokens = server.getRequiredAuthTokens();
```

--------------------------------

### GSIServer.Builder Constructor (bindPort)

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-server.md

Creates a builder that binds to all IP interfaces on the specified port.

```APIDOC
## GSIServer.Builder(int bindPort)

### Description
Creates a builder that binds to all IP interfaces on the specified port.

### Parameters
#### Path Parameters
- **bindPort** (int) - Required - Socket port to bind to (1-65535)

### Example
```java
GSIServer server = new GSIServer.Builder(1337)
    .requireAuthToken("password", "Q79v5tcxVQ8u")
    .registerListener(listener)
    .build();
```
```

--------------------------------

### getPhaseCountdowns()

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/game-state.md

Gets timing information for the current round phase. This information is only available if the client is spectating.

```APIDOC
## getPhaseCountdowns()

### Description
Gets timing information for the current round phase. This information is only available if the client is spectating.

### Method
```java
public Optional<PhaseCountdownState> getPhaseCountdowns()
```

### Returns
Optional containing PhaseCountdownState, or empty if not available.

### Required Data Component
- `DataComponent.PHASE_COUNTDOWNS` (spectator only)

### Example
```java
state.getPhaseCountdowns().ifPresent(countdowns -> {
    countdowns.getFreezeTimeCountdown().ifPresent(time ->
        System.out.println("Freeze time remaining: " + time + "s")
    );
    countdowns.getRoundEndCountdown().ifPresent(time ->
        System.out.println("Round end countdown: " + time + "s")
    );
});
```
```

--------------------------------

### Registering Listeners with GSIServer

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-listener.md

Demonstrates how to register and remove GSIListener instances with a GSIServer.

```APIDOC
## Usage with GSIServer

Listeners are registered with a `GSIServer` instance:

```java
// Register before server starts
GSIServer server = new GSIServer.Builder(1337)
    .registerListener(listener1)
    .registerListener(listener2)
    .build();

// Or register after server starts
server.registerListener(listener3);

// Remove a listener
server.removeListener(listener1);
```
```

--------------------------------

### Listen for CSGO Game State Information

Source: https://github.com/koczadly/csgo-gsi/blob/master/README.md

Set up a GSIServer to listen for game state updates and register a GSIListener to process the incoming data. Ensure the server is started in a try-catch block to handle potential IOExceptions.

```java
// Create a new listener (using a lambda for this example)
GSIListener listener = (state, context) -> {
    // Access state information with the 'state' object...
    System.out.println("New state from game client address " + context.getAddress().getHostAddress());
    
    state.getProvider().ifPresent(provider -> {
        System.out.println("Client SteamID: " + provider.getClientSteamId());
    });
    state.getMap().ifPresent(map -> {
        System.out.println("Current map: " + map.getName());
    });
};

// Configure server
GSIServer server = new GSIServer.Builder(1337)        // Port 1337, on all network interfaces
        .requireAuthToken("password", "Q79v5tcxVQ8u") // Require the specified password
        .registerListener(listener)                   // Alternatively, you can call this dynamically on the GSIServer
        .build();

// Start server
try {
    server.start(); // Start the server (runs in a separate thread)
    System.out.println("Server started. Listening for state data...");
} catch (IOException e) {
    System.err.println("Couldn't start server.");
}
```

--------------------------------

### Write GSI Configuration to CSGO Directory

Source: https://github.com/koczadly/csgo-gsi/blob/master/_autodocs/api-reference/gsi-config.md

Creates or overwrites a GSI configuration file within the CSGO game directory. Ensure the service name adheres to the specified format. This method can throw exceptions if the CSGO installation is not found, if there are I/O errors, or if required configuration values are not set.

```java
try {
    Path configFile = config.writeFile("my_service");
    System.out.println("Config written to: " + configFile);
} catch (GameNotFoundException e) {
    System.err.println("CSGO not found");
} catch (IOException e) {
    System.err.println("Cannot write config file");
}
```