From 2dcf55af1685a9a1c6992d3303e9d49f879bddb8 Mon Sep 17 00:00:00 2001
From: Jeremy Randolph <jer@argus.gg>
Date: Tue, 29 Aug 2023 14:36:24 -0700
Subject: [PATCH] Add some README instructions for the Nakama console

---
 README.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 105 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index c61ca97..f2ccc5a 100644
--- a/README.md
+++ b/README.md
@@ -62,13 +62,116 @@ We will add a future to hot reload this in the future.
 
 # Verify the Server is Running
 
-Visit `localhost:7351` in a web browser to access Nakama. For local development, use `admin:password` as your login
+Visit `localhost:7351` in a web browser to access the Nakama console. For local development, use `admin:password` as your login
 credentials.
 
 The Account tab on the left will give you access to a valid account ID.
 
 The API Explorer tab on the left will allow you to make requests to Cardinal.
 
+# Nakama Console
+
+You can verify the Nakama server is running by visiting `localhost:7351` in a web browser. For local development, use 
+`admin:password` as our login credentials.
+
+## API Explorer
+
+The API Explorer (on the sidebar) allows you to make requests to both Nakama and your Cardinal server.
+
+### Creating a User ID
+
+Before using any endpoints, you need to populate the User ID field (between the endpoint dropdown and the submit button). 
+The user ID `00000000-0000-0000-0000-000000000000` is a special admin user ID that will always be defined. Alternatively, 
+a new user can be created by selecting the `Authenticate Device` endpoint from the dropdown. Populate the request boy
+with a payload like:
+
+```json
+{
+  "account": {
+    "id": "123456789123456789"
+  },
+  "create": true,
+  "username": "some-username"
+}
+```
+
+And hit `Submit` no. User ID is required for this endpoint.
+
+To get the User ID of your newly created account, click the `Accounts` item in the sidebar. Copy the relevant User ID 
+and paste it into the User ID field on the API Explorer to hit other endpoints.
+
+### Claiming a Persona Tag
+
+A persona tag is essentially a cardinal based user. To create a persona tag in your cardinal game, select the `nakama/claim-persona` 
+endpoint from the dropdown. Make sure to paste in a valid User ID into the User ID field. Set the request body to:
+```json
+{
+  "persona_tag": "some-persona-tag",
+}
+```
+
+and hit Submit. You should see a response like:
+
+```json
+{
+  "persona_tag": "some-persona-tag",
+  "status": "pending",
+  "tick": 2567,
+  "tx_hash": "0x6bc26694dee4c4163335e4fe01d73eab2da071f38b991ae8424fa52de330c228"
+}
+```
+
+This means cardinal received the request, and the request is pending. Change your endpoint to `nakama/show-persona` and hit
+Submit (no request body needed) to verify the claim-persona operation was successful. The response body should be similar
+to the `nakama/claim-persona` response, except "status" should now say "accepted".
+
+This mean both Nakama and Cardinal are aware of your Nakama user and the related Persona Tag.
+
+### Custom Transactions
+
+Once your persona tag has been set up, you send transactions to your custom cardinal transaction endpoints. If
+you set up a transaction like this:
+
+```go
+package main
+
+import (
+	"pkg.world.dev/world-engine/cardinal/ecs"
+	"pkg.world.dev/world-engine/cardinal/ecs/inmem"
+)
+
+type MoveMsg struct {
+	Dx, Dy int
+}
+
+type MoveReply struct {
+	FinalX, FinalY int
+}
+
+var MoveTx = ecs.NewTransactionType[MoveMsg, MoveReply]("move")
+
+func main() {
+	world := inmem.NewECSWorld()
+	world.RegisterTransaction(MoveTx)
+}
+```
+
+The dropdown will contain an entry with `tx-move`. The request body for that transaction could be:
+```json
+{
+	"Dx": 100,
+	"Dy": 200,
+}
+```
+
+Hit submit, and the transaction will be sent to your cardinal implementation. What your game does with the transaction
+depends on what Systems you've defined.
+
+## Storage
+
+The `Storage` item in the sidebar allows you to view Nakama user data. Storage objects with a key name of `persona_tag`
+describe which persona tag has been associated with user ID.
+
 # Cardinal Editor
 
 The Cardinal Editor is a web-based companion app that makes game development of Cardinal easier. It allows you to inspect the state of Cardinal in real-time without any additional code.
@@ -79,4 +182,4 @@ To work with the Cardinal Editor, you must first start the Cardinal server in de
 mage dev
 ```
 
-Then, open the [Cardinal Editor](https://editor.world.dev) in a web browser.
\ No newline at end of file
+Then, open the [Cardinal Editor](https://editor.world.dev) in a web browser.