CTF 2005 Capture the Flag – Speciﬁcation.avardy/courses/se/ctf/ctf.pdf · CTF 2005 Capture the Flag – Speciﬁcation. Dennis Peters, Andrew Vardy∗. Software Engineering 7893

CTF 2005Capture the Flag – Specification.

Dennis Peters, Andrew Vardy∗. Software Engineering 7893

Revision 2.22005.07.07

NOTE: All of the following is subject to change. You are strongly encouragedto read this document carefully and bring any questions or suggestions to the attentionof the Instructor immediately.

Revision History

Revised or new text is coloured blue.

Rev. Date Description2.2 2005.07.07 Changed time allowed for an Escapee to return to home territory from

60 to 120 seconds.2.1 2005.06.21 Clarified conditions under which an EndMsg should be sent.2.0 2005.05.04 Initial revision based on version 1.21. Some wording changes. Switched

to Canadian spelling. Introduced clock factor and layered controller.

1 Introduction and overview

A CTF system is made up of two kinds of components. A Simulator simulates anddisplays the state of an imaginary game field. The simulator is also responsible forenforcing the rules of the CTF game. The moving objects on the field are players,divided into two teams, and two flags. Connected to the simulator are two controllers.Each controller directs the movements of one team of players.

The simulator and the controllers communicate over the Internet using the STEAL(Simulator-TEAm Link) protocol described in this document. STEAL is layered on topof TCP/IP.

The remainder of this document describes:

• The rules of the CTF game.

• The details of the STEAL protocol.

∗This specification is based in part on the specification for the previous SOCCER projects used inthis course, some of which are c©Theodore Norvell. It is used by permission.

1

Engineering 7893 CTF 2005 Specification

Figure 1: The field layout and player initial positions (not to scale).

• Other requirements on the components.

2 Rules of the CTF game.

The game being played is based on the real Capture the Flag game (see www.usscouts.

org/games/game cf.html), but is greatly simplified to make the project easier. Thegame described in this section is an ideal, being described in terms of real numbers.Furthermore, while it is based on the physics of the real world, it is not entirely realistic.For example we will ignore the third dimension of space and the angular momentum ofbodies. Simulation introduces drift from this ideal and a later section will discuss theacceptable limits of that drift.

The game is played on a large (1000×500 m) field that is divided down the middle toform two territories of equal size (500× 500 m) (see Figure 1). Players are permitted tomove about the field mostly freely, but are subject to capture if they are on the territoryof the opposing team. Each team has a flag, which is placed somewhere in their territorywithin 250m of the boundary line. The object of the game is to locate and ’capture’ theflag of the opposing team and return with it to your home territory.

2.1 Field

1. A field is a rectangle with corners at (0m,0m) and (1000m,500m).

2. Each territory contains 10 trees, which are represented as circles of 1.0m radius.Players can neither see through nor pass through the trees.

ctf.tex 2 2005.07.07 16 : 30


3. At the start of the game each controller requests the location of the trees on itsterritory, subject to the following constraints.

(a) The centre of a tree cannot be less than 10m from the centre of another treeon that territory.

(b) The centre of a tree cannot be less than 10m from a (field or territory) bound-ary.

(c) No part of any tree can overlap with any part of a player in its initial position.

(d) No part of any tree can be in the jail.

(e) No part of any tree can include the position of the flag.

2.2 Players

1. 2 teams of 8 players. Players are numbered (0,0), (1,0), (0,1), (1,1), ... (0,7), (1,7).

2. Each player is represented by a circle of 25 cm radius.

3. A player is in one of five modes: Normal, Prisoner, Escapee, Flag Carrier or TCTF(too close to flag) as described in subsections 2.2.1 through 2.2.5, below.

4. Aside from its number and mode, each player is fully described (at each instant)by the following state variables

• Its position. (The position of the circle’s centre.)

• Its (linear) velocity.

• Its (linear) acceleration.

• An orientation angle (its direction of motion)

• Its angular velocity (turning rate).

• The time of the most recent mode change for this player.

5. Players may change their direction of motion with an angular velocity of up to 90◦/sin either direction.

6. Except as restricted by paragraph 1 in Section 2.2.4, players may have a velocityof 0 to 10 m/s in the direction they point.

7. Players may accelerate by -5 to +2 m/s/s in the direction of motion.

8. The position of a player is limited to the field.

9. Players of team 0 have a home territory on the left 0 ≤ x < 500m and players ofteam 1 have a home territory on the right 500m < x ≤ 1000m.

