Updated README.

README.md

@@ -1,47 +1,76 @@
-# 0. Preface
+# Preface 
-If you'd like to play with the backend code seriously, please read the detailed explanation of its important "lifecycle events" in [this note](https://app.yinxiang.com/fx/5c575124-01db-419b-9c02-ec81f78c6ddc).
 
-There could be some left over wechat-game related code pieces, but they're neither meant to work nor supported anymore. 
+This project is a demo for a websocket-based input synchronization method inspired by [GGPO](https://www.ggpo.net/).   
+![screenshot-1](./screenshot-1.png)
+
+Please checkout [this demo video](https://pan.baidu.com/s/1ge9fEZNsRA8f6dpBKbdSjw?pwd=854g) to see whether the source codes are doing what you expect for synchronization.
+
+The video mainly shows the following feature (yet I'm not surprised if they're not obvious): when a player didn't have its input arrived at the backend in time (e.g. due to local lag, network delay or reconnection), backend forces confirmation of a prediction of its own and sends the confirmed input together w/ a reference render frame to that player.
 
 # 1. Building & running
 
-## 1.1 Golang1.19.1
+## 1.1 Tools to install 
-Documentation TBD.
+### Backend
+- [Command Line Tools for Xcode](https://developer.apple.com/download/all/?q=command%20line%20tools) (on OSX) or [TDM-GCC](https://jmeubank.github.io/tdm-gcc/download/) (on Windows) (a `make` executable mandatory)
+- [Golang1.19.1](https://golang.org/dl/) (mandatory, in China please try a mirror site like [that of ustc](https://mirrors.ustc.edu.cn/golang/))
+- [MySQL 5.7](https://dev.mysql.com/downloads/windows/installer/5.7.html) (mandatory)
+- [Redis 3.0.503 or above](https://redis.io/download/) (mandatory)
+- [skeema](https://www.skeema.io/) (optional, only for convenient MySQL schema provisioning)
+- [protobuf CLI](https://developers.google.com/protocol-buffers/docs/downloads) (optional, only for development)
 
-## 1.2 MySQL 
+### Frontend
-The database product to be used for this project is MySQL 5.7, you can install and manage `MySQL` server by [these scripts](https://github.com/genxium/Ubuntu14InitScripts/tree/master/database/mysql).
+- [CocosCreator v2.2.1](https://www.cocos.com/en/cocos-creator-2-2-1-released-with-performance-improvements) (mandatory, **ONLY AVAILABLE on Windows or OSX and should be exactly this version**, DON'T use any other version because CocosCreator is well-known for new versions not being backward incompatible)
+- [protojs](https://www.npmjs.com/package/protojs) (optional, only for development)
 
-We use [skeema](https://github.com/skeema/skeema) for schematic synchronization under `<proj-root>/database/skeema-repo-root/` which intentionally doesn't contain a `.skeema` file. Please read [this tutorial](https://shimo.im/doc/wQ0LvB0rlZcbHF5V) for more information. For `Windows 10/11`, you can compile `skeema` from source and config the host to be `127.0.0.1` instead of `localhost` to use it, i.e. circumventing the pitfall for MySQL unix socket connection on Windows.
+## 1.2 Provisioning
-
+### Backend/Database
-The following command(s)
+It's strongly recommended that `skeema` is used for provisioning [the required schema](https://github.com/genxium/DelayNoMore/tree/main/database/skeema-repo-root) in MySQL instance. When using `skeema` the steps are as follows.
 ```
-### Optional.
+### Mandatory after an initial clone
 user@proj-root/database/skeema-repo-root> cp .skeema.template .skeema
 
-###
+### Mandatory
-user@proj-root/database/skeema-repo-root> skeema diff
+user@proj-root/database/skeema-repo-root> skeema push
 ```
-is recommended to be used for checking difference from your "live MySQL server" to the latest expected schema tracked in git.
 
-## 1.3 Required Config Files
+On `Windows 10/11`, you can compile `skeema` from source and config the host to be `127.0.0.1` instead of `localhost` to use it, i.e. circumventing the pitfall for MySQL unix socket connection on Windows.
 
-### 1.3.1 Backend 
+### Backend/Golang
-- It needs `<proj-root>/battle_srv/configs/*` which is generated by `cd <proj-root>/battle_srv && cp -r ./configs.template ./configs` and necessary customization.
+```
+user@proj-root/battle_srv/configs> cp ./configs.template ./configs
+```
 
-### 1.3.2 Frontend 
+### Frontend
-- It needs CocosCreator v2.2.1 to build.
+```
-- A required "CocosCreator plugin `i18n`" is already enclosed in the project, if you have a globally installed "CocosCreator plugin `i18n`"(often located at `$HOME/.CocosCreator/packages/`) they should be OK to co-exist.
+user@proj-root/frontend/assets/plugin_scripts> cp ./conf.js.template ./conf.js
-- It needs `<proj-root>/frontend/assets/plugin_scripts/conf.js` which is generated by `cd <proj-root>/frontend/assets/plugin_scripts && cp conf.js.template conf.js`.
+```
 
-## 1.4 Troubleshooting
+## 1.2 Actual building & running
+### Backend 
+```
+### The following command runs mysql-server in foreground, it's almost NEVER run in such a way, please find a proper way to run it for yourself
+user@anywhere> mysqld
 
-### 1.4.1 Redis snapshot writing failure
+### The following command runs redis-server in foreground, it's OK to put it in background
+user@anywhere> redis-server
+
+### on Windows using TDM-GCC: mingw32-make run-test 
+user@proj-root/battle_srv> make run-test
+```
+
+### Frontend
+The easy way is to try out 2 players with test accounts on a same machine.
+- Open CocosCreator v2.2.1 (mandatory, it serves the web content of the following steps)
+- Open one browser instance, visit _http://localhost:7456?expectedRoomId=1_, input `add`on the username box and click to request a captcha, this is a test account so a captcha would be returned by the backend and filled automatically (as shown in the figure below), then click and click to proceed to a matching scene.
+- Open another browser instance, visit _http://localhost:7456?expectedRoomId=1_, input `bdd`on the username box and click to request a captcha, this is another test account so a captcha would be returned by the backend and filled automatically, then click and click to proceed, when matched a `battle`(but no competition rule yet) would start.
+- Try out the onscreen virtual joysticks to move the cars and see if their movements are in-sync.
+![screenshot-2](./screenshot-2.png)
+
+## 2 Troubleshooting
+
+### 2.1 Redis snapshot writing failure
 ```
 ErrFatal        {"err": "MISCONF Redis is configured to save RDB snapshots, but is currently not able to persist on disk. Commands that may modify the data set are disabled. Please check Redis logs for details about the error."}
 ```
 
 Just restart your `redis-server` process.
-
-# 2. Git configs cautions
-
-Please make sure that you've set `ignorecase = false` in your `[core] section of <proj-root>/.git/config`.