Scene Designer Dialogue Event Module

Scene Designer Dialogue Event Module is a deterministic integration module that adds dialogue as a first-class event type inside Scene Designer v1 without introducing hidden state, branching runtime behavior, or schema ambiguity. It keeps dialogue consequence resolution local and authored while leaving consequence accumulation, ordering, and playback context under Scene Designer control.

What Problem It Solves

Scene Designer already handles deterministic timeline-based composition, but v0.1 needed a clean way to place dialogue alongside existing tone-oriented events without breaking inspectability or portability. This module proves that mixed tone + dialogue timelines can resolve deterministically, export/import as JSON, and stay small enough to reason about directly.

v0.1 Features

• Mixed timeline support for tone and dialogue events in one scene.
• Deterministic dialogue resolution for authored variants only.
• Frozen dialogue event output contract.
• JSON export/import with explicit validation errors.
• Side-by-side text comparison for the included authored scenarios.
• Small TypeScript harness for build, demo, and focused tests.

Frozen Dialogue Event Contract

Every resolved dialogue event produces:

• selectedVariant
• resolvedText
• interpretation
• stateDelta
• cueOutputs

Recommended interpretation shape in v0.1:

• label
• stance
• intensity
• notes

Only selector.strategy = "fixed" is supported in v0.1. There is no LLM use, no runtime generation, no hidden state, and no branching dialogue engine.

Included Demo Scenes

• deflection_after_accusation
• soft_refusal

Both scenes include mixed event types and resolve through the same deterministic runtime path.

Sample Scene Snippet

{
  "id": "dialogue_soft_refusal_response",
  "type": "dialogue",
  "startBeat": 1,
  "dialogue": {
    "contractVersion": "dialogue-event.v0_1",
    "scenarioKey": "soft_refusal",
    "speaker": "guest",
    "listener": "host",
    "selector": {
      "strategy": "fixed",
      "variantId": "gentle_decline"
    },
    "variants": [
      {
        "id": "gentle_decline",
        "text": "I appreciate the offer, but I can't stay tonight.",
        "interpretation": {
          "label": "soft_refusal",
          "stance": "kind",
          "intensity": 0.39,
          "notes": "Speaker declines gently."
        },
        "stateDelta": [
          {
            "op": "set",
            "path": "dialogue.invitationOutcome",
            "value": "declined_softly"
          }
        ],
        "cueOutputs": [
          {
            "channel": "performance",
            "cue": "small_regretful_smile"
          }
        ]
      }
    ]
  }
}

Install

npm install

Build

npm run build

Test

npm test

Demo

npm run demo

The demo prints a compact side-by-side comparison of the two authored scenes after resolving them through the existing deterministic runtime path.

JSON Import / Export

The module includes minimal JSON portability helpers for unified scenes:

• export validates a scene before serializing it
• import parses JSON, validates the structure, and throws readable path-based errors when the payload does not match the frozen contract

Primary files:

• src/io/unifiedSceneJson.ts
• src/io/validateUnifiedScene.ts
• schema/unified-scene.schema.json

Current Scope Boundaries

v0.1 is intentionally narrow:

• no UI redesign
• no new selector modes
• no branching dialogue engine
• no runtime generative behavior
• no hidden state
• no PUTMAN/CDE/TVS integration
• no major authoring expansion beyond the included proof scenes

Repository Layout

• src/types/ frozen TypeScript contract
• src/events/ runtime event ordering and scene resolution
• src/dialogue/ deterministic dialogue helpers and resolver
• src/scenes/ authored v0.1 scenes
• src/io/ JSON validation and import/export
• src/compare/ compact comparison output
• test/ focused tests

Notes

This repository is the preliminary core build for a larger scene authoring tool in progress.

The current focus is the deterministic foundation: scene schema, dialogue event resolution, validation, JSON portability, and comparison output. It is not presented as a finished end-user product.

Created by Stephen A. Putman
Contact: putmanmodel@pm.me
GitHub: @putmanmodel

License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International license.

See the LICENSE file for the full text.