A Tandem Tales agent connects to the server via a TLS encrypted socket (on port 9005, by default) and plays a single interactive story session. All messages to and from the server are formatted as JSON and terminated by a new line character.

  • Starting a Session:
    • As soon as a new socket is established, the server sends the Connect message that lists the available worlds and partners.
    • When the agent is ready to play, it sends the Join message with the details of who it is and the settings for the game it wants to play.
    • Once the server has found a compatible partner, it starts a new session and sends the Start message to both agents, which tells them their roles, about the story world, and the world’s initial state.
  • During a Session:
    • The game master goes first.
    • On the game master’s turn, the game master can SUCCEED or FAIL any number of actions that do not require the player’s consent. The game master can PASS control to the player. The game master can PROPOSE an action if it requires the consent of the player and a non-player character, and then play immediately passes to the player.
    • The player always chooses one action and then passes control back to the game master. If the game master’s last action was to PROPOSE an action, the player must choose whether it will SUCCEED or FAIL. If the game master’s last action was to PASS, the player can PROPOSE any action that requires the player’s consent or PASS control back to the game master without choosing an action.
    • Each time a turn happens, the server sends an Update message to both agents, which has the history of turns taken so far, the current state, and the choices that agent can make. An agent knows it is their turn if their Update message has choices listed.
    • When it is an agent’s turn, they make a choice by sending a Choice message to the server with the index of a choice from their last Update.
    • At any time during the session, an agent can send a Report message to the server to record their answer to a question.
  • Ending a Session:
    • If the story reaches one of its pre-defined endings, the Update message sent to both agents will include an Ending object.
    • Either agent may end the session early by sending a Stop message. Once an agent sends a Stop message, it should not send any more messages to the server, but it may stay connected to wait for the End message.
    • If an agent disconnects from the server, it is treated as if it had sent a Stop message.
    • The server sends a Stop message to the agents when it is time for a session to end. This happens when the story reaches a pre-defined ending, when one agent stops the session early, or when the server is shutting down and needs to end all sessions early.
    • When an agent receives a Stop message (but has not yet sent one), it cannot send any more Choice messages, but it can still send Report messages to answer questions. Once an agent sends its Stop message, it cannot send any more messages to the server, but it may stay connected to wait for the End message.
    • Once the server has sent a Stop message to both agents, and once both agents have sent a Stop message to the server (or effectively sent one by disconnecting), the server sends the End message to both agents to tell them the session ID number and let them know it is time to disconnect.

If an agent does something that is not allowed, the server may send an Error message explaining the problem. Depending on the error, it may also disconnect the agent.


Messages

Messages are encoded in JSON. All messages include the key type which defines the type of message as a string that starts with a capital letter. Messages are always a single JSON object followed by a new line character. If a message contains a new line character, it should be encoded.

Connect Message

{
    "type": "Connect",
    "version": "1.0.0",
    "worlds": [
        {
            "name": "tutorial",
            "title": "Tutorial",
            "description": "A simple story about buying a drink that will teach you how to play."
        }
    ],
    "agents": [
        {
            "name": "random",
            "title": "Random",
            "description": "An agent that makes random choices."
        }
    ],
    "available": [
        {
            "agent": "random",
            "world": "tutorial"
        }
    ]
}

The Connect message is sent from the server to the client as soon as a new socket is opened.

  • version gives the server’s version number as a string.
  • worlds is an array of objects describing which worlds the server has publicly listed as available. Each has a name, title, and description.
  • agents is an array of objects describing which agent types the server has publicly listed as available. Each has a name, title, and description.
  • available is an array of objects listing agents who are currently connected and looking for partners to play in specific worlds. Each has an agent and world.

Join Message

{
    "type": "Join",
    "name": "web",
    "password": "dummy",
    "world": "tutorial",
    "role": "PLAYER",
    "partner": "random"
}

The Join message is sent from the client to the server when the client is ready to start its session.

  • name gives the client’s agent type. It does not need to be unique.
  • password gives the client’s password. A password is only required if the client’s name is reserved on the server.
  • world is the name of the story world the client wants to play in. If this is missing or null, the client is willing to play in any world.
  • role is the role the client wants to have in the story. It can be PLAYER or GAME_MASTER. If this is missing or null, the client is willing to play as either role.
  • partner is the agent type the client wants to play with. If this is missing or null, the client is willing to play with any partner.

