Character

The Character class defines story characters with traits, backstory, goals, and relationships. Characters are immutable — all modifier methods return new instances.

Import

import { Character } from '@spectator-ai/core'
import type { CharacterInput, CharacterData, RelationshipInput } from '@spectator-ai/core'

Static Methods

Character.create()

Character.create(input: CharacterInput): Character

Creates a new Character. The name field is required (minimum 1 character).

const char = Character.create({
  name: 'Zero',
  traits: ['resourceful', 'paranoid'],
  backstory: 'A data runner who lost their memory',
  goals: ['Recover lost memories'],
  personality: 'Guarded but fiercely loyal',
  relationships: [
    { target: 'Glass', type: 'handler', description: 'Provides jobs' }
  ],
  metadata: { faction: 'runners' },
})

Throws: ValidationError if validation fails (e.g., empty name).

Properties

All properties are readonly getters.

Property	Type	Description
name	string	Character name
traits	string[]	Traits (defaults to [])
backstory	string | undefined	Background story
goals	string[]	Character goals (defaults to [])
personality	string | undefined	Personality description
relationships	readonly RelationshipInput[]	Relationships (defaults to [])

Methods

withRelationship()

character.withRelationship(rel: RelationshipInput): Character

Returns a new Character with the relationship added.

const updated = char.withRelationship({
  target: 'Glass',
  type: 'handler',
  description: 'Provides jobs in exchange for loyalty',
})

RelationshipInput

interface RelationshipInput {
  target: string        // Target character name
  type: string          // Relationship type (freeform)
  description?: string  // Optional description
}

withTraits()

character.withTraits(...traits: string[]): Character

Returns a new Character with additional traits appended.

const updated = char.withTraits('determined', 'loyal')

extend()

character.extend(overrides: Partial<CharacterInput>): Character

Returns a new Character with overrides merged.

const updated = char.extend({ backstory: 'A reformed hacker...' })

toJSON()

character.toJSON(): CharacterData

Returns a plain serializable object.

toString()

character.toString(): string

Returns a human-readable summary, e.g. "Zero (resourceful, paranoid)".

Types

CharacterInput

interface CharacterInput {
  name: string                    // Required, min 1 character
  traits?: string[]
  backstory?: string
  goals?: string[]
  personality?: string
  relationships?: RelationshipInput[]
  metadata?: Record<string, unknown>
}