10. Players cannot occupy the same space as another player or solid object.

11. A player is taken to be on his/her home territory if any part of the player is insidethe territory.

The modes of the players are explained in the following sections.

ctf.tex 3 2005.07.07 16 : 30


2.2.1 Normal

As suggested by the name, this is the normal mode of players who are not in any othermode. The following events cause transition to another mode:Event New mode Comment

Capture Prisoner See section 2.6.Release Escapee See section 2.7. When a player enters the opposing

team’s jail and releases a prisoner teammate, bothplayers become escapees.

Flag zone change TCTF See section 2.4. When capture or movement of op-ponents in the exclusion zone of the flag causes aplayer to be within the exclusion zone illegally (s)heenters mode TCTF.

Capture Flag Flag Carrier See section 2.4. When a player passes within 1mof his/her opponent’s flag (s)he is deemed to havepicked it up.

2.2.2 Prisoner

A prisoner can only move within the jail (see Section 2.7) and cannot see beyond thewalls of the jail. The following events cause transition to another mode:Event New mode Comment

Release Escapee See section 2.7.Reset Normal Upon reset all players are set to normal mode.

2.2.3 Escapee

Upon being released from prison, or releasing a teammate from prison, a player is givenfree passage back to his/her home territory. An escapee cannot be captured and canneither capture the flag nor release another prisoner. The following events cause transitionto another mode:Event New mode Comment

Home territory Normal Upon entering his/her home territory the escapee modeis cleared and the player returns to normal mode.

Timeout Prisoner If a player remains in the escapee mode continuously formore than 120 s (s)he is returned to jail as a prisoner.

Reset Normal Upon reset all players are set to normal mode.

2.2.4 Flag Carrier

Once a player has picked up the flag they are in Flag Carrier mode and are restricted asfollows:

1. A player carrying the flag has a maximum speed of 9 m/s.

2. A player carrying the flag cannot enter their opponents jail.

ctf.tex 4 2005.07.07 16 : 30


The following events cause transition to another mode:Event New mode Comment

Home territory Normal Upon entering his/her home territory the Flag carrier’steam wins this round, scores 20 points and a reset oc-curs.

Capture Prisoner If the flag carrier is captured then the flag is dropped atthe point of capture.


2.2.5 TCTF

If the capture or movement of players in the region of a flag causes a player to be illegallywithin 25m of his/her own team’s flag then they are in the TCTF mode. The player isexpected to make every effort to exit the exclusion zone quickly. The following eventscause transition to another mode:Event New mode Comment

Exit zone Normal When the player exits the exclusion zone (i.e., centre tocentre distance from the flag > 25.25m) (s)he returns tonormal mode.

Zone change Normal When an opponent enters the exclusion zone any playersin TCTF mode return to normal mode.

Timeout Prisoner If a player remains in TCTF mode continuously for morethan 7s, (s)he is captured and sent to jail as a prisoner.


2.3 Visibility

To continue the analogy with the ’real’ game, you can envision that each player is equippedwith a GPS, a fancy positioning system that gives absolute locations of everything in hisview and a two-way radio to communicate with his/her teammates (each team has aprivate channel). The information that is available to the team is what is visible to oneor more of the players on the team.

1. Players have a field of view that is an arc of 120◦ centred about their orientation(i.e., θ ± 60◦) and a range of 100m, inclusive (i.e., any object inside or touchingthis region is in the field of view). Objects in this field of view may be obscured byother objects (trees or players) in the foreground (see Figure 2).

2. Players cannot see through the walls of a jail.

3. A controller will only be given information about objects that are visible to one ormore of its players.

4. A team’s flag and all players on the team are always visible to that team’s controller.

ctf.tex 5 2005.07.07 16 : 30


Figure 2: Player field of view (not to scale). Player (0,0) sees only Player (1,0).

2.4 Flag

1. At the beginning of the game the controller requests a location for its flag. Thislocation must be in the team’s territory within 250m of the central territory bound-ary (i.e., 250 ≤ x < 500 for team 0, 500 < x ≤ 750 for team 1) and cannot be insidea tree or less than 25m from any part of any player.

2. The flag is captured when the position of a player from the opposing team passeswithin 1m of the flag’s location. That is, the player’s centre and the flag areseparated by less than 1m.

3. A captured flag remains with the flag carrier (i.e., the position of the flag is equalto the centre of the flag carrier) until either

