UserTeam.hpp -- Win32 DLL C++ wrappers

Copyright ©1997-1999 Simon P. Bullen.

Macro: SS_DEFINETEAM()

Overview:

A Starship Soccer Team DLL can contain many teams. The SS_DEFINETEAM() macro registers a team with the DLL interface. A team will only be registered with the DLL interface if the DLL is linked with the object file containing the compiled macro expansion.

Usage:

 SS_DEFINETEAM( internalName, teamClassName, starshipClassName,
                teamName, teamAuthor ) This macro MUST be used in global .CPP scope. Team and starship classes may be re-used in multiple team definitions in a single file IF the internal name for each is unique.

Example:

#include "UserTeam.hpp"
#include "Sample.hpp"
SS_DEFINETEAM( S1, SampleTeam, SampleStarship, "Sample",  "Simon Bullen" )
SS_DEFINETEAM( S2, SampleTeam, SampleStarship, "Sample2", "Simon Bullen" )

Warning:

Do NOT expect teams to link properly if placed in a library. The DLL interface code contains no references to the teams, and thus the linker will NOT pull them in, and your DLL will not contain any teams. You must explicitly link the DLL interface object files with the object files that contain the SS_DEFINETEAM() macros.

Implementation:

You don't need to know how this works to use it, but you might if something goes wrong!
The registration of teams with the DLL interface has been achieved by an "automagic list".

The SS_DEFINETEAM() macro does 3 things:

  1. It declares a function to create an instance of the named team class
  2. And a function to create an instance of the named starship class
  3. Then it declares a static uTeamDefinition class, initializing it with pointers to the creation functions and the text strings.
The uTeamDefinition constructor, when executed, makes itself the head of a linked list, and makes the previous head it's next. Regardless of the order of execution of these constructors, the uTeamDefinitions will assemble themselves into a complete list. The creation of the linked list occurs when the start-up code runs the constructors for objects declared in global or file scope.
So long as the linker decides to pull in an object file, it's constructors will be included in the start-up code.
(And their destructors in the shutdown code).
This is why the only thing necessary to register a team is to link with it.

enum uObjectType

Each object has a type exposed to allow discrimination between objects.
Unlisted values are reserved for future use.
enum uObjectType
{
 ot_starship,
 ot_ball,
 ot_goal,
 ot_bullet
};

class uObject

A uObject is a game world object in the "sensor array".
It is used to represent the state of all game objects the starships can see.
The game engine uses an array of these each frame to pass a view of the game state the teams.
Note: The game engine may use a different array each frame to pass the object information -- you cannot rely on the pointers to uObjects remaining the same across frames.

Constructors

uObject()

Default constructor
 

 uObject( double newX, double newY, double newVX=0, double newVY=0, double newMass=0 )

Constructor with optional initializers
 

Attributes

Object Attribute Description
id The unique ID of the object. Every object created gets a unique ID that you can use to track the same object across calls. 
Do not rely on the pointer to the object array being the same across calls.
type The type of the object. How else could you tell them apart?
teamID The unique ID of the team the object is on.
The team number of the ball is undefined. 
x,  y The location of the object, in metres. 
Positive x is to the right, positive y is up.
vx, vy The velocity of the object, in metres/second
heading  The direction the object is pointing, in radians. 0 radians is the positive x axis (to the right), PI/2 radians is the positive y axis (up). 
Note that the heading of the object is not the direction the object is moving!
radius The radius of the object's bounding circle in metres
mass The mass of the object, in kilograms

 

class uTeam

This is the class to derive from when writing a team class.
The process() function must be provided, even if it does nothing.

Construction

uTeam::uTeam( const uTeamDefinition *teamDefinition );

Constructor.
The derived class must provide a constructor with an identical prototype.
The initializer must pass the teamDefinition through to the base class.
These classes are instantiated by the DLL interface, *not* the user!
(i.e. you will never be calling these constructors -- the engine will)

Deriver Supplied Functions

virtual void uTeam::process() = 0;

Do one time-slice's worth of processing for this team
The process() function of each starship will be called after this function returns.

Universe Constant Access

double uTeam::constant( int index ) const;

All of the universal constants are available through this function, using index values from constant.hpp. These constants do not vary during a game, but some may be user configured between runs.

Game State Access

int  uTeam::goalsScored() const;

The number of goals scored by this team

int  uTeam::goalsScoredAgainst() const;

The number of goals scored against this team

bool uTeam::normalPlay() const;

true if the game is in normal play.
(Not extra-time or victory dance).

bool uTeam::deadBall() const;

True if the ball is a dead ball. (just scored, smaller, and fast )

bool uTeam::doublePointBall() const;

True if the ball will score with double points (double hex)

bool uTeam::extraTime() const;

Extra-time is true if the game has gone into extra time.
In extra-time, explosions destroy ships. Destroying ships scores goals. The game is over when one team is without ships.

bool uTeam::victoryDance() const;

After the game is over, the survivors have an opportunity to do a victory dance.
If victoryDance() is true, then it's that time :-).

bool uTeam::debugLinesEnabled() const;

