public/subjects/zappy/README.md

zappy

Objectives

You have to create Zappy, which is an entirely automatic game where some AIs play amongst themselves. It is about creating families/teams, surviving by eating food and collecting stones in order to level up. Each level has different requirements for a ritual, which makes the adventure more and more difficult for the AI players, which play on their own, without any help form their creator. The game is over once six members of one family/team reach the highest possible level (8).

Game presentation

The Game Parts

Here are the different parts of the game:

• The server contains the field, the resources, and manages the logic and timing of the game.

• One or many clients will connect to the server and each will “pilot” one player. The players are spread over teams.

• A graphic client that connects to the server and displays the field and what happens there.

Geography

• The game consists in managing an entire world and its population. That world, "Minerth" is geographically made of plains, there won't be any obstacles on it.

• The world is spherical and the game board is represented as a map. So if a player leaves the board from the right, he will enter again from the left.

Resources

The place where we are contains many resources that can be used for your survival, what you have to do is just look for them and get them before other players do. Here you will find some stones and food that you will need if you want to survive and evolve.

• These stones are of 6 different types:

  • jade
  • peridot
  • amber
  • amethyst
  • garnet
  • ammolite

• These resources must be randomly generated by the server, despite being random, the generation must have some logical rules, for example:

• You can't put all the stones in one square.

• You can't put more than one food per square.

• Only one stone of each type in a square. You can have up to 3 stones of different types in the same square.

These are just some examples of some rules. It's up to you to decide them, but be prepared to explain them to the auditors.

General Rules

• Each player starts with 10 food and 0 stones.
• Each player starts on level 1.
• As you level up, your player sight improves.
• You must eat to survive and not starve and die.
• You must collect stones to level up.
• To win the game you must have at least 6 players of your family/team at level 8.

Player

• The local is happy just looking for stones and feeding on the way, but don't be fooled by him, he can get greedy and kick you out of his way!

• He meets, without issues, other people on the same location and sees as far as the eye can see.

• It is impossible to guess the Minerthian orientation when crossing him.

• The food that the Minerthian picks up is the only resource he needs to live.

• One food unit allows him to survive 126 time units, so 126/t seconds. The more he picks up the more he lives.

Evolution ritual

• The goal for everyone is to reach the top of the Minerthian hierarchy.

• The ritual that allows you to increase the Minerthian physical and mental capacities must be performed as follows:

  You need to gather in the same field unit (square):

  • A specific set of stones.
  • A specific number of players of the same level.

• The player will start the enchantment and the evolution will start.

• It is not necessary that all the players are on the same team, but they need to have the same levels.

• All players participating in the enchantment will reach a higher level.

• Only one player starts the enchantment and the others go to him and join.

• Only after two or more players are on the same square, they can start the enchantment.

• If one of the members dies, the others will continue the enchantment, unless the player is left alone, if that happens he has to start the process of enchantment again.

Here are the combinations of resources and players you need for the enchantment and evolution:

Level	Number of Players	jade	peridot	amber	amethyst	garnet	ammolite
1-2	1	1	0	0	0	0	0
2-3	2	1	1	1	0	0	0
3-4	2	2	0	1	0	2	0
4-5	4	1	1	2	0	1	0
5-6	4	1	2	1	3	0	0
6-7	6	1	2	3	0	1	0
7-8	6	2	2	2	2	2	1

Vision

• The player's view of the field is limited! In order to improve your vision you will have to level up.

With each evolution, your vision goes up one unit of measurement ahead and one on either side of a new line.

Here is the example for the first 3 levels (our player is at 0):

              ---- ---- ----
             | 1  | 2  | 3  |
              ---- ---- ----
                  | 0  |
                   ----
                  Level 1

         ---- ---- ---- ---- ----
        | 4  |  5 |  6 |  7 |  8 |
         ---- ---- ---- ---- ----
             | 1  | 2  | 3  |
              ---- ---- ----
                  | 0  |
                   ----
                  Level 2

 ----- ----- ----- ----- ----- ----- -----
