RFC 2 -- API based on JSON

[mein1156]

Within the server (backend) team, I think there is a consensus to use JSON (see http://www.json.org/ or RFC4627 for format). JSON is used like a python dictionary with loading and dumping to create the JSON object through the JSON module.

An API needs to at least be capable of exchanging requests for information, requests for changing the current state, and conveying encoded information (e.g. on character abilities and result of mission and actions).

Basically, the API will need to manage: Information Exchange Movement Combat Placement Choice of Actions (e.g. Missions) Encoded abilities Responses to the above Interrupts In game decisions

Overview An idea on the API so the Client and AI teams can get more done. Also, an SRS would be required for API stuff so the sooner we have something the better. This API is very incomplete. This is my idea only just to get something going. Very incomplete.

Sorry for the Bison like grammar. I didn’t know a better way.

Common to all JSON requests:

CONNECTION: “id:”:GAME_ID, “request”:REQUEST_ID GAME_ID: INTEGER (any game id or 0 if asking to join a game) REQUEST_ID: INTEGER (any unique number per player to identify responses)

Syntax [ CLIENT REQUESTS ] For things that the client initiates REQUESTS: REQUEST -- only one request per JSON allowed! Also must wait for response before next one REQUEST: {“request”: {“type”: OPTIONS }, CONNECTION } OPTIONS: CONNECT | INFORMATION | MOVEMENT | COMBAT | MISSION | PHASE | QUIT (CONNECT, PHASE, And QUIT might be combined into one option such as GAME)

Assuming no username and password required. CONNECT: “connect”, “options”: {“type”: CONNECT_OPTIONS} CONNECT_OPTIONS: “join” OPTIONAL_JOIN_OPTIONS ] | “start” OPTIONAL_START_OPTIONS ] | “find” OPTIONAL_JOIN_OPTIONS: , “id”:ID SIDE ID: INTEGER (a valid game id) OPTIONAL_START_OPTIONS: “side”:SIDE | SIDE: “imperial” | “rebel”

There can be a lot more options, e.g. for characters, list of things that have occurred since the last update? Depends on what everyone needs. INFORMATION: “information”, “options”: {“type”: TYPE } TYPE: MAP | UNITS | POINTS | PHASE | IDS MAP: “map” UNITS: “units” -- units in play tailored to the player POINTS: “points” PHASE: “phase” IDS: “ids” – the ids of everything, abstract (See RFC 1) and locations. Usually the first thing a client does when joining the game? (Includes all the mission cards, actions cards, locations)

UNIT LOCATION might be also be a value pair [ UNIT, LOCATION]. Note: LOCATION_ID should be a location directly assessable in one jump. The response will acknowledge the jump and tell of any result (interception, lost in space, etc.) MOVEMENT: “movement”, “options”: { UNIT LOCATION MOVEMENT_OPTION } UNIT: “unit”: UNIT_ID UNIT_ID: INTEGER LOCATION: “location”: LOCATION_ID LOCATION_ID: INTEGER MOVEMENT_OPTION: “type”: BOARD | DISEMBARK | TO BOARD: “board” DISEMBARK: “disembark” TO: “to”

Combat COMBAT: “combat”, “options”: { “units”:[UNITS], LOCATION } -- location and units will determine type of combat, e.g. space, character UNITS: UNIT | UNITS -- see above

Missions MISSIONS: “mission”, “options”: { [UNITS], LOCATION, MISSION } MISSION: INTEGER (valid mission id, i.e. 53-67 )

PHASE: “phase”, “options”: “end”

QUIT: “quit”, “options”: “quit”

Additional requests: Search, Collect Taxes, Commit Atrocities, Imperial Assignments, Assign Secret Base

Example: [ “request”: {“type”:”combat”, “options”: {“units”:[13245, 14124, 45324], “location”:511}}]

[ SERVER RESPONSE ] RESPONSE: REQUEST -- only one request per JSON allowed! Also must wait for response before next one REQUEST: {“request”: {“type”: RESPONSE }, CONNECTION } REPONSE: REQUESTED RESULT REQUESTED: “unknown” | “connect” | “information” | “movement” | “combat” | “mission” | “phase” | “quit”

RESULT: ERROR | SUCCESS ERROR: “id”: ID, “problem“: PROBLEM, text”:TEXT TEXT: STRING (any alphanumeric string [A-Za-z0-9 ]) SUCCESS: “success” -- follow up packet for requests PROBLEM: list of any problem options that are causing the error

Possible Errors: For bad packets “unknown” 1 – Invalid request type

For all: “invalid format” “invalid options”

For connect: 3 - “Invalid Game ID” 4 - “Game is not available”

For movement: 1 – “Invalid unit selected” 2 – “No direct connection to location”

For combat: 1 – “invalid unit selected” ...

The information response will require more details. Probably a list of results from the database as outline in RFC 1.

