Home | Story | Manual | Documents | Media | Blog | Download | Source Code
Mastrix Functional Specifications Document
March 13, 2005
Messaging Protocol
The client and server halves communicate through messages (datagrams) which
are either wrapped in TCP or just passed around locally. Each message has a
type, body, source and destination. The type determines the format of the body,
and the semantics. The destination identifies an instance of Client - that is,
both the destination host and, where split-screen is used, the specific screen.
Message types are enumerated and documented in protocol.hpp, and are as follows:
Generate a player, also known as "spawning."
Assign a name to a player.
Runs a tokenized command.
A new entity has appeared or entered view.
An entity has moved since the last update.
An entity has been destroyed or deleted.
Centers the camera on a point.
Places some text on the screen.
Plays a sound at a location.
Sends information about which engines are on or off.
Displays an explosion at this position.
Tells how much health and etc. you have.
Turns a color to represent the state of a bot.
Returns a bot to its normal color.
This client has disconnected.
The client communicates to the server by sending console commands
(message_command) to be interpretted by ServerScripting. The server sends
different message types to add and update things that should be displayed;
eg, for an object on the screen, message_add, message_update, message_drop.
Scripting
The scripting system is modelled after that used in the Quake series and
Half-Life (and, since the Quake engines are the basis for other games, many
others). It is generally familiar among modders and power user gamers.
The console is used in two ways: cvars and commands. A cvar (console variable)
is simply a global variable which has been made accessible through scripting.
For example,
ServerConsoleVar<float> turnSpeed("turn_speed", 3);
declares the variable turnSpeed (which is a float) so that it can be referred to
through the console as turn_speed, with default value 3. The user can type
turn_speed 5
and change the value of turnSpeed to 5. If he types just
turn_speed
then the output will be "turn_speed is 5 (default 3)".
The console variables are:
sound_range (changes the distance of sounds that can be heard by the client)
zoom (changes the level of zoom)
name (changes the name of the client)
fullscreen (turn full screen on/off)
track_mouse (turn mouse tracking on/off)
show_position (displays position on screen)
showfps (displays the framerate on screen)
split_vertically (split multiplayer
view_advantage (can give a third player extra screen space or just leave a blank
square)
cheapconsole (changes the console to a very graphically reduced appearance)
console_speed (changes the speed of the console open/close)
console_height (changes the size of the console)
show_keys (shows the keys currently assigned)
particle_fade (changes the speed of fadeout of particles)
enable_stars (turn the star field background on or off)
border_left (can change the value of the left edge)
border_right (can change the value of the right edge)
border_top (can change the value of the top edge)
border_bottom (can change the value of the bottom edge)
turn_speed (can change the speed at which the ships turn)
shot_delay (can change the delay between shots)
repulse (can change the reaction force experienced by the ships when shooting)
b_radius (can change the collision radius of the ships)
shotdist (can change how far the shots go before they die)
allow_strafe (can turn strafing on or off)
allow_mouse_aim (can turn mouse aiming on or off)
shots_get_ship_vel (can change whether the shots leave the ship with the ship's
velocity)
thrust_strength (can change the thrusting/acceleration of the ships)
brake_strength (can change the reverse thrusting/braking of the ships)
strafe_strength (can change the strafe thrusting of the ships)
respawn_delay (can change the time clients wait to spawn after dying)
elasticity (can change the elasticity of collisions)
shotspeed (can change the base speed of shots fired)
grav (can change the gravity experienced from planets)
show_dts (displays the amount of time (time delta) since the last frame)
frameskip (change the value n of: draw every 1 of n frames)
The console commands are:
echo (prints text to console)
say (client sends text to all players)
exit, quit (quits the game)
toggle_fullscreen (turns fullscreen mode on or off)
player (refers to this player, used as "player # command")
toggleconsole (binds to a key, used to open or close console)
bind (command used with key and command to assign a key to a command)
unbind (command used with key to remove assignment of key to command)
unbindall (command used to remove assignments of all keys)
showvel (shows the velocity of the ships)
mousepos (shows the position of the mouse)
left (turns left, inverse stops turning)
right (turns right, inverse stops turning)
strafe_left (strafes left, inverse stops strafing)
strafe_right (strafes right, inverse stops strafing)
thrust (thrusts/accelerates, inverse stops thrusting)
brake (brakes/deccelerates, inverse stops braking)
shooting (fires, inverse stops firing)
setpos (sets the position of the player)
addent (adds a non playable entity like a planet)
addbot (adds a computer controlled player)
addspawn (adds a new revive location at a position)
kill (commits suicide)
addclient (adds a client (human player) with its own screen (goes into
split-screen mode))
net_stats (shows statistics on bandwidth usage)
server_stats (shows statistics on bandwidth from the server's perspective)
let (defines a variable)
sv_let (does let on the server instead of the client)
exec (runs all of the commands in a file)
sv_exec (does exec on the server instead of the client)
The implementation uses a C++ template to fill in the type of variable. The code
for registering the variable with the scripting system is in the constructor,
and casting operators are provided to allow using a ConsoleVar in the same way
and at the same speed as the type of the variable itself.
Console commands take arguments, separated by spaces. For example,
bind up +thrust
executes the command "bind" with arguments "up" and "+thrust". (This command
assigns the up arrow to thrusting.) Commands are added either with
CLIENT_CONSOLE_COMMAND(command_name)
{ /* Command body */ }
for commands that execute on the client, or
SERVER_CONSOLE_COMMAND(command_name)
{ /* Command body */ }
for commands that execute on the client. The macro handles registration of the
command with the scripting system, and provides arguments argc (argument count),
argv (argument vector), and who (ID of the player that ran the command).
Class Overview
Server: Represents the machine that hosts connected clients. Processes all
games logic. Starts the game, checks for and handles collisions, updates
entities, plays sounds, etc.
SVEntity: Abstract base for server-side game objects. Stores data necessary for
processing the object's state.
mass, radius, position
Player :public SVEntity
Abstract base class for ships. Contains controls for steering the ship: thrust,
shoot, turnleft, etc.
HumanPlayer :public Player
Represents a human controlled ship. Has a clientID bound to the controlling
player's machine.
AIPlayer :public Player
An AI controlled ship (bot) has methods to determine behavior towards
environment. chase, evade, findBestTarget, etc.
EnvironmentEntity :SVENtity
An environmental obstacle, eg asteroids and planets. Has a gravitational force
that attracts ships.
Client: Represents a machine connected to a server. Processes interface and
audio/visual effects. Sends and receives message to and from server.
ImagePool: Container for images that need to be drawn.
SoundPool: Container for sound effects that need to be played.
CLEntity: Represents the client's view of a game object. Handles drawing and
motion prediciton.
UI: User interface elements such as health bar, radar, etc.
Console: Scroll-down screen with prompt and history for entering commands to
be run by ClientScripting.
ParticlePool: Controls particle generation and display for special effects
(such as explosions). Contains various explosion methods corresponding to the
explosion type.
Particle: An individual particle contained in a particle pool.
Keyboard: Accepts keypresses and translates them through bindings for execution
through ClientScripting.
Game Design Initiative at Cornell | CIS 300: Introduction to Computer Game Design