|  9  | 10  | 11  | 12  | 13  | 14  | 15  |
 ----- ----- ----- ----- ----- ----- -----
      |  4  |  5  |  6  |  7  |  8  |
       ----- ----- ----- ----- -----
             | 1  | 2  | 3  |
              ---- ---- ----
                  | 0  |
                   ----
                  Level 3

For the player to know what's around him, the client sends the command SEE and the server responds the following chain of characters (for level 1):

{content-square-0, content-square-1, content-square-2, content-square-3}

Our player cannot see himself and if there is more than 1 object in a square, they are all indicated and separated by a space:

              -------- -------- --------
             | amber  | garnet |        |
             | player | garnet |        |
              -------- -------- --------
                      |        |
                      |  food  |
                       --------
                        Level 1

{food, player amber, garnet garnet, }

The Time and Game Speed

The game speed is defined by a time unit. Each action in the game has a duration proportionate to this time unit.

The time unit is defined by the function 1/t :

• t is passed as parameter at the start of the server.
• A time unit lasts 1/t seconds.
• The Minerthians have second as an absolute time unit.
• The formula for the execution of an action is action/t.
• t is an integer. If t=1 "advance" takes 7 seconds. We choose by default, t=100 then "advance" will take 7/100 seconds.

Objects Management

It is impossible to distinguish two objects of the same class. Only the class of an object can be identifiable, that is, two 'ambers' will have the same denomination, as they belong to the same class, but 'garnet' will have a different class than 'ambers', that way you are able to identify the resources.

Teams/Families

The goal of the game is to create a team/family of six players and get them to level 8!

At the beginning of the game your family only has one member, so you have to complete the action of calling in order to get more family members.

Each player starts with 10 food and is controlled by a client. The clients cannot communicate or exchange amongst each other data outside of the game, in any way.

Calling

The execution of the fork command results in a ship being called. Your player will call another member of his family.

Once the call has been made, the player can proceed with his life while waiting for the "ship" to arrive. When the ship arrives, a new player will appear and will receive a random direction. This operation allows a new player to join.

The connect_nbr command sends back the number of connections that are underway and authorized for this family. This way you will also know how many spots you have free on you team/family.

• Time to call the ship: 48/t

• Time for the ship to arrive 600/t

Inventory

The inventory command allows you to see what objects the player has and how much time he has left. The server will send back, for example, the following line:

{food 300, amber 4, garnet 7, ..., peridot 2}

Kick

A player can kick all the players sharing the same square. It pushes them in the direction he is looking at. When a client sends the kick command to the server, all the clients in that square receive the following line:

moving <K>\n

With K indicating the direction the player is looking to, which is where the other players will be kicked. The kick only works for players, you can't kick food or other resources and you can't kick during the evolution ritual.

The commands

Here are the actions that a player will respond to and their syntax. Remember that the syntax must be the same as the following:

Action	Command	Delay/time	Response
advance one square	advance	7/t	ok
turn right 90 degrees	right	7/t	ok
turn left 90 degrees	left	7/t	ok
see	see	7/t	{square1, square2, ...}
inventory	inventory	1/t	{garnet n, amber n, ...}
pick an object	pick <object>	7/t	ok/ko
drop an object	drop <object>	7/t	ok/ko
kick a player from the square	kick	7/t	ok/ko
broadcast	broadcast <text>	7/t	ok
begin the enchantment	enchantment	300/t	evolution in progress
			current level : K
fork a player	fork	48/t	ok
know the number of unused connections by the team	connect_nbr	0/t	value
death of a player	-	-	death

All commands are passed as a character string that ends with a newline. In case of any unknown or incorrect command, the server must respond with "ko".

Broadcast

To send a message, the following command must be sent to the server by the client:

broadcast <text>

The server will send this line to all its clients:

message <K>,<text>

With K indicating the direction from where the sound comes.

Sound Transmission

All the players listen to the broadcasts without knowing who broadcasts them, what they understand from it, is only the direction from which the sound comes and the message.

