Major effort to re-organize, tidy-up, and fix the documentation!

backup/state-handling/overview.md

@@ -0,0 +1,15 @@
+# State Handling
+
+The room handlers are **stateful** in Colyseus. Each room holds its own state. The mutations of the state are synchronized automatically to all connected clients.
+
+## Serialization methods
+
+- [Schema](/state/schema/) (default)
+- [Fossil Delta](/state/fossil-delta/) (deprecated)
+
+## When the state is synchronized
+
+- When the user successfully joins the room, he receives the full state from the server.
+- At every [patchRate](/server/room/#patchrate-number), binary patches of the state are sent to every client (default is `50ms`)
+- [`onStateChange`](/client/room/#onstatechange) is called in the client-side after every patch received from the server.
+- Each serialization method has it's own particular way to handle incoming state patches.

docs/best-practices/overview.md

@@ -1,12 +1,138 @@
-# Best practices with Colyseus
+# Best practices & recommendations
 
-!!! Warning "Important"
-    This section needs improvement and more examples! Each paragraph needs it's own page with thorough examples and better explanation.
+!!! Note "Work-in-progress"
+    This documentation page is not complete
 
-- Keep your room classes as small as possible, without game logic.
+This section provides general recommendations and best practices to keep your codebase healthy and readable for your team. They are all optional, but if followed are going to improve code readability and cleanliness.
+
+- Keep your room classes as small as possible, delegating game-specific functionality to other composable structures.
 - Keep your synchronizeable data structures as small as possible
     - Ideally, each class extending `Schema` should only have field definitions.
     - Custom getters and setters methods can be implemented, as long as you don't have game logic in them.
 - Your game logic should be handled by other structures, such as:
-    - See how to use the [Command Pattern](/best-practices/command-pattern/).
-    - An Entity-Component System. We currently lack an ECS package that works well with Colyseus, some work [has started trying to combine ECSY with @colyseus/schema](http://github.com/endel/ecs).
+    - The [Command Pattern](#the-command-pattern).
+    - An [Entity-Component System](#entity-component-system-ecs).
+
+## Unit Testing
+
+> TODO: we need to provide a `@colyseus/testing` package to allow easily mocking the `Room` class and triggering its lifecycle events, as well as creating dummy clients.
+
+## Design Patterns
+
+### The Command Pattern
+
+**Why?**
+
+- Models ([`@colyseus/schema`](https://github.com/colyseus/schema)) should contain mostly data, without heavy game logic.
+- Rooms should have as little code as possible, and forward actions to other structures
+
+**The command pattern has several advantages, such as:**
+
+- It decouples the classes that invoke the operation from the object that knows how to execute the operation.
+- It allows you to create a sequence of commands by providing a queue system.
+- Implementing extensions to add a new command is easy and can be done without changing the existing code.
+- Have strict control over how and when commands are invoked.
+- Improves code readability and the possibility of unit testing.
+
+#### Usage
+
+Installation
+
+```
+npm install --save @colyseus/command
+```
+
+Initialize the `dispatcher` in your room implementation:
+
+```typescript fct_label="TypeScript"
+import { Room } from "colyseus";
+import { Dispatcher } from "@colyseus/command";
+
+import { OnJoinCommand } from "./OnJoinCommand";
+
+class MyRoom extends Room<YourState> {
+  dispatcher = new Dispatcher(this);
+
+  onCreate() {
+    this.setState(new YourState());
+  }
+
+  onJoin(client, options) {
+    this.dispatcher.dispatch(new OnJoinCommand(), {
+        sessionId: client.sessionId
+    });
+  }
+
+  onDispose() {
+    this.dispatcher.stop();
+  }
+}
+```
+
+```typescript fct_label="JavaScript"
+const colyseus = require("colyseus");
+const command = require("@colyseus/command");
+
+const OnJoinCommand = require("./OnJoinCommand");
+
+class MyRoom extends colyseus.Room {
+
+  onCreate() {
+    this.dispatcher = new command.Dispatcher(this);
+    this.setState(new YourState());
+  }
+
+  onJoin(client, options) {
+    this.dispatcher.dispatch(new OnJoinCommand(), {
+        sessionId: client.sessionId
+    });
+  }
+
+  onDispose() {
+    this.dispatcher.stop();
+  }
+}
+```
+
+How a command implementation looks like:
+
+```typescript fct_label="TypeScript"
+// OnJoinCommand.ts
+import { Command } from "@colyseus/command";
+
+export class OnJoinCommand extends Command<YourState, {
+    sessionId: string
+}> {
+
+  execute({ sessionId }) {
+    this.state.players[sessionId] = new Player();
+  }
+
+}
+```
+
+```typescript fct_label="JavaScript"
+// OnJoinCommand.js
+const command = require("@colyseus/command");
+
+exports.OnJoinCommand = class OnJoinCommand extends command.Command {
+
+  execute({ sessionId }) {
+    this.state.players[sessionId] = new Player();
+  }
+
+}
+```
+
+#### See more
+
+- See [command definitions](https://github.com/colyseus/command/blob/master/test/scenarios/CardGameScenario.ts)
+- See [usage](https://github.com/colyseus/command/blob/master/test/Test.ts)
+- See [implementation](https://github.com/colyseus/command/blob/master/src/index.ts)
+
+### Entity-Component System (ECS)
+
+We currently do not have an official ECS (Entity-Component System), although we've seen members of the community implement their own solutions.
+
+!!! Warning "Very experimental"
+    Some work [has started trying to combine ECSY with @colyseus/schema](http://github.com/endel/ecs).