                     Digital Distortion Login Matrix
                              Version 1.31
                        Release date: 2026-01-22

                                  by

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



This file describes the Digital Distortion Login Matrix.

Contents
========
1. Introduction
2. Installation & Setup
3. Main configuration file
4. Themes & theme configuration files
5. Multi-lingual support


1. Introduction
===============
This package contains a login matrix for Synchronet, written in JavaScript.
This script is designed to run when a user connects to the BBS.  When a
user connects, they will be presented with a menu containing options to
log in, create a new account, use the guest account (if available), email
the sysop, and page the sysop.  Additionally, a background ANSI/ASCII file
will be displayed behind the menu.  When the user chooses the option to log
in, another file (or perhaps the same file) is displayed for the background,
and the user is prompted for their username and password via text boxes.

This matrix is configurable with options for enabling/disabling the guest,
page sysop, and email sysop options on the menu.  Also, this login matrix
has support for "themes", where each theme is in its own subdirectory
containing background files and its own configuration file.  Each theme's
configuration file can specify the background files (without filename extension)
for initial connection and username/password entry, as well as various options
such as location of the menu, menu colors, and locations & colors of the
username & password boxes.

By default, there is an option on the matrix menu for the user to email the
sysop. When emailing the sysop from the matrix menu, now prompts the user for
their email address (for replies). The user will be logged in with the guest
account (if enabled) in order to save the email address that they enter.  If the
guest account is not enabled, then the login matrix will not prompt for an email
address when emailing the sysop.

The background files can be in ANSI format (.ans), Synchronet attribute codes
(.asc, or perhaps .msg), or sixel photo (with filename extension .sixel).
Sixel is a bitmap graphics format supported originally by DEC terminals and
printers; for BBS telnet clients, as of this writing, SyncTerm is the only one
I know of that supports displaying sixel images.
For more information on the sixel format:
https://www.wikipedia.org/wiki/Sixel
More information on using sixel photos in the themes is described in section 4
(Themes & theme configuration files).
The included USSExcelsior and USSEnterpriseB themes are examples of themes that
use sixel photos.

Theme directories can also include image files (in jpg, png, or gif format);
those images will be converted to sixel files, scaled to the user's terminal
size. In such instances, a sixel cache directory (called sixel_cache) will be
created in the theme directory to store the converted sixels for the terminal
size so that displaying of those sixels will be faster for future connections
with that terminal size.

The login matrix only works with ANSI terminals; however, you don't need to
worry about checking for non-ANSI users, because the script will perform a
traditional Synchronet login for non-ANSI users.

Another feature of this login matrix is that it has multi-lingual support via
the use of language files, so it's possible to change the language of
your matrix by adding/creating a new language file (see section 5: Multi-
lingual support).

Note: I have included some themes with the script.  The background screens
in the dd-eye theme were created by me; however, the background screens in
the other themes were created by other people.  Recognition goes out to
those other artists for their work.


2. Installation & Setup
=======================
These are the steps for installation:
 1. Unzip the archive.  If you're viewing this file, then you've probably
    already done this. :)
 2. Place the files and directories in a directory of your choice.  It is
    recommended that the files be placed in their own directory, because
    there are several files and subdirectories.  These are the files and
    directories that you will need to place together:
    DDLoginMatrix.js
    DDLoginMatrix.cfg
    langFiles
    themes
 3. Edit your login.js file (normally in the SBBS exec directory) to load
    the matrix script rather than run its own code.

Step 3 deserves a more detailed explanation.  For these instructions, I will
assume that the files in this archive were placed in sbbs/xtrn/DigDist.
login.js needs to be edited to contain ONLY the following line:
load("../xtrn/DigDist/DDLoginMatrix.js", "digdist/answer");

Note, again, that this assumes the matrix files are placed in
sbbs/xtrn/DigDist.  Also, note the second parameter: This specifies a file
in the SBBS text/menu directory to display when a non-ANSI user connects to
your BBS.
Rather than editing login.js, I would recommend creating a new login script
(with a name such as loginDD.js).  The reason is that login.js is included
with the standard Synchronet releases, and if you use login.js, it's possible
to accidentally overwrite your modifications when upgrading to newer versions
of Synchronet in the future.  You can change the login script that is used
by loading the Synchronet configuration program (SCFG) and choosing
System > Loadable Modules.  The setting to change is "Login".  As an example,
if you created a new login script called loginDD.js, you would type loginDD
here.