The number of squares traversed by the sound before reaching the player indicates its direction. This numbering is done by assigning '1' to the square in front of the player, then counting down the squares around the player in a trigonometric (counterclockwise) direction. Remember, sound is a wave that moves in a linear manner and the world is round, so we'll choose the shortest path for sound between the transmitter and the player we calculated for.

The following example indicates the sound trajectory that we must choose, as well as the numbers of the squares around the player. The player "A" is the source that sends the broadcast through the square 4 and "B" is the receptor witch receives the broadcast through square 2.

If the broadcast is sent from the same box as the receiving player, he will receive the message from square 0.

The Server

The server is the main engine that will interfere between the AI and the GUI. It will exchange all data with the AI and execute these instructions. At the same time, it send the information to the GUI. It can be written in one of these languages [C, C++, Rust].

For this part, you must create a TCP server to make a connection between clients and manage the entire world.

Server Instructions

• Your server must generate all the resources in a random way following the rules mentioned above in the resources section.
• Any request to your server must never hang forever. It must never block, and the client can be appropriately bounced if necessary.
• The server executes the client requests in the order they are received.
• The requests are buffered and the execution time of the command will only block the player concerned.
• It's forbidden to use any exec functions to run another server.
• It must stay available at all costs.

Use multiplexing connections on your server.

$ ./server
	Usage: ./server -p <port> -x <width> -y <height> n <team> [<team>] [<team>] ... -c <nb> [-t <t>]
    -p  is the port number
    -x  is the width of the world
    -y  is the height of the world
    -n  is the name of the teams
    -c  is the number of authorized clients per team
    -t  is the time unit divider (the greater t is, the faster the game will go)

Tip

• You can implement a non-blocking architecture with a circular buffer for every player action, allowing the data to be stored while performing the actions. The approach you take is up to you to decide.

The Client

The Client can be written in a language of your choice.

$./client
Usage: ./client -n <team> -p <port> [-h <hostname>]
  -n is the name of the team
  -p is the port number
  -h is the name of the host, the default is localhost

The client is autonomous, he must send the command order to the server without any intervention from humans.

Client/server communication

The communication between client and server will happen via sockets and TCP. The port used must be indicated in the programs parameters.

The client will send its requests without waiting for their execution, and the server sends back a message confirming the successful execution of the requests.

The client will open a socket on the server's port and the connection client to server will happen as such:

Client's message	Command
	WELCOME\n
\n
	\n
	\n

The nb-client indicates the number of clients that can still be accepted by the server for the team team-name. If that number is greater than 1 a new client connects. X and Y indicate the world’s dimensions.

If the team name passed by the client doesn't exist the server must print "Error: the team <name of team> doesn't exist"

The client can send up to 10 successful requests without a response from the server. More than 10, the server will no longer take them into account.

There is no chat room or sharing of data between players. Still, the Player can broadcast a message through a command-line sent to the server, which will be broadcasted to all players; All details are in the sound transmission part.

Graphic interface

To have a better vision of the game, which is simple, clear and ergonomic, the project will need to have a graphic visualization client. That client will propose a real-time representation of the world as it is on the server.

• Using any game Engine is forbidden!
• The interface must be at least in 2D with the use of icons allowing a representation of the world.
• You need to make sure you can see the in-game items.
• You need to implement the ability to click on a square to see its details, such as how many items of each are inside the square. It should look like a floating window, tooltip or something else.
• You need to make sure that the visualization of sounds is included.

The graphic part can be developed in a language of your choice [Javascript, Python, C, C++, PHP, Perl, etc]. This will communicate within the network with the server to retrieve the contents of the map, teams, inventories, etc, everything that is needed to see what is happening in the game.

BONUS

• Create a 3D interface or any other type of representation.
• Add a flag to for a log mode when running the server.
• Add a flag for the number of resources and food density (could be different levels for example).
• Implement a seed in the server and client so that specific scenarios could be reproduced.

Attention: siege is a stressing tool, use it ONLY to test your own server. Do NEVER use it on any server/website without the owner's permission. If you do so you would have illegally DDoSed a server and could face serious troubles.