diff --git a/docs/overview/game.md b/docs/overview/game.md index a7a31dd..81ad6fb 100644 --- a/docs/overview/game.md +++ b/docs/overview/game.md @@ -13,59 +13,9 @@ Regal was structured like this so that a client's only responsibilties are: The idea is that a Regal game is deterministic; i.e. it will always return the same output when given the same input. This makes debugging easier and means that no user-specific game data ever needs to be stored on the game servers—in fact, a Regal game can be serverless! All one needs is a client that can store data and call the Regal API. Multiple clients playing multiple games can call the same API, and they won't interfere with each other. -## Requests and Responses +## `GameResponse` -Interaction with a Regal game is done through the `Game` API. The API expects a `GameRequest` and returns a `GameResponse`. - -### `GameRequest` - -A `GameRequest` contains the player's command and the instance state of the game at that moment. A `GameRequest` is sent to the `Game` API whenever a command (such as "open door") is created. - -The `GameRequest` schema is as follows: - -```ts -interface GameRequest { - command: GameCommand; - instance?: GameInstance; -} -``` - -#### `GameCommand` - -`GameCommand` is an interface that represents a command. Its schema is as follows: - -```ts -interface GameCommand { - type: GameCommandType; - data: any; -} -``` - -The type of `GameCommand.data` is determined by the value of `GameCommand.type`. Different classes of `GameCommand` exist for different types of commands. - -The most common class of `GameCommand` is `PlayerCommand`, which is used for all commands that are spoken or typed by a player. For example, if a player entered the command "go west," the following `PlayerCommand` would be generated: - -```ts -{ - type: GameCommandType.PlayerCommand; - data: "go west"; -} -``` - -The following table shows the different classes of commands that are supported by Regal: - -Class | Command Data Type | Description ---- | --- | --- -PlayerCommand | string | Command spoken or typed by a player; usually used to do something in the game. -StartCommand | object | Starts a new game. The object passed in as the command's data can contain optional arguments specific to the game. -UndoCommand | void | Undoes the effects of the previous command. If the previous command was not a PlayerCommand, an error will be thrown. -GetOptionCommand | string[] | Returns the values of the named game options. -SetOptionCommand | GameOption[] | Sets the values of the named game options. -TimerCommand | TBA | TBA - -### `GameResponse` - -A `GameResponse` contains the output of the request's effect on the game and the new instance state of the game at that moment. A `GameResponse` is returned by the `Game` API whenever a `GameRequest` is sent to it. +A `GameResponse` contains the output of a request's effect on the game and the new instance state of the game at that moment. A `GameResponse` is returned by the `Game` API whenever one of its methods is called. The `GameResponse` schema is as follows: @@ -76,7 +26,7 @@ interface GameResponse { } ``` -#### `GameOutput` +### `GameOutput` `GameOutput` is an interface that represents the output generated by a request. Its properties are as follows: @@ -98,9 +48,21 @@ MINOR | Non-important line; emphasized less than `NORMAL` lines, and won't alway DEBUG | Meant for debugging purposes; only visible when the `DEBUG` option is enabled. | Debugging SECTION_TITLE | Signifies the start of a new section or scene in the game. | In games that have scenes, rooms, or other disconnected sections. (i.e. "**West of House**") + ## Calling the `Game` API -`Game` is a global object that contains the public API for interacting with a Regal game. It has the following methods: +`Game` is a global object that contains the public API for interacting with a Regal game. + +It has six methods: + +* `GetOptionCommand` +* `GetMetadataCommand` +* `PostPlayerCommand` +* `PostStartCommand` +* `PostUndoCommand` +* `PostOptionCommand` + +Each of these methods returns a `GameResponse` object. ### `Game.GetOptionCommand(instance: GameInstance, options: string[])` @@ -215,7 +177,7 @@ const response2 = Game.PostUndoCommand(response1.instance); response2.output === { wasSuccessful: false, error: { - message: "Can not undo an undo command; only a player command." + message: "Can not undo an undo command; only a player command can be undone." } }; ```