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:
-
You can target Pentium as the minimum processor.
-
The DLL entry point functions must use the C calling convention.
-
Structure member alignment must be 8 bytes.
-
Statically link to the run-time libraries, to avoid needing to distribute
your compilers run-time DLL. (This does make the teams quite a bit larger
-- if we find that the number of teams grows large, and the number of compilers
being used is small, then perhaps it would be better to switch to dynamically
linking the run-time libraries).
-
Don't include debug information in your release versions.
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.