====== 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. [[network:DOVE-Net]]). {{:module:avatars_announcement.png?300|}} Avatars are also displayed in [[module:sbbslist|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 ''[[dir:exec]]/[[module:logon]]''.js module (rev 1.26 or later). ===== Collections ===== The set of [[https://gitlab.synchro.net/sbbs/sbbs/-/tree/master/text/avatars/|stock avatar collections]] available for users to choose from includes over 150 original pieces of ANSI-art created and contributed by Synchronet sysops: [[person:digital man]], [[person:echicken]], and [[person: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 [[https://bbs.electronicchicken.com/?page=More/avatar-gallery.xjs|in the works]], per [[person:echicken]]): {{:module:avatars_animals.png?300|}} {{:module:avatars_emoji.png?300|}} {{:module:avatars_profiles.png?300|}} {{:module:avatars_gaming.png?300|}} {{:module:avatars_corporate.png?300|}} {{:module:avatars_musical.png?300|}} {{:module:avatars_danger.png?300|}} {{:module:avatars_starwars.png?300|}} * Additional avatar collections can be easily and automatically [[#sharing avatar collections|shared]] among sysops that are members of the same message network (e.g. [[network: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 ^ |''[[dir:exec]]/avatars.js'' | Utility module to import, export, and verify user avatars and avatar collections | | ''[[dir:exec]]/load/avatar_lib.js'' | Library for dealing with avatars | | ''[[dir:exec]]/load/sauce_lib.js'' | Library for dealing with SAUCE records | | ''[[dir:exec]]/load/graphic.js'' | ANSI "graphics" library | | ''[[dir:exec]]/load/ansiterm_lib.js'' | ANSI terminal library | | ''[[dir:exec]]/showmsghdr.js'' | Module to display a message header, with avatar (i.e. executed via ''msghdr.asc'' for v3.16 ) | | ''[[dir:exec]]/showmsgavatar.js'' | Module to display a message avatar, only (using ''text.dat'' approach or custom ''msghdr.asc'') | | ''[[dir:exec]]/showfileavatar.js'' | Module to display a file uploader's avatar (with v3.17) | | ''[[dir:exec]]/avatar_chooser.js'' | Avatar browser / selector / uploader / downloader / editor | | ''[[dir:text]]/menu/msghdr.asc'' | Only needed if using v3.16: executes ''showmsghdr.js'' | | ''[[dir:text]]/menu/main.asc'' | Updated to include new ''/A'' (change avatar) main menu option | | ''[[dir:exec]]/default.src'' | Updated to include new ''/A'' (change avatar) main menu option | | ''[[dir:exec]]/default.bin'' | Generated by compiling ''default.src'' using [[util:Baja]] | | ''[[dir:exec]]/logon.js'' | Updated to display user's avatar during logon sequence | | ''[[dir:exec]]/newuser.js'' | Updated to set a new user's default avatar, when configured in ''modopts.ini'' | | ''[[dir:text]]/avatars/*.bin'' | Avatar collections (from the Synchronet Source Repository and imported from SYNCDATA) | ===== Install ===== ==== 3.16 ==== If running Synchronet v3.16 or a non-current v3.17: Download the file ''[[https://gitlab.synchro.net/sbbs/sbbs/-/raw/master/text/menu/msghdr.asc|msghdr.asc]]'' to your ''[[dir:text]]/menu/'' directory, if you do not already have it (e.g. from [[dev:Git]]). This ''msghdr.asc'' will execute the script ''[[dir:exec]]/showmsghdr.js'' whenever a message header is displayed to a user of the Terminal Server. **If** you have an already-customized ''[[dir: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 ''[[dir: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). ==== Step 2 ==== From a command prompt, run ''jsexec avatars install'' This step will perform all the necessary [[util:SCFG]] changes and optional ''[[config: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 [[http://cvs.synchro.net/cgi-bin/viewcvs.cgi/exec/default.src?r1=1.18&r2=1.19|small change]] was already made in the "Synchronet Classic" command shell: ''[[dir:exec]]/default.src''. You will need to recompile ''default.src'' to ''default.bin'' using [[util:Baja]] (in the ''[[dir:exec]]'' directory): baja default.src There's a corresponding to change to the default main menu (''[[dir: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 [[util: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 [[util: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 ''[[dir:data]]/qnet'' directory. Validated avatar collections will then be copied into your ''[[dir: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 [[util: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 ''.*.bin'' in the ''[[dir: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 ''[[dir:ctrl]]/[[config:modopts.ini]]'' file: [avatars] sub = dove-syncdata export_freq = 7 The ''showmsgavatar.js'' module uses the ''sub_default'' or ''////_default'' or ''////_default'' values for a default avatar to show for messages from users without an avatar. ^ Option ^ Default ^ Description ^ | sub | //auto// | Sub-board internal code for import and export command (your networked //sync-data// message area) | | export_freq | ''7'' | Maximum export (to message-base) frequency, in days | | msg_default | //none// | Default avatar (base64-encoded) for displaying messages from users without an avatar | | ////_default |//none//| Default avatar (base64-encoded) for the specified message sub-board (internal code, lowercase) | | ////_default |//none//| Default avatar (base64-encoded) for the specified message group (name, lowercase)| | msghdr_draw_top | ''true'' | Display message avatar at the top-of-screen when the message header was displayed at top-of-screen | | msghdr_draw_above | ''true'' | Display message header avatar above current cursor position | | msghdr_draw_right | ''true'' | 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). Also in the ''[[dir:ctrl]]/[[config:modopts.ini]]'' file: [newuser] avatar = avatar_file = avatar_offset = <0-based record number of avatar to use> [logon] set_avatar = The ''set_avatar'' value in the ''[logon]'' section, when set to ''true'', will cause the ''[[module: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 ''[[dir:ctrl]]/[[config: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 [[util: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 ''[[dir:ctrl]]/[[config:modopts.ini]]'' file using [[util: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 ''////_default'' or ''////_default'' as desired. The ''////'' and ''////'' must be lower-case. ===== Specifications ===== Avatars consist of a 10w x 6h grid of IBM [[wp>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 [[http://www.acid.org/info/sauce/sauce.htm|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 [[person: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 [[http://syncterm.net|SyncTERM 1.0]]). ===== Tips ===== ==== PabloDraw ==== 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 ''.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 - 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 '' 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 ''[[dir: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: ''[[dir:text]]/avatars/////.*.bin'' will be automatically exported whenever the ''avatars.js'' ''export'' command is used. Where ''//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 ''='' suffix: ^ Command ^ Description ^ | import | Import user avatars and avatar collections from a networked message base | | import= | Import an avatar for a specific local user account number | | export | Export any new/updated local user avatars to a networked message base | | export | 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= | 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= | Display specified user's avatar | | draw | Display specified avatar collection files | | show | Display (using relative positioning and terminal-compliant representation) the current user's avatar | | show= | Display specified user's avatar | | show | Display specified avatar collection files | | verify | Verify specified avatar collection files | | remove | Remove current user's avatar | | remove= | Remove specified user's avatar | | enable | Enable current user's avatar | | enable= | Enable specified user's avatar | | disable | Disable current user's avatar | | disable= | Disable specified user's avatar | | newuser | Import a new user default avatar from specified avatar collection file (use with ''-offset'') | | msg-default | Import a default message avatar from specified avatar collection file (use with ''-offset'') | | normalize | 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= | 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= | 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= | Specify a user account number to operate on (not normally required) | | -file= | Specify a filename to operate on (not normally required) | ===== See Also ===== * [[:module:|Modules]] * [[:util:JSexec]] * [[https://bbs.electronicchicken.com/?page=More/avatar-gallery.xjs|Web-based Avatar Gallery]] {{tag>ansi avatar}}