DE | EN

Cat and mouse specification

Content

1. Mathematical definitions

This part describes the general rules of the cat and mouse game in a formal way, the game protocol and message formats are specified afterwards.

1.1 Basics

The cat and mouse game is played by two players.

In our case, the server chooses the starting position and plays the cat, the client plays the mouse.

The game plays on a plane (a two-dimensional area) with a circular shaped pond. The cat must strictly stay outside the pond. The mouse starts inside the pond and tries to reach the land. Once the mouse leaves the pond, the cat must immediately catch it to win, otherwise the mouse will win. The cat (running on land) moves faster than the mouse (swimming in the pond) by a factor of 3.0 to 4.5, depending on the chosen game level.

1.2 Number space and time steps

Mathematically, the game is continuous in space and continuous in time, but this is impossible to represent in a digital game. Furthermore, it might be a bad idea to rely on floating-point arithmetic because different platforms may do some operations differently. For this reason, the following rules are specified:

A location in the game area is represented as an x/y coordinate pair. Only whole numbers (positive and negative) are allowed as x and y values, but no fractions. The ponds center is at (x=0, y=0)

For the visual representation, the x-axis points to the right, the y-axis points down.

The pond has a radius of 160 000 and is defined to contain all points with less or equal distance to the origin.

A point (x, y) is inside the pond if: x^2 + y^2 <= 160000^2

(You may want to avoid the square root function, since it operates on floating-point numbers that introduce inaccuracy. Instead, compare squared distances as shown above.)

Cat and mouse move alternately, beginning with the mouse. Their travel distance is measured as the euclidean distance from one point to the following point and must stay below a given limit. When the mouse makes a move to a point outside the pond, the cat has one last move to reach the exact location of the mouse (and thus catch it) to win. If the distance is too large for a single move, the cat must move to some other point without catching the mouse and the mouse wins.

The maximum distance per move is defined as follows:

The mouse can always move a maximum distance of 400 per move.
Mathematically: A move from (x1, y1) to (x2, y2) is allowed if: (x2-x1)^2 + (y2-y1)^2 <= 400^2
(The rule for the cat applies accordingly, but with another distance.)

The cat can move a maximum distance per move, that depends on the game level:
Level 1: maximum distance = 1200 (3 times the speed of the mouse)
Level 2: maximum distance = 1600 (4 times the speed of the mouse)
Level 3: maximum distance = 1800 (4.5 times the speed of the mouse)

A cat move is valid, if its target location is outside the pond. Note, that a straight line from one location to the next might still intersect the pond border.

Example: The cat might move from (x=159999, y=-600) (which is outside the pond) to (x=159999, y=600) (which is also outside). This is a totally valid move.
However, if you check the middle point between both locations, where a straight line would go through: (x=159999, y=0) This point is inside the pond. The move is still valid, since only the final location of the move matters.

2. Protocol overview

First open the playing field in a web browser to get a room id.

Your client software should then connect to the server and authenticate using the room id that you got on the browser page.

Once authenticated, the client software can start a game with a chosen level, then play the game by controlling the mouse.

3. Protocol details

3.1 Connection

A client can choose between an unencrypted and an encrypted connection.
Connect to xn--frderer-n2a.de port 64090 via tcp for an unencrypted connection.
Alternatively, you may connect to the same name but port 64091 via tcp, then do a tls handshake, for an encrypted connection. The certificate presented by the server must be valid for xn--frderer-n2a.de. The protocol itself is the same on both ports, but on port 64091 it gets tunneled through a tls layer.

3.2 Number format

Signed numbers are used when transmitting coordinates. They are transmitted as 4 byte numbers, two's complement, big endian.

Examples:

decimal value byte representation
0 0x00 0x00 0x00 0x00
1 0x00 0x00 0x00 0x01
10 0x00 0x00 0x00 0x0a
260 0x00 0x00 0x01 0x04
-1 0xff 0xff 0xff 0xff
-3 0xff 0xff 0xff 0xfd
-160000 0xff 0xfd 0x8f 0x00

3.3 Location format

When sending a location (like the new location of the mouse when it moves), the x coordinate is always sent first, then the y coordinate. The location thus takes up 8 bytes.

3.4 Authentication Request

Right after connecting, the client must send an authentication message. It consists of a byte 0x00 followed by the room id string length in bytes (2 bytes, big endian), then the room id as an utf-8 string.

Example, how to authenticate using the room id abcdef_ghijkl

content 0x00 0x00 0x0d 0x61 0x62 0x63 0x64 0x65 0x66 0x5f 0x67 0x68 0x69 0x6a 0x6b 0x6c
meaning msg type = authenticate length = 13 abcdef_ghijkl

The authentication only succeeds, if the room is currently open. When you open a playing field, the browser automatically opens a room and shows the room id. When the browser is closed or otherwise loses connection, the room is closed again (and the player client is kicked, if there is one).

If you do not need a visualization, you may use the room id invisible to get to an always-open pseudo room that will not be visualized.

If you connect to a room where a client is already connected, the earlier client will be kicked out. (This rule does not apply for the invisible room.)

3.5 Authentication Response

The server responds to an authentication request with a single byte, indicating if the authentication was successful.
0x01 means: Authentication was successful, the client can continue now by starting a game.
0x02 means: Authentication was not successful. The client might retry the authentication by sending another authentication message, or just disconnect instead.

3.6 Game start Request

After successful authentication, the client sends a game start request message. It consists of a byte 0x10 followed by the level number (0x01, 0x02 or 0x03).

Example: Start a game with level 2 by sending two bytes: 0x10 0x02

The client may also use a Game start Request message to end an already running game and start a new one.

3.7 Game start Response

Note: There might be a delay after a Game start Request, before a Game start Response is sent back from server to client. During this time, a "new game" banner will be shown in the browser.

The Game start Reponse consists of 17 bytes in total. The first byte is 0x11. It is followed by the location of the cat (8 bytes), then the location of the mouse (also 8 bytes).

3.8 Move

After a new game has been started, the client (mouse) moves first. It does so by sending a Move message.

A Move message has 9 bytes in total. It consists of the byte 0x20 followed by the new location of the player (8 bytes).

Example: Moving to (x=17, y=-25)

content 0x20 0x00 0x00 0x00 0x11 0xff 0xff 0xff 0xe7
meaning msg type = move x = 17 y = -25

After a mouse move, the server will respond with a cat move (same message type 0x20, same message format) followed by a Game state message.

The Game state message consists of the byte 0x21 followed by one byte indicating the state:
0x00: The mouse did not leave the pond in its latest move, so the game continues.
0x01: The mouse left the pond and the cat could not catch up. The mouse won the game.
0x02: The mouse left the pond but the cat caught it right after. The cat won the game.

Further Move messages are only allowed, while the game is in the continue state. But the client can send a Game start Request at any time (during a running game or after a game ended).

3.9 Error codes

Generally, a client implementation should treat all unknown message types as error. The range 0xe0-0xff is explicitly intended for error codes.

Currently, the following error codes are defined and may be sent from server to client:

message type meaning
0xe0 The server received an invalid message (like an unknown message type)
0xe1 The server received a message with a type that either should never be sent from client to server or should not be sent at this protocol state.
0xe2 The browser visualizing the game disconnected. So the client will also be kicked.
0xe3 Another client connected to the same room id, so this client will now be kicked.
0xe4 The mouse moved too far (distance >400) which is not allowed.

These errors have no payload. They are a single byte, followed by a disconnect initiated by the server.