root/trunk/docs/dosdoors.txt

This is a howto for getting dos doors up and running under Enthral BBS.

# Enthral SVN: $Id$
# Source: $HeadURL$
# $LastChangedDate$
# $LastChangedRevision$
# $LastChangedBy$

1st edition, expect revisions.
Created by esc.

CONTENTS:
1 - Introduction / Notes
2 - Theory of Operation
3 - Autoexec.bat
4 - door_script
5 - Example start.bat
6 - Modifying DOSEMU control files
7 - Enthral Menu Commands
8 - Contact info
9 - CHANGELOG


CHAPTER 1 - Introduction / Notes
A few notes:

I am using Enthral alpha, build .401.  Some things may change in the 
future.  Additionally, I'm using dosemu 1.4, the latest release as of 
April 1st, 2009.  Finally, I'm using gentoo x86, kernel 2.6.27.

A few things to note:

I launch the bbs from the directory /home/bbs/enthral/.  My user 'bbs', 
the owner of the bbs files, has a $home directory located at /home/bbs/.  
When I am local, as the user 'bbs', and I launch dosemu, it links to 
/home/bbs/.dosemu/.  That being said, as the user bbs, launching dosemu 
in a terminal window, my "C:\" drive is located at 
/home/bbs/.dosemu/drive_c/.

However, when launched from my door script, it links to 
/home/bbs/enthral/.dosemu/, with the "C:\" drive being 
/home/bbs/enthral/.dosemu/drive_c/.  The reason I do this, is so that 
when a user is logged on and playing dos doors, you can locally log on 
as user 'bbs' or whomever you use, and you can launch dosemu locally to 
modify some settings or install more doors, without accidentally 
launching the door they're already in :)


CHAPTER 2 - Theory of Operation


Now, the theory of operation.  Ideally, this is what needs to happen:

1 - Command key is pressed.
        D- is the internal enthral command to create dropfiles and run a 
        door.

        Drop files are placed in BBSDIR/node/node(current node number)/
        Essentially, node 1 on my bbs will make:
                /home/bbs/enthral/node/node1/DOOR.SYS
                /home/bbs/enthral/node/node1/DORINFO1.DEF
                /home/bbs/enthral/node/node1/CHAIN.TXT

        Keep in mind, enthral will make DORINFO#.DEF for all nodes, with
        DORINFO1.DEF for node 1, DORINFO2.DEF for node 2, etc.

        Enthral will then launch an external script.  It will be a bash
        script, and is the basis for running all dos doors.  It will 
        essentially create the necessary batch files so that upon
        launch, dosemu will automatically run the door with the proper
        arguments.

        Dosemu's autoexec.bat will automatically run the batch file
        created by the previously mentioned bash script.  That batch
        file will change to the desired door directory, and launch
        the door with the proper node/directory arguments included.

        Finally, the batch file will exit back to the bbs.

Theory of operation complete.  Ok, got it?  Good, on to the example 
files :)

CHAPTER 3 - Autoexec.bat

We'll start with autoexec.bat.  I've modified both my 
/home/bbs/.dosemu/drive_c/autoexec.bat, as well as the 
/home/bbs/enthral/.dosemu/drive_c/autoexec.bat.  The changes that we 
need to make are as follows:

We need to make the file and directory structure make more sense for 
configuring doors, as well as call up a fossil driver, and finally call 
the batch file to run the doors.  What I suggest is changing to your 
/home/bbs/enthral/.dosemu/drive_c/ directory, and downloading BNU, as 
well as unzipping it.  Put it in your drive_c/ dir, but mkdir bnu and 
put the necessary files in there.  It's up to you, but that's just how I 
do it.  Here's MY autoexec.bat, with a line by line explanation.

BEGIN AUTOEXEC.BAT:
---------------------------------------------------------



@echo off
path z:\bin;z:\gnu;z:\dosemu
set HELPPATH=z:\help
set TEMP=c:\tmp
prompt $P$G
lredir d: linux\fs/home/bbs
lredir f: linux\fs/home/bbs/enthral/doors

