backgammon.js :: Detailed documentation
Backgammon is one of the most popular and ancient board games and there are zillion implementations of it for PC and mobile crafted around the world.
Alas, most implementations share some of the following shortcomings:
-
Not suitable for a quick game
They require registration, verification by E-mail, manually creating a game and setting up game options before starting the game.
-
Helping players too much
Most implementations are providing too much help to players, like highlighting movable pieces, pipe counters, and even move hints.
As a result the experience of playing the game suffers. What's more that prevents junior players from actually learning to play.
-
Based on specific culture
Most implementations only allow playing a single variant of backgammon (or at best a few). This is an ancient game with many variants being played in different countries on even in different regions in the same country.
-
Require more processing power to run
Some implementations have too high hardware requirements for a board game, which makes playing them on an old PC unpleasant.
-
Not mobile friendly
Could not be played on tablet or mobile phone.
The purpose of this project is to create an online backgammon game that has none of these shortcoming. This should be achieved by meeting the project goals.
Goals have been divided in two categories: "must have" and "under consideration".
Once a goal makes it to the "must have" list, objectives can be assigned to it.
This is the list of must-have goals, that should be available in first stable release:
- Allow anyone to challenge friends or play with strangers online with zero time to start the game - requires no registration or configuration.
- Fair gameplay that is as close to real game as possible:
- no visual hints for moves allowed;
- no pip counter;
- quality random generator.
- Extensible and modular engine that would allow the open source community to implement different variants of the game as known in different countries and different user interfaces (eg. themes).
- Lightweight - playable on any device, even old ones - anything that can run a modern browser;
- Works in browser @ PC & Mobile;
This is a set of optional goals that might or might not be considered as long-term goals for the future:
- Add multiple language support.
- Allow optional registration;
- Remember game history;
- Support player ratings;
- Create replay engine;
There will be two main types of users of the system:
- Players - Players will just play the game
- Developers - Developers will host the game at servers and write custom rules
Use cases for those actors complement the goals from users' perspective:
Create custom game and Join game are not fully implemented yet.
These are business objectives that exactly match goals.
Allow anyone to challenge friends or play with strangers online with zero time to start the game - requires no registration or configuration
- Allow players to quickly start a random game;
- Allow players to send invites by chat or E-mail;
Fair gameplay that is as close to real game as possible
- Use quality random generator
Extensible and modular engine that would allow the open source community to implement different variants of the game as known in different countries and different user interfaces (eg. themes)
- Allow writing custom rules
- Allow writing custom UI
Lightweight - playable on any device, even old ones - anything that can run a modern browser Works in browser @ PC & Mobile
- Make a lightweight client that works in both desktop and mobile browsers alike
Coming soon...
| Objective | State | Time Frame |
|---|---|---|
| Create documentation | 🔜 In Progress | |
| Choose network/communication library | ✅ Completed | |
| Choose DBMS | ✅ Completed | |
| Create object model | 🔜 Working | |
| Create a sample rule | 🚧 In Progress | |
| Create simple board UI | 🚧 In Progress | |
| Integrate Socket.IO | 🔜 Working | |
| Allow player to create and join game | 🚧 In Progress | |
| Allow player to start game | 🔜 Working | |
| Allow player to start random game | 🔜 Working | |
| Update board UI on game state change | 🚧 In Progress | |
| Allow player to roll dice (at server) | ✅ Completed | |
| Use quality random generator | ✅ Completed | |
| Always show player's pieces at bottom | ✅ Completed | |
| Play lowest die value on right click | ✅ Completed | |
| Reverse die values on click at dice | ✅ Completed | |
| Allow player to move pieces | ✅ Completed | |
| Validate moves at server, using rules | ✅ Completed | |
| Allow player to end turn, if a move cannot be played | ✅ Completed | |
| Force player to use all possible moves, if possible | ✅ Completed | |
| Continue game on page reload | 🔜 Working | |
| Implement matches | 🔜 Working | |
| Show an offcanvas game menu | 🔜 Working | |
| Show player names and match score in toolbar | 🚧 In Progress | |
| Show borne pieces | ⬜ Not implemented | |
| Allow player to resign from game/match | ✅ Completed | |
| Allow user to get "challenge" links | ✅ Completed | |
| Allow user to see list of games | ⬜ Not implemented | |
| Users can filter/sort games by rule | ⬜ Not implemented | |
| Users can choose use of clock, cube and match length | ⬜ Not implemented | |
| Polish simple board UI | ⬜ Not implemented | |
| Allow user to choose game rule (variant) | ✅ Completed | |
| End match if connection is broken for X mins | ✅ Not implemented | Next |
Possible states: ⬜ Not implemented, 🚧 In progress, 🔜 Working, ✅ Completed
The project uses a typical client/server architecture with several layers of responsibility.
The environment layer contains external systems and frameworks the project depends on, like Node.js and Socket.IO.
Foundation of project is laid on node.js. Network connectivity is implemented via Socket.IO. Storage of objects will be performed by MongoDB, but database layer has not been integrated yet, so everything is reset when the server application is restarted. Database will be required if we decide to allow players to register and save their game history.
The module layer contains classes shared between client and server all packaged in a single node.js package named backgammon.js-lib.
This package includes:
- Classes describing domain model;
- Messages exchanged on network layer;
- Rules for variants of the game.
JsDoc documentation of library classes is available at Library Reference.
Instructions on adding new variants of backgammon (rules) to the game can be found at Creating rules for backgammon.js.
The application layer consists of two node.js packages: backgammon.js-client and backgammon.js-server.
Both packages depend on the common library modules and use Socket.IO to communicate with each other.
Directory structure of code follows project architecture:
├─ [app] - Place for applications' code (server, browser, android, etc.)
│ ├─ [browser] - Sample web client application
│ │ ├─ [images]
│ │ ├─ [js]
│ │ │ ├─ bundle.js - browserify's output file (bundling all other scripts)
│ │ │ ├─ config.js - Config script for client
│ │ │ ├─ main.js - Main script file for index.html
│ │ │ └─ SimpleBoardUI.js - Sample user interface for game board
│ │ │─ [style]
│ │ │ └─ backgammon.css - Main style file for index.html
│ │ ├─ bower.json - Bower package file for web client
│ │ ├─ index.html - Home page of web client
│ │ ├─ package.json - Node.js package file
│ │ └─ README.md - Instructions for client installation and development
│ │
│ └─ [server] - Server application
│ ├─ package.json - Node.js package file
│ ├─ queue_manager.js - Node.js package file
│ ├─ README.md - Instructions for server installation and development
│ └─ server.js - Server startup script
│
├─ [docs]
│ ├─ [images]
│ ├─ backgammon.js.uml
│ ├─ INSTALL.md - Detailed installation instructions
│ ├─ README.md - This file
│ ├─ rules.md - Instructions on creating a new rule
│ └─ use-cases.md
│
├─ [lib] - Common library shared by clients and server
│ ├─ [rules] - Rules describing different variants of the game
│ │ ├─ rules\rule.js - Base class for defining game rules
│ │ ├─ rules\RuleBgCasual.js - Rule for most popular variant
│ │ ├─ rules\RuleBgGulbara.js - Example for `Gul bara` variant
│ │ └─ rules\RuleBgTapa.js - Example for `Tapa` variant
│ ├─ client.js - Messages exchanged on network layer
│ ├─ comm.js - Messages exchanged on network layer
│ ├─ model.js - Classes of the object oriented model
│ ├─ package.json - Node.js package file
│ └─ README.md - Library documentation and instructions on writing new rules
│
├─ .gitignore
├─ .tern-project - Sample configuration for atom-tern.js plugin
├─ CHANGELOG.md
├─ Dockerfile
├─ LICENSE - MIT License
├─ package.json - Main project package
└─ README.md - Project's readme with links to all documents
- Heroku - free tier of service used for running the demo
- Brackets & Atom editor (with
atom-tern.js) - Netbeans IDE
- White StarUML
- browserify.js
- watch.js
- watchify.js
- JsDoc
- Git
- Paint.NET
- Node.js
- Express
- Socket.IO
- jQuery
- Bootstrap
- OhSnap!.js
- Fittext.js
- clipboard.js
- js-cookie
Licensed under the MIT license.
Project README- Client application:
backgammon.js-client - Server application:
backgammon.js-server - Common Library:
backgammon.js-lib