Scene

The Scene class represents an individual narrative unit. Each beat in a plot generates one scene. Scenes are typically created by the engine, not manually.

Import

import { Scene } from '@spectator-ai/core'
import type { SceneInput, SceneData, CharacterStateData } from '@spectator-ai/core'

Constructor

new Scene(input: SceneInput)

Validates input against SceneSchema and freezes the data.

Throws: ValidationError if input is invalid.

Properties

All properties are readonly getters.

Property	Type	Description
id	string	Unique scene identifier
text	string	Narrative text content
beat	BeatData | undefined	The plot beat that generated this scene
location	string | undefined	Where the scene takes place
participants	string[]	Character names in this scene (defaults to [])
summary	string | undefined	Auto-generated scene summary
characterStates	CharacterStateData[] | undefined	Character states after this scene

CharacterStateData

interface CharacterStateData {
  characterName: string
  emotionalState: string
  currentGoals: string[]
  relationships?: DynamicRelationshipData[]
  internalConflict?: string
  notes?: string
}

Methods

toJSON()

scene.toJSON(): SceneData

Returns a plain serializable object.

toMarkdown()

scene.toMarkdown(): string

Returns formatted markdown. Includes location and participants as a header if present, followed by the scene text.

Types

SceneInput

interface SceneInput {
  id: string
  beat?: BeatInput
  location?: string
  participants?: string[]
  text: string
  summary?: string
  characterStates?: CharacterStateInput[]
  metadata?: Record<string, unknown>
}