@white-horse/soccer-engine

A TypeScript library for simulating realistic soccer matches with detailed player attributes, team management, and match events.

Note: This is an alpha release (v0.0.4). APIs may change in future versions.

Overview

The Soccer Manager Game Engine is a powerful TypeScript library designed for simulating realistic soccer matches. It provides a comprehensive framework for creating teams, managing players, and simulating matches with detailed events and statistics.

Core Components

The engine consists of several core components, each with specific responsibilities:

• Engine: The central orchestrator that manages teams, players, and match simulations
• Match: Handles the simulation of soccer matches between teams
• Team: Represents a soccer team with players, formation, and tactics
• Player: Represents an individual soccer player with attributes and state
• EventSystem: Manages the creation, dispatching, and handling of match events

For a deeper understanding of the architecture, see the Architecture Documentation.

Features

• Player Simulation: Players have realistic attributes (1-20 scale) that affect their performance
• Team Management: Create and manage teams with custom formations and tactics
• Match Simulation: Simulate matches with detailed events and statistics
• Tactical System: Implement different playing styles and formations
• Event System: Subscribe to match events for detailed analysis
• Substitution System: Make up to five substitutions during matches
• Customizable: Extend and customize the engine for your specific needs
• Configuration System: Fine-tune simulation parameters through a comprehensive configuration system

Installation

npm install @white-horse/soccer-engine

Requirements

• Node.js 14.0.0 or higher
• TypeScript 4.x or higher (for TypeScript projects)

Usage

Basic Example

import { Engine, Team } from '@white-horse/soccer-engine';

// Create a new engine instance
const engine = new Engine();

// Create two teams with random players
const homeTeam = engine.createTeam('Manchester United', '4-3-3');
const awayTeam = engine.createTeam('Liverpool FC', '4-4-2');

// Simulate a match
const match = engine.simulateMatch(homeTeam, awayTeam);

// Display the result
console.log(`Final Score: ${homeTeam.name} ${match.homeGoals} - ${match.awayGoals} ${awayTeam.name}`);

Creating Custom Players

import { Player, Team } from '@white-horse/soccer-engine';

// Create a custom player
const ronaldo = new Player({
  name: 'Cristiano Ronaldo',
  position: 'FWD',
  attributes: {
    pace: 18,
    shooting: 19,
    passing: 15,
    dribbling: 17,
    heading: 18,
    positioning: 19
  }
});

// Create more players...
const players = [ronaldo, /* ... */];

// Create a team with custom players
const team = new Team({
  name: 'All Stars',
  players,
  formation: '4-3-3'
});

Setting Custom Tactics

import { Team } from '@white-horse/soccer-engine';

// Update team instructions
team.updateInstructions({
  mentality: 'ATTACKING',
  pressing: 'HIGH',
  passingStyle: 'POSSESSION',
  width: 7,
  tempo: 8
});

// Update position-specific instructions
team.updatePositionInstructions('CM1', {
  role: 'Deep-Lying Playmaker',
  attackingFreedom: 6,
  defensiveResponsibility: 4,
  customInstructions: ['Dictate Tempo', 'Shorter Passing']
});

Subscribing to Match Events

import { Engine, EventSystem } from '@white-horse/soccer-engine';

const engine = new Engine();
const eventSystem = engine.getEventSystem();

// Subscribe to goal events
eventSystem.subscribe('goal', event => {
  const minute = event.minute;
  const scorer = event.player?.name || 'Unknown player';
  const team = event.team?.name || 'Unknown team';
  
  console.log(`⚽ GOAL! ${minute}' - ${scorer} scores for ${team}!`);
});

// Subscribe to all key events
eventSystem.subscribe('*', event => {
  if (event.isKeyEvent) {
    console.log(`${event.minute}' - ${event.description}`);
  }
});

// Simulate the match
const match = engine.simulateMatch(homeTeam, awayTeam);

Configuration System

The engine includes a comprehensive configuration system that allows you to customize various aspects of the simulation:

• Match Configuration: Control match simulation parameters
• Player Configuration: Adjust player attributes and behavior
• Team Configuration: Customize team formations and tactics
• Engine Configuration: Modify general engine settings

For more details, see the Configuration Documentation.

Examples

The package includes several examples demonstrating different features:

• Simple Match: Basic match simulation (documentation)
• Custom Teams: Creating and using custom teams
• Tactics: Working with team tactics and formations
• Luck Impact: Understanding how luck affects match outcomes
• Random Match: Simulating matches between random teams (documentation)
• Single Random Match: Detailed simulation of one match (documentation)

Quick Start

Here's a simple example to get you started:

import { Engine } from '@white-horse/soccer-engine';

// Create engine and teams
const engine = new Engine();
const homeTeam = engine.createTeam('Arsenal', '4-3-3');
const awayTeam = engine.createTeam('Chelsea', '4-4-2');

// Subscribe to goals
engine.getEventSystem().subscribe('goal', (event) => {
  console.log(`⚽ ${event.description}`);
});

// Simulate match
const match = engine.simulateMatch(homeTeam, awayTeam);
console.log(`Final: ${homeTeam.name} ${match.homeGoals} - ${match.awayGoals} ${awayTeam.name}`);

Documentation

Comprehensive documentation is available in the documentation directory:

Getting Started

• Installation

Core Concepts

• Architecture
• Configuration

API Reference

• Engine API
• Match API
• Player API

Tutorials

• Simulating Matches

Advanced Topics

• Extending the Engine

Player Attributes

Players have various attributes on a scale of 1-20:

• Physical: pace, strength, stamina, agility
• Technical: passing, shooting, dribbling, tackling, heading
• Mental: positioning, decisionMaking, teamwork, composure
• Special: luck (affects random outcomes and chance of favorable events)

Team Formations

The engine supports various formations including:

• 4-4-2
• 4-3-3
• 3-5-2
• 4-2-3-1
• 5-3-2

Custom formations can also be created.

Luck System

The engine includes a luck system that adds unpredictability to match outcomes:

• Each player has a luck attribute (1-20 scale)
• Luck affects various aspects of the game:
  • Shot accuracy and goal probability
  • Tackle success rates
  • Favorable referee decisions
  • Injury likelihood
  • Critical moments in matches
• Team luck is calculated as the average of all on-field players
• The luck system ensures that while better teams generally win more often, upsets can happen
• Run the runLuckImpactExample() to see how luck affects match outcomes

License

MIT