From 8969e0efb3c1e83cbfb7646521ce767f838f537a Mon Sep 17 00:00:00 2001 From: Andrew Pamment Date: Sat, 3 Feb 2018 21:00:55 +1000 Subject: [PATCH] Add the rest of the documentation so far --- docs/docs/guide/doors/dos.md | 0 docs/docs/guide/doors/dosbox.md | 114 ++++++++++++++++++++++++++++++++ docs/docs/guide/doors/dosemu.md | 100 ++++++++++++++++++++++++++++ docs/docs/guide/scripting.md | 43 ++++++++++++ docs/mkdocs.yml | 4 +- 5 files changed, 260 insertions(+), 1 deletion(-) delete mode 100644 docs/docs/guide/doors/dos.md create mode 100644 docs/docs/guide/doors/dosbox.md create mode 100644 docs/docs/guide/doors/dosemu.md diff --git a/docs/docs/guide/doors/dos.md b/docs/docs/guide/doors/dos.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/docs/guide/doors/dosbox.md b/docs/docs/guide/doors/dosbox.md new file mode 100644 index 0000000..aa7c039 --- /dev/null +++ b/docs/docs/guide/doors/dosbox.md @@ -0,0 +1,114 @@ +# DOS doors With DosBox + +This guide is aimed at Raspbian Linux (Stretch) on Raspberry PI, but should work on any Linux/UNIX like system DosBox supports. + +## Step 1. Install Pre-Requisites + +To compile DosBox, you will need SDL 1.2 and SDL-net in addition to the usual development toolchain. You will also need Subversion to get dosbox and patch to patch it. + + sudo apt-get install build-essential libsdl1.2-dev libsdl-net1.2-dev subversion automake dos2unix + +## Step 2. Fetch DosBox + +The most recent DosBox release has some issues with DOS doors, and the most recent Subversion code also has issues, so you will need a specific revision from the subversion repository. In my tests I have found r3933 to work well. Other revisions may work, but have not been tested. + + svn checkout -r3933 svn://svn.code.sf.net/p/dosbox/code-0/dosbox/trunk dosbox-code-0 + +## Step 3. Patch DosBox + +Now we have the DosBox code, you will probably want to patch it to fix a specific bug that happens with some doors which will appear as though when you press enter, it receives the enter command twice. + + wget https://gist.githubusercontent.com/apamment/bb438d9be6dc8e67c36239fd64047ece/raw/3e942c68d7a970f3404bffc2408165d810c4bef7/dosbox-nullmodem.diff + + cd dosbox-code-0 + + patch -p1 < ../dosbox-nullmodem.diff + + +## Step 4. Compile DosBox + +Compiling DosBox takes a long time on the Raspberry PI and will appear to have frozen a few times - particularly when compiling the render-scalers file - don't worry, just leave it it will eventually move on. + + ./autogen.sh + ./configure + make + sudo make install + +These commands will compile and install DosBox into /usr/local/bin. + +## Step 5. Create Configuration File + +Next you will need to create a config file which enables the serial port for socket inheritance, and also mounts drives so that DosBox can access both your doors and your BBS drop files. + +An example setup is here: [[https://gist.github.com/apamment/98e42db83c452105b3e21a8bc062c5c3|dosbox.conf]] + +In this example, drive C: is the location where my doors are stored, dropfiles will be copied to the door directory. + +## Step 6. Create Shell Script to Invoke DosBox + +The shell script you need will vary from system to system, but basically, you want to: + + * ensure no one else is using the door before you start it + * Copy the dropfile to the door directory + * make DosBox not use an X11 window, + * ensure that the dropfiles have DOS line endings + * launch DosBox with the command to start the batch file in the next section. + +Here is an example script I use for Freshwater Fishing: + + #!/bin/bash + export SDL_VIDEODRIVER="dummy" + NODE=$1 + SOCKET=$2 + + if [ ! -e /home/pi/MagickaBBS/doors/ffs.inuse ]; then + touch /home/pi/MagickaBBS/doors/ffs.inuse + cp /home/pi/MagickaBBS/node${NODE}/door.sys /home/pi/MagickaBBS/doors/ffs/ + /usr/local/bin/dosbox -socket $SOCKET -c "C:\ffs\ffs.bat ${NODE}" -conf /home/pi/MagickaBBS/doors/dosbox.conf + rm /home/pi/MagickaBBS/doors/ffs.inuse + fi + + +This will just dump the user back to the BBS if the door is in use. You could get fancy and use the 'inuse' door I created which will display an in-use message and then quit ([[https://github.com/apamment/inuse|INUSE Door]]), but that is outside the scope of this document. + +You will also need to make the bash script executable: + + chmod +x ffs.sh + +## Step 7. Create Batch File to Start Door + +Please note, you will need to setup your doors using DosBox in the normal fashion, either you set them up on a machine where you have a monitor attached and transfer the files over, or you run DosBox directly from your PI with either remote X11 or a local monitor. + +You will also most likely need a Fossil driver, [[http://www.pcmicro.com/bnu/|BNU]] works well. (Get the stable release 1.70). + +Different doors will need to be called in different ways, but the important thing to remember is that you end the batch file with "exit" else the door will stay stuck in DosBox. + +Here is an example I use for freshwater fishing: + + @echo off + C: + cd\bnu + bnu /L0=11520 + cd\ffs + fishing 2 C:\ffs\ /F + exit + +This loads BNU, then launches the door with the drop file. + +## Step 8. Setup BBS + +Finally, you will want to setup your BBS to call the script you made in Step 6. You also need to pass the node number and socket handle. + +In doors.ini, something like + + [Freshwater Fishing] + command = /home/pi/MagickaBBS/doors/ffs.sh + stdio = false + codepage = CP437 + +Then, add a command to your doors menu: + + HOTKEY 1 + COMMAND RUNDOOR + DATA Freshwater Fishing + diff --git a/docs/docs/guide/doors/dosemu.md b/docs/docs/guide/doors/dosemu.md new file mode 100644 index 0000000..8e071b6 --- /dev/null +++ b/docs/docs/guide/doors/dosemu.md @@ -0,0 +1,100 @@ +# Dos Doors with DOSEMU + +DOSEMU only runs on Linux/x86, if you're running on another platform, try the DOSBOX tutorial. + +In this example, I will be configuring for MagickaBBS and Tiny's Hangman game. + +## Install DOSEMU + +Depending on your distribution, this command will be different. On ubuntu: + + sudo apt-get install dosemu + +Should do the trick. + +## Configure DOSEMU + +First, run dosemu once to create /home/someuser/.dosemu/ paths then modify the supplied autoexec.bat. + + +This is my autoexec.bat (in /home/someuser/.dosemu/drive_c/) + + @echo off + break=off + path z:\bin;z:\gnu;z:\dosemu + set HELPPATH=z:\help + set TEMP=c:\tmp + prompt $P$G + lredir del d: > nul + lredir d: linux\fs/home/someuser/MagickaBBS/doors + unix -e + + + +## Step 4. Configure a Door ===== + +Firstly you want a dosemu.conf for calling the door, I use the same one for calling all my dos doors. + +This is my dosemu.conf (in /home/someuser/MagickaBBS/doors/) + + $_cpu = "80486" + $_cpu_emu = "vm86" + $_external_char_set = "utf8" + $_internal_char_set = "cp437" + $_term_updfreq = (8) + $_layout = "us" + $_rawkeyboard = (0) + $_com1 = "virtual" + +You will need both [[http://tinysbbs.com/files/tsoft/THANG23B.ZIP|THANG23B.ZIP]] and [[http://www.pcmicro.com/bnu/bnu170.zip|BNU170.ZIP]] + +First unzip BNU170.ZIP in /home/someuser/MagickaBBS/doors/bnu + +Then unzip THANG23B.ZIP in /home/someuser/MagickaBBS/doors/thang + +copy the executables from /home/someuser/MagickaBBS/doors/thang/dos to /home/someuser/MagickaBBS/doors/thang + +Next Configure Tiny's Hangman by editing THANG.CFG. Note: I use dorinfo1.def but you could just as easily use door.sys. + +Now create a batch file that we will use to launch tiny's hangman from DOS. + + @echo off + D: + CD \BNU + BNU /L0=11520 + CD \THANG + THANG /N%1 /DD:\THANG\NODE%1 + exitemu + +create the following sub directories in THANG + + mkdir node1 + mkdir node2 + mkdir node3 + mkdir node4 + +until you have a directory for each node. + +Finally, the script for running tinys hangman, thang.sh + + #!/bin/bash + + NODE=$1 + + cp /home/someuser/MagickaBBS/node${NODE}/dorinfo1.def /home/someuser/MagickaBBS/doors/thang/node${NODE}/ + + /usr/bin/dosemu -quiet -f /home/someuser/MagickaBBS/doors/dosemu.conf -I "dosbanner 0" -E "D:\THANG\THANG.BAT ${NODE}" 2>/dev/null + +You can then edit your doors.ini to include: + + [Tinys Hangman] + command = /home/someuser/MagickaBBS/doors/thang.sh + stdio = true + +and finally edit doors.mnu + + HOTKEY 1 + COMMAND RUNDOOR + DATA Tinys Hangman + +Then restart Magicka and you should be able to run Tinys Hangman by pressing 1 on the doors menu. \ No newline at end of file diff --git a/docs/docs/guide/scripting.md b/docs/docs/guide/scripting.md index e69de29..291a21b 100644 --- a/docs/docs/guide/scripting.md +++ b/docs/docs/guide/scripting.md @@ -0,0 +1,43 @@ +# LUA Scripting + +The first thing you need to do if you want to use scripts, is set your script path in the bbs.ini file. This is set under the paths section and the name is "Script Path", see the example config. + +Next, add scripts! + +## Menu Scripts + +## Login/Logout Scripts + +## Utility Scripts + +## BBS Script Commands + +**bbs_write_string** Takes one string, writes that string to the user. Returns nothing. + +**bbs_read_string** Takes one number (length), returns a string up to the length specified + +**bbs_display_ansi** Takes one string, displays that ansi from the ansis folder (don't include path or extension). Returns nothing. + +**bbs_read_char** Reads a character from the user, returns a string with one character in it. + +**bbs_version** Returns a string with the BBS version in it. + +**bbs_node** Returns a number with the node the user is on. + +**bbs_read_last10** takes a number which is the offset (0-9) and returns user (string), location(string) unix time(number) + +**bbs_get_emailcount** Returns the number of emails a user has. + +**bbs_mail_scan** Performs a mail scan. + +**bbs_run_door** takes two arguments, the command as a string and if it requires stdio redirection as a boolean, then runs the door. + +**bbs_time_left** Returns a number with the minutes a user has remaining. + +**bbs_cur_mailarea_info** Returns 4 values, The conference number, conference name, area number and area name. + +**bbs_cur_filearea_info** Returns 4 values, The directory number, directory name, sub number, sub name + +**bbs_display_automsg** Displays the current automessage + +**bbs_get_info** Returns 4 strings, the BBS name, the Sysop name, the OS name and the system architecture. \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index f83a938..0dd5be4 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -10,7 +10,9 @@ pages: - protocols.ini: 'guide/ini/protocols.md' - s10-99.ini: 'guide/ini/seclevels.md' - Doors: - - DOS Doors: 'guide/doors/dos.md' + - DOS Doors: + - DOSBOX: 'guide/doors/dosbox.md' + - DOSEMU: 'guide/doors/dosemu.md' - Native Doors: 'guide/doors/native.md' - Message Bases: - Local Bases: 'guide/msgs/local.md'