NetCore Networking

A production-ready networking system for multiplayer games with NetCore architecture. This package provides a complete networking solution with real-time communication, security features, and performance monitoring.

Features

$3

- 128Hz Server Tick Rate - High-frequency game state updates
- Client-Side Interpolation - Smooth gameplay despite network jitter
- Server-Side Prediction - Handles latency and input validation
- Real-Time Communication - WebSocket-based bidirectional messaging
- Automatic Reconnection - Robust connection handling

$3

- WebSocket Transport - Reliable TCP-based communication (default)
- UDP Transport - High-performance, low-latency communication
- Hybrid Transport - Automatic switching between WebSocket and UDP
- Auto-Detection - Smart transport selection based on network conditions
- Transport Switching - Runtime switching between transport layers
- Transport Manager - Unified management of multiple transport layers

$3

- Rate Limiting - Prevents spam and abuse
- Input Validation - Validates all client inputs
- IP Whitelisting/Blacklisting - Access control
- Connection Monitoring - Tracks suspicious activity
- Automatic Banning - Temporary bans for violations
- Session Management - Secure session tokens and validation
- Anti-Cheat Plugin System - Easy-to-use plugin architecture for custom anti-cheat
- Enhanced Security - Encryption, DDoS protection, and client integrity verification
- Transport-Agnostic Security - Security features work across all transport layers

$3

- Game Sessions - Create and manage multiple game sessions
- Player Management - Join, leave, and track players in sessions
- Session Settings - Configurable game rules and parameters
- Auto-Cleanup - Automatic cleanup of inactive sessions
- Session Statistics - Monitor session performance and activity

$3

- Load Balancing - Distribute players across multiple server instances
- Auto-Scaling - Automatically create/remove instances based on demand
- Instance Management - Monitor and manage multiple server instances
- Port Management - Automatic port allocation for new instances
- Performance Monitoring - Track performance across all instances

$3

- Real-Time Metrics - Ping, packet loss, jitter tracking
- Connection Quality Assessment - Automatic quality scoring
- Performance Alerts - Automatic issue detection
- Bandwidth Monitoring - Network usage tracking
- System Statistics - CPU, memory, and network stats

$3

- TypeScript Support - Full type safety
- Configuration Management - Flexible server configuration
- Network Utilities - Common networking functions
- Performance Analysis - Detailed metrics and reporting

Installation

> 📦 Note: Version 1.1.0 had a dependency issue that prevented downloads. Please use version 1.1.1 or later.

$3

``bash
bun add netcore-networking
`

$3

`bash
npm install netcore-networking
`

$3

`bash
yarn add netcore-networking
`

Quick Start

$3

`typescript
import { createServer, DEFAULT_CONFIG } from "netcore-networking";

// Create server with default configuration
const server = createServer(8080, DEFAULT_CONFIG);

// Start the server
await server.start(); // Note: start() is now async

// Handle graceful shutdown
process.on("SIGINT", () => {
server.stop();
process.exit(0);
});
`

$3

`typescript
import { NetCoreClient } from "netcore-networking";

// Create client
const client = new NetCoreClient("ws://localhost:8080");

// Set handshake data (REQUIRED: checksum and version)
client.setHandshakeData("your-client-checksum", "1.0.0");

// Connect to server
await client.connect();

// Send player input
client.sendInput({
movement: { x: 1, y: 0 },
actions: { shoot: true, jump: false },
});

