A modernized, TypeScript-first engine for simulating professional football matches.
This project is a high-performance fork of the original footballSimulationEngine. It has been rebuilt with a focus on strict type safety, modular architecture, and modern developer tooling.
While the engine is headless by design, you can see it in action via the official demo application: 👉 footballsim-demo
-
Strict TypeScript: Completely ported to TypeScript with
NodeNextmodule resolution for enterprise-grade safety. -
High-Performance Physics: Refined ball movement, trajectory calculations, and player collision logic.
-
Advanced AI Intent: Sophisticated decision-making trees for player movement, tackling, and attacking threats.
-
Developer Experience: Fully integrated with
Vitestfor testing andESLintwithSonarJSfor deep code analysis. -
Automated Releases: Continuous delivery pipeline using
Semantic Release.
npm install footballsim
The engine is designed to be integrated into any Node.js environment. You simply initialize a game with team and pitch configurations, then iterate through match steps.
import { initiateGame, playIteration } from 'footballsim';
// 1. Setup your match
const matchDetails = initiateGame(team1, team2, pitchConfig);
// 2. Run the simulation loop
while (!matchDetails.matchFinished) {
const currentStep = playIteration(matchDetails);
console.log(`Current Score: ${currentStep.score[0]} - ${currentStep.score[1]}`);
}The engine follows a modular "Intent-Action-Physics" flow:
-
Intent Logic: Players analyze their surroundings and decide on an action (pass, shoot, move).
-
Action Handler: Validates and executes the chosen intent based on player stats and game state.
-
Physics Engine: Resolves the final movement of the ball and players on the pitch, handling boundaries and collisions.
We maintain high standards for engine reliability:
-
Unit Testing: Over 500+ tests covering everything from offside logic to freekick positioning.
-
Coverage: Full transparency on logic and type coverage.
-
Architecture Integrity: Automated dependency cruising to prevent circular logic.
# Run the test suite
npm test
# Generate coverage reports
npm run coverage:all
This project is licensed under the ISC License. Originally forked from GallagherAiden/footballSimulationEngine.