c:
cd\bnu
call bnu.com /L0:57600,8N1 /F

c:
cd\
rundoor.bat


The @echo off is to keep the batch file from displaying all lines of 
instructions to the console.
The path is to simplify typing things in later, not really necessary.
The help path and temp directories were set that way by dosemu 
initially, and I'm not sure what they're for...I just left them :)
The prompt $p$g gives us our nice "C:\" prompt.
lredir d: linux\fs/home/bbs

^^^^ This is important.  This links your /home/bbs/ directory to D:\.
Change this to say:
lredir d: linux\fs/YOUR BBS USER'S HOME DIRECTORY

lredir f: linux\fs/home/bbs/enthral/doors

^^^^ This is equally important.  This links your doors directory to F:\.
Change this to say:
lredir f: linux\fs/YOUR DOORS DIRECTORY

c:
cd\bnu
call bnu.com /L0:57600,8N1 /F

^^^^ Change to your bnu directory that was discussed earlier.  Call 
bnu.com will load the tsr into memory.  It's important for some doors 
that you lock the port, and the arguments above lock it as virtual com1, 
57600 bps, fast ansi.  It works right 100% of the time this way, so 
don't change it :)

c:
cd\
rundoor.bat

^^^^  This is the part that will actually run the door.  rundoor.bat 
will be created by the bash script that we're going to create next.  
I'll explain when we get there.

-----------------------------------------------
END AUTOEXEC.BAT


**NOTE:  The rundoor.bat is not necessary in the autoexec.bat that is 
contained in your $HOME/.dosemu/drive_c/ directory, only the 
BBSDIR/.dosemu/drive_c/ directory.  However, if the rest is the same, it 
works very well for launching things like lordcfg.exe or whatever you 
need while someone is playing doors.


CHAPTER 4 - door_script


Now, we'll move on to the file you're actually going to call FROM 
enthral, via the D- command.  I'll explain the menu commands later, but 
for now, we need to make a file.  I like to call it door_script.  I 
place this file in /home/bbs/enthral/doors/dos/, but you can place it 
anywhere, however it's best to do it from somewhere connected to your 
enthral bbs directory.  Here is door_script:



#!/bin/bash
export HOME=/home/bbs/enthral
printf "Loading $2 ..

"
unix2dos /home/bbs/enthral/node/node$1/DOOR.SYS
unix2dos /home/bbs/enthral/node/node$1/DORINFO?.DEF
unix2dos /home/bbs/enthral/node/node$1/CHAIN.TXT

rm /home/bbs/enthral/.dosemu/drive_c/rundoor.bat
echo -e "\r@echo off \r" >> /home/bbs/enthral/.dosemu/drive_c/rundoor.bat
echo -e "f: \r" >> /home/bbs/enthral/.dosemu/drive_c/rundoor.bat
echo -e "cd $2 \r" >> /home/bbs/enthral/.dosemu/drive_c/rundoor.bat
echo -e "call start.bat $1 \r" >> /home/bbs/enthral/.dosemu/drive_c/rundoor.bat
unix2dos /home/bbs/enthral/.dosemu/drive_c/rundoor.bat

/usr/bin/dosemu -u virtual -I 'keystroke "\r"' #2>/dev/null /dev/null

rm /home/bbs/enthral/.dosemu/drive_c/rundoor.bat


Now, a line-by-line explanation.  Some of these commands may be 
superfluous or unnecessary, but I'll explain them anyway.  Hell, it 
works :)

#!/bin/bash
This line tells linux that you're executing a bash script.

export HOME=/home/bbs/enthral
This line is what I did to make dosemu look into the BBS 
directory/.dosemu/ for all of its information.  I find that this works 
very well, and suggest you don't change it, aside from reflecting your 
own bbs dir.  All it really does is make a different autoexec.bat 
launch, but it adds some functionality.

printf "Loading $2 ..

