Add some documentation about the Game import interface

[empires-server] / lmno.js

diff --git a/lmno.js b/lmno.js
index 175fe6300472cd914c562d7271131d8024cf6281..a22f9588537b2cae1e75adbbeb94a88e68420e0a 100644 (file)
--- a/lmno.js
+++ b/lmno.js
@@ -46,7 +46,37 @@ nunjucks.configure("templates", {
   express: app
 });
 
-/* Load each of our game mini-apps. */
+/* Load each of our game mini-apps.
+ *
+ * Each "engine" we load here must have a property .Game on the
+ * exports object that should be a class that extends the common base
+ * class Game.
+ *
+ * In turn, each engine's Game must have the following properties:
+ *
+ *     .meta:   An object with .name and .identifier properties.
+ *
+ *              Here, .name is a string giving a human-readable name
+ *              for the game, such as "Tic Tac Toe" while .identifier
+ *              is the short, single-word, all-lowercase identifier
+ *              that is used in the path of the URL, such as
+ *              "tictactoe".
+ *
+ *     .router: An express Router object
+ *
+ *              Any game-specific routes should already be on the
+ *              router. Then, LMNO will add common routes including:
+ *
+ *                 /        Serves <identifier>-game.html template
+ *
+ *                 /events  Serves a stream of events. Game can override
+ *                          the handle_events method, call super() first,
+ *                          and then have code to add custom events.
+ *
+ *                 /moves   Receives move data from clients. This route
+ *                          is only added if the Game class has an
+ *                          add_move method.
+ */
 const engines = {
   empires: require("./empires"),
   tictactoe: require("./tictactoe")
@@ -54,7 +84,7 @@ const engines = {
 
 class LMNO {
   constructor() {
-    this.ids = {};
+    this.games = {};
   }
 
   generate_id() {
@@ -64,19 +94,15 @@ class LMNO {
   create_game(engine_name) {
     do {
       var id = this.generate_id();
-    } while (id in this.ids);
+    } while (id in this.games);
 
     const engine = engines[engine_name];
 
-    const game = new engine.Game();
+    const game = new engine.Game(id);
 
-    this.ids[id] = {
-      id: id,
-      engine: engine.name,
-      game: game
-    };
+    this.games[id] = game;
 
-    return id;
+    return game;
   }
 }
 
@@ -112,8 +138,8 @@ function lmno_canonize(id) {
 
 app.post('/new/:game_engine', (request, response) =>  {
   const game_engine = request.params.game_engine;
-  const game_id = lmno.create_game(game_engine);
-  response.send(JSON.stringify(game_id));
+  const game = lmno.create_game(game_engine);
+  response.send(JSON.stringify(game.id));
 });
 
 /* Redirect any requests to a game ID at the top-level.
@@ -132,12 +158,12 @@ app.get('/[a-zA-Z0-9]{4}', (request, response) => {
     return;
   }
 
-  const game = lmno.ids[game_id];
+  const game = lmno.games[game_id];
   if (game === undefined) {
       response.sendStatus(404);
       return;
   }
-  response.redirect(301, `/${game.engine}/${game.id}/`);
+  response.redirect(301, `/${game.meta.identifier}/${game.id}/`);
 });
 
 /* LMNO middleware to lookup the game. */
@@ -160,14 +186,14 @@ app.use('/:engine([^/]+)/:game_id([a-zA-Z0-9]{4})', (request, response, next) =>
   }
 
   /* See if there is any game with this ID. */
-  const game = lmno.ids[game_id];
+  const game = lmno.games[game_id];
   if (game === undefined) {
     response.sendStatus(404);
     return;
   }
 
   /* Stash the game onto the request to be used by the game-specific code. */
-  request.game = game.game;
+  request.game = game;
   next();
 });
 
@@ -238,11 +264,11 @@ app.get('/admin/', auth_admin, (request, response) => {
   let active = [];
   let idle = [];
 
-  for (let id in lmno.ids) {
-    if (lmno.ids[id].game.clients.length)
-      active.push(lmno.ids[id]);
+  for (let id in lmno.games) {
+    if (lmno.games[id].clients.length)
+      active.push(lmno.games[id]);
     else
-      idle.push(lmno.ids[id]);
+      idle.push(lmno.games[id]);
   }
   response.render('admin.html', { test: "foobar", games: { active: active, idle: idle}});
 });
@@ -251,7 +277,46 @@ app.get('/admin/', auth_admin, (request, response) => {
 /* Mount sub apps. only _after_ we have done all the middleware we need. */
 for (let key in engines) {
   const engine = engines[key];
-  app.use(`/${engine.name}/[a-zA-Z0-9]{4}/`, engine.router);
+  const router = engine.Game.router;
+
+  /* Add routes that are common to all games. */
+  router.get('/', (request, response) => {
+    const game = request.game;
+
+    if (! request.session.nickname)
+      response.render('choose-nickname.html', { game_name: game.meta.name });
+    else
+      response.render(`${game.meta.identifier}-game.html`);
+  });
+
+  router.get('/events', (request, response) => {
+    const game = request.game;
+
+    game.handle_events(request, response);
+  });
+
+  /* Further, add some routes conditionally depending on whether the
+   * engine provides specific, necessary methods for the routes. */
+  if (engine.Game.prototype.add_move) {
+    router.post('/move', (request, response) => {
+      const game = request.game;
+      const move = request.body.move;
+
+      const legal = game.add_move(move);
+
+      /* Inform this client whether the move was legal. */
+      response.send(JSON.stringify(legal));
+
+      /* And only if legal, inform all clients. */
+      if (! legal)
+        return;
+
+      game.broadcast_move(move);
+    });
+  }
+
+  /* And mount the whole router at the path for the game. */
+  app.use(`/${engine.Game.meta.identifier}/[a-zA-Z0-9]{4}/`, router);
 }
 
 app.listen(4000, function () {