// Get network statistics
const stats = client.getNetworkStats();
console.log(Ping: ${stats.ping}ms, Packet Loss: ${stats.packetLoss}%);
`

> ⚠️ Important: You must call setHandshakeData(checksum, version) before connecting. The server will reject clients that do not provide a valid handshake.

$3

NetCore supports multiple transport layers with a unified Transport Manager system:

#### WebSocket Transport (Default)

`typescript
// Default WebSocket transport
const server = createServer(8080, {
transport: {
primaryTransport: "websocket",
websocket: {
enabled: true,
port: 8080,
host: "0.0.0.0",
maxPayload: 1024 * 1024, // 1MB
perMessageDeflate: false,
},
},
});
`

#### UDP Transport (High Performance)

`typescript
// High-performance UDP transport for hardcore FPS
const server = createServer(8080, {
transport: {
primaryTransport: "udp",
udp: {
enabled: true,
port: 8081,
host: "0.0.0.0",
enableReliableUDP: true,
enablePacketOrdering: true,
enableFragmentation: true,
maxPacketSize: 1400, // MTU-safe
fragmentSize: 1024,
retransmitTimeout: 100, // ms
maxRetransmits: 3,
sendBufferSize: 1024 * 1024, // 1MB
receiveBufferSize: 1024 * 1024, // 1MB
enableQoS: true,
priorityLevels: 4,
enablePerformanceMetrics: true,
},
},
});
`

#### Hybrid Transport (Best of Both Worlds)

`typescript
// Hybrid transport - automatic switching
const server = createServer(8080, {
transport: {
primaryTransport: "hybrid",
hybrid: {
enabled: true,
useWebSocketForReliable: true, // Reliable data via WebSocket
useUDPForFast: true, // Fast data via UDP
switchThreshold: 50, // 50ms latency difference
},
},
});
`

#### Auto-Detection Transport

`typescript
// Smart transport selection
const server = createServer(8080, {
transport: {
primaryTransport: "auto",
auto: {
enabled: true,
latencyThreshold: 100, // Use UDP if latency < 100ms
packetLossThreshold: 5, // Switch to WebSocket if packet loss > 5%
switchCooldown: 5000, // Minimum 5s between switches
},
},
});
`

$3

The new Transport Manager provides unified management of multiple transport layers:

`typescript
import { TransportManager, UDPTransport } from "netcore-networking";

// Create a transport manager
const transportManager = new TransportManager({
primaryTransport: "hybrid",
websocket: {
enabled: true,
port: 8080,
host: "0.0.0.0",
maxPayload: 1024 * 1024,
perMessageDeflate: true,
},
udp: {
enabled: true,
port: 8081,
host: "0.0.0.0",
enableReliableUDP: true,
enablePacketOrdering: true,
enableFragmentation: false,
maxPacketSize: 1024,
fragmentSize: 1024,
retransmitTimeout: 1000,
maxRetransmits: 3,
sendBufferSize: 1024 * 1024,
receiveBufferSize: 1024 * 1024,
enableQoS: false,
priorityLevels: 0,
enablePacketLogging: false,
enablePerformanceMetrics: true,
},
hybrid: {
enabled: true,
useWebSocketForReliable: true,
useUDPForFast: false,
switchThreshold: 100,
},
auto: {
enabled: false,
latencyThreshold: 50,
packetLossThreshold: 0.1,
switchCooldown: 1000,
},
});

// Start the transport manager
await transportManager.start();

// Send data via the transport manager
transportManager.send("Hello World", "client-id", {
reliable: true,
ordered: true,
priority: 1,
});

// Get transport statistics
const stats = transportManager.getStats();
console.log(Active transport: ${stats.activeTransport});
console.log(UDP latency: ${stats.udp.latency}ms);
console.log(WebSocket latency: ${stats.websocket.latency}ms);
`

$3

| Transport | Latency | Throughput | Reliability | Use Case | Security Integration |
| --------- | -------- | ---------- | ------------ | -------------------------------------- | --------------------- |
| WebSocket | ~50ms | ~1MB/s | High | General purpose, reliable data | Full security support |
| UDP | ~5ms | ~10MB/s | Configurable | High-performance games, real-time data | Full security support |
| Hybrid | Adaptive | Adaptive | High | Best of both worlds | Full security support |
| Auto | Adaptive | Adaptive | High | Smart selection based on conditions | Full security support |

$3

All security features work seamlessly across transport layers:

`typescript
// Security features work with any transport
const secureServer = createServer(8080, {
enableSecurity: true,
transport: {
primaryTransport: "udp", // Even UDP gets full security
udp: {
enabled: true,
port: 8081,
// ... UDP config
},
},
encryption: {
enabled: true,
algorithm: "aes-256-gcm",
keyRotationInterval: 300000,
},
ddosProtection: {
enabled: true,
maxConnectionsPerIP: 5,
maxRequestsPerSecond: 100,
},
clientIntegrity: {
enabled: true,
enableChecksumValidation: true,
enableBehaviorAnalysis: true,
},
});
`

$3

The NetCore networking system includes a powerful anti-cheat plugin architecture that makes it easy for developers to implement custom anti-cheat solutions.

#### Creating Custom Anti-Cheat Plugins

`typescript
import {
BaseAntiCheatPlugin,
ValidationResult,
PlayerState,
} from "netcore-networking";