Alternately, you could place all of the Digital Distortion Matrix files
into the SBBS exec directory and specify DDLoginMatrix.js as the Login
module in the Synchronet configuration program.


Note that the themes directory can alternately be called DDLoginMatrixThemes.
Also, the langFiles directory can alternately be called DDLoginMatrixLangFiles.

3. Main configuration file
==========================
The main configuration file, DDLoginMatrix.cfg, contains settings for the
behavior of the matrix.  The syntax for each line in the file is as
follows:
Option=Value
where Option is the option to set, and Value is the setting for that option.

The following is a description of the configuration file options:

Option                                Description
-------                               -----------
UseMatrix                             Whether or not to use the matrix-style
                                      login.  (If not, a more traditional style
                                      login will be used).  Valid values are
                                      Yes and No.

MenuTimeoutMS                         The menu input timeout, in milliseconds.
                                      If no input is received from the user
                                      within this amount of time, the script
                                      will disconnect.

MenuDisplayNewUser                    Whether or not to display the new user
                                      option in the menu.  Valid values are
                                      Yes and No.

MenuDisplayGuestAccountIfExists       Whether or not to display the menu option
                                      for the guest account, if available.
                                      Valid values are Yes and No.

MenuDisplayRetrievePassword           Whether or not to display the menu option
                                      to let the user retrieve their password.
                                      Valid values are Yes and No.

MenuDisplayEmailSysop                 Whether or not to display the menu
                                      option for emailing the sysop.  Valid
                                      values are Yes and No.

MenuDisplayPageSysop                  Whether or not to display the menu option
                                      for paging the sysop.  Valid values are
                                      Yes and No.

MaxLoginAttempts                      The maximum number of login attempts to
                                      allow before disconnecting the user.

AllowUserNumber                       Whether or not to allow logging in by
                                      user number (this is in addition to
                                      logging in via username).  Valid values 
                                      are Yes and No.

MatrixTheme                           The directory name of the theme to use.
                                      This can also be Random to tell the
                                      matrix script to select a random theme
                                      each time a user logs in.

RandomOnlySixelThemesForSixelTerminal When choosing a random theme, whether to
                                      only choose themes with sixels if the
                                      user's terminal supports sixels. Valid
                                      values are true and false (or yes and no)

Language                              Specifies the name of the language to
                                      use.  The text for the language will
                                      be loaded from a file in the
                                      DDLoginMatrixLangFiles directory, with
                                      the filename Language.lng, where Language
                                      is the language specified here.

SoundFile                             A name of a sound file to play when a
                                      user logs in successfully. Note: As of
                                      this writing (February 11, 2011),
                                      Synchronet only supports playing a sound
                                      in Windows.
                                      

PlaySound                             Whether or not to play the login sound.
                                      Valid values are Yes and No.

PathToImgToSixelConv                  The full path & filename of the image-
                                      to-sixel conversion program (provided by
                                      ImageMagick). For example, on Linux, this
                                      could be /usr/bin/convert


4. Themes & theme configuration files
=====================================
The DDLoginMatrixThemes directory contains the themes, where each theme is in
its own subdirectory.  Each theme subdirectory contains the following files:
- A file to display when the user connects
- Optional: Another file to display when the user is prompted for their
  username and password
- DDMatrixTheme.cfg: The theme's configuration file.  Each line of this
  configuration file is in the format of Option=Value.

Note: Digital Distortion Login Matrix can be used with PETSCII terminals, but
the login matrix doesn't detect the user's terminal width.  Thus, the use of
80-column login screens and menu positioning after 40 columns would be wrapped
on 40-column PETSCII terminals.

Notes about color settings
--------------------------
Each theme configuration file has settings for various colors.  The color
settings are simply a list of Synchronet attribute codes, as listed on the
following Synchronet wiki page:
http://wiki.synchro.net/custom:ctrl-a_codes

For example, to specify high blue, you would use hb (or HB - case does not
matter).

