KickScript
Language Specification — A Domain-Specific Language for Football Team, Tactic, and Match Simulation
Contents
1. Program Start Or End
2. Data Type
3. Identifiers
4. Initialization Rule
5. Loop — the Match Clock
6. Conditional Statement — the Card Rule
7. Set Of Operators
8. List Of Special Characters
9. Set Of Reserved Keywords
10. Functions
11. Sample Program
1. Program Start Or End
Formal Language:
#start : Marks the beginning of the KickScript program.
{ } : Represents the block of declarations and statements that make up the main body of the program — the match header, team and tactic
declarations, and the sequence of match events.
#end : Marks the end of the KickScript program.
Nested inside the program body, the keyword kickoff marks the beginning of match-time simulation, and the keyword fulltime marks the end
of match-time simulation. Every KickScript program is therefore bounded twice: once at the file level by #start / #end , and once at the
match-clock level by kickoff / fulltime .
Syntax:
#start
{
match "Title"
team TeamName1 { ... }
team TeamName2 { ... }
tactic TacticName { ... }
kickoff
minute N
<event statement>
...
fulltime
}
#end
Semantic rule enforced by the compiler: a program with statements outside #start / #end is rejected; a match section that does not open with
kickoff or does not close with fulltime is rejected.
2. Data Type
1— Integer
Formal Language: Integer is defined as a whole number, used by KickScript for match minutes, jersey numbers, goal counts, and card counts.
It can be positive, negative, or zero (negative integers are rejected later by semantic analysis, but are still lexically valid numbers).
Token: num Class: Data Type (DT)
RE: ^[+-]?\d+$
Explanation:
^ : Start of the string.
[+-]? : Optional sign at the beginning.
\d+ : One or more digits.
$ : End of the string.
Example: 8, 45, 90, 2, 11
2— Character
Formal Language: A character sequence is defined as one or more letters. A single letter or a combination of letters (a word) is considered a
character value, used for team names, player names inside quotes, and tactic style values.
Token: char Class: Data Type (DT)
RE: ^[A-Za-z]+$
Explanation:
^ : Start of the string.
[A-Za-z]+ : One or more occurrences of any letter.
$ : End of the string.
Example: "Liverpool", "GegenPress", "High"
3— Formation Literal (KickScript-specific)
Formal Language: A formation literal describes how a team's ten outfield players are arranged, line by line from defence to attack. It is written
as two to five positive integers separated by hyphens.
Token: formation_lit Class: Data Type (DT)
RE: ^[1-9][0-9]?(-[1-9][0-9]?){1,4}$
Explanation:
[1-9][0-9]? : A one- or two-digit positive integer (player count in one line).
(-[1-9][0-9]?){1,4} : One to four further hyphen-separated line counts.
$ : End of the string.
Example: 4-3-3, 4-4-2, 3-5-2, 4-2-3-1
Semantic rule: the digits of a formation literal, plus the goalkeeper, must sum to exactly 11 players.
3. Identifiers
Formal Language:
Always starts with a letter or an underscore.
Used to name players, teams, and tactics (both uppercase and lowercase letters allowed).
May contain letters, digits, and underscores.
Cannot be one of KickScript's reserved words (e.g. team , goal , pass ).
Token: player_name / team_name / tactic_name Class: Identifier (ID)
RE: ^[a-zA-Z_][a-zA-Z0-9_]*$
Explanation:
^[a-zA-Z_] : Starts with a letter (either uppercase or lowercase) or an underscore.
[a-zA-Z0-9_]* : Zero or more occurrences of letters, digits, or underscores.
$ : End of the string.
Example: Salah, VanDijk, Alexander_Arnold, team1, GegenPress
Token Class Part
Salah Identifier(ID)
VanDijk Identifier(ID)
Liverpool Identifier(ID)
4. Initialization Rule
Integer
An integer field can be initialised by assigning a whole-number value to a variable, such as the running match clock or a player's shirt number.
Example: minute = 8
Token Class Part
minute Identifier(ID)
= =
8 num
Character
A character field can be initialised by assigning quoted letters to a variable, such as a team name or a tactic setting.
Example: teamName = "Liverpool"
Token Class Part
teamName Identifier(ID)
= =
" "
Liverpool char
" "
5. Loop — the Match Clock
meanwhile: A construct for iterating over the match minute-by-minute while a specified condition holds. It drives the simulation engine that
walks through the event list a minute at a time.
Formal Language:
Initialization: The variable minute is initialised with the kickoff value.
Conditional Execution: The engine enters a loop where it checks a condition involving minute (for example, whether full time has been
reached). If the condition is true for the current value of minute , the events scheduled for that minute are simulated.
Iteration: After each iteration, minute is incremented by one.
Termination: The loop continues until minute reaches 90 (or later, if stoppage time events exist), at which point the loop exits and fulltime
is emitted.
Syntax:
Initialization
meanwhile condition:
echo("statement")
increment/decrement
Example:
minute = 0
meanwhile minute < 90:
echo("Match in progress, minute", minute)
minute = minute + 1
Token Class Part
minute identifier(ID)
= =
0 num
meanwhile reserved keyword(RK)
minute identifier(ID)
< <
90 num
echo reserved keyword(RK)
( (
Match in progress, minute char
, ,
minute identifier(ID)
) )
minute identifier(ID)
= =
minute identifier(ID)
+ +
1 num
6. Conditional Statement — the Card Rule
either or: A programming construct for decision-making based on a condition. KickScript uses it internally to decide whether a player's second
caution must be escalated into a dismissal.
Formal Language:
Initialization: Describes the initialisation of a variable ( yellowCount ) with an initial value.
Conditional_Execution: Describes the conditional execution of code based on the value of yellowCount , following an either block.
Action_1: Represents the action to be taken if the condition in the either statement is true — the caution is converted to a sending-off.
Action_2: Represents the action to be taken if the condition in the either statement is false (i.e., the or block) — the caution stands alone.
Syntax:
Variable = Initial value
either condition?
# Code block to execute if the condition is true
Action_1
or?
# Code block to execute if the condition is false
Action_2
Example:
yellowCount = 1
either yellowCount >= 2?
red Konate
or?
echo("Caution only, Konate stays on the pitch")
Token Class Part
yellowCount identifier(ID)
= =
1 num
either reserved keyword(RK)
yellowCount identifier(ID)
>= >=
2 num
? ?
red reserved keyword(RK)
Konate identifier(ID)
or reserved keyword(RK)
? ?
echo reserved keyword(RK)
( (
Caution only, Konate stays on the pitch char
) )
7. Set Of Operators
Arithmetic Operators:
+ (Addition — e.g. tallying goals into a running score)
− (Subtraction)
x (Multiplication)
/ (Division)
% (Modulus)
Relational Operators:
< (Less than — e.g. minute < 90)
<= (Less than or equal to)
> (Greater than)
>= (Greater than or equal to — e.g. yellowCount >= 2)
!= (Not equal to)
== (Equal to)
Logical Operators:
&& (Logical AND)
|| (Logical OR)
! (Logical NOT)
Assignment Operator:
= (Assignment)
Token Class Part Token Class Part
+ + >= >=
− − != !=
/ / == ==
x x && &&
% % || ||
< < ! !
<= <= = =
> >
8. List Of Special Characters
# (pound sign — comment marker)
{ } (braces — block delimiters)
, (comma)
= (equal sign)
− (hyphen — also used inside formation literals, e.g. 4-3-3)
( ) (parenthesis)
' (single quotation mark)
" (double quotation mark — string / char delimiter)
: (colon)
? (question mark)
; (semicolon — optional statement terminator)
-> (arrow — KickScript pass/cross direction operator, e.g. Salah -> Nunez)
_ (underscore)
Token Class Part Token Class Part
# # " "
{ { : :
} } ? ?
, , ; ;
= = -> ->
− − _ _
( ( ' '
) )
9. Set Of Reserved Keywords
Core Control Keywords
#start
#end
num
char
formation_lit
meanwhile
either
or
method
echo
get
return
Football Domain Keywords
match
team
formation
goalkeeper
defenders
midfielders
forwards
player
tactic
pressing
defensiveLine
buildUp
width
tempo
passing
kickoff
minute
halftime
fulltime
pass
cross
shoot
save
goal
header
foul
yellow
red
penalty
freekick
corner
throwin
offside
injury
substitute
for
Token Class Part
#start reserved keyword(RK)
#end reserved keyword(RK)
num reserved keyword(RK)
char reserved keyword(RK)
formation_lit reserved keyword(RK)
meanwhile reserved keyword(RK)
either reserved keyword(RK)
or reserved keyword(RK)
method reserved keyword(RK)
echo reserved keyword(RK)
get reserved keyword(RK)
return reserved keyword(RK)
match / kickoff / fulltime / halftime reserved keyword(RK)
team / formation / tactic / minute reserved keyword(RK)
goalkeeper / defenders / midfielders / forwards reserved keyword(RK)
pass / cross / shoot / save / goal / header reserved keyword(RK)
foul / yellow / red / penalty / freekick / corner / throwin / offside / injury reserved keyword(RK)
substitute / for reserved keyword(RK)
10. Functions
Formal Language
method: Keyword to define a function.
Function name: A valid identifier used to name the function.
Parentheses: Used to enclose the parameters (if any).
Colon: Used to indicate the beginning of the function body.
Indentation: The leading spaces or tabs that denote the scope of the function body.
return: Keyword used to return a value from the function (optional).
Syntax Of Defining A Function:
method function_name(parameter1, parameter2, ...):
#code statements
return expression
Syntax Of Calling A Function:
function_name(argument1, argument2, ...)
If function doesn't accept any arguments then:
function_name()
"get()" function
Retrieves a value at compile time or simulation time — for example, looking up a player record before an event is applied.
method get(prompt):
user_input = (prompt)
return user_input
Example:
method get(prompt):
user_input = (prompt)
return user_input
player_name = get("Enter the substitute's name: ")
echo("Bringing on,", player_name)
Token Class Part
method reserved keyword(RK)
get reserved keyword(RK)
( (
prompt parameter
) )
: :
user_input identifier(ID)
= =
( (
prompt parameter
) )
return reserved keyword(RK)
user_input identifier(ID)
player_name identifier(ID)
= =
get reserved keyword(RK)
"echo()" function
Emits a line of live match commentary — the code-generation phase calls this to produce the textual simulation log.
method echo(message):
return message
Example:
method echo(message):
return message
result = echo("GOAL! Liverpool 1-0 Madrid")
Token Class Part
method reserved keyword(RK)
echo reserved keyword(RK)
( (
message parameter
) )
: :
return reserved keyword(RK)
message parameter
result identifier(ID)
= =
echo reserved keyword(RK)
( (
GOAL! Liverpool 1-0 Madrid char
) )
11. Sample Program
A complete KickScript program, applying every construct defined above: the #start / #end program wrapper, team and tactic declarations, the
kickoff / fulltime match clock, the formation literal, identifiers, event statements, and the built-in echo() function.
#start
{
match "Champions League Final"
team Liverpool {
formation 4-3-3
goalkeeper Alisson
defenders { VanDijk Konate Robertson AlexanderArnold }
midfielders { MacAllister Szoboszlai Gravenberch }
forwards { Salah Diaz Nunez }
tactic GegenPress {
pressing High
defensiveLine High
buildUp Fast
width Wide
tempo High
}
}
team Madrid {
formation 4-4-2
tactic CounterAttack
}
kickoff
minute 8
pass Salah -> Nunez
shoot Nunez
goal Liverpool
echo("GOAL! Liverpool 1-0 Madrid")
minute 25
yellow Konate
minute 25
yellow Konate
# second caution: either/or escalates this to a dismissal
either yellowCount(Konate) >= 2?
red Konate
or?
echo("Caution only")
minute 45
halftime
minute 63
substitute Jota for Nunez
minute 80
corner Liverpool
cross Robertson -> VanDijk
header VanDijk
goal Liverpool
echo("GOAL! Liverpool 2-0 Madrid")
fulltime
}
#end
Semantic analysis on this program checks: exactly 11 players and exactly one goalkeeper per team; the formation literal digits sum to 10 outfield players;
no duplicate player names; kickoff precedes all events and fulltime follows all events; minute values never decrease; both endpoints of every
pass / cross exist and share a team; the repeated yellow Konate in minute 25 is automatically escalated to red Konate ; and the substitution at
minute 63 checks that Jota exists, Nunez is currently on the field, and the team has not exceeded five substitutions.