[][src]Crate mem6

"unForGetTable" (development name: mem6)

version: 2020.214.1939

mem6 is a simple drinking game to lose memory. It is made primarily for learning the Rust programming language and Wasm/WebAssembly with Virtual Dom Dodrio, WebSocket communication and PWA (Progressive Web App).

Idea

Playing the memory game alone is boring.
Playing it with friends is better. Playing with drinking friends is even better. More friends - more fun.
I hope you have at least 3 or 4 friends now and all of you are around the same table.
The first player opens bestia.dev/mem6 and starts the group. Other players scan the QR code and join the same group. Then put all phones on the table near to each other. It will look as a "big" board game.
The game is hyper simple: every player opens 2 cards. If the cards are the same, you drink. If not you don't drink. Then the next player opens 2 cards. And so on...

Rust and Wasm/WebAssembly

Rust is a pretty new language created by Mozilla for really low level programming.
It is a step forward from the C language with functionality and features that are best practice today.
It is pretty hard to learn. Some concepts are so different from other languages it makes it hard for beginners. Lifetimes are the strangest and most confusing concept.
The Rust language has been made from the ground up with an ecosystem that makes it productive.
The language and most of the libraries are Open Source. That is good and bad, but mostly good.
Rust is the best language today to compile into Wasm/WebAssembly.
That compiled code works inside a browser directly with the JavaScript engine.
So finally no need for JavaScript to make cross-platform applications inside browsers.
I have a lot of hope here.

Virtual DOM

Constructing a HTML page with Virtual DOM (vdom) is easier because it is scheduled to render completely on the next tick (animation frame). We can use the term here "state machine". The rendering depends only on the state of the data and not on the history of the changes.
Sometimes is very complex what should change in the UI when some data changes.
The data can change from many different events and very chaotically (asynchronously).
It is easier to think how to render the complete DOM for a given state of data.
The Rust Dodrio library has ticks, time intervals when it does something. If a rendering is scheduled, it will be done on the next tick. If a rendering is not scheduled I believe nothing happens.
This enables asynchronous changing of data and rendering. They cannot happen theoretically in the same exact moment. So, no data race here.
When GameData change and we know it will affect the DOM, then rendering must be scheduled.
The main component of the Dodrio Virtual Dom is the Root Rendering Component (rrc).
It is the component that renders the complete user interface (HTML) and contains all the data state.

GameData

All the game data state are in this simple struct inside the Root Rendering Component.

WebSocket communication

HTML5 has finally bring a true stateful bidirectional communication.
Most of the programming problems are more easily and effectively solved this way.
The old unidirectional stateless communication is very good for static html pages, but is terrible for any dynamic page. The WebSocket is very rudimental and often the communication breaks for many different reasons. The programmer must deal with it inside the application.
I send simple structs text messages in json format between the players. They are all in the WsMsg enum and therefore easy to use by the server and client.
The WebSocket server is coded especially for this game and recognizes the players string that has a vector of ws_uid to whom send the message.

WebSockets is not reliable

Simple messaging is not reliable. On mobiles it is even worse. There is a lot of possibilities that something goes wrong and the message doesn't reach the destination. The protocol has nothing that can be used to deal with reconnections or lost messages.
That means that I need additional work on the application level - always reply one acknowledgement "ack" message.
Workflow:

This is very similar to a message queue...

gRPC, WebRTC datachannel

The new shiny protocol gRPC for web communication is great for server-to-server communication. But it is still very limited inside the browser. When it eventually becomes stable I would like to change WebSockets for gRPC.
The WebRTC datachannel sounds great for peer-to-peer communication. Very probably the players will be all on the same wifi network, this solves all latency issues.
TODO: try to add this to version 6.

The game flow

In a few words:
Playing player : Status1 - user action - send msg - await for ack msgs - update game data - Status2
Other players: Status1 - receive WsMessage - send ack msg - update game data - Status2

In one moment the game is in a one Game Status for all players.
One player is the playing player and all others are awaiting.
The active user then makes an action on the GUI. This action will eventually change the GameData and the GameStatus. But before that there is communication.
A message is sent to other players so they can also change their local GameData and GameStatus.
Because of unreliable networks there must be an acknowledge ack msg to confirm, that the msg is received to continue the game.
The rendering is scheduled and it will happen shortly (async).

Futures and Promises, Rust and JavaScript

JavaScript is all asynchronous. Wasm is nothing else then a shortcut to the JavaScript engine.
So everything is asynchronous too. This is pretty hard to grasp. Everything is Promises and Futures. Fortunately lately there is async/await for Rust and it is great for dealing with javascript.
JavaScript does not have a good idea of Rust datatypes. All there is is a generic JSValue type.
The library wasm-bindgen has made a fantastic job of giving Rust the ability to call anything JavaScript can call, but the way of doing it is sometimes cumbersome.

Html templating

In the past I wrote html inside Rust code with the macro html! from the crate typed-html
https://github.com/bodil/typed-html
It has also a macro dodrio! created exclusively for the dodrio vdom.
I had two main problems with this approach:

  1. Any change to the html required a recompiling. And that is very slow in Rust.
  2. I could not add new html elements, that the macro don't recognize. I wanted to use SVG. There was not support for that.