(a) the flag carrier crosses back into his/her own territory, at which time the gameresets,

(b) the flag carrier is captured by a player from the opposing team, at which pointthe flag is left at its current location and the flag carrier becomes a prisonerand is immediately transported (teleported) to jail.

4. A player is not permitted to be entirely on his/her home territory within 25m ofhis own team’s flag unless there is a member of the opposing team within 25m ofthe flag. In a case where a player would be forced to violate this rule by the flagbeing freed from a captor, or by movement of other players, the player enters TCTFmode and must quickly exit the zone.

5. The flag cannot leave the field.

ctf.tex 6 2005.07.07 16 : 30


2.5 Collisions

In the case where a player collides with another object (player or tree) or a boundary,the following defines the behaviour:

1. The speed of the player will be set to 0.

2. (Linear) acceleration is unchanged, but will have no effect on speed as long as theplayer’s orientation is such that it cannot move in that direction (i.e., the forceremains applied, but the other object blocks movement).

3. Orientation and angular velocity are not changed.

2.6 Player Capture

1. When 2 players of opposing teams are entirely within the same territory (i.e., nopart of either is touching the territory boundary) and pass within 1m of each other(centre to centre), the player that is on the opposing team’s territory is captured.

2. A captured player enters Prisoner mode and is immediately teleported to the jailof the opposing team and remains there until released.

3. Capturing a player has no effect on the capturing player (i.e., the one who is onhis/her home territory).

2.7 Jail

1. The jail for team 0 is the square with corners (0m, 0m) and (25m, 25m), and forteam 1 it is the square with corners (975m, 0m) and (1000m, 25m).

2. The walls of a jail are opaque.

3. The walls of the jail are solid objects to players in modes other than Normal orEscapee.

4. A player who enters the jail area of the opposing team without being captured willrelease the lowest numbered teammate from jail if any are there. If no teammatesare in the jail then entering the jail has no effect.

5. Upon release the released player and the releasing player are both set in Escapeemode and must leave the territory as quickly as possible to avoid becoming prisonersagain due to timeout.

2.8 Scoring

Points are awarded to each team, as follows:

ctf.tex 7 2005.07.07 16 : 30


Event Points

Capturing a player 1Releasing a player 1Capturing all players (bonus) 10Capturing the flag 2Reaching home territory with the captured flag 20

Note that if a player remains in TCTF or Escapee mode for too long and is thus sentto Jail, the player is deemed to have been captured and the opposing team is awarded apoint.

2.9 Initial configuration

At the start of each game and after every reset the configuration is set so:

1. The players are in Normal mode and are positioned as follows:

Player Team 0 Team 1

0 (400, 75) (600, 75)1 (400, 125) (600, 125)2 (400, 175) (600, 175)3 (400, 225) (600, 225)4 (400, 275) (600, 275)5 (400, 325) (600, 325)6 (400, 375) (600, 375)7 (400, 425) (600, 425)

2. All velocities are 0 in magnitude and orientations are 90◦ for team 0 and 270◦ forteam 1.

3. All accelerations are 0 and no player is initially spinning.

4. The flags and trees are positioned as requested in the initial handshaking stages ofthe protocol.

2.10 Game Clock

The game clock will run at a rate that is a positive integer multiple of real time. Forexample, if the clock factor is one, then the game will run in real time. However, if theclock factor is two then the game will run at twice real time. In this case each second ofgame time will take only 0.5 seconds of real time. The clock factor will be input by theuser when starting the simulator.

For the competition a fixed clock factor (probably 2) will be used.

2.11 Duration

Each game will last 10 minutes of game clock time.

ctf.tex 8 2005.07.07 16 : 30


2.12 Reset

The game is reset if any of the following occurs:

1. A flag is carried to the territory of the opposing team.

2. All players on one team are captured.

2.13 Coordinate systems

The x direction goes from left to right, from 0 to 1000m. The y direction goes from downto up, from 0 to 500m.

Positions are in metres, velocities in m/s, and accelerations in m/s/s.Angles are all clockwise from the y axis and are in degrees. Thus 0◦ is up (North).

(This is the same as compass bearings.)Team 0 will have home territory on the left and team 1 on the right.Players are numbered from 0 to 7.Times are in milliseconds since the start of the game. Thus the game ends at

600,000ms.

3 Simulator-Team Link (STEAL) Protocol Details

3.1 TCP/IP details.

