croupier: Add schema.md and update README.md
The README was updated to reflect recent changes.
schema.md describes the Syncbase schemas used by Croupier.
Change-Id: I9684c5ffe3b2e9b3b65246808174a7de820ff541
diff --git a/Makefile b/Makefile
index 8317a00..b9338ad 100644
--- a/Makefile
+++ b/Makefile
@@ -162,7 +162,7 @@
clean:
ifdef ANDROID
# Clean syncbase data dir.
- adb -s $(DEVICE_ID) shell rm -rf $(APP_HOME_DIR)/syncbase_data
+ adb -s $(DEVICE_ID) shell run-as org.chromium.mojo.shell rm -rf $(APP_HOME_DIR)/syncbase_data
endif
rm -f croupier.flx snapshot_blob.bin
rm -rf bin tmp
diff --git a/README.md b/README.md
index f958bb1..9cef7b2 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,16 @@
# Croupier
Croupier is a Vanadium demo app of a general card playing game for multiple
-devices. The app combines Syncbase with Mojo and Flutter and in the near future,
-will also demonstrate P2P discovery and Syncgroup formation.
+devices. Croupier utilizes Syncbase and P2P Discovery as the foundations for
+game formation and state synchronization.
-Croupier's primary card game is Hearts, but it is only available in single-device
-form. More games will be added in the future.
+This repository contains two implementations of Croupier, one in Go and the
+other in Mojo and Flutter. As Croupier's primary card game is Hearts, the two
+sides are meant to interoperate with that game. The Flutter version also
+supports Solitaire and is built so that more games can be added in the future.
-In order to run the program, it is recommended to use Android devices. (Support
-for desktop is deprecated and will be removed soon.)
+Instructions for running the program with Flutter on Android follow.
+TODO(alexfandrianto): Add instructions for running the Go version.
# Prerequisites
@@ -18,6 +20,12 @@
Please ensure that your Mojo checkout is located at $MOJO_DIR and has built
out/android_Debug. Instructions are available [here](https://github.com/domokit/mojo).
+## Flutter
+
+Development now also depends on the alpha branch of the Flutter repo. It is
+possible that the `pubspec.yaml` file will need to be modified to accomodate
+your installation of Flutter. Instructions are available [here](http://flutter.io/getting-started/).
+
## Dart
Flutter depends on a relatively new version of the Dart SDK. Therefore, please
@@ -34,15 +42,26 @@
## Vanadium
-A Vanadium installation is expected, since Croupier also depends on the
-https://github.com/vanadium/mojo.discovery project.
+A Vanadium installation is not required since Croupier pulls all of its
+Vanadium-related dependencies from pub.
# Running Croupier
## Credentials
-Begin by creating your credentials. These are used to determine who can access
-your Syncbase instance. Note that running the following command will pop-up the
+There are two ways to get credentials. These are used to determine who can
+access your Syncbase instance. __You do not need to follow both instructions.__
+
+### On-Device OAuth Credentials
+
+One way to obtain them is through OAuth. When Syncbase is started on Android,
+it will ask you to select an account. You must have an account added on the
+Android device for this to work.
+
+### Test Credentials
+
+During tests, it may be more convenient to create test credentials locally and
+push them onto the phone. Note: running the following command will pop-up the
standard `principal seekblessings` tab in order to obtain your approval to use
OAuth.
@@ -50,7 +69,7 @@
make creds
```
-__Any time you clean the credentials, you will need to obtain fresh credentials.__
+__If you clean the credentials, you will need to obtain fresh credentials.__
## Note on Multiple Devices
@@ -76,14 +95,9 @@
ANDROID=1 make start
```
-Alternatively, use a different integer. Since the first device creates a syncgroup,
-it is recommended that you wait a short duration before starting up any other devices.
-
-Note: Some devices may limit the number of characters the `adb connect` command
-accepts. If this is the case, the app will not launch under `make start`. One
-workaround is to delete some non-critical lines in the Makefile, such as
-`--checked` and `--free-host-ports`.
-See https://github.com/vanadium/issues/issues/831
+Alternatively, use a different integer. Since the first device creates a
+syncbase instance that the others are mounted upon, it is recommended that this
+one is started before the other devices.
## Deleting Mojo Shell
@@ -99,15 +113,13 @@
Due to some issues with mojo_shell, you may occasionally fail to start the
program due to a used port. Follow the error's instructions and try again.
-Between builds of Mojo and Syncbase, you may wish to clean the app and database
-info (for rooted devices only) up.
+Between builds of Mojo and Syncbase, you may wish to clean up the app and
+database info.
```
ANDROID=1 make clean
```
-For non-rooted devices, you can manually clear the data of the Mojo Shell app.
-
You can also clean credentials instead:
```
diff --git a/schema.md b/schema.md
new file mode 100644
index 0000000..c1e4bda
--- /dev/null
+++ b/schema.md
@@ -0,0 +1,91 @@
+# Overview
+
+Croupier uses Syncbase to store game data and player settings. It is the primary
+means of communication between players. Since Syncbase Mojo only allows storage
+of bytes, the schema for Croupier assumes only string keys and values.
+
+# Game Table
+
+This table stores information about all the games that the player has ever
+participated in. The schema is as follows:
+
+```
+For advertising and setting up the game:
+<game_id>/type = <game_type>
+<game_id>/owner = <user_id>
+<game_id>/players/<user_id>/player_number = <player_number>
+
+For the game log writer:
+<game_id>/log/<timestamp>-<player_id> = <command_string>
+<game_id>/log/proposals/<player_number> = <JSON-encoded Proposal>
+```
+
+The game log writer is a protocol where all players in the same game write their
+moves to a game log. Games are structured such that replay of the log in key
+order will lead to the exact same UI state.
+
+When player actions are turn-based or independent from each other, players
+writes can occur to the log in an order enforced by the application. However, if
+the actions are dependent, then the proposals protocol is followed.
+
+Proposals are described below. Since the proposal system is not efficient with
+the current implementation of Syncbase, it has been avoided as much as possible.
+
+```
+// Proposals are used to obtain consensus between all players when a game allows
+// users to make actions simultaneously that conflict with each other. When a
+// proposal is made, players will agree with the proposal with the lowest
+// timestamp (and player_number, if there are ties). Once all players are in
+// agreement, no further changes can be made, so the command proposed can be
+// safely executed. This protocol ensures that only one of these conflicting
+// actions can proceed.
+struct Proposal {
+ timestamp int // When the proposal was created.
+ command_string string // What ought to be run if the proposal goes through.
+ player_number int // Original player that proposed this command.
+}
+```
+
+# Settings Table
+
+This table stores information about the player and every user they have ever
+interacted with. The schema is as follows:
+
+```
+users/<user_id>/settings = <JSON-encoded Settings>
+users/personal = <user_id>
+```
+
+The settings table will inform the user of their random, unique `<user_id>`.
+When a user id is found, the relevant settings data can be retrieved and
+displayed. The user is allowed to personalize their profile.
+
+```
+// Settings contains the personal settings for a Croupier player.
+// This consists of fake identifying information that helps them differentiate
+// themselves from each other during the game.
+// Note: This is NOT tied to the user's blessing, so it should never be used for
+// authentication or authorization purposes.
+struct Settings {
+ userID int // Cannot be changed by the user.
+ avatar string // Must point to an avatar asset bundled into the app.
+ name string // The user's display name in-game. Usually a pseudonym.
+ color int // An 8 digit hex-encoded integer. 0x{alpha}{red}{green}{blue}
+}
+```
+
+## Syncgroups
+
+Croupier has two types of Syncgroups: one for games and one for settings.
+* Game Syncgroups
+ * Table: The Games table, Prefix: `<game_id>`
+ * ACLs are not implemented, but in theory, it would be like this:
+ * ACL: Owner: RWA, Players: RW, NonPlayers: RW ==> R (after game starts)
+* Settings Syncgroups are based on the `<user_id>` prefix.
+ * Table: The Settings table, Prefix: `<user_id>`
+ * ACLs are not implemented, but in theory, it would be like this:
+ * ACL: Owner: RWA, Other Players: R
+
+When a game is created, the owner will advertise both the game Syncgroup as well
+as their own settings Syncgroup. Players can discover the owner's `<game_id>`
+and `<user_id>` and decide if they wish to join that game.
