Realtimebattle-Team-Framework Manual
Author: David Tibbe and Tino Truppel

# Chapter 1.2 - Definitions of Terms (by Johannes Nicolai)

Before you can start, you should have a basic overview about some basic terms used in the framework. If you are a total novice to this project, first take a look into the minutes of our first introduction meeting that can be found in the sourceforge documentation manager. There all basic terms about rtb team are explained. Now the definitions, that are essential for the strategy development.

## RealTimeBattle

Programming game, hosted on realtimebattle.sourceforge.net, under this resource one can find further documentation, sources and some sample robots.

## RTB-Team Framework

Official name of this project by sourceforge.net, this project is hosted on rtb-team.sourceforge.net, rtb-team is the Unix name of this project.

## RTB-Server

Name of the process with the name "realtimebattle" of the RealTimeBattle project, this server is used to simulate the virtual reality for all robots, gives them the information they need and processes their commands.

## Master-Server

If more than one of the robots, written in this project will participate in a single game, one of it will become Master- Server, that means, it has to fulfill two roles: acting a robot itself (as a local client) and coordinating the other robots (remote clients) as well. The second role even persists, if the local client will be already dead.

## Framework

The term framework in this project applies to all classes, that are needed for the robots of our project to communicate with each other and the RTB-Server, log messages, synchronize, choose the strategy, read and follow the rules in the configuration files and provide an abstract finite state machine to the concrete strategies. The only thing that does not belong to the framework is the concrete strategy that should and have to use the services being served by the framework that IS NOT PART of the RTB-Server.

## Strategy

The collection of corresponding states and data repositories for the clients and the server in order to implement a certain team behaviour of the robots which use the strategy. NOTE: One team can only have one strategy at a single sequence.

A strategy technically is a collection of classes that define how the robots in a team interact with each other. The whole behavior of the complete team is defined in a strategy. All robots in the team have the same strategy. A strategy consists of the following parts:

- one strategy factory
- the client states
- the server states
- the client and server repositories

## Strategy Factory

The strategy factory is a class whose solely purpose is to create the client states, the server states and repositories when the framework wants it to do so. Only the strategy factory knows the names of the concrete server and client states / repositories. It has to determine the initial server state, the initial client state and the token that is used by this strategy to end the server tip sequence (a string that is never used as a server tip [see below]). The strategy factory will register itself in the framework with its name. It will be automatically selected by the framework if the user of the robot has specified it in the configuration file (see section resources provided by the framework).

## States

Defines the behaviour of the robots is controlled by client and server states. You can think about one state as a state in a finite state machine. Every message that is sent by the Realtime Battle server will be parsed by the framework at first and then delegated to the appropriate method in the current client state. This state can decide what to do with the supplied information. It has the ability to let the framework delegate the following messages of the Realtime Battle server to another client state (state chance), change values / invoke methods of the client specific repository, log messages to the framework (see section resources provided by the framework), retrieve runtime / configuration / game specific values from the framework (see section resources provided by the framework) and / or send commands to the Realtime Battle server.

After all messages of one round are received by the framework, it will notify the current state about that fact, that now has gathered all information and in the meantime, it will send all received messages to the master server.

Here the obtained data will be processed by the corresponding server states (every robot has its own finite state automate in the master server) that can act similar to the client states (except sending commands to the realtime battle server). Furthermore, on master server side, the different robots in the team can share information about each other and so can profit about hints, the client states could not have.

To tell the client states about this information and actions the robot should do as reaction to the messages reported by the environment (given by the Realtime Battle server), the server states can send back "server tips"" to the client states.

## Server Tip

A server tip is a string sent by a server state to a client state in order to influence the behaviour of the robot. The format, meaning and parsing of this server tip is only determined by the concrete strategy.

After all received messages for the robot are processed in the master server, the framework will notify the current states in the server side automates so that they can generate these server tips. Of course, the client and server states have to understand themselves and have to work together. These tips will be send to the corresponding clients.

There, they will be delegated to the current state in the corresponding client-side automate (the current change can decide to switch to another state at this stage, too). After all server tips are processed, the framework will notify the current client state a last time in this round.

Now, this state has to send the last commands to the Realtime Battle server. After this step, the next round will begin. Note: A round lasts about some milliseconds, so this round trip (described in detail (petri nets, sequence diagrams) in the design documents located on the rtb team web site, section framework) will be done very often.

It is possible for a strategy not to send any server tip at all. If you chose this option, the server automates are useless and the complete behaviour of the robots is determined by the client states (you won't profit by the team framework at all).

On the other hand it is possible to send many server tips that will do the whole work and to have only one client state that will act according these tips. With this way, you will waste a lot of CPU time in the client processes and have a high load in the master server process. You should attempt to balance the responsibilities between client and server states, for example do all computations based on the environment given by the Realtime Battle server in the client states and process shared information between the robots and the resulting actions on server side.

Also the number of states is a design decision. You must have at least one server and one client state (the initial state) but you can have hundreds if you want (unpractical but possible). It depends on your strategy how many states you will need.

All states will be reset (after the repositories have been reset) automatically by the framework before a new game will begin. Furthermore, the initial state (specified by the factory) will be set to be the current state, then.

Annotation: The finite state automates are described as coordinators in the framework: The client coordinator is responsible for managing the client states of one robot, the server coordinator for controlling the server states.

## Repositories

Repositories are objects that contain data and corresponding methods that are shared between different state objects. The kind of data and the methods are only determined by the concrete strategy (exception: GameOptionsRepository). Every repository will be reset automatically by the framework before a new game will begin. There are four types of repositories:

- GameOptionsRepository: At the beginning of every game, the RealTime Battle server will send the values of a dozen game specific constants defined by the rtb protocol (like max energy a robot can have, max cannon rotation speed, air resistance, graivity, ...). These messages will be automatically parsed by the framework and filled into the corresponding data members of this object. Every strategy factory has access to this repository. It is the responsibility of the factory to pass this object to the created states.
- ClientSpecificRepository: All client states of one client side automate have access to this object. The strategy can decide by itself what it wants to store here.
- InternalServerSpecificRepository: All server states of one server automate have access to this object (one object for every robot in the team). Use this repository to coordinate actions between the states of one single robot.
- SharedServerSpecificRepository: All server states of all server automates have access to this object (only one object of this kind in the whole master server). Use this repository to coordinate actions between different robots in a team and share information between robots (like position of friends / enemies, ...).

To repeat myself: The last three types of repositories have to be defined by the strategy itself. Only a reset method is required in any case. Whether you share only position information, the names of your robot, or provide a sophisticated path finding engine and a visual map constructed from the gathered information is your choice. The framework will only reset / update (game options) and delete the repositories when it is necessary in the control flow (e. g. when a new game starts).