132 lines
3.5 KiB
Markdown
132 lines
3.5 KiB
Markdown
# 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`.
|