Three processes will interact over the Internet using TCP/IP connections: The simulatorand two team controllers.

Each simulator acts as a “server” (in TCP terms) and listens on a specific port. Eachteam of software engineering students will be assigned a different port, so that studentteams can use the same host without both trying to use the same port.

• Team red 23450

• Team green 23451

• Team blue 23452

• Team purple 23453

• Team orange 23454

• Team black 23455

Each team controller must be capable of connecting with servers on any of the aboveport numbers and on any host on the Internet. Hosts are described either by a 4 bytehost address —e.g. 134.153.12.83— or host name —e.g. tera.engr.mun.ca.

ctf.tex 9 2005.07.07 16 : 30


3.2 Requests and replies

Each team controller may send requests to the simulator. The environment simulatorwill attempt to fairly merge requests from the two team controllers and to deal with andreply to each request promptly.

Each request from a team controller will be one line of text. For each request therewill be a one line reply.

Each reply contains the game clock time at which it was sent. This is useful becausein any distributed application, there are small, but unavoidable delays, so it is useful toknow when the information your application is receiving was valid.

In the event of a reset the next request from each team will not be honoured and doesnot get a normal reply. Instead of a normal reply, the environment simulator will sendan indication that there was a reset. See the grammar of the interaction for completedetails.

Team controllers must not send a subsequent request before they receive a reply tothe previous request.

3.2.1 Requests

The main body of the protocol consists of a sequence of requests, sent from team con-trollers to the environment simulator, and replies sent from the environment simulatorto the team controller. There are two classes of request. “Feedback requests” requestinformation about the game state. “Control requests” request a change in the state ofsome player. The simulator must reply to each request promptly.

Feedback requests In each case t is the game clock time (in milliseconds since thegame start) at which the information is valid.

• all?

Normal Reply: t s0 s1 q0 f0,x f0,y

m(0,0) px,(0,0) py,(0,0) v(0,0) θ(0,0) m(0,1) px,(0,1) py,(0,1) v(0,1) θ(0,1) . . . m(0,7) px,(0,7) py,(0,7) v(0,7) θ(0,7)

q1 f1,x f1,y

m(1,0) px,(1,0) py,(1,0) v(1,0) θ(1,0) m(1,1) px,(1,1) py,(1,1) v(1,1) θ(1,1) . . . m(1,7) px,(1,7) py,(1,7) v(1,7) θ(1,7)

r0 t0,x t0,y r1 t1,x t1,y . . . r9 t9,x t9,y

where (for all i ∈ {0, 1}, j ∈ {0, 1, 2, . . . , 7} and k ∈ {0, 1, 2, . . . , 9})

– t is the current game clock time in milliseconds since the game start.

– si is the current score for team i.

– qi is 1 if the flag for team i is in view, 0 if it is not.

– (fi,x, fi,y) is the position of team i’s flag in metres.

– m(i,j) is the visibility and mode for player (i, j), as follows:

ctf.tex 10 2005.07.07 16 : 30


0 not visible1 Normal2 Prisoner3 Escapee4 Flag Carrier5 TCTF

– (px,(i,j), py,(i,j)) is the position of player (i, j) in metres.

– (θ(i,j), v(i,j)) is the velocity of player (i, j). We require that 0 ≤ θ(i,j) < 360.

– rk is 1 if the kth tree on the opposing team’s territory is in view, 0 if it is not.

– (tk,x, tk,y) is the position of the kth tree on the opposing team’s territory.

Note:

– The flag and all players for a particular team are always visible to that team.

– When qi = 0 the values of (fi,x, fi,y) are arbitrary.

– When m(i,j) = 0 the values of px,(i,j), py,(i,j), θ(i,j), and v(i,j) are arbitrary, al-though we still require 0 ≤ θ(i,j) < 360.

– When rk = 0 the values of (tk,x, tk,y) are arbitrary.

– Owing to simulation imperfections, the values reported may be slightly out ofnormal range, for example, a player x position that is negative should not beconsidered an error.

Control Requests “Control requests” request that an action be executed either imme-diately or in the future. This is accomplished by a time field in the request. The simulatormust act on the request at the earliest time possible which is equal to or greater than thetime field’s value. Thus, to request immediate action, a controller may use a time of 0.When there is a reset all pending actions must be dropped by the simulator.

If two or more control requests of the same kind for the same player are scheduled tooccur at the same future time then only the last request to be received should be actedupon (i.e., the later request overrides the earlier ones).

