                      Digital Distortion Animated Pause
                                 Version 1.0
                           Release date: 2023-03-19

                                     by

                                Eric Oulashin
                          Sysop of Digital Distortion
                  BBS internet address: digitaldistortionbbs.com
                     Alternate address: digdist.bbsindex.com
                        Email: eric.oulashin@gmail.com

This file describes the Digital Distortion Animated Pause script and the
instructions for installing it.

Contents
========
1. Disclaimer
2. Introduction
3. Installation instructions
4. Configuration file

1. Disclaimer
=============
I can only guarantee that the contents of the Digital Distortion Archive
Viewer script and accompanying files take up space on your computer.  I
have tested this script with my BBS in Windows; it has not been tested
with Linux.  However, it should operate just as well in Linux as in
Windows.

2. Introduction
===============
This is a script that does an animated pause prompt (for ANSI users).  The
animation will only be used if the user's terminal supports ANSI and the user
has animated pause enabled in their user preferences.  The animated pause
option in the user preferences is available as "[S] Spinning Cursor" from the
user preferences list.  When a user disables the spinning cursor, Synchronet
will ask the user if they still want a spinning cursor for the pause prompt.
The pause animation will be displayed when the user has either the spinning
cursor option enabled fully or only for the pause prompt.  If the user does
not have either of those enabled, then the animation script will only display
the pause prompt text and not animate it.

3. Installation instructions
============================
To use this animated pause script, do the following:
 1. Copy animatedPause.js to your sbbs/mods directory
 2. Edit your text.dat (in the sbbs/ctrl directory) and change line 563 (Pause)
    to:
    "@EXEC:animatedPause@"
 After savign text.dat, wait for Synchronet to restart (or manually restart it)
 3. Optionally, edit animatedPause.cfg with a text editor and configure the
    options to your preferences.  See the next section for the configuration
    file settings.

4. Configuration file
======================
The configuration file, animatedPause.cfg, can be placed in one of the
following directories:
- Your sbbs/mods directory
- Your sbbs/ctrl directory
- The same directory as animatedPause.js
Additionally, the script will search for the configuration file in the
directories in the order listed above.

These are the options that are specified in the configuration file:
Option                      Description
------                      -----------
pauseText                   The text to use for the pause prompt.  This can
                            contain Synchronet color/attribute codes.

animationType               The pause animation type.  Valid values are as
                            follows:
                            PAUSE_CHARACTER_CYCLE: Cycles through the
                                characters specified in animatedCursorChars
                            PAUSE_CHARACTER_RANDOM: Chooses random characters
                                 specified in animatedCursorChars
                            PAUSE_PROMPT_COLOR_CYCLE: For each character in the
                                 pause prompt text, cycles through the colors
                                 listed in colorCodes
                            PAUSE_PROMPT_RANDOM_COLORS: For each character in
                                 the pause prompt text, a random color will be
                                 chosen from the colors listed in colorCodes
                            PAUSE_PROMPT_TRAIN_LEFT: Continually moves the
                                 pause prompt text to the left (like a train)
                            PAUSE_PROMPT_TRAIN_RIGHT: Continually moves the
                                 pause prompt text to the right (like a train)
                            PAUSE_PROMPT_ROTATE_LEFT: Continually rotates the
                                 pause prompt text to the left (like a train)
                            PAUSE_PROMPT_ROTATE_RIGHT: Continually rotates the
                                 pause prompt text to the right (like a train)
                            Random: Chooses an animation type at random

cursorSpinColor             The color to use for the changing cursor character.
                            This is used with PAUSE_CHARACTER_CYCLE and
                            PAUSE_CHARACTER_RANDOM.

inputTimeoutMS              inputTimeoutMS is the timeout (in milliseconds) to
                            use for user input before moving on to the next step
                            in the animation.  The lower this is, the faster the
                            animation will be.

animationTimeoutMS          The timeout (in milliseconds) to use for user input
                            before moving on to the next step in the animation.
                            The lower this is, the faster the animation will be.

inputTimeoutMS              The timeout (in milliseconds) for input when waiting
                            for the user to press a key

animatedCursorChars         A comma-separated list of characters to use for
                            single-character pause animation (for
                            PAUSE_CHARACTER_CYCLE and PAUSE_CHARACTER_RANDOM)

colorCodes                  A comma-separated list of Synchronet color codes to
                            use for animating the pause text color (for
                            PAUSE_PROMPT_COLOR_CYCLE and
                            PAUSE_PROMPT_RANDOM_COLORS).