class CustomSpeedHackDetector extends BaseAntiCheatPlugin {
constructor() {
super("CustomSpeedHackDetector", "1.0.0");
}

initialize(config?: any): void {
console.log("Custom speed hack detector initialized");
}

validatePlayerAction(playerId: number, action: any): ValidationResult {
// Your custom logic here
return { valid: true, severity: "low", action: "ignore" };
}

validatePlayerState(playerId: number, state: PlayerState): ValidationResult {
// Your custom logic here
return { valid: true, severity: "low", action: "ignore" };
}
}
`

#### Using Anti-Cheat Plugins

`typescript
import {
NetCoreServer,
AntiCheatManager,
SpeedHackDetector,
TeleportDetector,
} from "netcore-networking";

// Create server and anti-cheat manager
const server = new NetCoreServer(8080);
const antiCheatManager = new AntiCheatManager({
enabled: true,
autoAction: true,
logViolations: true,
maxViolationsPerPlayer: 3,
});

// Register built-in plugins
antiCheatManager.registerPlugin(new SpeedHackDetector());
antiCheatManager.registerPlugin(new TeleportDetector());

// Register your custom plugin
antiCheatManager.registerPlugin(new CustomSpeedHackDetector());

// Configure plugins
antiCheatManager.getPlugin("SpeedHackDetector")?.initialize({
maxSpeed: 15,
});

// Start the server
await server.start();
`

#### Built-in Anti-Cheat Plugins

- SpeedHackDetector - Detects players moving too fast
- TeleportDetector - Detects impossible position changes
- BaseAntiCheatPlugin - Base class for creating custom plugins

$3

Create and manage multiple game sessions with different settings and player limits.

`typescript
import { SessionManager } from "netcore-networking";

const sessionManager = new SessionManager({
maxSessions: 10,
sessionTimeout: 300000, // 5 minutes
defaultSettings: {
tickRate: 128,
maxPing: 200,
allowSpectators: true,
autoBalance: true,
roundTime: 120000, // 2 minutes
maxRounds: 30,
},
});

// Create a new session
const session = sessionManager.createSession(
"My Game",
"deathmatch",
"map1",
10
);

// Join a player to the session
sessionManager.joinSession(session.id, clientId, "Player1", 1);

// Get session statistics
const stats = sessionManager.getSessionStats();
console.log(Active sessions: ${stats.activeSessions});
`

$3

Run multiple server instances with automatic load balancing and scaling.

`typescript
import { createMultiInstanceServer } from "netcore-networking";

const multiServer = createMultiInstanceServer(8080, {
maxInstances: 5,
autoScale: true,
loadBalancing: true,
sessionManager: true,
});

// Start the multi-instance server
await multiServer.start();

// Get the session manager
const sessionManager = multiServer.getSessionManager();

// Create a session
const session = sessionManager.createSession("Game1", "deathmatch", "map1", 8);

// Auto-creates an instance for the session
const instance = multiServer.createInstance(session.id, session);

// Get instance statistics
const stats = multiServer.getInstanceStats();
console.log(Active instances: ${stats.activeInstances});
`

$3

`typescript
import { createNetworkConfig, validateNetworkConfig } from "netcore-networking";

// Create custom configuration
const config = createNetworkConfig({
tickRate: 128,
maxClients: 20,
enableSecurity: true,
transport: {
primaryTransport: "hybrid",
websocket: {
enabled: true,
port: 8080,
host: "0.0.0.0",
maxPayload: 1024 * 1024,
perMessageDeflate: true,
},
udp: {
enabled: true,
port: 8081,
host: "0.0.0.0",
enableReliableUDP: true,
enablePacketOrdering: true,
enableFragmentation: false,
maxPacketSize: 1024,
fragmentSize: 1024,
retransmitTimeout: 1000,
maxRetransmits: 3,
sendBufferSize: 1024 * 1024,
receiveBufferSize: 1024 * 1024,
enableQoS: false,
priorityLevels: 0,
enablePacketLogging: false,
enablePerformanceMetrics: true,
},
hybrid: {
enabled: true,
useWebSocketForReliable: true,
useUDPForFast: false,
switchThreshold: 100,
},
auto: {
enabled: false,
latencyThreshold: 50,
packetLossThreshold: 0.1,
switchCooldown: 1000,
},
},
rateLimit: {
maxMessagesPerSecond: 100,
maxInputsPerSecond: 60,
burstLimit: 10,
},
security: {
requireAuthentication: false,
maxFailedAttempts: 5,
banDuration: 300000,
},
});

