footballsimulationengine

The matchDetails object is the primary state container passed between all engine functions.

Key Fields:

• kickOffTeam / secondTeam: Objects containing team metadata and player arrays.
• pitchSize: Array [width, height].
• ball: Contains position [x, y, z], withPlayer (boolean), direction, and lastTouch details.
• ball.ballOverIterations: An array used to track ball movement over time. If empty, no new ball movements occur.
• half: Current half number.
• kickOffTeamStatistics / secondTeamStatistics: Objects tracking goals, shots, corners, freekicks, penalties, and fouls.
• iterationLog: An array of strings providing a summary of events in the last iteration.

In the player object returned during iterations, you can override the default action (which is 'null' for normal simulation) to force specific behaviors.

Valid Actions:

• 'shoot' (Requires player to have the ball)
• 'throughBall'
• 'pass'
• 'cross'
• 'tackle'
• 'intercept'
• 'slide'
• 'run'
• 'sprint'
• 'cleared'
• 'boot'

Note: Any invalid action will result in the simulation running as normal.

Install the engine via npm. Ensure your Node.js version is at least 7.6.0 to support async/await syntax.

npm install --save footballsimulationengine

The initiateGame() function is a Promise that starts a new match. It requires two team objects and a pitch information object in JSON format. It returns a matchDetails object containing player start positions, match statistics, ball position, and an iteration log.

initiateGame(team1, team2, pitch).then(function(matchDetails){
  console.log(matchDetails);
}).catch(function(error){
  console.error("Error: ", error);
})

The playIteration() function is a Promise that advances the simulation by one step. It accepts the matchDetails object (the output from initiateGame or a previous playIteration) and resolves with an updated matchDetails object, representing the new state of the match and player positions.

playIteration(matchDetails).then(function (matchDetails) {
  console.log(matchDetails);
}).catch(function(error) {
  console.error("Error: ", error);
})

The startSecondHalf() function is a Promise used to switch the sides of each team (e.g., at halftime). It accepts the current matchDetails object and returns an updated version with teams swapped.

startSecondHalf(matchDetails).then(function (matchDetails) {
  console.log(matchDetails);
}).catch(function(error) {
  console.error("Error: ", error);
})

Define the dimensions of the pitch. Tested ranges: width 120-680, height 600-1050, and goal width of 90.

{
	"pitchWidth": 680,
	"pitchHeight": 1050,
  "goalWidth": 90
}

A standard simulation lifecycle involves initializing the game, playing a series of iterations, switching to the second half, and continuing iterations until the match is complete. Because each iteration returns a new state, you must pass the output of one iteration as the input to the next.

// 1. Initialize
let matchState = engine.initiateGame(team1, team2, pitch);

// 2. Play first half
matchState = await engine.playIteration(matchState);
matchState = await engine.playIteration(matchState);

// 3. Switch to second half
matchState = await engine.startSecondHalf(matchState);

// 4. Play second half
matchState = await engine.playIteration(matchState);
matchState = await engine.playIteration(matchState);

Use initiateGame(team1, team2, pitchDetails) to set up a new match. This function validates the input teams and pitch, populates match details, determines the kickoff team via a decider, and sets initial player positions. It returns a matchDetails object which serves as the state for the entire simulation.

Parameters:

• team1: The first team object.
• team2: The second team object.
• pitchDetails: An object containing pitch configuration.

Returns: A matchDetails object containing the initial state of the game.

const { initiateGame } = require('./engine');

const matchDetails = await initiateGame(team1, team2, pitchDetails);

The simulation progresses through discrete steps called iterations. Use engine.playIteration(inputIteration) to advance the game state. The function accepts the current state of the match (the inputIteration) and returns a new state object representing the match after that iteration has been processed.

let nextIteration = await engine.playIteration(currentIteration);

Use playIteration(matchDetails) to advance the simulation by one discrete step (one iteration).

Process Flow:

1. Validates the current matchDetails state.
2. Processes injuries.
3. Moves the ball.
4. Determines the closest players to the ball for both teams.
5. Calculates and executes player movements and ball actions (e.g., passing, shooting).
6. Checks for offsides.
7. Updates the iterationLog.

Returns: The updated matchDetails object. If the iteration results in the end of a specific game state, the object may contain an endIteration flag (which is deleted before returning).

const { playIteration } = require('./engine');

// matchDetails is obtained from initiateGame()
const updatedMatchDetails = await playIteration(matchDetails);