@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.10

package/src/core/avatar/avatar-ref.ts

@@ -0,0 +1,34 @@
+/** Building {@link AvatarRef}s from codes, payloads and seeds. */
+import { decodeLook, defaultLook, encodeLook } from '@diffenderfer-games/hub-contract/avatar';
+import type { AvatarRef } from './avatar-types';
+
+/** A ref for a code (`''` = hidden). */
+export function refOf(code: string, isDefault = false): AvatarRef {
+  if (code === '') {
+    return { code: '', look: null, isDefault: false, hidden: true };
+  }
+  return { code, look: decodeLook(code)?.look ?? null, isDefault, hidden: false };
+}
+
+/** A seeded default look as a ref (bots, previews, local pass-and-play seats). */
+export function botRef(seed: string | number): AvatarRef {
+  const look = defaultLook(seed);
+  return { code: encodeLook(look), look, isDefault: true, hidden: false };
+}
+
+/** Anything that carries a player's look: a seat, a `PlayerLite`, a racer, a ticket user. */
+export interface CarriesLook {
+  readonly look?: string;
+  readonly userId?: number;
+  readonly id?: number;
+  readonly uid?: number;
+}
+
+/** The ref a payload carries; an old hub's payload (no `look`) falls back to the id's default. */
+export function refFrom(carrier: CarriesLook): AvatarRef {
+  if (carrier.look !== undefined) {
+    return refOf(carrier.look);
+  }
+  const id = carrier.userId ?? carrier.id ?? carrier.uid;
+  return id === undefined ? refOf('') : botRef(id);
+}

package/src/core/avatar/avatar-types.ts

@@ -0,0 +1,43 @@
+/** The shapes `hub.avatar` works with (avatars.md §6). */
+import type { AvatarLook } from '@diffenderfer-games/hub-contract/avatar';
+
+/**
+ * A player's avatar as games hold it: the code (pass it to any renderer),
+ * the decoded look, whether it is their generated default, and whether the
+ * player is hidden from you (draw the silhouette).
+ */
+export interface AvatarRef {
+  readonly code: string;
+  /** `null` when hidden or the code is malformed (renderers draw the silhouette). */
+  readonly look: AvatarLook | null;
+  /** They never designed one: this is their generated default. */
+  readonly isDefault: boolean;
+  /** Hidden where the username is hidden (§2.8). */
+  readonly hidden: boolean;
+}
+
+/** A player's avatar changed (`hub.avatar.on('change')`). */
+export interface AvatarChange {
+  readonly userId: number;
+  readonly ref: AvatarRef;
+}
+
+/** Options for the designer. */
+export interface OpenDesignerOptions {
+  /** Why it opened (`'game'`, `'world'`, …), for metrics only. */
+  readonly reason?: string;
+}
+
+/** What the designer reports when it closes. */
+export interface DesignerResult {
+  /** The player saved a new look. */
+  readonly saved: boolean;
+}
+
+/** What the social runtime adds for avatars (feature version 5). */
+export interface RuntimeAvatarApi {
+  /** Open "Make your avatar" over the page; resolves when it closes. */
+  openDesigner(options?: OpenDesignerOptions): Promise<DesignerResult>;
+  /** Live `ev:avatar` changes (yours, friends', your room's). */
+  on(event: 'change', listener: (change: { readonly userId: number; readonly code: string }) => void): () => void;
+}

package/src/core/avatar/hub-avatar.ts