Start Message

{
    "type": "Start",
    "role": "GAME_MASTER",
    "world": # World object #
}

The Start message is sent from the server to the client once the server has found a compatible pair of agents and started a new session.

  • role is the client’s role in the story. It will be either PLAYER or GAME_MASTER.
  • world is a World object.

Update Message

{
    "type": "Update",
    "status": # Status object #
}

An Update message is sent from the server to the client each time the state of the world changes.

Choice Message

{
    "type": "Choice",
    "index": 3
}

A Choice message is sent from the client to the server when it is the client’s turn to notify the server which turn the agent wants to take.

  • index is the array index (starting at 0) of a choice from the most recent Update message sent to the agent.

Report Message

{
    "type": "Report",
    "item": "structure",
    "value": "4",
    "comment": "strongly agree"
}

A Report message is sent from the client to the server any time after the server sends the Start message and before the client sends their Stop message. It is used by the client to answer questions about the story or play experience.

  • item is the name of the question the client is answering.
  • value is the client’s answer to the question as a string.
  • comment is a comment on the value as a string.

Stop Message

{
    "type": "Stop",
    "role": "PLAYER",
    "message": "End the session early."
}
{
    "type": "Stop",
    "message": "The story has ended.",
    "ending": # Ending object
}

A Stop message can be sent by either the server or client. It can only be sent by either party after the server has sent the Start message. The client can end the session early by sending this message. The server sends this message if the story reaches one of its pre-defined endings, if the client’s partner ended the session early or disconnected, or if the server needs to end the session early (i.e. because it is shutting down).

  • role identifies which client ended the session early. This should be missing or null if the story reached a pre-defined ending or if the server is ending the session early.
  • message is an explanation for why the session is ending.
  • ending is an Ending object. This should be set if the message is coming from the server and the story reached a pre-defined ending; otherwise, it should be missing or null.

End Message

{
    "type": "End",
    "session": "MWD7D5R590"
}

The End message is sent by the server to the client once the session is complete and the client can disconnect.

  • session is a unique ID string that identifies the session in the server logs.

Error Message

{
    "type": "Error",
    "message": "The message could not be parsed as a JSON object."
}

An Error message is sent from the server to the client if it cannot parse the client’s message or if the message has invalid values (i.e. if the client sends a Choice message at the wrong time or with an invalid index).

  • message is a string that explains the problem.

Objects

Objects are encoded in JSON. If an object is being sent as part of a Message and contains a new line character, the new line character should be encoded to avoid terminating the message prematurely.

Action Object