I reinvented "html templating".
First a graphical designer makes a html/css page that looks nice. No javascript, nothing is dynamic. It is just a graphical template.
Then I insert in it html comments and "data-" attributes that I can later replace in my code.
The html is not changed graphically because of it. So both the graphical designer and the programmer are still happy.
In my code I parse the html template as a microXml file. Basically they are the same with small effort. When I find a comment or "data-" attribute then the value of the next node is replaced.
I can replace attributes, strings and entire nodes. And I can insert event for behavior with "data-t".
When developing, the html template is loaded and parsed and a dodrio node is created. That is not very fast. But I can change the html in real time and see it rendered without compiling the Rust code. This is super efficient for development.
I have in plans to add a Rust code generator, that creates the Rust code for the dodrio node before compile time. In that case nothing is parsed in runtime and I expect great speeds. But the flexibility of easily changing the html template is gone. For every change I must recompile the Rust code.

Browser console

At least in modern browsers (Firefox and Chrome) we have the developer tools F12 and there is a console we can output to. So we can debug what is going on with our Wasm program. But not on smartphones !! I save the error and log messages in sessionStorage and this is displayed on the screen.

Safari on iOS and FullScreen

Apple is very restrictive and does not allow fullscreen Safari on iPhones.
The workaround is to Add to HomeScreen the webapp.

PWA (Progressive Web App)

On both android and iPhone is possible to use PWA.
To be 100% PWA it must be secured with TLS and must have a service worker.
I added also the PWA manifest and png images for icons and now the game is a full PWA.

Very important : On Android Chrome to Clear & reset the cached data of the website you must click on the icon of the URL address (the lock) and choose Site Settings.
Sometimes even that does not work. Than I go in the Menu to Settings - Privacy - Clear browser data and delete all. Very aggressive, but the only way I found that works.

Modules

Rust code is splitted into modules. They are not exactly like classes, but can be similar.
Rust has much more freedom to group code in different ways. So that is best suits the problem.
I splitted the rendering pages and that into sub-components.
And then I splitted the User Actions by the Status1 to easy follow the flow of the game.
I try to use the philosophy od "state machine" because is easier to follow.

Clippy

Clippy is very useful to teach us how to program Rust in a better way.
These are not syntax errors, but hints how to do it in a more Rusty way (idiomatic).
Some lints are problematic and they are explicitly allowed here.

font-size

Browsers have 2 types of zoom:

When the font-size in android is increased (accessibility) it applies somehow also to the browser rendering.
I have tried many different things, but it looks this cannot be overridden from the css or javascript. Only the user can change this setting in his phone.

SVG

This is why I chose to use SVG for my html templates. Svg promises that the user cannot ruin the layout completely. But also SVG has its set of complication small and big.
It is annoying that SVG must use namespaces for all the elements and subelements.
I will use percents to define x, y, width and height. Because for the game is only logical to be always full screen.

font-family

The size of the font depends a lot of the font-family. Every browser show different fonts even when they call them the same. I need to use a third-party web font. Google seems to be a good source of free fonts. I choose Roboto. Having them download every time from google is time consuming. So I will download them and host them locally on my website.
I use the https://google-webfonts-helper.herokuapp.com to download fonts.

favicon.ico

Crazy stuff. I used the website https://www.favicon-generator.org/ to generate all the different imgs, sizes and code. And than add all this into index.html. There is more lines for icons than anything else now. Just crazy world.

Modules

ackmsgmod

acknowledge msg

divfordebuggingmod

information for debugging

divgridcontainermod

renders the grid container with the images and most important the on click event

divnicknamemod

load and save nickname

divplayeractionsmod

renders the div to inform player what to do next and get a click action from the user

fetchallimgsforcachemod

fetch all imgs for cache

fetchgameconfigmod

fetch game_config

fetchgamesmetadatamod

fetch the names of all games

fetchmod

Async world

fncallermod

fncallermod

gamedatamod

structs and methods around game data

htmltemplatemod

htmltemplatemod
html templating for dodrio

logmod

logging in wasm

rootrenderingcomponentmod

renders the web page

routermod

A simple #-fragment router for dodrio.

sessionstoragemod

for debugging texts accessible everywhere

status1stcardmod

code flow from this status

status2ndcardmod

code flow from this status

statusdrinkmod

code flow from this status

statusgamedatainitmod

code flow from this status

statusgameovermod

code flow from this status

statusjoinedmod

code flow for this status

statustaketurnmod

code flow from this status

statuswaitingackmsgmod

code flow from this status

utilsmod

small generic helper functions

websocketcommunicationmod

module that cares about WebSocket communication

websocketreconnectmod

reconnection for websocket must be part of the application.

Functions

__wasm_bindgen_generated_wasm_bindgen_start

To start the Wasm application, wasm_bindgen runs this functions

get_url_and_hash

get url and hash from window.location

wasm_bindgen_start

To start the Wasm application, wasm_bindgen runs this functions