kv docs

ref DRE-1449

Author: luludotdev

docs/guide/kv.mdx

@@ -0,0 +1,156 @@
+---
+sidebar_position: 999
+title: Key-Value (KV) Storage
+---
+
+# Key-Value Storage
+
+Dreamlab games are stateless by default, when a new instance is created the game is started fresh every time. In order
+to persist state between instances you can use the Key-Value (KV) API.
+
+Data stored in Dreamlab KV is scoped to the project, you cannot have cross-project persistent data. KV data is also
+scoped per-player, and players (clients) can only read/write to their own scope. The server has its own scope, and is
+also able to read/write to any player scopes.
+
+The KV API can be accessed by `this.game.kv` and exposes `get` / `set` / `list` / `delete` / `clear` methods. KV keys
+must be of `string` type, and values can be any JSON serializable value.
+
+## KV Debugger
+
+Attach this behavior script to a `UILayer` in the world root to debug the KV data stored in your project.
+
+```tsx title="kv-debugger.tsx"
+import { JsonValue, rpc, UIBehavior } from "@dreamlab/engine";
+
+export default class KvDebugger extends UIBehavior {
+  #player: string = "";
+  #players = new Set<string>();
+  #list: Record<string, JsonValue> = {};
+
+  @rpc.server()
+  async getKv(playerId: string) {
+    if (!this.game.isServer()) throw new Error("rpc not on server");
+    const kv = this.game.kv;
+
+    const [players, list] = await Promise.all([
+      kv.info.players(),
+      playerId === "" ? kv.server.list() : kv.player.list(playerId),
+    ]);
+
+    return { players: [...players], list };
+  }
+
+  async #update(): Promise<void> {
+    if (!this.game.isClient()) return;
+
+    const { players, list } = await this.getKv(this.#player);
+    this.#players = new Set(players);
+    this.#list = list;
+
+    this.rerender();
+  }
+
+  onInitialize(): void {
+    super.onInitialize();
+    if (!this.game.isClient()) return;
+
+    const css = `
+div.container {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  background: #252a36;
+  padding: 1rem;
+
+  & h1 {
+    margin: 0;
+  }
+
+  & div.selector {
+    display: flex;
+    gap: 1rem;
+  }
+
+  & div.data {
+    flex-grow: 1;
+    overflow-y: scroll;
+    padding-bottom: 2rem;
+
+    & > span {
+      font-style: italic;
+    }
+
+    & > div {
+      display: grid;
+      grid-template-columns: max-content auto;
+      gap: 0.4rem 1rem;
+
+      & > *:nth-child(1), & > *:nth-child(2) {
+        font-weight: bold;
+      }
+
+      & code, & pre {
+        margin: 0;
+        padding: 0;
+        font-family: var(--font-mono), monospace;
+        font-size: 0.9rem;
+      }
+    }
+  }
+}
+`;
+
+    this.setCss(css);
+    this.#update();
+  }
+
+  render() {
+    const entries = Object.entries(this.#list);
+
+    return (
+      <div className="container">
+        <h1>KV Debugger</h1>
+
+        <div className="selector">
+          <label htmlFor="player">Player Selector</label>
+          <select
+            id="player"
+            onChange={(ev) => {
+              if (!ev.target) return;
+              if (!(ev.target instanceof HTMLSelectElement)) return;
+
+              this.#player = ev.target.value;
+              this.#update();
+            }}
+          >
+            <option value="">[server]</option>
+            {[...this.#players].map((player) => (
+              <option value={player}>{player}</option>
+            ))}
+          </select>
+        </div>
+
+        <div className="data">
+          {entries.length === 0 ? (
+            <span>No data stored.</span>
+          ) : (
+            <div>
+              <span>Key</span>
+              <span>Value</span>
+
+              {entries.map(([key, value]) => (
+                <div style={{ display: "contents" }}>
+                  <code>{key}</code>
+                  <pre>{JSON.stringify(value)}</pre>
+                </div>
+              ))}
+            </div>
+          )}
+        </div>
+      </div>
+    );
+  }
+}
+```