# 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

```ts
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

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

---

## File layout

```text
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`.