We’ve talked a bit about Spycursion and its open source model, but we haven’t really delved into how that will work from a practical standpoint. In this post I’ll talk about application programming interfaces, or API‘s, with the goal of helping you understand some of the decisions that go into designing an API for a multiplayer game like Spycursion. Please note, this information is intended for a more general audience, so many of the details have been simplified. This post is an introduction, not a reference manual!
What is an API?
An API is a set of rules and agreements, through which developers of various software components agree how those components will communicate. You can search the internet for API documents of all sorts to get a feel for what typically goes into those documents, but if you’ve never tried writing code for an API before (or writing code at all), you may get lost in the jargon.
Instead, let’s look at a simple real-world example…
Server: Hello, and welcome to Foodz R Us! Can I get you anything to drink?
You: Purple cow.
Server: Excuse me?
You: Purple cow.
Server: Err, I’m… sorry, we don’t have that on the menu. Would you like-
You: PURPLE COW!
When a server at a restaurant asks if you’d like anything to drink, they are usually expecting you to name something on the drink menu, or perhaps to ask a question. Here, though, you violated their expectations and the server’s “API” returned an “error.” (I personally have never seen “purple cow” on any drink menu, but if you do, let me know!) In computer-speak, this example could be converted to something like…
Server:
{ "request": "drink_choice" }
You:
{ "drink_choice": "purple_cow" }
Server:
{
"error": "purple_cow not found",
"drinks": [ "water", "tea", "milk", "juice", "beer" ]
}
{ "request": "drink_choice" }
You:
{ "drink_choice": "purple_cow" }
Server:
{
"error": "purple_cow not found",
"drinks": [ "water", "tea", "milk", "juice", "beer" ]
}
{ "request": "drink_choice" }
You:
{ "drink_choice": "purple_cow" }
Seasoned programmers will recognize that the messages above are in the popular JSON format. Certainly not all API’s use JSON (Spycursion’s does), but I will be using it throughout this post, for its simplicity and readability.
Movement
Just about every multiplayer video game will, at some point, involve you moving one or more characters from point A to point B on a game map. To keep things simple, let’s say our game map is a 2D grid made up of integer coordinates. (You know, the grids your high school Geometry teacher made you draw.) When you first start the game, you don’t necessarily know your character’s starting point, but the server should have that information, and so it lets your game client know:
{ "player_position": [ "x": 5, "y": -2 ] }
Now that the client and server are synced, you can move your character around the map. In a flat, boring world with no obstacles whatsoever, your client could just do something like this:
{ "move": [ "x": 3, "y": 1 ] }
But where’s the fun in that? In Spycursion, as in most other games, pathfinding may be required. Walking directly from A to B in a straight line might have you plowing through buildings or getting run over by a car! So the client, or the server, or both, will need to be able to navigate your character around obstacles. In practice, you would likely rely on the client for pathfinding, then convert that into API requests. If you as a player click the point (3,1), but there is an object in the way, the actual API requests might look like this:
{ "move": [ "x": 6, "y": -2 ] }
{ "move": [ "x": 6, "y": 1 ] }
{ "move": [ "x": 3, "y": 1 ] }
But what happens if a player hacks their client to just ignore those obstacles? What does the server do with a request that seems to defy the laws of physics? This is where collision detection comes into play, and any well-designed game server will include it. Basically, upon a player trying to run through a tree, the server sends a message to said player’s client…
{ "player_position": [ "x": 5, "y": -2 ] }
… as if to say, “Sorry, that thing is impermeable. You’re still at (5,-2).”
REST
No.
… Sorry, I should explain. REST stands for representational state transfer and is very often used in a sentence with “API.” Without getting into too many details, REST is an architectural style that is common among web API’s, and one of its more notable features is that the server does not store any client context between requests. In other words, every client request has all of the information that the server needs in order to process it. In a RESTful API, movement requests would look something like this:
{
"from": [ "x": 5, "y": -2 ],
"to": [ "x": 6, "y": -2 ]
}
{
"from": [ "x": 6, "y": -2 ],
"to": [ "x": 6, "y": 1 ]
}
{
"from": [ "x": 6, "y": 1 ],
"to": [ "x": 3, "y": 1 ]
}
A little verbose, but not terrible, right? Well, think about that little cheater with the hacked game client:
{
"from": [ "x": 5, "y": -2 ],
"to": [ "x": 3, "y": 1 ]
}
{
"from": [ "x": 6, "y": -2 ],
"to": [ "x": 4, "y": 7 ]
}
{
"from": [ "x": 666, "y": 666 ],
"to": [ "x": 666, "y": 666 ]
}
A stateless API would give the kid free reign to teleport around the game map! Naturally, this makes no sense for Spycursion, and you should treat any multiplayer game advertising a “REST API” with extreme skepticism.
Vision
I don’t believe we’ve talked about this, but here’s a new Spycursion tidbit for you — every player and NPC in the game has a vision cone. You can only see characters about 135 degrees in front of you (buildings and other stationary objects are always visible), so it matters which direction you’re facing. If you sneak up behind another player, they can’t see you without turning around. The API request to change where you’re facing is straightforward:
{ "look": 1.570795 }
You might recognize that number — yes, here are those Geometry nightmares again — as half of pi, telling the server that your character is now looking at pi/2 radians, or 180 degrees, which in this case just means “due south.” When you turn around, you might discover another player trying to sneak up on you, about which the server now sends a warning:
{
"player_id": 66666,
"player_position": [ "x": 5, "y": -3" ],
"player_looking": 0
}
In reality, you wouldn’t be sent the opposing player’s actual ID (see below), but instead a lot of information about their appearance, and perhaps an indication that you’d encountered them before. Again, we’re keeping things simple here.
Interaction
Another MMO trope: Interacting with other characters. (I know, it’s awful.) In most games, if you wanted to converse with and/or hit on another character, your client might send a request like this:
{
"action": "talk",
"player_id": 66666,
"message": "Hey, stop sneaking up on me."
}
And that’s all well and good, if your client has the player’s ID, which it probably does, as it was probably already sent by the server. Spycursion, though, is a bit different. We can’t tell you a given player’s actual ID or username, because of the possibility of disguises. (This is a spy game, after all!) If you knew that little Johnny’s player ID was 66666, and this fact was always shared by the server, then little Johnny could never truly fool you. Instead, we have to assign a temporary ID for every character who enters your vision cone. This is shared between client and server, until enough time has passed, or you leave the map, at which point you “forget what they looked like.”
If another player starts a conversation with you, your client gets a message like this:
{
"player_id": 1234,
"says": "I heard there was a new Spycursion blog post today!"
}
Other spy-like requests look similar, except of course the server doesn’t notify your client that someone has just planted a bug on you. 😉
Hacking
This post wouldn’t be complete without me talking about the API details behind what happens on your character’s computer screen. That said… there actually isn’t much to talk about! Spycursion’s in-game internet will offer many services which can essentially be divided into two types — “hackable” and “unhackable.” The “unhackable” services will have their own API specifications, while the “hackable” services will consist of in-game programs written in Slang. All of the Slang programs follow one simple API request:
{
"command": "rm",
"args": [ "-rf", "/" ],
"target": "0123:4567:89ab:cdef:0123:4567:89ab:cdef",
"session_key": "0123456789abcdef"
}
The target and session key are just for verification that you are logged into a remote host, and for allowing you to have multiple terminals running at once. That request includes every (non-client-specific) command you’ll run from the terminal, including network tools, the Slang compiler, and your programs themselves.
We haven’t fully decided which services will fall under which categories. Transparently, we would love every service to fall under the “hackable” category, but it’s just a question of feasibility and what we actually want players mucking around with.
Spycursion’s API documents aren’t yet ready for public release (and even if they were, the server isn’t ready for public release, so you wouldn’t be able to do much with them). In the meantime, hopefully this post has taught you a few things about video game API’s, and maybe even motivated you to design your own!