Avatars

This module enables personal user avatars/icons to be displayed in the headers of messages posted by those users, even over supported message networks (e.g. DOVE-Net).

Avatars are also displayed in Synchronet BBS List v4 (rev 1.33+). If using an updated v3.17 build, avatars are displayed in the details of user-uploaded files as well.

While its conceivable these avatars will be displayed in door games, chat, and instant messaging in the future, that has not yet been implemented.

A user's avatar is displayed to them during logon when using the latest exec/logon.js module (rev 1.26 or later).

The set of stock avatar collections available for users to choose from includes over 150 original pieces of ANSI-art created and contributed by Synchronet sysops: digital man, echicken, and kirkman.

The following screen shots are some of the stock avatar collections being shown in the ANSI terminal mode Avatar Chooser (a web-based avatar chooser is also in the works, per echicken):

• Additional avatar collections can be easily and automatically shared among sysops that are members of the same message network (e.g. DOVE-Net).

Avatar support can be enabled in Synchronet v3.16 and later. Avatar support will be enabled by default in new installations of v3.17 and later.

Synchronet versions older than v3.16 are unlikely to work with the Avatar modules, but you can give it a try (or better yet, upgrade).

If running Synchronet v3.16 or a non-current v3.17:

Download the file msghdr.asc to your text/menu/ directory, if you do not already have it (e.g. from Git).

This msghdr.asc will execute the script exec/showmsghdr.js whenever a message header is displayed to a user of the Terminal Server.

If you have an already-customized text/menu/msghdr.asc file, you can alternatively add the following line to to the end (before the last blank line, if you wish to have a blank line separating the message header and body) of the msghdr.asc file:

@EXEC:SHOWMSGAVATAR@

If running a current v3.17, you should delete the msghdr.asc file to get fast message header display.

If you haven't already, get the text/avatars directory contents either via Git or download from this web-page: https://gitlab.synchro.net/sbbs/sbbs/-/tree/master/text/avatars/

