Table of Contents
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.
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).
|Utility module to import, export, and verify user avatars and avatar collections|
| ||Library for dealing with avatars|
| ||Library for dealing with SAUCE records|
| ||ANSI “graphics” library|
| ||ANSI terminal library|
| || Module to display a message header, with avatar (i.e. executed via
| || Module to display a message avatar, only (using
| ||Module to display a file uploader's avatar (with v3.17)|
| ||Avatar browser / selector / uploader / downloader / editor|
| || Only needed if using v3.16: executes
| || Updated to include new
| || Updated to include new
| || Generated by compiling
| ||Updated to display user's avatar during logon sequence|
| || Updated to set a new user's default avatar, when configured in
| ||Avatar collections (from the Synchronet Source Repository and imported from SYNCDATA)|
If running Synchronet v3.16 or a non-current v3.17:
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
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).
.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
Update your command shells to either execute
avatar_chooser.js directly (using Baja
exec_bin or JS
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.bin using Baja (in the
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 ║ ╚══════════════════════════════════════════════════════════╝
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
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.
[avatars] sub = dove-syncdata export_freq = 7
showmsgavatar.js module uses the
<sub-code>_default values for a default avatar to show for messages from users without an avatar.
|sub||auto||Sub-board internal code for import and export command (your networked sync-data message area)|
|export_freq|| ||Maximum export (to message-base) frequency, in days|
|msg_default||none||Default avatar (base64-encoded) for displaying messages from users without an avatar|
|<sub-code>_default||none||Default avatar (base64-encoded) for the specified message sub-board (internal code, lowercase)|
|<group-name>_default||none||Default avatar (base64-encoded) for the specified message group (name, lowercase)|
|msghdr_draw_top|| ||Display message avatar at the top-of-screen when the message header was displayed at top-of-screen|
|msghdr_draw_above|| ||Display message header avatar above current cursor position|
|msghdr_draw_right|| ||Display message header avatar right-justified|
When user avatars or shared avatar collections (
.bin files) are updated, they will be exported immediately (or when the
AVAT-OUT event is executed).
[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>
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
This value can be set/changed with the
newuser command. For example, using JSexec:
jsexec avatars newuser=/sbbs/text/avatars/silhouettes.bin -offset=0
-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
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
Message Default Avatar
jsexec avatars msg-default=/sbbs/text/avatars/silhouettes.bin -offset=0
-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
<group-name>_default as desired. The
<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
Each SAUCE comment is an optional avatar description which corresponds with the relative avatar in the collection (comment describes the first avatar, comment 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:
- PabloDraw defaults to 80 columns width, so you may need to change the width to 10 columns manually
- PabloDraw defaults to enabling iCE colors, so you may want to disable this to be sure you don't accidentally include the BLINK attribute
- PabloDraw truncates (chops-off) the last row of
.binfiles 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
- 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
- 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.
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.
.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
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
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
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
export command is used.
<QWK-ID is the local system's QWK-ID (SCFG->Message Options->BBS ID) value, in uppercase.
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:
Commands are just words (no special prefix), but many commands support an optional
|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 -share|| Export any/all locally-shared avatar collections (throttled by
|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
|msg-default <filename>|| Import a default message avatar from specified avatar collection file (use with
|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|
Command-line options contain a
- prefix and are used to modify the default behavior of the
|-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 avatars, include the user's full real name as well as their alias|
|-aliasonly||When exporting user avatars, do not include even an MD5-digest of the user's real name|
|-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
|-user=<value>||Specify a user account number to operate on (not normally required)|
|-file=<value>||Specify a filename to operate on (not normally required)|