Synchronet v3.19b-Win32 (install) has been released (Jan-2022).

You can donate to the Synchronet project using PayPal.

This is an old revision of the document!


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).

Collections

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).

Dependencies

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).

Support Files

File Description
exec/avatars.js Utility module to import, export, and verify user avatars and avatar collections
exec/load/avatar_lib.js Library for dealing with avatars
exec/load/sauce_lib.js Library for dealing with SAUCE records
exec/load/graphic.js ANSI “graphics” library
exec/load/ansiterm_lib.js ANSI terminal library
exec/showmsghdr.js Module to display a message header, with avatar (i.e. executed via msghdr.asc for v3.16 )
exec/showmsgavatar.js Module to display a message avatar, only (using text.dat approach or custom msghdr.asc)
exec/showfileavatar.js Module to display a file uploader's avatar (with v3.17)
exec/avatar_chooser.js Avatar browser / selector / uploader / downloader / editor
text/menu/msghdr.asc Only needed if using v3.16: executes showmsghdr.js
text/menu/main.asc Updated to include new /A (change avatar) main menu option
exec/default.src Updated to include new /A (change avatar) main menu option
exec/default.bin Generated by compiling default.src using Baja
exec/logon.js Updated to display user's avatar during logon sequence
exec/newuser.js Updated to set a new user's default avatar, when configured in modopts.ini
text/avatars/*.bin Avatar collections (from CVS and imported from SYNCDATA)

Install

3.16

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 CVS).

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.

Step 1

If you haven't already, get the text/avatars directory contents either via CVS or download from this web-page: http://cvs.synchro.net/cgi-bin/viewcvs.cgi/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).

Step 2

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.

Step 3

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.

Configuration

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

AVATCHOO

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.

AVAT-IN

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).

AVAT-OUT

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.

modopts.ini

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.

Option Description
sub Sub-board internal code for import and export command (default: auto-detected)
export_freq Maximum export (to message-base) frequency, in days (default: 7)
msg_default Default avatar (base64-encoded) for displaying messages from users without an avatar
<sub-code>_default Default avatar (base64-encoded)for the specified message sub-board
<group-name>_default Default avatar (base64-encoded) for the specified message group

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.

New User Default Avatar

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.

Message Default Avatar

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.

Specifications

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.

Collections

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).

Tips

PabloDraw

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

TheDraw

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.

Import Local Avatar Files

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).

Sharing Avatar Collections

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).

Automatic Sharing

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.

Command-Line

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

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

Command Description
import Import user avatars and avatar collections from a networked message base
import=<usernum> Import an avatar for a specific local user account number
export Export any new/updated local user avatars to a networked message base
export <filenames> Export one or more avatar collections to a networked message base (forced, not throttled by export_freq value)
export -share Export any/all locally-shared avatar collections (throttled by export_freq)
dump=<usernum> Display a JSON representation of a local user account's avatar configuration
draw Display (using absolute positioning and ANSI only) the current user's avatar
draw=<usernum> Display specified user's avatar
draw <filenames> Display specified avatar collection files
show Display (using relative positioning and terminal-compliant representation) the current user's avatar
show=<usernum> Display specified user's avatar
show <filenames> Display specified avatar collection files
verify <filenames> Verify specified avatar collection files
remove Remove current user's avatar
remove=<usernum> Remove specified user's avatar
enable Enable current user's avatar
enable=<usernum> Enable specified user's avatar
disable Disable current user's avatar
disable=<usernum> Disable specified user's avatar
newuser <filename> Import a new user default avatar from specified avatar collection file (use with -offset)
msg-default <filename> Import a default message avatar from specified avatar collection file (use with -offset)
normalize <filenames> Normalize one or more avatars
normalize Normalize the current user's avatar
install Install the avatars and avatar_chooser modules into a Synchronet system

Options

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

Option Description
-v Increase verbosity of console output (e.g. for trouble-shooting)
-offset=<value> Specify a record offset of an avatar in an avatar collection file
-realnames When exporting user avatar, include the user's real name as well as their alias - required if the message network uses/requires real names
-ptr=<value> Over-ride the stored import/export message pointer value
-all Import/export all messages (even those exported locally) - not normally recommended
-share When combined with the export command, automatically exports any new/updated shared avatar collections and will re-export at the configured export_freq interval
-user=<value> Specify a user account number to operate on (not normally required)
-file=<value> Specify a filename to operate on (not normally required)

See Also