These section will be more complex. Basically we will have to deal with interception, mission details such as bonus selection.

[ SERVER REQUEST ] Asks if the player want to use the PB if the opportunity arises? (Detection will be automatic?) Player wants to Break-off? Bonus Option? (since this occurs during the mission phase depending on the circumstance). Flee?

[ CLIENT REPONSE ] How to reply the server request above.

Also, there are interrupting events [EVENT] Here for galactic events Something like { “event”: { “type”:”galactic”, “id”:id of card }

Finally, many of the cards have special abilities that will need to be processed somehow. The question is how they are selection if they are optional. For items, this could be part of a request. Sometimes in the middle of combat an item can be used. These might be good questions to ask and plan for instead of trying to integrate them later.

[ CLIENT INTERRUPTS ] Something like { “interrupt” : { “type”:”item”, “id”:id of ability (Possession_Abilities.ID) }

[CARD] TBD

[hallister]

@mein1156 I'm going to take a closer look, but I believe SnakeMQ serializes python data types automatically, so we shouldn't need to serialize it (via JSON, Pickle, etc).

[mein1156]

Then we can exchange JSON with python dictionary. That as far as know won`t change my syntax.

---

From: Justin Hall [notifications@github.com] Sent: Tuesday, October 15, 2013 11:42 AM To: ui-cs383/Freedom-Galaxy Cc: Meine, Robert Subject: Re: [Freedom-Galaxy] RFC 2 -- API based on JSON (#26)

@mein1156https://github.com/mein1156 I'm going to take a closer look, but I believe SnakeMQ serializes python data types automatically, so we shouldn't need to serialize it (via JSON, Pickle, etc).

— Reply to this email directly or view it on GitHubhttps://github.com/ui-cs383/Freedom-Galaxy/issues/26#issuecomment-26360984.

[mein1156]

I originally had in mind to get ideas from the client and AI team since we talked about having an API to talk between the server and everyone else. So, this is primarily for their benefit.

I talked with Jordon after class about what the AI needs.

I imagine a conversation like this (assuming JSON and the above syntax)

[ {“request”: {“type”: “information”, “options”: {“type”: “units” } }, “id”:1, “request”:234534 } ]

The reply I wasn't sure on the syntax. My description above wasn't at all clear on this point I think. (Also have an error where the response packet should be "response" not "request"). I originally had a thought were the request would generate a response of success or error, but I think the success should also contain the information if requested. UNITS option would return a list of all non-location objects in the game everywhere. The player can then pick the ones that are important.

Response:

[ {“response”: {“type”: “information”, result="success", information=[[ UNIT_ID, STATUS, DAMAGE , LOCATION_ID], [UNIT_ID, ...]] }, “id”:1, “request”:234534 } ]

Most of the others, a simple success message would be fine.

The information would be a list of lists.

The question I have, do starships also need to be locations? Or can be just glob units together can check to make sure there are enough seats on starships for the people. Also, do items need to belong to a certain person or can we make sure at least one person is available at the location to hold it?

[mein1156]

2 mistakes in my last post.

One, forgot the type_id of the unit in the information and correct JSON formatting. [ {“response”: {“type”: “information”, "result":"success", "information":[[ UNIT_ID, TYPE_ID, STATUS, DAMAGE , LOCATION_ID], [UNIT_ID, ...]] }, “id”:1, “request”:234534 } ]

UNIT_ID will be a unique integer for all objects, TYPE_ID will specify the type (0 might be starships, 1 might be characters (more discussion in RFC 1)), status will indicate status code, damage will be the amount of damage, location_id the location. I think this provides all the necessary information in the game. The standard information will be from the TYPE_ID.

Instead of a list of lists, a dictionary of dictionaries is an option. Something like "information":{"unit_id"=UNIT_ID, "type_id":TYPE_ID", etc.}. This would be better if we need to make further improvements yet still have backward compatibility at the expense of longer messages.

Second, about boarding/items, etc. The types of people on a starship will determine its defense again PB, so it does seem like it is necessary to know which ship someone is on if not clear from context. In that case, the location_id of objects might be other objects. the location_id of an item will be a character, and the location of a character will might be a starship. In that case, the non-moveable locations (e.g. stars, planets) and the moveable locations (characters, starships, mobile units) will have to have unique ids to discriminate between them. That might be that all non-moveable objects are preceded by a 1 and others by 2 for example (if integer ids are necessary), or they are preceded by 9 (since no system id starts with a 9). Therefore the LOCATION_ID of the BOARD option for MOVEMENT above will be a starship or imperial unit capable of transport UNIT_ID and LOCATION_ID in general can be expanded to include both starships and characters units and some military units.

UNIT_ID and TYPE_ID might be 0 to indicate mobile units or units that the user can see, but does not have permission to know about.

[hallister]

Going to close this as well. We will go over this in much of the next meeting.