// Validate configuration
const errors = validateNetworkConfig(config);
if (errors.length > 0) {
console.error("Configuration errors:", errors);
}

// Create server with custom config
const server = createServer(8080, config);
`

API Reference

$3

#### NetCoreServer

Main server class for handling game networking with transport-agnostic architecture.

`typescript
class NetCoreServer {
constructor(port: number, config?: Partial);

start(): Promise; // Now async
stop(): void;
getNetworkStats(): NetworkStats[];
getConnectedClients(): ClientConnection[];
getServerInfo(): ServerInfo;
getDetailedNetworkStats(): DetailedNetworkStats;
}
`

#### TransportManager

Manages multiple transport layers with automatic switching and fallback.

`typescript
class TransportManager {
constructor(config: Partial);

start(): Promise;
stop(): void;
send(data: Buffer | string, target: string, options?: SendOptions): number;
switchTransport(transport: TransportType): void;
getStats(): TransportStats;
getConfig(): TransportConfig;
}
`

#### UDPTransport

High-performance UDP transport with configurable reliability features.

`typescript
class UDPTransport {
constructor(config: Partial, isServer?: boolean);

start(): Promise;
stop(): void;
send(
data: Buffer | string,
address: string,
port: number,
options?: SendOptions
): number;
getStats(): UDPStats;
getConfig(): UDPConfig;
}
`

$3

#### NetCoreClient

Client class for connecting to NetCore servers.

`typescript
class NetCoreClient {
constructor(serverUrl: string);

setHandshakeData(checksum: string, version: string): void;
connect(): Promise;
disconnect(): void;
sendInput(input: Partial): void;
getNetworkStats(): NetworkStats;
isClientConnected(): boolean;
getClientId(): number | null;
getPing(): number;
}
`

$3

#### EnhancedSecurityManager

Comprehensive security manager with encryption, DDoS protection, and client integrity.

`typescript
class EnhancedSecurityManager {
constructor(config: Partial);

start(): void;
stop(): void;
canConnect(clientId: number, ipAddress: string): SecurityCheck;
canRequest(clientId: number, ipAddress: string): SecurityCheck;
registerClient(clientId: number, checksum: string, version: string): void;
createEncryptionSession(clientId: number): string | null;
encrypt(sessionId: string, data: string): EncryptedMessage | null;
decrypt(message: EncryptedMessage): string | null;
getMetrics(): SecurityMetrics;
}
`

#### AntiCheatManager

Manages anti-cheat plugins and validation.

`typescript
class AntiCheatManager {
constructor(config?: Partial);

registerPlugin(plugin: AntiCheatPlugin): boolean;
unregisterPlugin(pluginName: string): boolean;
validatePlayerAction(playerId: number, action: any): ValidationResult;
validatePlayerState(playerId: number, state: PlayerState): ValidationResult;
getPlugin(pluginName: string): AntiCheatPlugin | undefined;
getPlugins(): AntiCheatPlugin[];
getCombinedStats(): AntiCheatStats;
}
`

$3

`typescript
const monitor = new PerformanceMonitor();

// Record metrics
monitor.recordTick(serverTick, connectedClients);
monitor.recordClientMetrics(clientId, ping, packetLoss, jitter);

// Get alerts
const alerts = monitor.getPerformanceAlerts();
alerts.forEach((alert) => console.warn(alert));

// Get metrics history
const history = monitor.getMetricsHistory(300); // Last 5 minutes
`

$3

`typescript
// Get server statistics
const serverStats = server.getNetworkStats();
serverStats.forEach((stat) => {
console.log(
Client ${stat.clientId}: ${stat.ping}ms ping, ${stat.packetLoss}% loss
);
});

