====== Install Doors ======

Instructions for installing external online programs (a.k.a. doors) into the Synchronet BBS for use by users of the [[server:terminal|Terminal Server]].

===== Overview =====

BBS "doors" are external online programs, often games, that may be installed on a BBS system for its remote terminal users to use interactively. Doors are usually 16-bit DOS programs from "back in the day" and can be challenging to get working on the computers and operating systems of today. A little patience and the use of pages like this one can usually get them working however.



==== Supported External Program Types ====

The following table should help you to identify what types of online external programs (doors, external editors, file transfer protocol drivers) are supported by Synchronet and in what environments:

^ I/O Method         ^ Description                                           ^ Examples                                               ^ Typical Drop File Types   ^ OS ^
| [[ref:FOSSIL]]     | 16-bit DOS BBS doors and external editors             | TradeWars 2002, GlobalWar, LORD, FDSZ                  | DOOR.SYS and DORINFO#.DEF | Windows and [[howto:dosemu|Linux]]|
| COM/UART           | 16-bit DOS BBS doors and external editors             | DSZ, NukeWars                                          | DOOR.SYS and DORINFO#.DEF | Windows |
| DOS Console        | 16-bit Synchronet and WWIV doors and external editors | Food Fight! by Rigor Mortis, Dragon's Hoard, SBJ/SBL v2.x | CHAIN.TXT and XTRN.DAT    | Windows |
| TCP/IP Socket      | Native TCP/IP BBS doors and external editors          | DoorMUD, PimpWars/Win32, Darkness/Win32, SBJ/SBL v3.x  | DOOR32.SYS and XTRN.DAT   | Windows and *nix |
| Standard           | Native stdio/console programs (traditionally, UNIX)         | PimpWars/Linux, Lord/X, "scfg -d", cmd.exe, bash, pico | DOOR32.SYS | Windows and *nix |

==== Supported Drop File Types ====
Synchronet can create and read-back a variety of drop file types based on the requirements of the door program:

^ Software	^ Write File(s)		                ^ Read File(s)     ^
| Mystic        | ''DOOR32.SYS''                        |                  |
| GAP (original)| ''DOOR.SYS'' (31 lines)                | ''DOOR.SYS'': Flags, SecLevel, ExpireDate, FileDLed, KBsDLed |
| GAP (extended)| ''DOOR.SYS'' (52 lines)                | ''DOOR.SYS'': Flags, SecLevel, ExpireDate, FileDLed, KBsDLed, MinuteCredits |
| WWIV		| ''CHAIN.TXT''                         |                  |
| PCBoard 15.x	| ''PCBOARD.SYS'' and ''USERS.SYS''     | ''USERS.SYS'': SecLevel and ExpireDate |
| QuickBBS	| ''DORINFO#.DEF'' and ''EXITINFO.BBS'' | ''EXITINFO.BBS'': Flags and SecLevel |
| Wildcat! 2.x	| ''CALLINFO.BBS''                      |                  |
| SpitFire	| ''SFDOORS.DAT''                       |                  |
| TriBBS	| ''TRIBBS.SYS''                        |                  |
| Solar Realms	| ''DOORFILE.SR''                       |                  |
| Synchronet  	| ''XTRN.DAT''			        | ''MODUSER.DAT'': Credits, SecLevel, Flags, ExpireDate, MinuteCredits  |

=== CIOXTRN ===
Through the use of Deuce's ''CIOXTRN.EXE'' program (similar to the old 16-bit DOS DoorWay program), DOS and Windows-native console I/O programs not intended to run on a BBS can also be run on Synchronet for Windows.

=== Modules ===
Although technically not //external programs//, Synchronet also supports the interpretation and execution of external [[:module:|modules]] written in [[util:Baja]] or [[custom:JavaScript]] (preferred), on all currently supported platforms.

**Note:**
There is an active movement within the Synchronet development community to port or re-write old BBS door games and utilities in JavaScript so that they may be run natively on all Synchronet-supported platforms without any compiling or communications issues. In fact, the latest Synchronet Installer (for Windows) release includes no 16-bit DOS programs and very few native external programs, replacing the traditionally pre-configured DOS door games and external editors with newer, better games and editors written in JavaScript.
===== Installation =====

Doors are usually installed into a sub-directory of the Synchronet ''[[dir:xtrn]]'' directory. Example: ''/sbbs/xtrn///doorname//'', where ''//doorname//'' is a short (8 characters or less) abbreviation of the door's name. 

:!: Tip: do **not** install DOS doors into a directory with a long name (more than 8 characters) or with spaces or other special characters in the directory name or the door program may not work.