"
This will write "Loading LORD" or "Loading USURPER" or whatever.  Not 
really necessary, but it works.  The $2 means it's the second argument 
passed in the launching of the script.  I'll get more into that later.

unix2dos /home/bbs/enthral/node/node$1/DOOR.SYS
unix2dos /home/bbs/enthral/node/node$1/DORINFO?.DEF
unix2dos /home/bbs/enthral/node/node$1/CHAIN.TXT
This changes all of the dropfiles from linux format to contain dos style 
CR/LF's at the end of every line.  This causes the dropfiles to be 
readable by the dos doors.  Now, the latest version of unix2dos will 
automagically modify the files and output them to their original 
filenames.  If you have an old version of unix2dos (I suggest you 
upgrade), you may have to unix2dos directory/DOOR.SYS 
directory/DOOR.SY1, and copy it back later.  Do the same for all 
dropfiles...but if you upgrade your unix2dos, this won't be necessary :)

rm /home/bbs/enthral/.dosemu/drive_c/rundoor.bat
This will delete the old rundoor.bat located in C:\.  It's important to 
do this before making a new one, or it will just append.

echo -e "\r@echo off \r" >> /home/bbs/enthral/.dosemu/drive_c/rundoor.bat
echo -e "f: \r" >> /home/bbs/enthral/.dosemu/drive_c/rundoor.bat
echo -e "cd $2 \r" >> /home/bbs/enthral/.dosemu/drive_c/rundoor.bat
echo -e "call start.bat $1 \r" >> /home/bbs/enthral/.dosemu/drive_c/rundoor.bat
unix2dos /home/bbs/enthral/.dosemu/drive_c/rundoor.bat
Ok, this is the interesting part.  Remember that we made autoexec.bat 
look for a file, c:\rundoor.bat, right?  Well, in this portion, we 
create it.  The $1 is the node number, being passed from enthral.  The 
$2 is the door name, which also has to be the directory under f:\ that 
the door is located...so install lord to f:\lord, lord2 should be 
f:\lord2, etc.  Keep them all 8 characters or less...Planets: TEOS will 
be f:\teos, for example, you get the idea.  Here's what would happen if 
we tried to launch this from enthral on node 1 with the door name being 
"LORD".  We'd make the following c:\rundoor.bat:

@echo off
f:
cd lord
call start.bat 1


Also, remember to put the unix2dos command in there, so that the file is 
readable by dos.

/usr/bin/dosemu -u virtual -I 'keystroke "\r"' #2>/dev/null /dev/null
This is where we actually call dosemu.  /usr/bin/dosemu is where it's 
found on my installation, but change appropriately.  The -u virtual is 
important to make a virtual comport to pipe everything through.

rm /home/bbs/enthral/.dosemu/drive_c/rundoor.bat
Just doing some cleaning up after a proper exit of the door :)  I know 
it's redundant to have it in the door_script twice, but redundancy is 
sometimes helpful to alleviate potential problems.

Finally, make that file executeable.  After creating door_script, 
remember to chmod +x door_script.


CHAPTER 5 - Example start.bat


Ok!  That was the hardest part, I suppose.  Keep in mind that 
rundoor.bat will go to the door directory, and launch start.bat with the 
node number as an argument.  I'll leave it up to you to create a 
start.bat for each of your doors, but I'll explain the basics here:

random start.bat:

@echo off
f:
cd \doorgamedirectory
pause
call doorgame.exe %1
exitemu

Explanation:
@echo off
Don't pipe batch output :)

f:
door drive

cd \doorgamedirectory
change to the directory once again...redundant I know :)  But it works!

pause
This is necessary because of the -I 'keystroke "\r"' upon launch of 
dosemu...it's more of a hack than anything else, because if we don't put 
the keystroke arg in there in the first place, it won't launch for some 
reason.  So just put the pause in there and it'll work for you :)