{
    "id": 0,
    "name": "go(Player, Shop)",
    "signature": # Signature object #,
    "consenting": [ # Entity objects # ],
    "description": "The player enters the shop.",
    "code": "0001"
}

An Action object defines:

  • An id number. All actions in a story world are numbered sequentially starting at 0.
  • A name, which is the symbol used to refer to that action.
  • A signature, which is a Signature object.
  • An array of consenting characters, which is an array of Entities that represent the characters in the story who are taking the action. Characters only appear in this array if they are taking the action on purpose. An attack action would not list the victim in this array, since the victim is not taking the action on purpose.
  • A description as a short natural language phrase.
  • A code string, which is always composed of 0s and 1s and uniquely identifies the action from other actions in the story world.

Assignment Object

{
    "variable": # Variable object #,
    "value": # Value object #,
    "visible": true,
    "description": "The player is outside the shop.",
    "code": "011"
}

An Assignment object defines:

  • A variable from the story world.
  • The value assigned to that variable, which is a Value object.
  • Whether this assignment is currently visible to the client, as a Boolean. All values are always visible to the game master, because the game master always has accurate knowledge of the current state of the story world. If the player cannot currently observe this assignment’s variable, then the value will be its last known value, which may not be its actual value.
  • A description as a short natural language sentence.
  • A code string, which is always composed of 0s and 1s and uniquely identifies the value assigned to the variable.

Constant Object

{
    "type": "Constant",
    "value": true
}

A Constant object defines:

  • A value, which represents a fixed value for this constant. Values include null, the Boolean values true and false and numbers. This key is missing or null if the constant represents null.

Ending Object

{
    "id": 3,
    "name": "bought(Coffee)",   
    "signature": # Signature object #,
    "description": "The player purchased a coffee.",
    "code": "100"
}

An Ending object defines:

  • An id number. All endings in a story world are numbered sequentially starting at 0.
  • A name, which is the symbol used to refer to that ending.
  • A signature, which is a Signature object.
  • A description as a short natural language phrase.
  • A code string, which is always composed of 0s and 1s and uniquely identifies the ending from other endings in the story world.

Entity Object

{
    "type": "Entity",
    "id": 1,
    "name": "Barista",
    "description": "the barista",
    "code": "010"
}

An Entity object defines:

  • An id number. All entities in a story world are numbered sequentially starting at 0.
  • A name, which is the symbol used to refer to that entity.
  • A description as a short natural language phrase.
  • A code string, which is always composed of 0s and 1s and uniquely identifies the entity from other values in the story world.

Signature Object

{
    "name": "at",
    "arguments": [ # Value objects # ]
}

A signature is a structure that defines a unique, parameterized object in a story world. Variables, Actions, and Endings have signatures. It defines:

  • A name, which is a relationship that applies to the signature’s arguments.
  • An array of arguments, which are Value objects.

State Object

{
    "assignments": [ # Assignment objects # ],
    "description": "You are standing outside your favorite corner store. ...",
    "code": "011100001000000"
}

A State object defines:

  • An array of Assignment objects that give a value for each of the variables in a story world.
  • A natural language description of the current state or what has changed since the previous state.
  • A code string, which is always composed of 0s and 1s and uniquely identifies the state from other possible states the story could be in.

Status Object

{
    "role": "GAME_MASTER",
    "history": [ # Turn objects # ],
    "state": # State object #,
		"ending": # Ending object #,
    "descriptions": [ # Entity objects # ],
    "choices": [ # Turn objects # ]
}

A Status object defines:

  • The role the client this object was sent to is playing in the story world.
  • The history of Turns taken so far in the story.
  • The current state of the story world.
  • The ending of the story, if one has been reached. This will be missing or null if the story has not yet ended.
  • The descriptions of objects currently visible to the client. Descriptions are sent as Entity objects so they can be matched by their names and ID numbers, but the description key will be a longer, more detailed description than the short phrase usually given to an entity.
  • The choices currently available to the client, as an array of Turn objects. This array will be missing, null, or empty if it is not currently the client’s turn.

Turn Object

{
    "role": "PLAYER",
    "type": "PROPOSE",
    "action": # Action object #,
    "description": "The player offers some money to the barista.",
    "code": "1000111"
}

A Turn object defines:

  • The role who took (or will take) this turn.
  • The type of action, which is either SUCCEED, FAIL, PROPOSE or PASS.
  • The action that happens as part of this turn. This will be missing or null if the type is PASS.
  • A description as a short natural language sentence.
  • A code string, which is always composed of 0s and 1s and uniquely identifies the turn from other possible turns.

There are four turn types:

  • SUCCEED means the action occurs and is narrated.
  • FAIL means the action does not occur, but an attempt at the action is narrated.
  • PROPOSE means the action requires the other client to agree to it. The other client will need to choose SUCCEED or FAIL.
  • PASS means no action occurs and the client gives control of the story to its partner.

Value Objects

The following are considered Value objects:

Variable Object

{
    "type": "Variable",
    "id": 0,
    "name": "at(Player)",
    "signature": # Signature object #,
    "encoding": "entity3",
    "description": "the player's location"
}

A Variable object defines:

  • An id number. All variables in a story world are numbered sequentially starting at 0.
  • A name, which is the symbol used to refer to that variable.
  • A signature, which is a Signature object.
  • An encoding, which defines the type of values that variable can have.
  • A description as a short natural language phrase.

World Object

{
    "name": "tutorial",
		"title": "Tutorial",
		"description": "A simple story about buying a drink that will teach you how to play.",
    "entities": [ # Entity objects # ],
    "variables": [ # Variable objects # ],
    "actions": [ # Action objects # ],
    "endings": [ # Ending objects # ]
}

A story World object defines:

  • The name, title, and description of the story world as strings.
  • An array of Entity objects defining the objects that exist in the story world.
  • An array of Variable objects defining the variables that make up the story world’s state.
  • An array of Action objects defining the actions which can change the story world’s state.
  • An array of Ending objects defining the possible endings that a story in this world can reach.