google / web-bsd-hunt

Port of the networked real-time multi-player 2D maze war BSD game "Hunt" to Google App Engine and modern web browsers

#Web Hunt Port of the real-time multiplayer 2D maze war BSD game "Hunt" to Google App Engine and modern web browsers.

https://en.wikipedia.org/wiki/Hunt_(video_game)

Moderately complex multiplayer real-time web and mobile games require a mix of stateless and stateful components to deal with managing game state, load balancing, scaling, matchmaking, statistics gathering, monitoring, analytics, and more.

This project implements one such design and architecture for modernizing the retro terminal based real-time multiplayer 1980's BSD game, "Hunt" and running in Google App Engine (GAE) Platform as a Service.

It includes the entire client and server side applications, from the Javascript Single Page App running in a browser, to the stateless serving infrastructure running in the GAE Standard Environment, a stateful game engine in the GAE Flexible environment. Memcache, Datastore, Cloud Pub-Sub, Cron, and Metadata services are utilized as architectural components.

##Highlights

• Client: HTML / Javascript
• Frontend: Golang application for App Engine Standard
• Backend: Game engine (Original Hunt daemon & Golang instance manager) in App Engine Flex

##Licenses

• All Google authored code is covered by the license detailed in the LICENSE file at the top of the tree.
• This repository also contains code covered by other licenses. All such code can be found within the "third_party" directory tree.

##Installation ###Prerequisites

• Install The Go Programming Language
  Installation instructions can be found at https://golang.org

• Install docker
  Installation instructions can be found at https://docker.github.io/engine/installation

• Install the App Engine SDK for Go
  Installation instructions can be found at https://cloud.google.com/appengine/docs/go/download

• Install the Google Cloud SDK
  Installation instructions can be found at https://cloud.google.com/sdk/docs/quickstarts

###Build and Deploy

• Using the Google Cloud Platform dashboard, go to the Projects page and create a new project.
  https://console.cloud.google.com/iam-admin/projects
  Make note of the name assigned to the new project.

• From the root of the web-bsd-hunt directory, build and deploy the project by executing the command:

  make PROJECT=<project-name> build deploy

  Where <project-name> is the name given to the Google Platform project created in the previous step.

• Once the build and deployment finishes, you can view the application in a web browser using the following URL:
  https://<project-name>.appspot.com

##Notes

• This is not an official Google product.

web-bsd-hunt's Issues

JavaScript client doesn't handle handle playfield updates which span multiple HTTP requests

The JS client uses HTTP long-polling to wait for GameDataResponse events. The GameDataResponse payload contains a stream of bytes describing commands in the form of ([opcode], [data]), where either the opcode or data (but not both) may be elided. If present, opcode is a single byte. If data is present it may be one or more bytes. There is no strict guarantee that a GameDataResponse will hold a complete command. Thus a multibyte command may be split across multiple GameDataResponse events.

In fact, a single GameDataResponse may contain multiple commands, and may start with payload bytes from earlier commands, and end either on a command boundary or not.

The only guarantee is that as long as the client only ever has at most 1 GameDataRequest outstanding, the GameDataResponse payloads will describe a correctly ordered stream of bytes. This means that response payloads can simply be concatenated together to unpack the incoming event stream.

This is perhaps best explained via example:
Assume the Game Server wants to move the cursor to X=10,Y=20 and draw the text "Foo" there. The stream of bytes that describes to the client how to do this will look something like this (byte 0 is the first byte delivered to the client).

     0      1    2     3      4      5      6       7
+--------+----+----+-------+------+------+------+---------+
|  Move  | Y= | X= |  Add  | Char | Char | Char | Refresh |
| Cursor | 20 | 10 |  Char | 'F'  | 'o'  | 'o'  | Screen  |
+--------+----+----+-------+------+------+------+---------+

The problem is that the GameDataResponse might not begin with a command opcode, nor contain the entire command payload. For example, the client could receive a series of GameDataResponse each which contains payload bytes from the above stream as follows:

• Response 1: bytes 0..1: Can't process any commands
• Response 2: bytes 2..4: Can process Move (bytes 0..2)
• Response 3: bytes 5..7: Can process Add Char (bytes 3..6) and Refresh (byte 7)

This means that it's up to the client to only process commands that it has full payloads for, and the client currently does not contain any logic to handle commands split across GameDataResponse messages.

The solution requires the client to identify command boundaries, and only process fully received commands, buffering partial commands until they're complete.

Luckily we can rely on some protocol features to help (http://cvsweb.netbsd.org/bsdweb.cgi/src/games/hunt/README.protocol?annotate=1.1). Some opcodes don't have any payload (i.e. they're single bytes). Some opcodes are inferred rather than explicitly provided (i.e. ADDCH is optional). Identifying any of these opcodes in the incoming bytes is sufficient to know that bytes up to and including this one can be processed. It turns out that all command opcode bytes have the high bit set, while payload bytes are guaranteed not to have it set. As a result, opcode bytes are easy to detect, and the protocol description enumerates the full set of commands along with their payloads.

You may be wondering this sounds like how does this work at all right now!?. In practice we're getting lucky that the mechanism the game server uses to write multi-byte commands causes the multiplexer to read full commands, and thus package one or more full commands into the GameDataResponse payloads. Essentially we're relying on undefined behavior, which today works in our favor, but could change at any time due to things outside our control.

Add some more intuitive keyboard controls

Most folks these days didn't grow up using 'hjkl' for moving the cursor around, even those folks that use vi. We're a dying breed. The JS keyboard controls should be updated to something that modern players find intuitive.

Social integration

It would be cool if It could be expanded so that certain messages (started playing, killed/killed by ...) are posted to twitter or your facebook wall.

Convert README to Markdown

Security Policy violation Binary Artifacts

This issue was automatically created by Allstar.

Security Policy Violation
Project is out of compliance with Binary Artifacts policy: binaries present in source code

Rule Description
Binary Artifacts are an increased security risk in your repository. Binary artifacts cannot be reviewed, allowing the introduction of possibly obsolete or maliciously subverted executables. For more information see the Security Scorecards Documentation for Binary Artifacts.

Remediation Steps
To remediate, remove the generated executable artifacts from the repository.

Artifacts Found

• third_party/src/github.com/dmauro/Keypress/compiler.jar

Additional Information
This policy is drawn from Security Scorecards, which is a tool that scores a project's adherence to security best practices. You may wish to run a Scorecards scan directly on this repository for more details.

---

Allstar has been installed on all Google managed GitHub orgs. Policies are gradually being rolled out and enforced by the GOSST and OSPO teams. Learn more at http://go/allstar

This issue will auto resolve when the policy is in compliance.

Issue created by Allstar. See https://github.com/ossf/allstar/ for more information. For questions specific to the repository, please contact the owner or maintainer.

Add build & deploy instructions

Authenticated game play

One thing that I've been thinking is problematic is that currently there is no authentication / authorization at all. It's good in that it's thus low friction to play, but it's also bad because it leaves things open for abuse. We could either lock it down entirely, requiring login using a 3rdparty oauth identity provider (Google, Facebook, etc), or do something like provide a limited set of instances wide open (free for all), with more features (such as leaderboards, better matchmaking, etc) behind an auth-wall.