Some doors may require the sysop to run some sort of //setup// or //initialization// program before the door can be used, so be sure to read the door's documentation files (e.g. ''readme.1st'', ''sysop.txt'', ''*.doc'', etc.) first. Remember that most door documentation was written in the 1990's (or earlier), so take some instructions (specifically those referring to FOSSIL drivers) with a grain of salt.

==== Automated Install ====

If the door is included with Synchronet, or Synchronet already has a configuration for it (in xtrn/3rdp-install), you can use the install-xtrn.js script to install your door.

Run ''[[dir:exec]]/jsexec install-xtrn.js''

For more information, see [[module:install-xtrn|Install Xtrn]]

==== Manual Install ====

If the door you're installing is listed in the following [[#how-to_install_specific_doors|How-To Install pages]], that might be all the instructions you need.

==== Runtime error 200 ====

Some 16-bit DOS programs (including many old doors) which were written
and compiled with Turbo Pascal will have a problem (divide by zero) running on faster computers.
The error will show
itself upon execution of the door something like this:
  Runtime error 200 at 345A:0091

This is a well known problem (often referred to as "RTE200") and there are several programs
which you can use to 'patch' the ''.EXE'' files to fix the problem.
Which patch works seems to depend upon the program in question.

  * [[ftp://vert.synchro.net/main/util/patchcrt.zip]]

[[http://web.archive.org/web/20200202223544/http://www.merlyn.demon.co.uk:80/pas-r200.htm|This]] is an entire page on the subject matter with links to several patching programs.

You may need to patch the ''.EXE'' files before you can even install or setup the door.

==== FOSSIL Driver ====

With Synchronet on 32-bit Windows operating systems, you **do not** need to install a FOSSIL driver (Synchronet comes with its own). There is a free 3rd party FOSSIL driver for Windows NT-based operating systems called [[http://netfoss.com|NetFoss]], but you should not need it and installing it will only complicate matters. The old 16-bit DOS FOSSIL drivers (e.g. BNU, X00) will not work either.

=== DOSXTRN.EXE ===
The 16-bit DOS component of the Synchronet FOSSIL driver for Windows (all flavors) is called ''DOSXTRN.EXE'' and it is located in the Synchronet ''[[dir:exec]]'' directory. This program [[:faq:win#win64|will not work]] with 64-bit versions of Windows since Microsoft does not include a DOS virtual machine (NTVDM) with those versions of Windows.

=== Windows ===
The kernel component of the Synchronet FOSSIL driver for Microsoft Windows NT-based operating systems is called ''[[faq:win#sbbsexecdll|sbbsexec.dll]]'' and it is loaded when needed by Synchronet automatically if/when [[faq:win#win64|NTVDM]] is enabled((NTVDM is normally only available 32-bit/x86 editions of Windows)).

This FOSSIL driver is also a //virtual UART// driver so that external DOS programs that require COM/UART access for input and output (i.e. do not support FOSSIL), can still be used on the BBS. When supported, doors should be configured to use a FOSSIL interface instead of COM/UART for input and output (for better performance and compatibility).

This FOSSIL driver can be configured (tweaked) for the specific needs of your system or a particular DOS door program by editing your ''[[config:sbbsexec.ini]]'' file.

===== Configuration =====

Add the program in SCFG [[util:SCFG:external programs:Online Programs]] under ''%%Online Programs...%%'' in a new or existing Online Program Section.

The most critical [[util:SCFG]] configuration options for successful installation of an online program (door) are:

  - [[#Start-up Directory]]
  - [[#Command Line]]
  - [[#I/O Method]]
  - [[#Native Executable/Script]]
  - [[#BBS Drop File Type]]  
 

==== Name ====

Enter a descriptive name for the program, but try not to be redundant (the words "door" and "game" and not likely useful in the name). Some sysops choose to include the version of the program as well as the name.

==== Internal Code ====

Enter a short (up to 16 characters), unique name for the program which Synchronet will use for internal reference purposes.

The chosen internal code may not be the same as any other installed external program.

The internal code may be used to programmatically launch the external program when the remote user views a specific text or menu file (see [[custom:atcodes]]) or from a custom [[:module:]] or command shell.

==== Start-up Directory ====

The ''Start-up Directory'' should normally be the directory where the door was installed (e.g. ''../[[dir:xtrn]]///doorgame//'').

If the door was installed in a subdirectory of your ''[[dir:xtrn]]'' directory, it is recommended that you use a //relative// path (e.g. starting with ''../xtrn/'') rather than an //absolute// path (e.g. ''c:\sbbs\xtrn\doorgame'' or ''/sbbs/xtrn/doorgame'') as this will allow you to move the Synchronet directory tree to another drive or to another directory hierarchy without requiring modifications to your external program configurations.

On Windows, the ''Start-up Directory'' may use forward-slashes (''/'') or back-slashes (''\'') as path separators, but for compatibility with other OSes, it is recommended to use forward-slashes (e.g. ''../xtrn/doorgame/'' instead of ''..\xtrn\doorgame\'') always.

The ''Start-up Directory'' may or may not end in a trailing path separator (slash).

If no ''Start-up Directory'' is specified, the current working directory when the program is executed will be your Synchronet ''[[dir:ctrl]]'' directory.

An invalid (e.g. non-existing) ''Start-up Directory'' will cause Synchronet to log and display an error message and not attempt to execute the program.

When executing an in-process Baja module (''.bin'' file), the ''Start-up Directory'' is not used.

When executing an in-process JavaScript module (''.js'' file), the ''Start-up Directory'' is searched for the script to execute and the string is also placed in the global JavaScript property/variable: ''startup_dir''.

==== Command Line ====

This is the command to be executed when a remote user launches this external program.

Some programs may require command-line switches or options to enable specific behavior (e.g. ''/F'' to enable FOSSIL support) or specify the path to the BBS drop file.

As part of the command-line, you may use Synchronet Command Line [[config:cmdline#Specifiers]]. These are variables which will expand to useful dynamic values before the command-line is executed.

The most commonly used [[config:cmdline#Specifiers]] for use with external program command-lines are:

^Specifier ^Description ^
|  ''%f''  |Path to the drop file created by the BBS for this external program execution (e.g. ''C:\SBBS\NODE1\DOOR.SYS'')|
|  ''%s''  |Path to the program's startup directory, if specified (e.g. ''../xtrn/mygame/'') |
|  ''%n''  |Path to the current node directory (e.g. ''C:\SBBS\NODE1\'')|
|  ''%#''  |Current node number (1-255)|
|  ''%h''  |Current socket descriptor |
|  ''%t''  |User's time remaining/available, in seconds (e.g. ''60'')|
|  ''%.''  |Expands to ''.exe'' on Windows, nothing on other operating systems. Useful when hosting BBS nodes on multiple OSes with the same configuration files.|

=== Modules ===

When executing an in-process module (Baja or JavaScript), begin the [[#Command Line]] with a ''*'' (JavaScript or Baja) or ''?'' (JavaScript only) character.

The path to the module and the ''.bin'' or ''.js'' file suffix/extension is not required.

Example: ''?mymodule''

==== Clean-up Command Line ====

This is an optional command-line to be executed after the program has returned control to the BBS. 

The ''Clean-up Command Line'' may contain Command Line [[config:cmdline#Specifiers]].

The [[#Native]], [[#I/O Method]], and [[#Use Shell or New Context]] options affect the execution of the ''Clean-up Command Line'' (if non-blank).

Most external programs do not require a ''Clean-up Command Line'' to be specified.

==== Execution Cost ====

This optional value is the number of credits to deduct from the user when executing this program.

==== Access Requirements ====

This is the optional //Access Requirements String// (ARS) which specifies which users may //see// this program (default: //all// users).

==== Execution Requirements ====

This is the optional //Access Requirements String// (ARS) which specifies which users may //execute// (run) this program (default: //all// users).

If you are host BBS nodes on multiple OSes and this program is only compatible with a subset of those OSes, you may want to specify the compatible ARS OS keywords here (e.g. ''WIN32'', ''LINUX'', etc.).

==== Multiple Concurrent Users ====

If this program supports execution by multiple simultaneous users, then this option should be set to ''Yes''.

Note: for multiple-user programs, it is highly recommended that the BBS drop file be created in the ''[[dir:node]]'' directory.

==== I/O Method ====

If the program requires the BBS to intercept standard console input and output operations, then this option should be set to ''Standard''.

  * Most 16-bit (DOS) BBS doors will require this option be set to ''FOSSIL or UART'' (only available for 16-bit DOS programs).
  * Most //native// (Win32 or *nix) BBS doors will require this option be set to ''Socket'' (only available for native programs).
  * When executing an in-process module (Baja or JavaScript), the ''I/O Method'' option is not applicable.

==== Native Executable/Script ====

If this program is native to the host operating system (e.g is **not** a 16-bit DOS program), then this option should be set to ''Yes''.

  * BBS Doors that use FOSSIL I/O are inherently 16-bit DOS programs and must have this option set to ''No''.
  * BBS Doors that use COM/UART I/O are usually 16-bit DOS programs and should therefore have this option set to ''No''.
  * BBS Doors that use Socket I/O are native (32-bit or 64-bit) programs and must have this option set to ''Yes''.

When executing an in-process module (Baja or JavaScript), the ''Native Executable/Script'' option is not used (all //modules// are native).

==== Use Shell or New Context ====

If this program requires an OS command shell (e.g. it's a *nix shell script, ''.sh'' file, or Windows ''.bat'' or ''.cmd'' file), then this option should be set to ''Yes''.

When executing a JavaScript module, enabling this option forces a new JS engine context (i.e. sandbox) to be created and used to execute the script.

==== Modify User Data ====

If this program supports modification of the user's data via drop file, then this option should be set to ''Yes''.

==== Execute on Event ====

If you wish for this program to be automatically executed based on specific user operations, you may select those events here.

The available events are:

  * Logon          
  * Logoff         
  * New User       
  * Birthday       
  * Message Posted 
  * File Uploaded  
  * File Downloaded 
  * Local/Sysop Chat

If an event is selected, you may also specify that the program may be executed **only** on that event and not purposely selected by the user from a menu for manual execution.

Normally, this option is set to ''No'' for most door programs.

==== Pause After Execution ====

This option may be useful if you wish to debug a problem with a program which is displaying text just before quitting and the screen is being cleared (and you don't have scroll-back capabilities).

Normally, this option is set to ''No'' for most door programs.

==== BBS Drop File Type ====

Most BBS door programs require a //drop file// to be created by the BBS in a predetermined format and often with a predetermined filename. 

This menu option allows you to select the proper drop file format, name, and case (sometimes important on non-Windows systems) and whether or not to include the user's //alias// or //real name// in the drop file.

The available drop file formats are:

^Type            ^File            ^
|Synchronet      |''XTRN.DAT    ''|
|WWIV            |''CHAIN.TXT   ''|
|GAP             |''DOOR.SYS    ''| 
|RBBS/QuickBBS   |''DORINFO#.DEF''| 
|Wildcat         |''CALLINFO.BBS''|
|PCBoard         |''PCBOARD.SYS ''| 
|SpitFire        |''SFDOORS.DAT ''| 
|MegaMail        |''UTIDOOR.TXT ''| 
|Solar Realms    |''DOORFILE.SR ''| 
|RBBS/QuickBBS   |''DORINFO1.DEF''|
|TriBBS          |''TRIBBS.SYS  ''| 
|Mystic          |''DOOR32.SYS  ''| 

==== Place Drop File In ====

The drop file (if not set to ''None'') may be created in either the ''[[dir:node]]'' directory or the specified ''[[#Start-up Directory]]'' based on the setting of this option.

If the path to the drop file (e.g. ''%f'') is included on the ''[[#Command Line]]'', then it may not matter where the drop file is created.

However, for multiple-user programs, it is highly recommended that the drop file be created in the ''[[dir:node]]'' directory to avoid collisions and race conditions between nodes.

==== Time Options ====

This sub-menu allows you to specify certain time constraints and monitoring behavior while the program is being run by the user.

The defaults ''Time Options'' settings are:

|''Extra Time               ''|''None      ''|
|''Maximum Time             ''|''None      ''|
|''Suspended (Free) Time    ''|''No        ''|
|''Monitor Time Left        ''|''No        ''|

===== How-To Install Specific Doors =====
Note: When using Linux with dosemu, specify full filename with extension under the Command Line option in the [[util:scfg]] External Programs settings, more specifically when using batch (.bat) files. For example LORD2 would be "lord2.bat %#" and not "lord2 %#" which is mentioned on the [[howto:dosemu|Use DOS Doors with Synchronet on Linux]] page.

{{indexmenu>.|tsort}}

===== See Also =====
  * [[:faq:win#sbbsexecdll|sbbsexec.dll]]
  * [[:config:sbbsexec.ini]]
  * [[:config:cmdline|Configure Command Lines]]
  * [[:howto:dosemu]]
  * [[:howto:doscmd]] 
  * [[:howto:|How-To Pages]]
  * [[:howto:cioxtrn]]
  * [[https://www.youtube.com/channel/UCcHJZZmXcXRtJjqCr9_W4eA|Door Game Review Videos]]
  * [[https://if50.substack.com/p/1991-trade-wars-2002|Trade Wars 2002]]

{{tag>door fossil uart}}