@@ -0,0 +1,308 @@
+/**
+ * `hub.avatar` (avatars.md §6): players' looks without the renderer. Codes
+ * arrive in payloads (seats, `PlayerLite`, racers), so `from()` needs no
+ * request; `of()` and `many()` batch and cache the rest; your own look is
+ * cached on the device so it works offline. `load()` brings in the renderer
+ * (`@diffenderfer-games/hub/avatar`) and its art when a game wants to draw.
+ *
+ * It follows the page's account (the menu's account events, the runtime's
+ * socket hello, this client's sign-ins): when your account appears or
+ * changes, or the hello says your look is not the one cached, your look is
+ * fetched again and `change` fires. Each hello also re-checks the players
+ * this page asked about, so a change sent while the socket was down is not
+ * missed.
+ */
+import type { MyAvatar } from '@diffenderfer-games/hub-contract';
+import { encodeLook, type AvatarLook } from '@diffenderfer-games/hub-contract/avatar';
+import type * as AvatarEntry from '../../avatar';
+import { pageBridge } from '../../realtime/bridge';
+import { createRuntimeOpener } from '../../realtime/runtime-opener';
+import type { AccountListener, PageUser } from '../page-account';
+import { AvatarCache } from './avatar-cache';
+import { botRef, refFrom, refOf, type CarriesLook } from './avatar-ref';
+import type { AvatarChange, AvatarRef, DesignerResult, OpenDesignerOptions } from './avatar-types';
+import { createPageStore } from '../storage/key-value';
+
+/** What `hub.avatar` needs from its client. */
+export interface AvatarHost {
+  /** The signed-in user's id, or `null` (`hub.userId()`). */
+  readonly currentUserId: () => number | null;
+  /** Hear every report of who is signed in (the page's account). */
+  readonly onAccount: (listener: AccountListener) => () => void;
+  /** `GET /avatar/me`; rejects when offline. */
+  readonly fetchMine: () => Promise<MyAvatar>;
+  /** `POST /avatar/batch`. */
+  readonly fetchCodes: (ids: readonly number[]) => Promise<Record<string, string>>;
+  /** Queue a save of your look (sent now when online, replayed later when not). */
+  readonly queueSave: (code: string, savedAt: number) => Promise<void>;
+}
+
+/** The renderer module `load()` resolves with. */
+export type AvatarModule = typeof AvatarEntry;
+
+type ChangeListener = (change: AvatarChange) => void;
+
+const BATCH_MAX = 100;
+const openWithRuntime = createRuntimeOpener(pageBridge);
+
+/** The look `mine()` gives before the account exists (a new guest's is being made). */
+const NO_ACCOUNT_YET = botRef('you');
+
+/** `hub.avatar`. */
+export class HubAvatar {
+  private readonly host: AvatarHost;
+  private readonly cache = new AvatarCache(createPageStore());
+  private readonly listeners = new Set<ChangeListener>();
+  private pending = new Map<number, ((code: string) => void)[]>();
+  private flushQueued = false;
+  private detachRuntime: (() => void) | null = null;
+  /** The account the last report named. */
+  private lastUserId: number | null;
+  /** The code of your look the page was last given (`mine`, `mineSync`, `change`). */
+  private mineShown: string | null = null;
+  /** Players this page asked about or was handed (re-checked on each socket hello). */
+  private readonly seen = new Set<number>();
+
+  constructor(host: AvatarHost) {
+    this.host = host;
+    this.lastUserId = host.currentUserId();
+    host.onAccount((user, source) => {
+      this.onAccount(user, source === 'session');
+    });
+  }
+
+  /**
+   * Your look (your default if you never designed one). Works offline from
+   * the device cache. Before your account exists (a new guest's is made just
+   * after the game starts) it resolves at once with a default look, and
+   * `change` brings yours when the account is there.
+   */
+  async mine(): Promise<AvatarRef> {
+    const userId = this.host.currentUserId();
+    if (userId === null) {
+      return this.showMine(NO_ACCOUNT_YET);
+    }
+    try {
+      const mine = await this.host.fetchMine();
+      return this.noteMine(userId, mine);
+    } catch (failure) {
+      const cached = this.mineSync();
+      if (cached !== null) {
+        return cached;
+      }
+      throw failure;
+    }
+  }
+
+  /** Your cached look, or your default; `null` only while nobody is signed in. */
+  mineSync(): AvatarRef | null {
+    const userId = this.host.currentUserId();
+    if (userId === null) {
+      return null;
+    }
+    const cached = this.cache.readMine(userId);
+    return this.showMine(cached === null ? botRef(userId) : refOf(cached.code, cached.isDefault));
+  }
+
+  /** Any player's look: from the cache, else batched with other requests in the same tick. */
+  of(userId: number): Promise<AvatarRef> {
+    this.seen.add(userId);
+    const cached = this.cache.codeOf(userId);
+    if (cached !== undefined) {
+      return Promise.resolve(refOf(cached));
+    }
+    return new Promise((resolve) => {
+      const waiting = this.pending.get(userId) ?? [];
+      waiting.push((code) => {
+        resolve(code === '' ? botRef(userId) : refOf(code));
+      });
+      this.pending.set(userId, waiting);
+      this.scheduleFlush();
+    });
+  }
+
+  /** Many players' looks at once. */
+  async many(userIds: readonly number[]): Promise<Map<number, AvatarRef>> {
+    const refs = await Promise.all(userIds.map(async (id) => [id, await this.of(id)] as const));
+    return new Map(refs);
+  }
+
+  /** The look a payload already carries (a `RoomSeat`, `PlayerLite`, racer or ticket user). No request. */
+  from(carrier: CarriesLook): AvatarRef {
+    const ref = refFrom(carrier);
+    const id = carrier.userId ?? carrier.id ?? carrier.uid;
+    if (id !== undefined && carrier.look !== undefined) {
+      this.seen.add(id);
+      this.cache.remember(id, carrier.look);
+    }
+    return ref;
+  }
+
+  /** A seeded default for bots, previews and local pass-and-play seats: `bot('local:2')`. */
+  bot(seed: string | number): AvatarRef {
+    return botRef(seed);
+  }
+
+  /** Save your look (designer code paths; queued offline, latest wins). */
+  async save(look: AvatarLook): Promise<AvatarRef> {
+    const code = encodeLook(look);
+    const savedAt = Date.now();
+    const userId = this.host.currentUserId();
+    if (userId !== null) {
+      this.noteMine(userId, { code, isDefault: false, updatedAt: savedAt });
+    }
+    await this.host.queueSave(code, savedAt);
+    return refOf(code);
+  }
+
+  /**
+   * Hear about look changes (yours, friends', your room's, and yours when
+   * your account appears). Returns the unsubscribe function. Wait for this
+   * rather than polling `mine()`.
+   */
+  on(_event: 'change', listener: ChangeListener): () => void {
+    this.listeners.add(listener);
+    this.attachRuntime();
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** Open "Make your avatar" over the game; resolves when it closes. */
+  openDesigner(options: OpenDesignerOptions = {}): Promise<DesignerResult> {
+    return new Promise((resolve) => {
+      openWithRuntime((realtime) => {
+        if (realtime.avatar === undefined) {
+          resolve({ saved: false });
+          return;
+        }
+        void realtime.avatar.openDesigner(options).then(resolve, () => {
+          resolve({ saved: false });
+        });
+      });
+    });
+  }
+
+  /** Loads the renderer and its art; resolves when rendering is synchronous. */
+  async load(): Promise<AvatarModule> {
+    const avatar = await import('../../avatar');
+    await avatar.ready();
+    return avatar;
+  }
+
+  /** Remember the ref the page was given for your look. */
+  private showMine(ref: AvatarRef): AvatarRef {
+    this.mineShown = ref.code;
+    return ref;
+  }
+
+  /** Cache your look; `change` fires when it differs from the one the page last had. */
+  private noteMine(userId: number, mine: Pick<MyAvatar, 'code' | 'isDefault' | 'updatedAt'>): AvatarRef {
+    const before = this.mineShown ?? this.cache.readMine(userId)?.code ?? null;
+    this.cache.writeMine({ userId, code: mine.code, isDefault: mine.isDefault, updatedAt: mine.updatedAt });
+    const ref = this.showMine(refOf(mine.code, mine.isDefault));
+    if (mine.code !== before) {
+      this.emit({ userId, ref });
+    }
+    return ref;
+  }
+
+  /** Someone said who is signed in: fetch your look when the account is new or its look isn't the cached one. */
+  private onAccount(user: PageUser | null, isHello: boolean): void {
+    const userId = user === null || user.id === 0 ? null : user.id;
+    const isNewAccount = userId !== this.lastUserId;
+    this.lastUserId = userId;
+    if (user === null || userId === null) {
+      return;
+    }
+    if (isNewAccount || (user.look !== null && user.look !== this.cache.readMine(userId)?.code)) {
+      void this.refreshMine(userId);
+    }
+    if (isHello) {
+      void this.recheckSeen();
+    }
+  }
+
+  private async refreshMine(userId: number): Promise<void> {
+    const mine = await this.host.fetchMine().catch(() => null);
+    if (mine !== null && this.host.currentUserId() === userId) {
+      this.noteMine(userId, mine);
+    }
+  }
+
+  /** The socket (re)connected: a change sent while it was down never arrived, so ask again. */
+  private async recheckSeen(): Promise<void> {
+    if (this.listeners.size === 0 || this.seen.size === 0) {
+      return;
+    }
+    const codes = await this.fetchCodes([...this.seen]);
+    for (const [userId, code] of codes) {
+      if (code !== '' && code !== this.cache.codeOf(userId)) {
+        this.cache.remember(userId, code);
+        this.emit({ userId, ref: refOf(code) });
+      }
+    }
+  }
+
+  private emit(change: AvatarChange): void {
+    for (const listener of this.listeners) {
+      listener(change);
+    }
+  }
+
+  private attachRuntime(): void {
+    if (this.detachRuntime !== null) {
+      return;
+    }
+    this.detachRuntime = pageBridge.subscribe((realtime) => realtime.avatar?.on('change', ({ userId, code }) => {
+      if (userId === this.host.currentUserId()) {
+        this.noteMine(userId, { code, isDefault: false, updatedAt: Date.now() });
+        return;
+      }
+      this.cache.remember(userId, code);
+      this.emit({ userId, ref: refOf(code) });
+    }) ?? (() => undefined));
+  }
+
+  private scheduleFlush(): void {
+    if (this.flushQueued) {
+      return;
+    }
+    this.flushQueued = true;
+    queueMicrotask(() => {
+      this.flushQueued = false;
+      void this.flush();
+    });
+  }
+
+  private async flush(): Promise<void> {
+    const batch = this.pending;
+    this.pending = new Map();
+    const codes = await this.fetchCodes([...batch.keys()]);
+    for (const [id, waiting] of batch) {
+      const code = codes.get(id) ?? '';
+      if (code !== '') {
+        this.cache.remember(id, code);
+      }
+      for (const resolve of waiting) {
+        resolve(code);
+      }
+    }
+  }
+
+  /** Players' codes, in batches; offline or failing, the missing ones are left out (they get their default). */
+  private async fetchCodes(ids: readonly number[]): Promise<Map<number, string>> {
+    const codes = new Map<number, string>();
+    for (let i = 0; i < ids.length; i += BATCH_MAX) {
+      const slice = ids.slice(i, i + BATCH_MAX);
+      const answered = await this.host.fetchCodes(slice).catch((): Record<string, string> => ({}));
+      for (const id of slice) {
+        const code = answered[String(id)];
+        if (code !== undefined) {
+          codes.set(id, code);
+        }
+      }
+    }
+    return codes;
+  }
+}