Starship Soccer Team Development

Overview

Teams can be developed using any language that can build Win32 DLLs that conform to the Starship Soccer interface.
The header files provided are for C and C++, but the interface is simple enough that other languages could be used.
For each ship you need to decide whether to turn left, right, thrust or fire.
You can find out any of the game constants, and you are given the location, velocity, allegiance, type, radius and heading of all game objects.
When a team is called by the engine, the team process() function is called, then the process() function of each starship is called in turn. This allows processing common to all starships can be done once in the team, and the results used by the individual starships. The team may call functions on the starships -- you do not need to implement a starship process function if your team does all the work. Conversely you do not need any code in your team processing function if your starships do all the work.
It is a flexible design that should not restrict how you structure your implementation.
 

Building a new team DLL with C++

If you're reasonably familiar with your development environment, you should be able to have a built team up and going in under 5 minutes, even if you haven't build a DLL before. Most development environments should let you set up an empty Win32 DLL project fairly easily.

The important things to know are:

Once you've got an empty DLL project, add the files listed below into the project.
 
Files required for developing Starship Soccer team DLLs with C++
Filename  Description
TeamDLL/Constant.h Lists all exposed game-world constants
TeamDLL/TeamDLL.def DLL definition file for linkers that need it.
TeamDLL/TeamDLL.h Win32 DLL interface for Starship Soccer teams
TeamDLL/TeamDLL.cpp Maps the C/DLL interface to friendly C++ classes.
TeamDLL/UserTeam.hpp
TeamDLL/UserTeam.cpp
Win32 DLL C++ wrappers. 
Defines the user team and starship base classes.

Your project should now compile into a valid Starship Soccer DLL (with 0 teams).
Even though it contains no teams, you can still get Starship Soccer to validate the DLL.
If Starship Soccer complains that it didn't load any teams, then the DLL is fine. Otherwise you will get an error message describing something about the DLL that didn't match up.
When it checks the version information, Starship Soccer also queries the DLL about the sizeof() various objects to ensure the DLL has been compiled correctly. (If you are interested in how this works, see TeamDLL/TeamDLL.cpp).

Building the Sample teams

Add SampleDLL/Sample.hpp and SampleDLL/Sample.cpp to the project, rebuild, and you should have a valid Starship Soccer DLL with teams in it!
Note that the DLL contains more than one team, and that you didn't have to add it into a table anywhere. The teams automatically register themselves when the DLL is loaded (via static constructors).
 

Building your own team

Either follow the instructions in TeamDLL/UserTeam.hpp to build your own team from scratch, or just start modifying Sample.
To write a team you need to derive a team class from uTeam, and a starship class from uStarship.
Use the SS_DEFINETEAM() macro to register the team in the DLL, and you're done.
 

Tips for beginners

1. Verify your build process. Your first step should be to verify that you can build a team and see it run. Give sample a new name and author, and knobble it somehow so that you'll know it is really your DLL controlling the ships. For example, you could make all your ships turn left and fire.

2. Build some training dummies. It can be hard to debug your teams flying code while the other team are scoring madly around you. Build a team that does nothing at all, or hides in a corner.

3. Use debug lines. The game engine allows teams to draw vectors into the game world. This enables you to plot points, draw velocity vectors, and anything else you need to figure out why your ships aren't doing what you think they should be doing!
The display of debug lines can be toggled by pressing "Insert" or "Delete" for the left and right teams respectively. They default to off, unless the -debug command line option has been specified.

4. Build good base routines. The flyToPoint() function that comes with Sample isn't awfully good. It gets the job done, but slowly -- and it certainly has no idea about flying to a moving point! There is no point worrying about team strategy until you've got a good collection of base routines. It is also a good idea to move your good routines into team/starship base classes, for re-use in future teams.

5. Keep it simple and stateless. Things change quickly in Starship Soccer - there's not much point keeping state about what's already happened. Look to the future! Keep your routines as simple and small as possible. The bigger the routine, the less likely it is going to do what you think it will.

6. Do the algebra! Shooting at moving targets, predicting collisions, other useful abilities, require a little math. Don't be scared! :-)

7. Code defensively. Starship Soccer contains exception handlers that will catch most crashes within your team. When this happens, your team will be "flatlined" by the Engine, and your team will not be called again for the remainder of the game. You can disable the exception handling with -debug. Note that this does not disable flatlines caused by the team writing to read-only memory.

8. Don't assume that objects will always exist. If you are flat-lining in your victory dance, chances are you are attempting to dereference the ball, which no longer exists. Don't forget that Starships, too, can be destroyed during Extra-Time.
 

DLL Troubleshooting

Problem: Starship Soccer is crashing when checking the DLL versions at start-up

Cause: This is probably being caused by a DLL that is not using the C calling convention for its functions.
Solution: Figure out how to specify the C calling convention for your DLL exports. Most compilers use __cdecl for this. See SSI_CALLSPEC in TeamDLL/TeamDLL.h
 

Problem: Starship Soccer is reporting the sizeof(someObject) is wrong

Cause: This is due to the packing of the structures defined in TeamDLL.h
Solution: Set structure member alignment to 8 bytes.
 

Problem: Starship Soccer is reporting the version number of the DLL is wrong

Cause: This is due to the DLL being compiled for a later version of Starship Soccer than the one you are using.
Solution: Upgrade to the latest version of Starship Soccer.