Notes about password length
---------------------------
As of Synchronet 3.17c, the minimum and maximum pasword lengths are known to
JavaScript scripts, and this login matrix makes use of those values.  The
minimum password length is configurable in SCFG in System > Users Can Change
Password - One of the questions there is the minimum password length.
load/sbbsdefs.js currently defines LEN_PASS as 40, the maximum length of a user
password.
However, to override the default password box width, a theme configuration file
can optionally include the setting PasswordBoxInnerWidth, which specifies the
inner width of the password input box (without the borders).  This login matrix
will still allow inputting the full password typed by the user, regardless of
the PasswordBoxInnerWidth setting;; when the cursor gets to the end of the
password input box, it will simply stop outputting * characters, but it will
still be inputting the password from the user.

Notes about sixel photos
------------------------
The background files (specified by InitialBackgroundFilename and
LoginBackgroundFilename) can be in ANSI format (with file extension .ans),
Synchronet color code format (with extension .asc or perhaps .msg), or sixel
format (with filename extension .sixel). Sixel is a text-based format for
photos, initially used by DEC printers & terminals. Currently, SyncTerm is the
only BBS-capable telnet client I know of that supports displaying sixel photos.
If the user's terminal doesn't support sixel photos (as reported by Synchronet),
the sixel photo won't be displayed, and an .ans/.asc version will be displayed
instead, if there is one.