// Get detailed network statistics with transport info
const detailedStats = server.getDetailedNetworkStats();
detailedStats.clients.forEach((client) => {
console.log(
Client ${client.id} (${client.transport}): ${client.ping}ms ping, ${client.packetLoss} loss
);
});

// Get client statistics
const clientStats = client.getNetworkStats();
const summary = NetworkUtils.getNetworkSummary(clientStats);
console.log(Connection Quality: ${summary.quality} (${summary.score}/100));
`

Troubleshooting

$3

1. High Ping

- Check network connection
- Reduce server load
- Optimize game logic
- Consider using UDP transport for better performance

2. Packet Loss

- Check network stability
- Reduce packet size
- Enable compression
- Use reliable UDP or switch to WebSocket

3. Connection Drops

- Check firewall settings
- Verify server availability
- Increase timeout values
- Check transport configuration

4. Handshake Failures

- Ensure setHandshakeData() is called before connect()
- Verify checksum and version are valid
- Check server security settings

5. Transport Issues
- Verify transport configuration
- Check port availability
- Ensure transport manager is properly initialized
- Review transport statistics for issues

$3

`typescript
// Enable debug logging
const debugConfig = createNetworkConfig({
enableSecurity: true,
enableCompression: false,
maxPacketSize: 2048,
transport: {
primaryTransport: "websocket", // Start with reliable transport
websocket: {
enabled: true,
port: 8080,
host: "0.0.0.0",
maxPayload: 1024 * 1024,
perMessageDeflate: false, // Disable compression for debugging
},
},
});

// Monitor performance
const monitor = new PerformanceMonitor();
setInterval(() => {
const metrics = monitor.getCurrentMetrics();
if (metrics) {
console.log("Performance:", metrics);
}
}, 1000);

// Monitor transport statistics
setInterval(() => {
const serverInfo = server.getServerInfo();
if (serverInfo.transport) {
console.log("Transport Stats:", serverInfo.transport.stats);
}
}, 5000);
`

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Support

For support and questions:

- Create an issue on GitHub
- Check the documentation
- Review the examples

Version History

- 1.0.0 - Initial Release

- Core Features: Security and performance monitoring
- Language Support: TypeScript support
- Architecture: Production-ready architecture
- Communication: WebSocket-based communication
- Security: Basic anti-cheat system

- 1.0.1 - Enhanced Security and Stability

- Encryption: Improved encryption system
- DDoS Protection: Better DDoS protection
- Client Integrity: Enhanced client integrity verification
- Performance: Bug fixes and performance improvements

- 1.0.2 - Transport System Improvements

- WebSocket: Enhanced WebSocket transport
- Error Handling: Improved error handling
- Connection Management: Better connection management
- Security: Additional security features

- 1.1.0 - Major Transport System Update

- UDP Transport: Added UDP transport with configurable reliability
- Transport Manager: Unified transport management
- Hybrid Transport: WebSocket + UDP combination
- Auto-Detection: Smart transport switching
- Security Integration: Transport-agnostic security features
- Performance Monitoring: Enhanced monitoring capabilities
- Documentation: Improved documentation and examples

- 1.1.1 - Dependency Fix and Maintenance

- Fixed: Removed unused uWebSockets.js dependency that was causing 404 download errors
- Maintenance: Cleaned up package dependencies
- No breaking changes: All functionality remains identical
- Improved reliability: Package now downloads successfully from npm

- 1.1.2 - Dependency Cleanup and Maintenance

- Fixed: Removed unused uWebSockets.js dependency that was causing 404 download errors
- Maintenance: Removed unused enet dependency as precautionary cleanup
- Dependency Optimization: Streamlined package dependencies for better reliability
- No breaking changes: All functionality remains identical
- Improved reliability: Package now downloads successfully from npm

- 1.1.3 - Critical Bug Fix: Double Server Startup Issue

- Fixed: Resolved critical issue where server was starting twice, causing port conflicts
- Removed: Eliminated unused MainServer class that was causing automatic server startup
- Cleanup: Removed main-server.ts` file that was not being used
- Package.json: Fixed conflicting module field in package.json
- No breaking changes: All existing APIs remain unchanged
- Improved reliability: Server now starts correctly without port conflicts