call doorgame.exe %1
This is to actually launch the door.  The %1 is the node argument being 
passed from c:\rundoor.bat to this file.  Remember some games need other 
arguments, like you may need to point to the dropfile, in which case it 
would be something like 
call doorgame.exe %1 d:\enthral\node\node%1\DOOR.SYS, or 
you may need 
call doorgame.exe %1 /DREW (lord for example).

exitemu
This exits dosemu after the door closes properly.

Some things to note:  D:\ is your /home/bbs directory.
That being said, when you setup your doors, have them look for dropfiles 
in D:\enthral\node\node#, with the # changing for each node.  If I could 
explain each door I would, but I'd be here all day :)


CHAPTER 6 - Modifying DOSEMU control files


Now that that's all taken care of, there are just a couple of small 
things to worry about.  Dosemu is NOT setup out of the box to do things 
like this, so we need to make a few small modifications to how dosemu 
works.  Here's what I've done:

In /etc/dosemu/dosemu.conf, add the following toward the top of the 
file:

ifdef u_virtual
        serial { virtual com 1 }
endif


This will enable the virtual comport on com 1 for us, and pipe 
everything appropriately.

Additionally, go through the file and uncomment the following lines, 
making them the same values that I have:

$_cpu = "80586"
$_hogthreshold = (10)
$_dpmi_base = (0x10000000)
$_external_char_set = "cp437"
$_internal_char_set = "cp437"
$_layout = "us"


EVERYTHING ELSE NEEDS TO BE COMMENTED, or you only have yourself to 
blame for funny input/output issues :)  This is the first place I'd look 
if things aren't displaying properly.

In your /etc/dosemu/dosemu.users, append the following line at the end:

bbs c_all

This will make the bbs user able to do whatever he needs to in dosemu.  
Not sure how necessary it is, but it'll alleviate any problems in the 
future with accessing directories or whatever.

Leave your /etc/dosemu/global.conf alone, it's not a big deal.

Finally, I chose to edit my /usr/bin/dosemu executable file.  I CAUTION 
YOU to not do this, but if you're feeling adventurous, go for it.  
Dosemu wants a 25 line terminal, and will complain upon startup.  
If you look for where it does that stupid complaining crap and change 
the value from 25 to 24, you'll prevent it from complaining in the 
future.  I won't explain exactly how to do this because I caution 
against it and don't want to be held accountable for broken dosemu's :)  
So, Good luck!


CHAPTER 7 - Enthral Menu Commands


Finally, your setup in your BBSDIR/menu/main.txt or doors.txt if you 
create one...

We'll use lord as an example here, and we'll use CommandRec 001, but 
ensure you change that to the sequential number that this command will 
actually be in your menu data.

[CommandRec001]
LDesc[001]      = "lord"
SDesc[001]      = ""
CKeys[001]      = "L"         < Use whatever you want to launch the 
door.  I use L, but you can use a number or something else if you want.
Acs[001]        = "s50"       < Registered users only.  Not a big deal.
CmdKeys[001]    = "D-"        < Create dropfiles, launch a door.
MString[001]    = "/bin/bash /home/bbs/enthral/doors/dos/door_script %NN LORD"
This will launch the bash script we made earlier.  Just have it point to 
your door_script file.  Pass %NN as the first arg, which is the node, 
and the name of the directory where your door game is located under the 
F:\ dir as your second arg.
HiString[001]   = ""
LoString[001]   = ""
Xcoord[001]     = ""
Ycoord[001]     = ""
LBarCmd[001]    = "FALSE"      < Change all of this for litebars.
SText[001]      = "FALSE"
STLen[001]      = "0"

That should do it!


CHAPTER 8 - Contact info


The end of this file will be a changelog that I will update with each 
revision of this file.  If you have any questions, find myself, 
Mercyful, or Netsurge on irc...irc.bbs-scene.org #bbs.  Or on haunting 
the chapel bbs, htc.zapto.org, or the enthral support website, 
http://www.enthralbbs.com.  Thanks!



CHAPTER 9 - CHANGELOG

2 APRIL 2009
Initial version of dosdoors howto.