go-client

README

Pulse Networking Go Client

A battle-tested, production-grade game networking client for Go

Features • Installation • Quickstart • Documentation • Examples • Contributing • License

Overview

The Pulse Networking Go Client provides a high-performance, production-ready networking stack for connecting Go applications to Pulse Networking servers. This library handles all aspects of network communication, state synchronization, and client-side prediction to create smooth, responsive multiplayer experiences even in challenging network conditions.

Features

• Reliable UDP Communication: Automatic packet retries, ACK tracking, and timeout management
• Delta-Compressed Snapshots: Bandwidth-efficient entity state synchronization
• Split Packet Handling: Automatic splitting and reassembly of large payloads
• Client-Side Prediction: Input replay and state correction for responsive gameplay
• Chaos Resilience: Robust operation in high packet loss, latency, and jitter conditions
• Optimized for Go: Clean, idiomatic Go API with minimal dependencies
• Cross-Platform: Works on any platform supported by Go

Installation

go get git.pulsenet.dev/pulse/go-client

Ensure you're using Go 1.24 or newer for the best experience.

Quickstart

Here's a simple example of creating a client, connecting to a Pulse server, and handling state updates:

package main

import (
    "context"
    "log"
    "time"

    "git.pulsenet.dev/pulse/go-client"
)

func main() {
    // Create a new client
    c, err := client.New(client.Options{
        ServerAddress: "127.0.0.1:7777",
    })
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }
    defer c.Close()

    // Connect to the server
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()
    if err := c.Connect(ctx); err != nil {
        log.Fatalf("Failed to connect: %v", err)
    }
    log.Println("Connected to server!")

    // Register state update handler
    c.OnStateUpdate(func(entities []client.Entity) {
        for _, entity := range entities {
            log.Printf("Entity %d: Position (%.2f, %.2f), Velocity (%.2f, %.2f)",
                entity.ID, entity.PosX, entity.PosY, entity.VelX, entity.VelY)
        }
    })

    // Main loop - send inputs every 16ms (60Hz)
    ticker := time.NewTicker(16 * time.Millisecond)
    defer ticker.Stop()

    for {
        select {
        case <-ticker.C:
            // Create and send input
            input := client.InputPacket{
                Sequence: c.NextInputSequence(),
                Timestamp: uint32(time.Now().UnixMilli()),
                Flags: client.FlagThrust, // Example: pressing thrust button
                TurnDirection: 1,         // Example: turning right
            }
            if err := c.SendInput(input); err != nil {
                log.Printf("Error sending input: %v", err)
            }
        }

        // Process network messages
        c.Update()
    }
}

Documentation

Complete documentation is available at https://docs.pulsenet.dev/client/go.

Key Concepts

• Entity: A game object with position, velocity, and rotation
• Snapshot: A point-in-time representation of the game state
• Input Packet: A client-to-server message containing player actions
• Reliable Channel: A layer ensuring ordered message delivery on top of UDP
• Client-Side Prediction: Applying inputs locally before server confirmation

Examples

The examples/ directory contains several complete examples:

• Basic Client: Simple connection and state handling
• Prediction: Client-side movement prediction with server correction
• Chaos Testing: Client that simulates poor network conditions
• Entity Interpolation: Smooth entity movement between snapshots
• Command Buffer: Storing and replaying missed inputs

To run an example:

go run examples/basic/main.go

Configuration

The client can be configured with various options:

c, err := client.New(client.Options{
    ServerAddress:  "127.0.0.1:7777",
    ReliableResendDelayMs: 100,
    MaxResendAttempts: 5,
    ReorderingEnabled: true,
    ReorderingMaxDelayMs: 50,
    SimulatedPacketLoss: 0.0, // Set to >0 to test packet loss
    SimulatedMinLatencyMs: 0,
    SimulatedMaxLatencyMs: 0,
})

See the configuration documentation for all available options.

Performance Benchmarks

The Go client has been tested with:

• 1,000+ simulated clients on a single machine
• Average processing time <1ms per client
• 95% bandwidth reduction with delta compression
• Reliable synchronization with up to 40% packet loss

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

By submitting a pull request, you agree to license your contributions under the GNU Affero General Public License v3.0.

Commercial Support and Licensing

While this client is released under the AGPL license, commercial licensing options are available for those who wish to use Pulse Networking in proprietary applications.

For licensing inquiries, please contact:

• Email: licensing@pulsenet.dev
• Website: https://www.pulsenet.dev/licensing

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the LICENSE file for details.

Important Notice

The AGPL license requires that if you modify and use this software as part of a network service, you must make the source code of your modified version available to users of that service.

This means:

1. If you modify this client and use it in an application accessed over a network, you must make your modified source code available to all users who interact with it
2. The entire Go application statically linked with this client (not just the client code) falls under the AGPL requirements
3. You must include proper attribution and license notices

If you cannot or do not wish to comply with these terms, please consider our commercial licensing options.