alexei.dolgolyov
492bdb95e3
Receive real-time events from games (CS2, Dota 2, LoL, etc.) and drive LED effects through the existing color strip and value source pipelines. Core: - GameEventBus (thread-safe pub/sub) with standardized 23-type event vocabulary - GameAdapter ABC + AdapterRegistry + MappingAdapter (YAML-driven) - Built-in adapters: CS2 GSI, Dota 2 GSI, LoL Live Client, Generic Webhook - Community YAML adapters: Minecraft, Valorant, Rocket League - GameEventColorStripStream with 5 effects (flash/pulse/sweep/color_shift/breathing) - GameEventValueSource with EMA smoothing and timeout - 4 built-in effect presets (FPS Combat, MOBA Health, Racing, Generic Alert) - Auto-setup for Valve GSI games (Steam path detection, cfg file writing) - Demo capture engine exposed to non-demo mode Frontend: - Game tab in Streams tree navigation with integration cards - Game integration editor modal with adapter picker, config fields, event mappings - game_event source type in CSS and ValueSource editors - Setup instructions overlay (markdown rendered) - Live event monitor and connection test API: - Full CRUD for game integrations - Event ingestion endpoint (adapter-level auth) - Adapter metadata, presets, auto-setup, status/diagnostics endpoints
86 lines
4.1 KiB
Markdown
86 lines
4.1 KiB
Markdown
# Feature Context: Game Integration
|
|
|
|
## Configuration
|
|
- **Development mode:** Automated
|
|
- **Execution mode:** Orchestrator
|
|
- **Strategy:** Big Bang
|
|
- **Build (frontend):** `cd server && npm run build`
|
|
- **Test:** `cd server && py -3.13 -m pytest tests/ --no-cov -q`
|
|
- **Lint:** `cd server && ruff check src/ tests/ --fix`
|
|
- **TypeScript:** `cd server && npx tsc --noEmit`
|
|
|
|
## Architecture Decisions
|
|
|
|
### Not a Capture Engine
|
|
Game events are discrete data points, not pixel buffers. The integration lives as a separate `core/game_integration/` module with two output channels into existing pipelines:
|
|
1. `GameEventColorStripSource/Stream` — renders LED effects on game events
|
|
2. `GameEventValueSource` — exposes game metrics as 0.0-1.0 scalars for parameter binding
|
|
|
|
### Standardized Event Vocabulary
|
|
All adapters map game-specific data into universal event categories (health, kill, death, round_start, etc.). Users configure effects against categories, not game-specific IDs. This means a "health < 30% → flash red" config works across CS2, LoL, and any future game.
|
|
|
|
### Three Adapter Tiers
|
|
1. **Built-in** — CS2 GSI, LoL Live Client, Dota 2 GSI, generic webhook (ship with app)
|
|
2. **Community YAML** — declarative adapter files mapping JSON paths to standard events (no code)
|
|
3. **Generic webhook** — fallback with UI-guided JSON path mapping
|
|
|
|
### Event Types
|
|
- **Continuous** (health, armor, mana, ammo) → best for ValueSource (drive brightness/speed/color)
|
|
- **Trigger** (kill, death, round_start, bomb_planted) → best for ColorStripStream (fire effects)
|
|
|
|
## Tech Stack Context
|
|
|
|
### Backend Patterns (from codebase analysis)
|
|
- **Entity pattern**: dataclass model (`storage/`) + JSON/SQLite store (`storage/*_store.py`) + Pydantic schemas (`api/schemas/`) + routes (`api/routes/`)
|
|
- **Store base**: `BaseSqliteStore[T]` with write-through cache, RLock, `_check_name_unique()`
|
|
- **ID generation**: `f"{prefix}_{uuid.uuid4().hex[:8]}"`
|
|
- **Events**: `fire_entity_event(entity_type, action, entity_id)` for UI invalidation
|
|
- **ColorStripSource**: inheritance with `_SOURCE_TYPE_MAP` registry, `to_dict()`/`from_dict()`/`create_from_kwargs()`/`apply_update()`
|
|
- **ColorStripStream**: `_SIMPLE_STREAM_MAP` in `color_strip_stream_manager.py`
|
|
- **ValueSource**: similar inheritance with `_VALUE_SOURCE_MAP` registry
|
|
- **NotificationColorStripStream**: closest analog — event-driven, deque + lock, 30 FPS render loop, double-buffered output
|
|
- **Bindable**: `BindableFloat`/`BindableColor` for value source parameter binding
|
|
- **Dependencies**: `init_dependencies()` in `dependencies.py`, FastAPI `Depends()`
|
|
- **STORE_MAP**: in `api/routes/system.py` for backup/restore
|
|
|
|
### Frontend Patterns
|
|
- Vanilla TypeScript modules, no framework
|
|
- `CardSection` for entity lists with reconciliation
|
|
- `Modal` base class with `snapshotValues()` for dirty check
|
|
- `TreeNav` for sidebar navigation in Streams tab
|
|
- `DataCache` for state management
|
|
- `fetchWithAuth()` for all API calls
|
|
- `t('key')` for i18n, keys in en.json/ru.json/zh.json
|
|
- `fire_entity_event` → frontend listens for cache invalidation
|
|
- Icons from `core/icons.ts` (SVG paths), NEVER emoji
|
|
- `IconSelect` for predefined item grids, `EntitySelect` for entity references
|
|
|
|
## Current State
|
|
Feature not yet started. Branch created, plan files written.
|
|
|
|
## Temporary Workarounds
|
|
None yet.
|
|
|
|
## Cross-Phase Dependencies
|
|
- Phase 2 depends on Phase 1 (EventBus, AdapterRegistry)
|
|
- Phase 3 depends on Phase 1 (GameAdapter ABC, MappingAdapter)
|
|
- Phase 4 depends on Phase 1 (EventBus) and Phase 2 (GameIntegrationStore for config)
|
|
- Phase 5 depends on Phase 1 (EventBus) and Phase 2 (GameIntegrationStore)
|
|
- Phase 6 depends on Phase 2 (API endpoints) and Phase 3 (adapter metadata)
|
|
- Phase 7 depends on Phase 4 (CSS source type) and Phase 5 (value source type)
|
|
- Phase 8 depends on all prior phases
|
|
- **Phases 4 and 5 are independent** — can run in parallel
|
|
|
|
## Deferred Work
|
|
None yet.
|
|
|
|
## Failed Approaches
|
|
None yet.
|
|
|
|
## Review Findings Log
|
|
None yet.
|
|
|
|
## Phase Execution Log
|
|
| Phase | Agent Used | Test Writer | Parallel | Notes |
|
|
|-------|-----------|-------------|----------|-------|
|