You can convert any photo to sixel format and use the sixel; however, for an
80x24 terminal, photo dimensions of 640x370 or so seem to work best (in
particular, 640 pixels wide seems to fit exactly into an 80-column terminal. A
height of 300 would leave some empty space at the bottom, which could be used
for writing your BBS information.

To convert a photo to sixel format, there are some online-based tools to do so.
You can search online with queries like "convert photo to sixel" or "convert PNG
to sixel". Some of the online tools have limits on how many you can convert
before they want you to pay. These are a couple of results, at the time of this
writing:
https://convertio.co/png-sixel/
https://www.vertopal.com/en/convert/jpg-to-sixel

Additionally, for Linux systems, there is a program called img2sixel that can be
used to convert images to sixel format. It's included with the libsixel-bin
package. If you use an apt-based Linux system, you can install it as follows:

sudo apt install libsixel-bin

For more information:
https://manpages.ubuntu.com/manpages/xenial/man1/img2sixel.1.html


The background files can also be image files (PNG, JPG, or GIF). If they are
any of these formats, they will be converted to sixel format and scaled for the
user's terminal size to be displayed as such to the user. For these themes, a
sixel cache directory (called sixel_cache) will be created in the theme
directory to store the converted sixels for the terminal size so that displaying
of those sixels will be faster for future connections with that terminal size.

Note that ImageMagick needs to be installed in order for that to work.
ImageMagick is available for both Windows and Linux and can be downloaded from:
https://imagemagick.org
Image files will be scaled up or down, according to the user's terminal size.
An image size of 640x370 seems to correspond to an 80x24 terminal, and an image
will be scaled accordingly. The user's terminal width can be given priority when
scaling an image file to a sixel; alternately, both the user's terminal width
and height can be taken into account when scaling an image file to a sixel. The
section on theme configuration files has more details.

For themes with image files, if you want to remove the sixel cache directories
to recover some drive space, you can run the script rm_sixel_cache_dirs.js with
jsexec to do so:
jsexec rm_sixel_cache_dirs.js
You can also leave off the .js filename extension when running it.
If desired, you could also add a timed event to periodically run that script.
You would do so via SCFG->External Programs->Timed Events. Note that
../xtrn/DDLoginMatrix is used as an example directory; you would need to use the
directory on your system where you have copied DDLoginmatrix.
For example, to run it once a month on the first day of the month:
+====================================================================+
|                     DDLM_RM_SCACHE Timed Event                     |
+====================================================================+
| |Internal Code                   DDLM_RM_SCACHE                    |
| |Start-up Directory              ../xtrn/DDLoginMatrix             |
| |Command Line                    ?rm_sixel_cache_dirs.js           |
| |Enabled                         Yes                               |
| |Execution Node                  1                                 |
| |Execution Months                Any                               |
| |Execution Days of Month         1                                 |
| |Execution Days of Week          All                               |
| |Execution Time                  00:00                             |
| |Requires Exclusive Execution    No                                |
| |Force Users Off-line For Event  No                                |
| |Native Executable               No                                |
| |Use Shell to Execute            No                                |
| |Background Execution            No                                |
| |Always Run After Init/Re-init   No                                |
+====================================================================+



In the theme configuration file, as of version 1.31, please note that the
MenuBorders option is no longer used, in favor of 4 separate options:
InitialMenuBorder, LoginNameBoxBorder, LoginPasswordBoxBorder, and
LoginStatusBoxBorder. Previously, MenuBorders was only used for the matrix
menu which was shown on connect; that was a bug, as it should have applied to
all boxes. Now there are individual configuration options to specify the border
styles for all boxes.

If you have any existing themes that only have the MenuBorders option, it will
be used for all boxes.

The following is a list of the theme configuration options:

Option                        Description
-------                       -----------
MinTerminalWidth              This is optional. This specifies a minimum terminal
                              width (in characters); currently, this is only used
                              for themes with a sixel photo for the initial or
                              login background image - If the user's terminal
                              width is less than this, then a sixel image would
                              not be displayed.

InitialBackgroundFilename     The name of a file to display when a user connects.
                              This should not include the extension.

LoginBackgroundFilename       The name of a file to display when the user is
                              prompted for their username and password.  The
                              value can be the same as InitialBackgroundFilename.
                              If this value is blank, the screen will simply be
                              cleared before prompting for the user's username &
                              password.

ScaleInitialBkgImgWithHeight  Optional: Whether or not to take the user's
                              terminal height into account when scaling the
                              initial background image file to a sixel. Valid
                              values are true and false. Defaults to false. If
                              false, only the user's terminal width will be
                              taken into consideration when scaling an image to
                              a sixel.

ScaleLoginImgWithHeight       Optional: Whether or not to take the user's
                              terminal height into account when scaling the
                              login background image file to a sixel. Valid
                              values are true and false. Defaults to false. If
                              false, only the user's terminal width will be
                              taken into consideration when scaling an image to
                              a sixel.

MenuX                         The horizontal cursor position of the top-left
                              corner of the matrix menu. See the subsection
                              "Options that are X and Y screen character
                              coordinates" for more information.

MenuY                         The vertical cursor position of the top-left corner
                              of the matrix menu. See the subsection
                              "Options that are X and Y screen character
                              coordinates" for more information.

InitialMenuBorder             The border style of initial (matrix) menu. This
                              can be Single or Double.

LoginNameBoxBorder            The border style of the box around the user name
                              for login. This can be Single or Double.

LoginPasswordBoxBorder        The border style of the box around the password
                              for login. This can be single or Double.

LoginStatusBoxBorder          The border style of the status box border for
                              login. This can be Single or Double.

ClearSpaceAroundMenu          Whether or not to clear a space around the matrix
                              menu (to help it stand out). Valid values are Yes
                              and No.

MenuTitle                     The text to display above the matrix menu

DisplayMenuTitle              Whether or not to display the menu title. Valid
                              values are Yes and No.

MenuColor_Border              The color to use for the menu border

MenuColor_Unselected          The color to use for non-selected menu items

MenuColor_Selected            The color to use for selected menu items

MenuColor_Hotkey              The color to use for menu item hotkeys

MenuColor_ClearAroundMenu     The color to use when clearing a space around the
                              menu

UsernameX                     The horizontal cursor position of the top-left
                              corner of the username box. See the subsection
                              "Options that are X and Y screen character
                              coordinates" for more information.

UsernameY                     The vertical cursor position of the top-left corner
                              of the username box. See the subsection "Options
                              that are X and Y screen character coordinates" for
                              more information.

UsernameLength                The maximum allowed username input length

UsernameBoxBorderColor        The color to use for the border of the username box

UsernameBoxBkgColor           The color to use when clearing the inside of the
                              username box

UsernamePromptColor           The color to use for the username prompt text

UsernameTextColor             The color to use for the user's inputted username

PasswordX                     The horizontal cursor position of the top-left
                              corner of the password box. See the subsection
                              "Options that are X and Y screen character
                              coordinates" for more information.

PasswordY                     The vertical cursor position of the top-left
                              corner of the password box. See the subsection
                              "Options that are X and Y screen character
                              coordinates" for more information.

PasswordBoxInnerWidth         Optional: This can be used to specify the inner
                              width of the password input box. Users will still
                              be able to enter any length of password. If this is
                              not specified, DDLoginMatrix will use a width that
                              is based on the system-configured maximum password
                              length.

PasswordBoxBorderColor        The color to use for the border of the password box

PasswordBoxBkgColor           The color to use when clearing the inside of the
                              password box

PasswordPromptColor           The color to use for the password prompt text

PasswordTextColor             The color to use for the user's inputted password

StatusX                       The horizontal cursor position of the top-left
                              corner of the status box (displayed when the user
                              is prmopted for their username & password). See
                              the subsection "Options that are X and Y screen
                              character coordinates" for more information.

StatusY                       The vertical cursor position of the top-left corner
                              of the status box (displayed when the user is
                              prmopted for their username & password). See
                              the subsection "Options that are X and Y screen
                              character coordinates" for more information.

StatusBoxInnerWidth           The inner width to use for the status box (displayed
                              when the user is prompted for their username and
                              password)

StatusBoxBorderColor          The color to use for the border of the status box
                              (displayed when the user is prmopted for their
                              username & password)

StatusBoxBkgColor             The color to use when clearing the inside of the
                              status box (displayed when the user is prmopted for
                              their username & password)

StatusTextColor               The color to use for the status text
                              (displayed when the user is prmopted
                              for their username & password)

InitialBackgroundInfoLine*    Lines that start with this can be used to specify
                              some text to display at a certain location on the
                              screen, along with colors. You can specify multiple
                              lines staring with InitialBackgroundInfoLine. You
                              can append to the option name (such as
                              InitialBackgroundInfoLine1,
                              InitialBackgroundInfoLine2, etc.). These lines are
                              used when the theme has a sixel photo for the
                              initial background; with a sixel photo, @-codes
                              can't be used inside the sixel image itself. If you
                              make a theme with a sixel photo as the
                              InitialBackgroundFilename, you can have multiple
                              InitialBackgroundInfoLine specifiers in the theme
                              configuration file. The value for these is a comma-
                              separted list specifying attributes, X & Y
                              coordinates, and the string to display:
                              colors,X,Y,string
                              The colors are simply a list of Synchronet attribute
                              code characters (without the control character). For
                              example, for high cyan at column 1 & row 1, to
                              display "Welcome to " the BBS name:
                              ch,1,1,Welcome to @BBS@
                              See the subsection "Options that are X and Y
                              screen character coordinates" for more
                              information.

Options that are X and Y screen character coordinates
-----------------------------------------------------
The options that are a X or Y screen character coordinate can be one of the
following:
- A number (absolute position)
- A percentage (number with a % at the end). For example, if it's an X
  coordinate and the value is 23%, then for an 80-column terminal, the column
  will be 18. The number is always rounded down.
- A percentage with a positive or negative offset at the end (for example,
  23%+3 or 23%-3).  For example, if it's a Y value and the user's terminal is 25
  rows tall, for a value of 76%+3, the row will be 22 (76% of 25 is 19, plus 3,
  which is 22).
- A decimal point number (such as .52), which means the coordinate is a
  fraction of the terminal width/height
The fractional/decimal versions are useful when the background is an image,
which would be converted to a sixel and  scaled.


5. Multi-lingual support
========================
This login matrix supports multiple languages via the use of files stored in
the DDLoginMatrixLangFiles containing the text strings for different languages.
Each line in the language file contains a specifier and text string, in the
following format:
specifier=string

Furthermore, the language files are divided into 3 sections, with the following
headers:
[MATRIX] - These strings are used in matrix mode
[STANDARD] - These strings are used in the standard (non-matrix) login mode
[GENERAL] - These strings are various strings used for both modes.

The specifiers are in English, but the strings contain the actual language text.
The following is a list of the specifiers and what they are used for:
[MATRIX]  (Matrix mode text)
LOGIN: The text for the login menu option (Note: An ampersand (&) precedes a shortcut character)
NEWUSER: The text for the New User menu option
GUEST: The text for the Guest Account menu option
RETRIEVE_PASSWORD: The text for the menu option to retrieve a password
EMAIL_SYSOP: The text for the menu option to email the sysop
PAGE_SYSOP: The text for the menu option to page the sysop
DISCONNECT: The text for the menu option to disconnect
USERNAME_NUM_PASS_PROMPT: The text used to let the user know to enter their username or number.
                          Note: Only this one OR the next one will be used.
USERNAME_PASS_PROMPT: The text used to let the user know to enter their username (not allowing
                      user number input).  Note: Only this one OR the previous one will be
                      used, depending on the configuration settings.
USERNAME_OR_NUM_PROMPT: The prompt text for the user's username/number.  Note: Only this
                        one OR the next one will be used, depending on the configuration
                        settings.
USERNAME_PROMPT: The prompt text for the user's username.  Note: Only this one OR the
                 previous one will be used, depending on the configuration settings.
PASSWORD_PROMPT: The text to use for the password prompt
UNKNOWN_USERNAME_OR_NUM: The error message displayed when the user enters an unknown
                         username or number.  Note: Only this one OR the next one
                         will be used, depending on the configuration settings.
UNKNOWN_USERNAME: The error message displayed when the user enters an unknown username.
                  Note: Only this one OR the previous one will be used, depending on the
                  configuration settings.
LOGIN_ATTEMPTS_FAIL_MSG: The error message to display after the user fails all login attempts
GUEST_ACCT_FAIL: The error message to display if the guest account can't be used
SYSOP_HAS_BEEN_PAGED: The message to display to let the user know the sysop has been paged
UNABLE_TO_PAGE_SYSOP: The message to display if the sysop can't be paged right now
LOGOFF_CONFIRM_TEXT: The text to use for the question to confirm if the user really wants
                     to log off
DISCONNECT_MESSAGE: The message to display before disconnecting the user when the user
                    chooses to disconnect
INPUT_TIMEOUT_REACHED: The message to display when the input timeout has been reached
INVALID_LOGIN: The text "Invalid login", or the equivalent in another language

[STANDARD]  (Standard (non-matrix) mode text)
USERNAME_PROMPT: The text to use to tell the user to enter their username
OR_NUMER_PROMPT: The text " or number", displayed if user number logins are supported
NEW_USER_INFO: The text to tell the user how to log in as a new user
GUEST_INFO: The text to tell the user how to log into the guest account
LOGIN_PROMPT: The text to use for the login prompt
PASSWORD_PROMPT: The text to use for the password prompt

[GENERAL]   (General text strings)
NEW: The word "new" (in the respective language)
EMAIL_ADDR_CONFIRM_PROMPT: The text to use when having the user confirm their email
                           address (for password retrieval)
DID_YOU_FORGET_PASSWORD_CONFIRM: The text to use for asking the user if they forgot
                                 their password (for password retrieval)
ACCT_INFO_REQUESTED_ON_TIME: Used when emailing a user their password, this text
                             is displayed before the time their information was
                             requested.
BY: The word "by" (in the respective language)
VIA: The word "via" (in the respective languge)
PORT: The word "port" (as applied to network ports, in the respective language)
INFO_ACCT_NUM: Used when emailing a user their password, this text
               is displayed before the user's account number
INFO_CREATED: Used when emailing a user their password, this text
              is displayed before the user's account creation date
INFO_LAST_ON: Used when emailing a user their password, this text
              is displayed before the user's last logon date/time
INFO_CONNECT: Used when emailing a user their password, this text
              is displayed before the user's connection type used when requesting
              their information
INFO_PASSWORD: Used when emailing a user their password, this text
               is displayed before the user's password
INFO_INCORRECT_EMAIL_ADDR: This is the error message displayed if the user
                           enters an incorrect email address when asked to
                           confirm theirs.
ACCT_INFO_EMAILED_TO: Used when emailing a user their password, this text
                      is displayed to show the address where their information
                      was emailed to.
ERROR_SAVING_BULKMAIL_MESSAGE: Used when emailing a user their password, this is
                               an error message to display if there was a problem
                               saving the mail.
UNKNOWN_USERNAME: This is an error message telling the user that their username is
                  unknown (used for password retrieval).
UNABLE_TO_RETRIEVE_ACCT_INFO: This is an error message displayed if the login
                              script is unable to send the user their account
                              information (i.e., if their email address is not
                              valid, if they are the sysop, etc.).
