# 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`.