OpenSpec Change: enterprise-gaming-fauna

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

Summary

Deliver @suaveplan/fauna on the genesis branch from scratch at enterprise quality. The package provides wildlife AI with herding behavior (Reynolds boids), predator-prey state machines, territorial zones, and taming mechanics. HerdSimulator runs separation/alignment/cohesion forces for a group of fauna instances; PredatorPreyFsm manages hunt/flee/rest state transitions; TerritoryZone defines a radius around a home position that triggers defend behavior when intruders enter; TamingManager tracks taming progress and trust state. Genesis adds Zod species definition schemas, structured errors, OTel population gauge, injectable clock and RNG, 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:^`)	`FaunaError`; `FAUNA.*` codes
`@suaveplan/types` (`workspace:^`)	`Clock`, `Rng`
`@suaveplan/events` (`workspace:^`)	`fauna:hunt`, `fauna:flee`, `fauna:tamed` events
`@suaveplan/npc` (`workspace:^`)	`SpawnPool` extended for wildlife instances
`@suaveplan/spatial-hash` (`workspace:^`)	Neighbor queries for boid steering
`zod` (`catalog:forms`)	`SpeciesDefinition` schema
`@opentelemetry/api` (`catalog:observability`)	Herd size gauge, hunt counter

Public API surface

interface SpeciesDefinition {
  id: string
  name: string
  role: 'prey' | 'predator' | 'neutral'
  maxSpeed: number
  perception: number       // detection radius (meters)
  territory?: number       // home territory radius
  herds?: boolean
  canBeTamed?: boolean
  tamingDifficulty?: number   // 1–10
}

// Boid herding
function createHerdSimulator(options: HerdOptions): HerdSimulator

interface HerdOptions {
  separationRadius: number
  alignmentRadius: number
  cohesionRadius: number
  separationWeight?: number
  alignmentWeight?: number
  cohesionWeight?: number
  spatialHash?: SpatialHash3D
}

interface HerdSimulator {
  update(agents: HerdAgent[], dt: number): HerdUpdate[]
}

interface HerdAgent {
  id: string
  position: Vec3
  velocity: Vec3
}

interface HerdUpdate {
  id: string
  steering: Vec3    // force to add to velocity
}

// Predator-prey FSM
type FaunaState = 'rest' | 'wander' | 'alert' | 'hunt' | 'flee' | 'defend'

function createPredatorPreyFsm(def: SpeciesDefinition, clock?: Clock): PredatorPreyFsm

interface PredatorPreyFsm {
  update(context: FaunaContext): FaunaState
  readonly state: FaunaState
}

interface FaunaContext {
  nearbyPrey: string[]
  nearbyPredators: string[]
  nearbyPlayers: string[]
  distanceToHome?: number
  health: number
  hungerLevel: number    // 0–1
}

// Taming
function createTamingManager(clock?: Clock): TamingManager

interface TamingManager {
  startTaming(playerId: string, faunaId: string, difficulty: number): void
  applyTamingAction(playerId: string, faunaId: string, action: TamingAction): TamingResult
  getProgress(playerId: string, faunaId: string): number   // 0–1
  isTamed(faunaId: string): boolean
}

type TamingAction = 'feed' | 'pet' | 'speak' | 'bribe'

interface TamingResult {
  progress: number
  tamed: boolean
  failed: boolean
}

Error codes

type FaunaErrorCode =
  | 'FAUNA_SPECIES_NOT_FOUND'
  | 'FAUNA_NOT_TAMEABLE'
  | 'FAUNA_TAMING_FAILED'
  | 'FAUNA_TERRITORY_INVALID'

New additions for genesis

Boid steering — separation/alignment/cohesion using @suaveplan/spatial-hash neighbor queries.
Hunger drive — hungerLevel escalates over time (injectable clock); at threshold, switches FSM to hunt.
Taming trust decay — idle taming sessions lose progress over time; feed/pet actions advance faster at low fear.
OTel — fauna.herd_size gauge; fauna.hunts_total counter; fauna.tamed_total counter.

File layout

gaming/ai/fauna/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    error-codes.ts
    constants/index.ts
    types/common.ts
    types/common.md
    core/
      herd-simulator/
        herd-simulator.ts
        herd-simulator.md
        herd-simulator.types.ts
        herd-simulator.test.ts
        index.ts
      predator-prey-fsm/
        predator-prey-fsm.ts
        predator-prey-fsm.md
        predator-prey-fsm.types.ts
        predator-prey-fsm.test.ts
        index.ts
      taming-manager/
        taming-manager.ts
        taming-manager.md
        taming-manager.types.ts
        taming-manager.test.ts
        index.ts
  tests/
    integration.test.ts

Impact

Downstream: @suaveplan/r3f-npc renders fauna instances using the same pipeline as NPCs. Prerequisites: @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/npc, @suaveplan/spatial-hash.

5.0 KiB Raw Permalink Blame History Unescape Escape