Refactored app to include all the ink.js typography.

2025-04-01 22:43:19 +00:00
parent 89b8cf8311
commit 53f9eb9265
16 changed files with 3940 additions and 858 deletions
@@ -0,0 +1,48 @@
+# 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`.