... and place these files in your Synchronet text/avatars directory (create it if it doesn't exist).

These .bin files represent the initial set of avatars available for your BBS users to choose from. Additional avatar collections may be later imported automatically via the SYNCDATA networked-message area (e.g. from DOVE-Net or FidoNet).

From a command prompt, run jsexec avatars install

This step will perform all the necessary SCFG changes and optional modopts.ini changes detailed later in this article.

Optional:

Update your command shells to either execute avatar_chooser.js directly (using Baja exec_bin or JS bbs.exec or load functions) or use Baja exec_xtrn or JS bbs.exec_xtrn to execute the module via internal code (e.g. AVATCHOO). This small change was already made in the “Synchronet Classic” command shell: exec/default.src. You will need to recompile default.src to default.bin using Baja (in the exec directory):

baja default.src

There's a corresponding to change to the default main menu (text/menu/main.asc) display file to include the new /A (change avatar) option.

If your BBS users use other command shells on your BBS, you may want to make similar changes to those shells to enable avatar selection/changing. Otherwise, those users will have to use the external program menu to change their avatar.

These configuration steps are automated by running the jsexec avatars install command-line but are detailed here for your information.

The Avatar Chooser script (by echicken) configured in SCFG->External Programs->Online Programs->Main:

╔══════════════════════════════════════════════════════════╗
║                      Avatar Chooser                      ║
╠══════════════════════════════════════════════════════════╣
║ │Name                       Avatar Chooser               ║
║ │Internal Code              AVATCHOO                     ║
║ │Start-up Directory                                      ║
║ │Command Line               ?avatar_chooser              ║
║ │Clean-up Command Line                                   ║
║ │Execution Cost             None                         ║
║ │Access Requirements                                     ║
║ │Execution Requirements     ANSI & !GUEST & REST !Q      ║
║ │Multiple Concurrent Users  Yes                          ║
║ │Intercept I/O              No                           ║
║ │Native Executable          No                           ║
║ │Use Shell to Execute       No                           ║
║ │Modify User Data           No                           ║
║ │Execute on Event           New User                     ║
║ │Pause After Execution      No                           ║
║ │BBS Drop File Type         None                         ║
║ │Place Drop File In         Node Directory               ║
╚══════════════════════════════════════════════════════════╝

Note: Be sure to set Execute on Event to New User or your new users will not likely select an initial avatar.

Create a timed event to import network user avatars and shared avatar collections via SCFG->External Programs->Timed Events:

╔════════════════════════════════════════════════════════════════════╗
║                         AVAT-IN Timed Event                        ║
╠════════════════════════════════════════════════════════════════════╣
║ │Internal Code                   AVAT-IN                           ║
║ │Start-up Directory                                                ║
║ │Command Line                    ?avatars import                   ║
║ │Enabled                         Yes                               ║
║ │Execution Node                  1                                 ║
║ │Execution Months                Any                               ║
║ │Execution Days of Month         Any                               ║
║ │Execution Days of Week          All                               ║
║ │Execution Time                  48 times a day                    ║
║ │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                                ║
╚════════════════════════════════════════════════════════════════════╝

This will import any new personal avatars and avatar collections received via SYNCDATA into your data/qnet directory. Validated avatar collections will then be copied into your text/avatars directory where your users should be able to select them for personal use (using the avatar_chooser.js).

Create a timed event to export local users' avatars to message networks via SCFG->External Programs->Timed Events:

╔════════════════════════════════════════════════════════════════════╗
║                         AVAT-OUT Timed Event                       ║
╠════════════════════════════════════════════════════════════════════╣
║ │Internal Code                   AVAT-OUT                          ║
║ │Start-up Directory                                                ║
║ │Command Line                    ?avatars export                   ║
║ │Enabled                         Yes                               ║
║ │Execution Node                  1                                 ║
║ │Execution Months                Any                               ║
║ │Execution Days of Month         Any                               ║
║ │Execution Days of Week          All                               ║
║ │Execution Time                  48 times a day                    ║
║ │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                                ║
╚════════════════════════════════════════════════════════════════════╝

This will export any updated user avatars, disabled user avatars (if they were previously exported), and (optionally) any shared avatar collections that have been updated.

Regardless of how often this event is configured to run, the export frequency is throttled by the export_freq configuration setting. Only when an item has been modified will it be exported more frequently than the configured export_freq value (in days).

To share a locally-created custom avatar collection with other BBSes in a message network (e.g. DOVE-Net), add the -share option to the avatars export command-line:

?avatars export -share

This option will enable the automatic sharing of any avatar collections named <QWK-ID>.*.bin in the text/avatars directory, where QWK-ID is your BBS's QWK-ID.

Other than command-line parameters, the only configuration options for avatars.js are stored in the [avatars] section of the ctrl/modopts.ini file:

[avatars]
sub          = dove-syncdata
export_freq  = 7

The showmsgavatar.js module uses the sub_default or <group-name>_default or <sub-code>_default values for a default avatar to show for messages from users without an avatar.

When user avatars or shared avatar collections (.bin files) are updated, they will be exported immediately (or when the AVAT-OUT event is executed).

Also in the ctrl/modopts.ini file:

[newuser]
avatar = <base64-encoded avatar data>
avatar_file = <filename of avatar collection>
avatar_offset = <0-based record number of avatar to use>
 
[logon]
set_avatar = <true or false>

The set_avatar value in the [logon] section, when set to true, will cause the logon module to prompt users to choose their avatar if they have not already done so, during logon.

See the next section on details about the [newuser] avatar-related settings.

The new user default avatar, if you have one, will be set with the avatar value in the [newuser] section of the ctrl/modopts.ini file:

[newuser]
avatar=IH8gfyB/3H/cf9x/3H8gfyB/IH8gfyB/3n/bf9t/23/bf91/IH8gfyB/IH/ef9t/23/bf9t/3X8gfyB/IH8gf9x/23/bf9t/23/cfyB/IH8gf9t/23/bf9t/23/bf9t/238gfyB/23/bf9t/23/bf9t/23/bfyB/

This value can be set/changed with the avatar.js newuser command. For example, using JSexec:

jsexec avatars newuser=/sbbs/text/avatars/silhouettes.bin -offset=0

Note:
If no -offset value is provided, then an avatar will be chosen from the specified avatar collection (.bin file) at random.

Another option is to set the avatar_file key value to the path and filename of one of the avatar collection (.bin) files in your text/avatar directory.

If the avatar_offset key is not set (e.g. to a 0-based record index into the .bin file), then an avatar will be chosen at random from the specified avatar_file.

A default message avatar may be imported into the msg_default key of the [avatars] section of the ctrl/modopts.ini file using JSexec:

jsexec avatars msg-default=/sbbs/text/avatars/silhouettes.bin -offset=0

Note:
If no -offset value is provided, then an avatar will be chosen from the specified avatar collection (.bin file) at random.

Once imported into the modopts.ini file, you can rename or copy the msg_default key to <sub-code>_default or <group-name>_default as desired. The <sub-code> and <group-name> must be lower-case.

Avatars consist of a 10w x 6h grid of IBM Color_Graphics_Adapter character/attribute cells:

• 8-bit CP437 character (certain control characters and 0xFF are excluded)
• 8-bit attribute (color) value (the blink attribute bit is currently not supported)

... for a total unencoded/uncompressed size of 120 bytes per avatar.

Support for high-intensity background attributes (so-called iCE colors) are being considered.

Avatar collections are distributed and stored as 10-column “BinaryText” (.bin) files with a valid SAUCE record describing the contents. Up to 255 avatars may be collected in a single .bin file.

Each SAUCE comment is an optional avatar description which corresponds with the relative avatar in the collection (comment[0] describes the first avatar, comment[1] describes the second, and so-on). While SAUCE comments are allowed to be as long as 64 characters each, it is recommended to keep avatar descriptions to 10 characters or less for BBS-display considerations.

Accurate Title, Author, and Group values in the SAUCE record may be helpful to users selecting avatar collections of interest to them.

Avatars containing illegal characters (e.g. terminal control characters) or attributes (currently, BLINK) will not be imported or exported.

If you are an ANSi/Block-text artist and would like to contribute an avatar collection for stock-inclusion or network-distribution, please contact digital man. I'm particularly interested at this time in the merits of iCE colors and whether or not we should go through the effort to support them (they're already supported in SyncTERM 1.0).

