Strategic Primer: API design

The past few weeks I’ve gotten quite a bit done on my new attempts on the computer version of my strategy game, Strategic Primer. But part of the new direction I’m trying to take this in is to minimize the amount of coupling I introduce; I intend to eventually create servers and clients in different languages for different purposes. Because of this, I need to design a strong API for the game, and I need to think carefully about this. In this short essay I’ll describe what I’ve come up with so far.

First of all, I need different APIs for different kinds of users. I’ve identified four:

  • Administrators, who need to be able to view and edit everything in the whole map.
  • Players, who need to be able to see and, to a very limited extent, edit their part of the map and give orders to their units. Complicating this is that I want the game to support both turn-based and real-time play.
  • AI players, who should eventually need no more information than ordinary players.
  • Observers, who can see the whole map but can’t make any changes. (This class of users is not essential.)

So, first of all, I need some way of restricting a user’s access so that players can’t order each other’s units around or otherwise circumvent the rules and normal mechanics of the game.

Once that’s in place, the administrative API should be fairly easy, since a superuser has the power to change anything–I can basically just expose every property I can imagine myself wanting to change, and push cleaning up the interface onto the client libraries and applications. Similarly, the API for observers can simply be a read-only version of the administrative one. And each of these APIs might differ from server to server depending on how the game is implemented there, or what level the players are at (eventually a player will be able to take any part from a front-line soldier to commander-in-chief, but for the foreseeable future each version of the game will only need to handle one level of detail).

But in designing the API for unprivileged users I need to be much more careful. And this API needs to be much more intuitive, hiding implementation details from the user.

Here’s what I’ve thought of:

  • The player needs to be able to see what he or she knows about the map. This should not include things the player doesn’t know about certain areas that have been explored, and could include information that has since changed.
  • The player needs to know enough to make reasonable decisions. In particular, once I add (roughly standard RPG) statistics to units, the player needs to know the relative strengths and weaknesses of each unit approximately, but not exactly.
  • The player needs to be able to give orders to units. But this is the place where I need the most thought: what orders? Movement, attacking, amd so forth might be obvious, but there are less obvious orders. Units will be able to do “actions” to interact with terrain objects, other units, buildings, etc. Should multiple actions be possible in any given situation? Saying “yes” would vastly simplify the API and the game, but that limitation doesn’t seem reasonable, especially given the multiple-level design goal. And, again, what actions should the game support? Should this be a single enumerated type, or should each unit expose the actions it supports through the API?
  • The player needs to be able to tell what’s been going on, at the very least including the results of his or her recent actions, without getting the state of the world and manually finding the differences.

But for now, I’m just muddling through. Comments?


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s