True if calls to debugLine() will actually draw.

double uTeam::gameTimeRemaining() const;

How long until the current game period finishes, in seconds.
This is relative to the mode of play, i.e. normalPlay, extraTime and victoryDance each have their own countdown.

Starship Access

uStarship *uTeam::starship( int n );

Access to this team's starships.
Note that a starship may have a NULL pointer if it has been destroyed during extra time. Try not to crash! :-)

int uTeam::starships() const;

Access to the number of starships

Object Access

int uTeam::objects() const;

Returns the number of objects in the universe

const uObject *uTeam::object( int n ) const;

Returns a pointer to the given (read-only) object

Accessors

int uTeam::teamID() const;

Access to the ID of this team

const uTeamDefinition *uTeam::teamDefinition() const;

Access to this team's name, author, etc.

Debug Lines

void debugLine( double x1, double y1, double x2, double y2, int colour );

Draw a debug line to the screen.

uStarshipAction

This is used to express the state of the controls of the ship.
The values may be combined. e.g. (sa_turnLeft | sa_fire)

uStarshipAction Values: sa_none, sa_turnLeft, sa_turnRight, sa_fire, sa_thrust.

uStarship - User starship base class

This is the class to derive from when writing a starship class.
The process() function must be provided, even if it does nothing.
Note that uStarship inherits the properties of uObject, which gives easy access to your starship's position, etc.
Warning: this will mean you can't use x, y, vx, vy, as variable names if you want to access the member functions at the same time!

Construction

uStarship::uStarship( uTeam *team );

Constructor
The derived class must provide a constructor with an identical prototype.
The initializer must pass the team through to the base class.
These classes are instantiated by the DLL interface, *not* the user!
(i.e. you will never be calling these constructors -- the engine will)

Team Access

uTeam *uStarship::team() const;

Access to this starships team.
It is worthwhile to override this function with one that returns your team class pointer, instead of just the base one.
e.g.
    myTeam *myStarhip::team() const { return (myTeam*)uTeam::team(); }

This allows you to call functions you've added to your team from your starships more easily.

Deriver Supplied Functions

virtual void uStarship::process() = 0;

Do one time-slice's worth of processing for this starship
The process() function of each starship is called after the team process() function is called once.

Starship Controls

void turnLeft(); void turnRight(); void thrust(); void fire();

Request an action to be taken for this time-slice.
Note that these requests can be cancelled by calling the function with a parameter of false.
e.g.
    fire( false ) // cancel any fire() call

uStarshipAction action() const;

Find out the current action.
Mask with a specific action if you want to find out what you've asked for.
e.g.
    bool pressedFire = ( (action() & sa_fire) == sa_fire );

void action( uStarshipAction newAction );

Specify the starship's next action. This is equivalent to calling turnLeft(), etc. except that you can specify the entire action in one go. This overrides any previous actions requested this time-slice.

void reset();

Cancel any actions requested so far this frame.
Same as calling action( sa_none )

Gun Information

bool uStarship::canFire() const;

True if the ship is capable of firing right now

double uStarship::gunReloadTime() const;

How long, in seconds, before the gun will have reloaded.

double uStarship::gunTemperature() const;

The current temperature of the gun, in degrees.
The gun must cool below its maximum firing temperature before the above gunReloadTime will be relevant

double uStarship::timeToFireGun() const;

How long before the gun can fire, in seconds.
This function takes into account the reload time, temperature and gun constants

double uStarship::timeToCoolGun() const;

How long before the gun is completely cool, in seconds

Object Access

int uStarship::objects() const;

Returns the number of objects in the universe

const uObject *uStarship::object( int n ) const;

Returns a pointer to the given (read-only) object

Universe Constant Access

double uStarship::constant( int index ) const;

All of the universal constants are available through this function, using index values from constant.hpp. These constants do not vary during a game, but some may be user configured between runs.

Game State Access

int  uStarship::goalsScored() const;

The number of goals scored by this team.

int  uStarship::goalsScoredAgainst() const;

The number of goals scored against this team.

bool uStarship::normalPlay() const;

True if the game is in normal play.  (Not extra-time or victory dance).

bool uStarship::deadBall() const;

True if the ball is a dead ball. (just scored, smaller, and fast )

bool uStarship::doublePointBall() const;

True if the ball will score with double points (double hex)

bool uStarship::extraTime() const;

Extra-time is true if the game has gone into extra time.
In extra-time, explosions destroy ships. Destroying ships
scores goals. The game is over when one team is without ships.

bool uStarship::victoryDance() const;

After the game is over, the survivors have an opportunity to do a victory dance.
If victoryDance() is true, then it's that time :-).

bool uStarship::debugLinesEnabled() const;

True if calls to debugLine() will actually draw.

double uStarship::gameTimeRemaining() const;

How long until the current game period finishes, in seconds.
This is relative to the mode of play, i.e. normalPlay, extraTime and victoryDance each have their own countdown.

Debug Lines

void uStarship::debugLine( double x1, double y1, double x2, double y2, int colour ) const;

Draw a debug line to the screen.