OpenSpec Change: enterprise-gaming-emotes

Change ID: enterprise-gaming-emotes
Package: @suaveplan/emotes
Category: gaming/multiplayer
Target path: gaming/multiplayer/emotes
Status: PROPOSED
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/emotes.md

Summary

Deliver @suaveplan/emotes on the genesis branch from scratch at enterprise quality. The package provides an emote/expression system with a typed registry, per-emote cooldowns, and level-gated unlocking. An EmoteRegistry holds EmoteDefinition objects with animation clip reference, duration, and required level; an EmoteManager per player tracks active emote, enforces cooldown, and validates unlock status before playing; it fires @suaveplan/events emote:play and emote:stop events. Genesis adds Zod definition schemas, structured errors, OTel emote-play counter, injectable clock, and 100% coverage.

Current-state audit (genesis)

Package does not exist on genesis yet — fresh build.

Available workspace deps on genesis

Package	Role
`@suaveplan/error` (`workspace:^`)	`EmoteError`; `EMOTE.*` codes
`@suaveplan/types` (`workspace:^`)	`Clock`
`@suaveplan/events` (`workspace:^`)	`emote:play`, `emote:stop`, `emote:unlocked` events
`zod` (`catalog:forms`)	`EmoteDefinition` schema
`@opentelemetry/api` (`catalog:observability`)	Emote-play counter

Public API surface

interface EmoteDefinition {
  id: string
  name: string
  animationClipId: string
  duration: number           // seconds; 0 = loop until stopped
  cooldown?: number          // seconds, default 2
  requiredLevel?: number     // default 0 (available to all)
  category?: string
  isLooping?: boolean
}

function createEmoteRegistry(): EmoteRegistry
interface EmoteRegistry {
  register(def: EmoteDefinition): void
  get(id: string): EmoteDefinition | undefined
  listByCategory(category?: string): EmoteDefinition[]
}

function createEmoteManager(options: EmoteManagerOptions): EmoteManager

interface EmoteManagerOptions {
  playerId: string
  registry: EmoteRegistry
  unlockedIds?: string[]
  clock?: Clock
}

interface EmoteManager {
  play(emoteId: string, playerLevel?: number): EmotePlayResult
  stop(): void
  unlock(emoteId: string): void
  isUnlocked(emoteId: string): boolean
  isOnCooldown(emoteId: string): boolean
  tick(dt: number): void
  readonly activeEmote: EmoteDefinition | null
  readonly unlockedIds: ReadonlySet<string>
}

interface EmotePlayResult {
  emoteId: string
  startedAt: number
  endsAt: number | null   // null = looping
}

Error codes

type EmoteErrorCode =
  | 'EMOTE_NOT_FOUND'
  | 'EMOTE_LOCKED'
  | 'EMOTE_ON_COOLDOWN'
  | 'EMOTE_LEVEL_REQUIRED'
  | 'EMOTE_ALREADY_PLAYING'

File layout

gaming/multiplayer/emotes/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    error-codes.ts
    constants/index.ts
    types/common.ts
    types/common.md
    core/
      emote-registry/
        emote-registry.ts
        emote-registry.md
        emote-registry.test.ts
        index.ts
      emote-manager/
        emote-manager.ts
        emote-manager.md
        emote-manager.types.ts
        emote-manager.test.ts
        index.ts
  tests/
    integration.test.ts

Impact

Downstream: @suaveplan/r3f-animation plays the emote animation clip on the character. Prerequisites: @suaveplan/error, @suaveplan/types, @suaveplan/events.

3.5 KiB Raw Permalink Blame History