docs: API docs for Game APIs

README.md

@@ -356,7 +356,7 @@ class Agent {
 
 A game object, or *agent*, is a JavaScript object that contains Regal game state. Every agent should inherit from the `Agent` class.
 
-Before an agent's properties can be accessed in a game cycle, the agent must be activated with [`GameInstance.using`](#gameinstance-1). If you try to read or modify the property of an agent that hasn't been activated, a `RegalError` will be thrown.
+Before an agent's properties can be accessed in a game cycle, the agent must be activated with [`GameInstance.using()`](#gameinstance-1). If you try to read or modify the property of an agent that hasn't been activated, a `RegalError` will be thrown.
 
 #### Constructor
 
@@ -378,9 +378,9 @@ Common charsets used for pseudo-random string generation.
 
 ```ts
 const Charsets = {
-    EXPANDED_CHARSET: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789~!@#$%^&*()-_=+{}[]|;:<>,.?",
-    ALHPANUMERIC_CHARSET: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789",
-    ALPHABET_CHARSET: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
+    EXPANDED_CHARSET: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789~!@#$%^&*()-_=+{}[]|;:<>,.?"
+    ALHPANUMERIC_CHARSET: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+    ALPHABET_CHARSET: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
     NUMBERS_CHARSET: "0123456789"
 }
 ```
@@ -407,9 +407,13 @@ A function that modifies a [`GameInstance`](#gameinstance-1).
 ```ts
 type EventFunction<StateType = any> = (
     game: GameInstance<StateType>
-) => EventFunction<StateType> | void;
+) => EventFunction<StateType> | void
 ```
 
+#### Subtypes
+
+* [`TrackedEvent`](#trackedevent)
+
 #### Generic Type Parameters
 
 Parameter | Description
@@ -443,6 +447,14 @@ interface EventQueue<StateType = any> extends TrackedEvent<StateType> {
 
 #### Description
 
+An `EventQueue` is a special type of [`TrackedEvent`](#trackedevent) that contains a sequence of `TrackedEvent`s. When an `EventQueue` is invoked, it immediately invokes every event in `immediateEvents` sequentially. The events in `delayedEvents` are added to the end of the game instance's internal queue and will be invoked sequentially once all other events are finished.
+
+The `EventQueue`/[`TrackedEvent`](#trackedevent) API is chainable and can be used to invoke a complicated sequence of events.
+
+```ts
+firstEvent.then(secondEvent, thirdEvent).enqueue(lastEvent)
+```
+
 #### Extends
 
 [`TrackedEvent`](#trackedevent)
@@ -467,7 +479,7 @@ Property | Description
 Adds events to the end of the event queue.
 
 ```ts
-enqueue(...events: Array<TrackedEvent<StateType>>): EventQueue<StateType>;
+enqueue(...events: Array<TrackedEvent<StateType>>): EventQueue<StateType>
 ```
 
 **Parameters**
@@ -485,15 +497,197 @@ Parameter | Description
 Alias of [`EventQueue.enqueue()`](#enqueue).
 
 ```ts
-nq(...events: Array<TrackedEvent<StateType>>): EventQueue<StateType>;
+nq(...events: Array<TrackedEvent<StateType>>): EventQueue<StateType>
 ```
 
 ### `Game`
 
+**_Const Object_**
+
+Global implementation of [`GameApiExtended`](#gameapiextended).
+
+```ts
+const Game: GameApiExtended = { ... }
+```
+
+#### Description
+
+The `Game` object serves as an exportable API for playing the game. It is used for external interaction with the game, and shouldn't be accessed within the game itself.
+
+#### Implements
+
+[`GameApiExtended`](#gameapiextended)
+
 ### `GameApi`
 
+**_Interface_**
+
+Public API for interacting with the Regal game.
+
+```ts
+interface GameApi {
+    getMetadataCommand(): GameResponse
+    postPlayerCommand(instance: GameInstance, command: string): GameResponse
+    postStartCommand(options?: Partial<GameOptions>): GameResponse
+    postUndoCommand(instance: GameInstance): GameResponse
+    postOptionCommand(instance: GameInstance, options: Partial<GameOptions>): GameResponse
+}
+```
+
+#### Description
+
+A client application will consume this API, using the endpoints to generate game instances and receive output.
+
+#### Subtypes
+
+* [`GameApiExtended`](#gameapiextended)
+
+#### Methods
+
+##### `getMetadataCommand()`
+
+Gets the game's metadata. Note that this is not specific to any [`GameInstance`](#gameinstance-1), but refers to the game's static context.
+
+```ts
+getMetadataCommand(): GameResponse
+```
+
+**Returns**
+
+[`GameResponse`](#gameresponse): A game response containing the game's metadata as output if the request was successful. Otherwise, the response will contain an error.
+
+##### `postPlayerCommand()`
+
+Submits a command that was entered by the player, usually to trigger some effects in the [`GameInstance`](#gameinstance-1).
+
+If the [`onPlayerCommand`](#onplayercommand) hook has not been implemented, an error will be thrown.
+
+```ts
+postPlayerCommand(instance: GameInstance, command: string): GameResponse
+```
+
+**Parameters**
+
+Parameter | Description
+--- | ---
+`instance: GameInstance` | The current game instance (will not be modified).
+`command: string` | The player's command.
+
+**Returns**
+
+[`GameResponse`](#gameresponse): A game response containing a new [`GameInstance`](#gameinstance-1) with updated values and any output logged during the game cycle's events if the request was successful. Otherwise, the response will contain an error.
+
+##### `postStartCommand()`
+
+Triggers the start of a new game instance.
+
+If the [`onStartCommand`](#onstartcommand) hook has not been implemented, an error will be thrown.
+
+```ts
+postStartCommand(options?: Partial<GameOptions>): GameResponse
+```
+
+**Parameters**
+
+Parameter | Description
+--- | ---
+`options?: Partial<GameOptions>` | Any option overrides preferred for this specific instance, which must be allowed by the static configuration's `allowOverrides` option.
+
+**Returns**
+
+[`GameResponse`](#gameresponse): A game response containing a new [`GameInstance`](#gameinstance-1) and any output logged during the game cycle's events if the request was successful. Otherwise, the response will contain an error.
+
+##### `postUndoCommand()`
+
+Reverts the effects of the last player command on the game instance.
+
+Calls the [`beforeUndoCommand`](#beforeundocommand) hook to determine if the undo is allowed. If the hook has not been implemented, undo is allowed by default.
+
+```ts
+postUndoCommand(instance: GameInstance): GameResponse
+```
+
+**Parameters**
+
+Parameter | Description
+--- | ---
+`instance: GameInstance` | The current game instance (will not be modified).
+
+**Returns**
+
+[`GameResponse`](#gameresponse): A game response containing a new [`GameInstance`](#gameinstance-1) with updated values if the request was successful. Otherwise, the response will contain an error.
+
+##### `postOptionCommand()`
+
+Updates the values of the named game options in the game instance.
+
+```ts
+postOptionCommand(instance: GameInstance, options: Partial<GameOptions>): GameResponse;
+```
+
+**Parameters**
+
+Parameter | Description
+--- | ---
+`instance: GameInstance` | The current game instance (will not be modified).
+`options: Partial<GameOptions>` | The new option overrides, which must be allowed by the static configuration's `allowOverrides` option.
+
+**Returns**
+
+[`GameResponse`](#gameresponse): A game response containing a new [`GameInstance`](#gameinstance-1) with updated options if the request was successful. Otherwise, the response will contain an error.
+
 ### `GameApiExtended`
 
+**_Interface_**
+
+Extended API for interacting with the Regal game.
+
+```ts
+interface GameApiExtended extends GameApi {
+    readonly isInitialized: boolean
+    init(metadata: GameMetadata): void
+    reset(): void
+}
+```
+
+#### Description
+
+Contains the standard methods from [`GameApi`](#gameapi) as well as additional methods for advanced control.
+
+#### Extends
+
+[`GameApi`](#gameapi)
+
+#### Properties
+
+Property | Value
+--- | ---
+`readonly isInitialized: boolean` | Whether `Game.init()` has been called.
+
+#### Methods
+
+##### `init()`
+
+Initializes the game with the given metadata. This must be called before any game commands may be executed.
+
+```ts
+init(metadata: GameMetadata): void
+```
+
+**Properties**
+
+Property | Value
+--- | ---
+`metadata: GameMetadata` | The game's configuration metadata.
+
+##### `reset()`
+
+Resets the game's static classes.
+
+```ts
+reset()
+```
+
 ### `GameEventBuilder`
 
 ### `GameInstance`

src/api/game-api-extended.ts

@@ -15,7 +15,7 @@ import { GameApi } from "./game-api";
  * methods for advanced control.
  */
 export interface GameApiExtended extends GameApi {
-    /** Whether `Game.init` has been called. */
+    /** Whether `Game.init()` has been called. */
     readonly isInitialized: boolean;
 
     /**

src/api/game-api.ts

@@ -1,9 +1,6 @@
 /*
  * Contains the public-facing API for interaction with a Regal game.
  *
- * A client application will consume this API, using the endpoints to
- * modify the game and receive output.
- *
  * Copyright (c) 2018 Joseph R Cowman
  * Licensed under MIT License (see https://github.com/regal/regal)
  */
@@ -14,6 +11,9 @@ import { GameResponse } from "./game-response";
 
 /**
  * Public API for interacting with the Regal game.
+ *
+ * A client application will consume this API, using the endpoints to
+ * generate game instances and receive output.
  */
 export interface GameApi {
     /**
@@ -29,56 +29,53 @@ export interface GameApi {
      * Submits a command that was entered by the player, usually to trigger
      * some effects in the `GameInstance`.
      *
-     * If the `onPlayerCommand` hook has not been implemented by the game
-     * developer, an error will be thrown.
+     * If the `onPlayerCommand` hook has not been implemented, an error will be thrown.
      *
      * @param instance The current game instance (will not be modified).
      * @param command The player's command.
      *
      * @returns A `GameResponse` containing a new `GameInstance` with updated
-     * values and any output logged during the game cycle's events, if the request
+     * values and any output logged during the game cycle's events if the request
      * was successful. Otherwise, the response will contain an error.
      */
     postPlayerCommand(instance: GameInstance, command: string): GameResponse;
 
     /**
      * Triggers the start of a new game instance.
      *
-     * If the `onStartCommand` hook has not been implemented by the game
-     * developer, an error will be thrown.
+     * If the `onStartCommand` hook has not been implemented, an error will be thrown.
      *
-     * @param options Any option overrides preferred for this specific instance.
-     * Must be allowed by the static configuration's `allowOverrides` option.
+     * @param options Any option overrides preferred for this specific instance,
+     * which must be allowed by the static configuration's `allowOverrides` option.
      *
      * @returns A `GameResponse` containing a new `GameInstance` and any output
-     * logged during the game cycle's events, if the request was successful.
+     * logged during the game cycle's events if the request was successful.
      * Otherwise, the response will contain an error.
      */
     postStartCommand(options?: Partial<GameOptions>): GameResponse;
 
     /**
-     * Reverts the effects of the last command that modified the game instance.
-     * (A `postPlayerCommand`, `postStartCommand`, or `postUndoCommand`)
+     * Reverts the effects of the last player command on the game instance.
      *
      * Calls the `beforeUndoCommand` hook to determine if the undo is allowed.
      * If the hook has not been implemented, undo is allowed by default.
      *
      * @param instance The current game instance (will not be modified).
      *
      * @returns A `GameResponse` containing a new `GameInstance` with updated
-     * values, if the request was successful. Otherwise, the response will contain an error.
+     * values if the request was successful. Otherwise, the response will contain an error.
      */
     postUndoCommand(instance: GameInstance): GameResponse;
 
     /**
-     * Updates the values of the named game options in the `GameInstance`.
+     * Updates the values of the named game options in the game instance.
      *
      * @param instance The current game instance (will not be modified).
-     * @param options The new option overrides. Must be allowed by the static
+     * @param options The new option overrides, which must be allowed by the static
      * configuration's `allowOverrides` option.
      *
      * @returns A `GameResponse` containing a new `GameInstance` with updated
-     * options, if the request was successful. Otherwise, the response will contain an error.
+     * options if the request was successful. Otherwise, the response will contain an error.
      */
     postOptionCommand(
         instance: GameInstance,

src/api/impl/game-impl.ts

@@ -99,10 +99,11 @@ const NOT_INITALIZED_ERROR_MSG =
     "Game has not been initalized. Did you remember to call Game.init?";
 
 /**
- * Game API
+ * Global implementation of `GameApiExtended`.
  *
- * Used for external interaction with the game, and shouldn't be accessed
- * within the game itself.
+ * The `Game` object serves as an exportable API for playing the game.
+ * It is used for external interaction with the game, and shouldn't
+ * be accessed within the game itself.
  */
 // tslint:disable-next-line:variable-name
 export const Game = {