It is not an error to send a request that is inconsistent with the player’s mode.It is not an error to send a request with a time field greater than or equal to 600,000.If, when a request is acted on, it is inconsistent with the player’s mode, the request

is simply ignored.There is no communication from the simulator to the controller that the request has

been acted on; the controller can assume that actions will be acted on at (or soon after)the time specified, provided that it is consistent with the mode of the player involved andno reset has in the mean time.

For all these requests, the normal reply is simply the current time in milliseconds sincethe game start. In all cases the player number must be in {0, 1, . . . , 7}.

• spin! t number rate

number is a player number.

ctf.tex 11 2005.07.07 16 : 30


rate is angular velocity in degrees per second (-90 to 90).

Sets the angular velocity for the player.

• accelerate! t number acceleration


acceleration is the rate of acceleration (-5 to +2).

Sets the acceleration for the player.

Note that while negative accelerations are allowed, negative velocities are not, decel-eration continues uniformly until the velocity is 0. Similarly, velocities are cappedat +10.

• place flag trees! fx fy t0,x t0,y t1,x t1,y . . . t9,x t9,y

(fx, fy) is the requested location of the flag, which must satisfy the criteria detailedin Section 2.4. (ti,x, ti,y), for i ∈ {0, 1, 2, . . . , 9} are requested locations for the trees,which must satisfy the criteria detailed in Section 2.1. This command is only usedduring the initial game setup (use case “request a game”) between the controllersand the simulator. It is an error to request an invalid flag or tree location.

• place player! t number x y θ


(x, y) is the location to place the player and θ is the orientation. Velocity andaccelerations are set to 0.

This command can only be used in “test mode”, explained below.

• set time! t t′

The game clock is set to time t′, which must be in the future. Object positions arenot modified directly by this command but may be unreliable following it (i.e., it isan implementation decision as to how object positions are updated when the timehas been advanced by more than the normal update period for the model). Anytimeouts (e.g., too long in a particular mode) that would occur should be actedupon. The reply is the time before the request is acted upon.

This command can only be used in “test mode”, explained below.

3.3 Test Mode

In order to facilitate testing, the simulator must be capable of starting in either “gamemode” or “test mode”. The only difference between these two modes is that in test modethe place player!, and set time! commands are honoured.

3.4 Starting each game

The simulator must be capable of dealing with multiple games between the two teamcontrollers. The motivation for allowing multiple games is largely to facilitate testing.Team controllers should offer to play at least one game, but may quit after the first game.

ctf.tex 12 2005.07.07 16 : 30


To start the game each team controller will identify itself and request a side. Theenvironment simulator will send back a reply indicating which side the team will be. Thecontrollers then set the flag and tree location and wait for the response “0” indicatingthat both flags and all trees have been set in place and the game has begun. Teamcontrollers should be capable of requesting either side based on user input.

3.5 Grammar for interactions

Before proceeding, read the handout on context free grammars.The following context free grammar shows the possible communication histories be-

tween the environment simulator and one team controller.Neither the environment simulator nor the team controller should send more than

2500 bytes without a newline.I use the following conventions

• The alphabet of this grammar is the set of 256 bytes tagged according to thedirection they are going.

• s2t(E) indicates a communication sent from the environment simulator to the teamcontroller.

• t2s(E) indicates a communication sent from the team controller to the environmentsimulator.

• This grammar does not show which replies normally go with which requests. Thatis done in section 3.2 on page 10.

• typewriter font indicates terminals. Each character is represented as a byteaccording to the ASCII code. This means that case (upper or lower) is significant.

• space indicates a byte of value 3210, the ASCII code for a space.

• newline indicates a byte of value 1010, the ASCII code for a newline (in Java: ’\n’)

.1

• The start symbol of the grammar is Start.

3.5.1 Common nonterminals:

Sps → {space}1

Name → {Letter}101

Int → {Digit}91

Float → OptMinus Int . Int

Letter → [a− z] | [A− Z]

Digit → [0− 9]

OptMinus → − | ε1Note that the Java println subroutine may send both a byte 13 and a byte 10, and thus should be

avoided.

ctf.tex 13 2005.07.07 16 : 30


Note. No name should exceed 10 letters.No Int should exceed 9 digits.No Float should exceed 9 digits in its integral part, nor 9 digits for its fractional part.

As you can see, the decimal point is not optional and must be preceded by and followedby at least one digit.

3.5.2 Initialization, play and ending.