When using PabloDraw to create or edit avatars or avatar collections, be aware:

1. PabloDraw defaults to 80 columns width, so you may need to change the width to 10 columns manually
2. PabloDraw defaults to enabling iCE colors, so you may want to disable this to be sure you don't accidentally include the BLINK attribute
3. PabloDraw truncates (chops-off) the last row of .bin files when saving them, so you'll need to add an extra line (e.g. of X's) before saving, and repeat this step if you close and re-open the file in PabloDraw
4. PabloDraw has issues creating the SAUCE comment block correctly (at least, on Windows) - instead of an array of 64 character fields, it creates a single \n-delimited field, of up to 64 characters
5. You can use jsexec sauce -e <filename> to edit SAUCE records of files and work around some of these issues

The old MS-DOS program, TheDraw, can load and edit BinaryText (.bin) files. However, it is limited to 50 lines (8 avatars) and does not create or update SAUCE records.

You can import a local avatar from a .bin file into a local user account by running:

jsexec avatars import=usernum /full/path/to/filename.bin

Where usernum is the user's account number (e.g. 1 for the sysop) and the filename.bin is a valid avatar file or collection.

If the .bin file contains an avatar collection (multiple avatars), the *first* avatar in the file will be imported unless you add the -offset=n option (where n is the record offset of the avatar you wish to import).

Before sharing an avatar collection, it's a good idea to verify the file first using the command-line:

jsexec avatars verify filename.bin

If you do not specify a full path to filename.bin, the avatars module will look for it in the text/avatars directory.

The SAUCE record of an avatar collection is important. You may use the sauce.js utility script to view a file's sauce record like so:

jsexec sauce -v /full/path/to/filename.bin

If you would like to edit the SAUCE record, you can use same utility script like so:

jsexec sauce -e /full/path/to/filename.bin

You can now share a locally created avatar collection to a message network by running:

jsexec avatars export /full/path/to/filename.bin

Note: Multiple filenames may be specified (and exported) per invocation. If you wish to use wildcards to automatically expand to multiple files on the command-line with JSexec for Windows, you will need a recent v3.17 build of JSexec.exe (linked with setargv.obj).

If you use the -share command-line option along with the export command, then any files matching the pattern: text/avatars/<QWK-ID>.*.bin will be automatically exported whenever the avatars.js export command is used. Where <QWK-ID is the local system's QWK-ID (SCFG->Message Options->BBS ID) value, in uppercase.

Note: Export frequency controls (export_freq setting in modopts.ini) applies to avatar collections as well as user avatars.

avatars.js supports several commands and options, many are only to be used for experimental or trouble-shooting purposes. For a comprehensive list of commands and options, view the file: avatars.js:

Commands are just words (no special prefix), but many commands support an optional =<value> suffix:

Command-line options contain a - prefix and are used to modify the default behavior of the avatars.js module:

• Modules
• JSexec
• Web-based Avatar Gallery