ai.interactive.fiction/references/README.md

Animated Fiction Engine - Modular Refactoring

This directory contains the refactored, modular version of the interactive fiction engine, previously implemented monolithically in references/game.js. The refactoring follows the recommendations outlined in Chapter 8 of references/Documentation.md.

Overview

The engine is now broken down into several distinct, reusable components, each with a specific responsibility. This improves maintainability, testability, and allows for easier integration into different projects or replacement of individual components.

Modules

The core modules are:

1. animation-queue.js (AnimationQueue): Manages the timing and execution queue for animations, primarily text reveal. Handles scheduling, fast-forwarding, stopping, and speed control.
2. text-processor.js (TextProcessor): Encapsulates text pre-processing steps (SmartyPants for typography, Hyphenopoly for hyphenation).
3. paragraph-layout.js (ParagraphLayout): Interfaces with the Knuth-Plass line breaking algorithm (kap function) to calculate optimal paragraph layouts. Requires a text measurement function.
4. layout-renderer.js (LayoutRenderer): Translates the calculated layout data into DOM elements, handles visual tag rendering (images, backgrounds, etc.), and schedules animations using the AnimationQueue.
5. audio-manager.js (AudioManager): Manages loading and playback of non-TTS audio effects triggered by Ink tags (AUDIO, AUDIOLOOP).
6. tts-player.js (TtsPlayer): Handles interactions with Text-to-Speech services (using tts-factory.js for selection) and manages TTS playback.
7. persistence-manager.js (PersistenceManager): Handles saving and loading the game state (Ink state JSON and rendered history) using a configurable storage backend (defaulting to localStorage).
8. ink-story-player.js (InkStoryPlayer): Orchestrates the Ink narrative flow. Manages the inkjs.Story instance, processes story content and tags, and delegates tasks to other modules (text processing, layout, rendering, audio, TTS, persistence).
9. ui-controller.js (UiController): Manages user interface interactions (buttons, sliders, keyboard shortcuts) and updates UI elements. Interacts with other modules to trigger actions (e.g., change speed, save/load, choose choice).
10. animated-fiction.js (AnimatedFiction): The main application class that integrates all the modules. It handles initialization, loading the story, and starting the application flow.

Supporting Libraries

This engine relies on several external and internal libraries located in public/js:

• ink.js (Loaded via CDN in modular-index.html, wrapped in window.inkjs)
• smartypants.js
• linked-list.js (Used by linebreak.js)
• linebreak.js (Core Knuth-Plass algorithm)
• knuth-and-plass.js (Adapter for linebreak.js)
• Hyphenopoly_Loader.js & Hyphenopoly.js (Hyphenation library)
• kokoro-js.js, kokoro-handler.js, tts-handler.js, tts-factory.js (Text-to-Speech components)

Usage

1. Include Libraries: Ensure all necessary supporting libraries (smartypants.js, ink.js, Hyphenopoly, etc.) are loaded in your HTML file before the main application module.
2. Include Main Module: Load the main application module (animated-fiction.js) using <script type="module">.
3. HTML Structure: Ensure your HTML has the necessary container elements (e.g., #story, #choices) and UI controls (buttons, sliders) with the expected IDs, or configure the UiController with the correct element references.
4. Initialization: The animated-fiction.js script will automatically instantiate the AnimatedFiction class on window.onload, load the story specified in its configuration (Herrenhaus.ink.json by default), and start the interactive experience.

Refer to public/modular-index.html for a working example of how to structure the HTML and include the necessary scripts.

Original Files

• The original monolithic implementation can be found in references/game.js.
• The documentation detailing the original implementation and the refactoring plan is in references/Documentation.md.