Start → t2s(CTF2005 Sps Name newline) s2t(CTF2005 newline) Init

Init → t2s(want side Sps Int newline) s2t(on side Sps Int newline) Config

| t2s(want side Sps Int newline) s2t(quit newline)

| t2s(want side Sps Int newline) s2t(EndMsg) Init

| t2s(quit newline) s2t(quit newline)

Config → t2s(place flag trees! {Sps Float Sps Float }1111 newline) Config′

Config′ → s2t(0 newline) Play

| s2t(EndMsg) Init

Play → t2s(Request) Play′

Play′ → s2t(Reply) Play

| s2t(ResetMsg) Play

| s2t(EndMsg) Init

ResetMsg → reset newline

EndMsg → end Sps Int newline

Note that the Name parameter to the team’s CTF2005 message should be the nameof the team controller in lower case. I.e., one of: red, green, blue, purple, orange, black.

Team controllers have the option of quitting before each game, if either team requeststo quit then the simulator sends back a quit message and ends the connection. The fourchoices for nonterminal Init represent respectively the following four possibilities:

• that both teams request to play;

• this team requests to play, but the other requests to quit;

• this team requests to play, but the message is in error; and

• this team does not wish to play.

The Int parameter to want side should be 0 or 1 and indicates which side the teamcontroller wants to be. The parameter to on side indicates which side the team controllerreally will be for the duration of the game. (If the team controllers want opposite sides,they get what they request.) The on side message is not sent to either controller untilboth controllers have requested sides.

The parameter to end should be 0 or 1 or 2. 0 indicates a victory for team 0; 1 avictory for team 1; and 2 a draw.

ctf.tex 14 2005.07.07 16 : 30


3.5.3 Request syntax

Request → all? newline

| spin! Sps Int Sps Int Sps Float newline

| accelerate! Sps Int Sps Int Sps Float newline

| place player! Sps Int Sps Int Sps Float Sps Float newline

| set time! Sps Int Sps Int newline

| EndMsg

The last kind of request should only be used if a team controller detects a problem withcommunications coming from the simulator or in test mode to end the game. In bothcases the parameter is ignored and the simulator response is to send the correct end

message to both controllers and end the game. The team controller should print theerroneous message so that it is clear that the simulator did make a mistake.

3.5.4 Reply Syntax

The choice of reply format is entirely governed by the previous request.

Reply → Time newline

| Time Sps Int Sps Int Sps Players Sps Players Trees newline

Time → Int

Players → Int Sps Float Sps Float { Sps Int Sps FourCoords }88

FourCoords → Float Sps Float Sps Float Sps Float

Trees → {Sps Int Sps Float Sps Float }1010

3.6 Error Handling

Any incorrect use of the protocol by either side must be reported by the other side. Thisincludes

• any deviation from the grammar,

• numerical values that are out of range (but note that positions and velocities re-ported by the simulator may be a bit weird, these are not considered out of range)

• names that are out of range,

• attempts to use test mode commands when the simulator is not in test mode.

These errors should be reported by at the very least

• Printing an error message (to “standard output”).

• Clearly printing the offending line (to “standard output”) exactly as it was received.For the simulator there must be an indication of the name of the offending client(red, blue, etc.).

ctf.tex 15 2005.07.07 16 : 30


• Controllers send an EndMsg as the next request. Simulators send an EndMsg asthe next reply to the next request from each controller.

• Optionally, simulators and controllers may pop up a dialog box to inform the userof the problem.

4 Requirements and Use Cases

4.1 Use cases for the Simulator and the Team Controller

Important note. Normally Use Cases are phrased in terms of the “the system” andvarious actors that interact with the system. In our case, we have not a single system tobe specified, but two kinds of systems: The simulators and the team controllers. Thereforethese use cases are phrased in terms of the simulator, the team controllers, and variousother actors.

4.1.1 Top level Use Case “play game”:

Actors: The simulator, the two controllers (which I will call A and B), the user of the sim-ulator (simulator user), the user of the A controller (A user), the user of the B controller(B user).

Initiated by the simulator user.

1. Simulator user: starts the simulator (see use case “start simulator” in game mode.

2. A user and B user: start the controllers (see use case “start controller”) using thehost of the simulator and the appropriate port.

3. A and B initiate a handshake (see use case “handshake”)

4. A and B request a game (see use case “request a game”)

5. A and B complete the game (see use case “complete the game”)

6. A and/or B opt to quit (see use case “opt to quit”)

7. A, B, and the Simulator: close their ports and exit.

Alternative paths. The simulator should be prepared to play:

• 1 game (above sequence),

• 0 games (steps 1, 2, 3, 6, 7), or

• multiple games (steps 1, 2, 3, 4, 5, 4, 5, ..., 4, 5, 6, 7).

ctf.tex 16 2005.07.07 16 : 30


4.1.2 Top level Use Case “run tests”:

Actors: The simulator, a test process, a user.Initiated by the user.

1. The user: starts the simulator (see use case “start simulator”) in “test” mode.

2. The user: starts the test process.

3. The test process connects to the simulators port twice.

4. The test process and the simulator proceed as in use case “play game” with thetest process taking the part of both A and B.

Note: In test mode the simulator must deal with all requests.

4.1.3 Use case “start simulator”

Type: This is a partial use case.Actors: The simulator, the user of the simulator.

1. User: instructs the OS to run the simulator.

2. Simulator: prompts for mode (game mode or test mode).

3. User: selects either game mode or test mode.

4. Simulator: prompts for clock factor.

5. User: enters a positive integer.

6. Simulator: Prompts for TCP port number.

7. User: enters the port number, or opts for default.

8. Simulator: Opens the port as a server.

9. Simulator: Listens on the port until two connections have been made to the port.

10. Simulator: Creates a window for displaying the game state.

Note: Prompts to the user may be combined into a graphical window with sensibledefault values for mode, clock factor, and port number.

Note: The final step can happen earlier or later, so long as the game state is displayedwhen the game is on.

Note: Although each Software Team is assigned a default port, each simulator shouldbe capable of using any TCP port.

Exceptions: The simulator may fail to open the port. In this case it prints an errormessage to the console and exits.

ctf.tex 17 2005.07.07 16 : 30


4.1.4 Use case “start controller”

Type: This is a partial use case.Actors: A controller, the user of the controller.

1. User: instructs the OS to run the controller.

2. Controller: Prompts for an Internet host address.

3. User: Supplies a host address.

4. Controller: Prompts for a port number.

5. User: Enters the port number.

6. Controller: Connect to the given port on the given host.

Note: In step 3, the user may be permitted to supply the IP host name, rather thanthe IP host address, but supplying the IP address must be an option.

Exceptions: The controller may fail to connect to the port. In this case it prints anerror message to the console and exits.

4.1.5 Use case “handshake”

Type: This is a partial use case.Actors, the simulator and the two controllers (A and B)

1. A: sends a CTF2005 message with its name (colour) to the simulator.

2. Simulator sends a CTF2005 message to A.

3. B: sends a CTF2005 message with its name (colour) to the simulator.

4. Simulator: sends a CTF2005 message to B.

Note, as long as 2 follows 1 and 4 follows 3, order of the above steps is arbitrary.Exceptions: If a connection is lost, the agent should print a message, close its port(s)

and exit.If any agent detects an incorrectly formatted message, it should print a detailed error

message (including the incorrect message and, for the simulator, an indication of where itcame from), close its port(s) and exit. The simulator should send an EndMsg as describedin section 3.6 prior to exit.

4.1.6 Use case “request a game”

Type: This is a partial use case.Actors, the simulator and the two controllers (A and B)

1. A: sends a want side message to the simulator.

2. B: sends a want side message to the simulator.

ctf.tex 18 2005.07.07 16 : 30


3. Simulator: initializes the game state.

4. Simulator: sends an on side message to each controller.

5. A: sends a place flag trees! message to the simulator.

6. B: sends a place flag trees! message to the simulator.

7. Simulator: places flags and trees and starts simulating.

8. Simulator: sends a 0 (the time) to each controller.

Notes: Steps 1 and 2 can happen in either order. If A and B want different sides, theyeach get their request, otherwise the simulator selects one to be side 0 and the other tobe side 1.

Exceptions: If a connection is lost, the agent should print a message, close its port(s)and exit.

If any agent detects an incorrectly formatted message, it should print a detailed errormessage (including the incorrect message and, for the simulator, an indication of where itcame from), close its port(s) and exit. The simulator should send an EndMsg as describedin section 3.6 prior to exit.

4.1.7 Use case “complete the game”

Type: This is a partial use case.Actors: the simulator and the two controllers (A and B)

1. One controller: sends a request to the simulator.

2. If the game has ended and the controller in question has not been informed yet

• The simulator: sends an end message to the controller

Otherwise

• The simulator: sends an appropriate reply to the controller

3. Repeat from step 1, unless both teams have now been informed of the end of thegame.

Note: Once one side has been informed of the end of the game it may send a quit orwant side message. Hold this message in the buffer for now.

Note: When both sides send requests at about the same time, the simulator must dealwith them in some unbiased manner.

Exceptions: If a controller detects that the connection is lost, it should print a message,close its port, and exit. If a simulator detects that a connection is lost, it should print amessage, send end and quit to the remaining controller, close its ports, and exit.

If a controller detects an incorrectly formatted reply, or end message, or a reply without of bounds values, it should print a detailed error message and send an end messageto the simulator.

ctf.tex 19 2005.07.07 16 : 30


If the simulator detects an incorrectly formatted request, a request with out of rangeparameters, or, when in game mode, a request not allowed in game mode it should dothe following: print a detailed error message and send an EndMsg, as described in section3.6, which awards victory to the other team.

4.1.8 Use Case “Opt to quit”

Type: This is a partial use case.Actors: the simulator and the two controllers (A and B)

1. One controller sends a quit message.

2. The other controller sends a quit message.

3. The simulator sends a quit message to both controllers.

Alternative paths. One controller may send a quit message and the other a want side

message.Exceptions: If a connection is lost, the agent should print a message, close its port(s)

and exit.

4.2 Requirements for the Simulator

4.2.1 Functional requirements

1. The simulator must faithfully follow the rules of CTF described above.

2. The simulator must be capable of following the above use cases and must respectthe STEAL protocol described above.

3. The simulator must report errors made by the controllers. The error report mustcontain the complete text of the erroneous message sent by the controller and thereason that the simulator decided it was erroneous.

4. The simulator must display the game state graphically as it progresses, includingthe score and the positions of the players, flags and trees. Delays in the graphicalpresentation of events should be minimal.

4.2.2 Performance

Performance requirements assume a minimum platform of either Athlon 1.4 GHz runningWindows XP or Linux 2.2.19.

1. The simulator must be capable of updating and redisplaying the game state at least10 times per real time second.

2. The simulator must be capable of handling an average of at least 10 requests fromeach side per real time second.

ctf.tex 20 2005.07.07 16 : 30


3. Control requests with future times should be acted on no more than 1/10th of areal time second after the requested game clock time. Control requests with past(or present) times should be acted upon no more than 1/10th of a real time secondafter they arrive at the simulator.

4. Control requests should not be acted on before the requested time.

5. With a clock factor of one (i.e. rate of game clock = rate of real time clock), thesimulator must simulate the movements of players with a drift of no more than25cm per second. In other words, no matter what happens, after 1 second everyplayer must be within 25cm of it’s theoretically correct position; after 4 seconds itis 1 metre; and so forth.

There is no specified upper limit on the processing rate, however I recommend carethat numerical error does not creep in due to the use of very small time differences. Youshould also consider the effect of clock resolution on your simulation, i.e., avoid time stepsof 0.

4.2.3 Nonfunctional Requirements for the Simulator

1. The simulator must be capable of running under either Windows XP or Linux.

2. The simulator must be written in Java.

4.3 Requirements for the Team Controller

4.3.1 Functional Requirements for the Team Controller

1. The controller must respect the use cases above and must follow the STEAL pro-tocol.

2. The controller must report errors made by the simulator. The error report mustcontain the complete text of the erroneous message sent by the simulator and thereason that the controller decided it was erroneous.

4.3.2 Nonfunctional Requirements for the Team Controller

1. The controller must be capable of running under either Windows XP or Linux.

2. The controller must be written in Java.

3. The controller is to be composed of two layers. Layer 1 will be designed and im-plemented by each team of students as a group. Layer 2 will be designed andimplemented by each individual student. Layer 1 will provide the underlying func-tionality to support a variety of game strategies. Each instance of layer 2 will utilizelayer 1 to implement a game strategy.

4. The controller as a whole must be designed and written to make a reasonable effortto play the game well. For example a controller that simply spins its player for theentire game will be judged to be unacceptable.

ctf.tex 21 2005.07.07 16 : 30

Documents

CTF 2005 Capture the Flag – Speciﬁcation.avardy/courses/se/ctf/ctf.pdf · CTF 2005 Capture the Flag – Speciﬁcation. Dennis Peters, Andrew Vardy∗. Software Engineering 7893