KINGDOMS SYSTEM OPERATOR DOCUMENTATION Version 2.18 Programming & Design : Dave Chapman : The Web BBS Copyright c 1993, 94, 95, 96 - Dave Chapman All Rights Reserved 3:712/523@FidoNet 61:9600/350@WorldNet 69:1171/200@AdultNet 169:3005/2@BattleNet 151:6121/823@EzyNet InterNet - dave.chapman@ibm.net - Kingdoms Support Page - http://www.magna.com.au/~davec/kingdom.htm KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ TABLE OF CONTENTS SECTION 1 - KINGDOMS LICENSING INFORMATION 5 1.1. Software License Agreement 5 1.2. Definitions 5 1.3. Terms 5 1.4. Limited Warranty 6 1.5. Technical Support 6 1.6. Problem Reporting 7 1.7. Upgrades 7 SECTION 2 - GAME OVERVIEW 8 SECTION 3 - KINGDOMS FILES 9 3.1 Executable Files 9 3.1.1. KINGDOM.EXE 9 3.1.2. KM.EXE 9 3.1.3. KNETIN.EXE 9 3.1.4. KNETOUT.EXE 9 3.1.5. KMNT.EXE 10 3.2 Data Files 10 3.2.1. KIDX.DAT 10 3.2.2. KGAME.DAT 10 3.2.3. K*.KDI 10 3.3. Generated Files 11 3.3.1. KMSGHEAD.DAT & KMSGTXT.DAT 11 3.3.2. KUSR.DAT 11 3.3.3. KCFG.DAT 11 3.3.4. KTRANSIT.DAT 11 3.3.5. KSCORE?.KDI 11 3.3.6. K?.LOG 12 SECTION 4 -REQUIRED SOFTWARE/KINGDOMS ENVIRONMENT 13 _____________________________________________________________ 2 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ SECTION 5 - INSTALLATION 15 5.1. Overview 15 5.2 Installation Step 1 - The Basics 15 5.2.1. Unpack the Archive 15 5.2.2. Setting up your Configuration File 15 5.3 Installation Step 2 - Network Configuration 16 5.3.1. The KIDX.DAT File 16 5.3.2. Network Setup 16 5.4. Installation Step 3 - Getting it Running 17 5.4.1. Logging on Locally 17 5.4.2. Starting Kingdoms 18 5.4.3. Maintenance, Network Tasks 19 5.5. Installation Step 4 - Multiline Configuration 20 SECTION 6 - MAINTENANCE OPTIONS 23 6.1. Game Reset 23 6.2. Override Reset 23 6.3. Delay Processing 23 6.4. Same-Day Run Override 24 6.5. Create ACS/ANS Files 24 6.6. Create Scoreboards 24 SECTION 7 - REGISTRATION 26 SECTION 8 - CONTACT INFORMATION 26 SECTION 9 - FAQ 28 9.1. Where do I specify my locked port? 28 9.2. Kingdoms thinks someone is online when there isn't. 28 9.3. Kingdoms thinks Maintenance is running when it isn't. 28 9.4. I have an Index file, but the Manager is telling me I don't! 28 9.5. Realms on my Index are numbered differently to my uplink!28 _____________________________________________________________ 3 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ APPENDIX A : ERROR CODES 29 APPENDIX B : QUICKSTART INSTALLATION 31 APPENDIX C : UPGRADING FROM PRIOR RELEASES 32 _____________________________________________________________ 4 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ Section 1 - Kingdoms Licensing Information This Software is Licensed, not sold. The Software in this package is licensed according to the terms of the following agreement: 1.1. Software License Agreement IMPORTANT: Please read this license agreement before using this software. By using this software you acknowledge your agreement to the terms of this license. If you do not wish to follow the terms of this license agreement, you must remove this software from your system. The only portion of the Software that you may retain is the distribution archive itself which may be used solely for distribution purposes. 1.2. Definitions `` The term '' Software as used in this agreement means the full system and all utility computer programs contained in the distribution archive, together with any updates subsequently supplied by DM BBS Services. `` The term Related Materials means all the printed materi '' als provided in this package or later supplied by Dave Chapman for use with the Software. Author `` The as used in this document is Dave Chapman who owns '' and holds copyright to the Kingdoms software. 1.3. Terms You are granted a limited license to use this software for a sixty-day trial period. After expiration of the trial period, you must either register with the Author or remove the Software from your system. The registration fee is $30.00 (thirty) Australian dollars. A Registration Form is included in the distribution archive and is called KREG.TXT. Once registered, you will receive a license to use the Software on your system for an unlimited period of time. Additional payments may be required for major game upgrades in future at the discretion of the Author. Group registration discounts are available as described in the Registration document, KREG.TXT. Kingdoms is Copyright 1993-96 by Dave Chapman. All rights are reserved. You may copy the Software and documentation for backup purposes. You also may copy and share unmodified copies of the distribution archive, providing that the copyright notice is _____________________________________________________________ 5 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ reproduced and included on all copies and no fee is charged for distributing the distribution archive. You may not sell this software for a fee and/or distribute this software along with other products without expressed written permission from the Author, nor may you modify or remove the Copyright Notice from the program or the documentation. Those who register this program, will receive a registration number. This number will be delivered either by Internet mail, personal upload, or postal service. Allow up to 6 weeks for delivery for locations outside Australia. For locations within the Australia, allow 2-6 weeks for delivery. All registrations are processed in a timely manner and usually only take a few days to deliver. However, when unforseen circumstances arise, registration turnaround times may be delayed. The Author reserves to right to revoke software licenses in lieu of any violation of the terms of this license agreement. 1.4. Limited Warranty THIS PRODUCT IS PROVIDED AS IS `` WITHOUT WARRANTY OF ANY KIND. '' THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF THE PROGRAM IS ASSUMED BY YOU. THE AUTHOR DOES NOT WARRANT, GUARANTEE, OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, RESULTS OF, MERCHANTABILITY OR FITNESS FOR A PARTICULAR USE OF THE PRODUCT. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU (AND NOT THE AUTHOR) ASSUME THE ENTIRE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. FURTHER, THE AUTHOR DOES NOT WARRANT, GUARANTEE, OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THE PROGRAM IN TERMS OF CORRECTNESS, ACCURACY, RELIABILITY, CURRENTNESS, OR OTHERWISE; AND YOU RELY ON THE PROGRAM AND RESULTS SOLELY AT YOUR OWN RISK. THE AUTHOR WILL NOT BE LIABLE FOR ANY DAMAGES, INCLUDING BUT NOT LIMITED TO SYSTEM DAMAGE, SERVICE, REPAIR, CORRECTION, LOSS OF PROFIT, LOST SAVINGS, OR ANY OTHER INCIDENTAL, CONSEQUENTIAL, OR SPECIAL DAMAGES OF ANY NATURE WHATSOEVER RESULTING FROM THE USE OR INABILITY TO USE THIS PRODUCT. 1.5. Technical Support Comments, suggestions and bug reports are welcome. If you have any, you should contact Dave Chapman at one of the addresses listed below: Primary Support Site: : The Web BBS _____________________________________________________________ 6 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ System Operator: : Dave Chapman Mailer/BBS Software: : Front Door/EzyCom Line 1 : (02) 528-5941 to 28800, Continuous Mail, FREQ Line 2 : (02) 528-2235 to 14400, BBS - 24 hours Line 3 : (02) 528-4250 to 9600, BBS - 24 hours Sysops can FREQ magic name `KINGDOMS' anytime for the latest version on line 1. I can be contacted on the Battlenet Kingdoms echo by name or by Internet mail to dave.chapman@ibm.net. Kingdoms is also available from the Australian & US Beta/Registration sites and Internet FTP site listed in Section 8 - Contact Information, in this document. 1.6. Problem Reporting If you're reporting a bug, please give as much detail as possible about the problem you are experiencing (including the version you're running) so that it can be duplicated and fixed. Please include the error report that will be provided in KERR.LOG. 1.7. Upgrades Program updates consist of minor and major revisions. All minor updates are available for download and usage free of charge to registered Sysops. Major updates may require a small upgrade fee based on the complexity of the update. The program version number indicates whether this a major or a minor upgrade. For example, release revisions 1.10, 1.43, 1.90 etc would indicate minor program revisions and no upgrade fee would be charged to those who are currently registered 1.00 users. A release revision of 2.00 would indicate a major program revision and may require a small upgrade fee. _____________________________________________________________ 7 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ Section 2 - Game Overview Kingdoms is a multi user online game with InterBBS capability. It will run under all BBS systems that support the standard DORINFO1.DEF, DORINFOx.DEF or DOOR.SYS drop file formats, or for which these file can be generated. Other games have purported to be InterBBS, but they merely offer the user the ability to play on one BBS and send forays to others which must return to their home BBS. This is really just an extension of a local BBS game and does not offer true Inter-BBS functionality. Kingdoms does. :-) Under Kingdoms, players have a `Home' BBS, which is the one they logon to most frequently. On that BBS, they own a Castle which can be fortified in a number of ways, they can attack other players either on the local BBS or on another, send messages between them, etc. As far as Inter-BBS goes it's all good fun, there is nothing really new here. What is new, and what makes Kingdoms truly unique is that players in Kingdoms can purchase castles on other BBS's in their net. They can hire an `Agent' to run the castle for them, fortify that castle, store gold in it, send attacks from it and much more, all by remote command from their Home BBS. If they have created a remote castle, they can also directly logon to the remote and they will be recognised as a `Visiting Lord' (or Lady!), owner of the castle there and operate it directly. The possibilities for strategic play, multiple alliances and subterfuge here are enormous. It is not the purpose of this document to discuss the game itself in depth, so if you would like to know more, please read the Player documentation. I hope you and your users enjoy the game! _____________________________________________________________ 8 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ Section 3 - Kingdoms Files The following files should be in your Kingdoms Archive and are required to operate Kingdoms on your BBS. If any are missing, the latest version and archive can be FREQ'd from the Web BBS at the addresses provided in the Support section of this documentation. 3.1 Executable Files 3.1.1. KINGDOM.EXE This program is the one that is executed when shelling from a BBS or in local mode by using the /L command line parameter. 3.1.2. KM.EXE This is the Kingdoms Manager. When you've unpacked your Kingdoms archive, this should be the first program you run. A full description of KM.EXE is provided in the accompanying document, KM.DOC. 3.1.3. KNETIN.EXE KNetIn processes Kingdom inbound files from other Realms on your Kingdoms Net. These inbounds could be messages, gold or monster transfer, Castle fortifications or a number of other Kingdom transit data. It will search for files named KNET*.* and process them from your inbound files directory as defined in KM.EXE. Please note that you should NEVER edit this file. Information in it is check summed and very strange things can happen to your inbound processing if the file data does not correspond to the file and record checksums. 3.1.4. KNETOUT.EXE KNetOut processes the file KTransit.Dat. KTransit is the file which holds outbound information and data, some generated by Kingdoms itself, most generated by InterBBS activities of the players on your BBS. Please note that you should NEVER edit this file. Information in it is check summed and very strange things can happen to your outbound Transit file data does not correspond to the file and record checksums. _____________________________________________________________ 9 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ 3.1.5. KMNT.EXE KMNT is the Kingdoms Maintenance program. It should be run once daily. I suggest you put it in your nightly maintenance. It updates the player records, brings dead players back to life, packs the news files to manageable lengths and does other assorted housekeeping. It is also the means by which you can regularly poll other Kingdom nodes for net statistic information. It will not, unless you specifically request it, run more than once per day. Further information about KMNT is provided in the Kingdoms Installation section. 3.2 Data Files 3.2.1. KIDX.DAT Your distribution archive may or may not contain this file. KIDX.DAT is the `Nodelist' for a Kingdoms network. Generally, the file should be obtained from the Kingdoms coordinator for a Kingdoms net in which you are to participate. As it is specific to a network of BBS's, it generally won't be found in the archive. If your BBS is not listed in this file, Kingdoms InterBBS functions will not operate. 3.2.2. KGAME.DAT This file contains much of the static data used by Kingdoms such as Armor, Weapons and Monster information. It MUST reside in your game directory, as defined in the Manager and you should NEVER edit this file. Records in it are checksummed and the game will not operate properly (or not at all) if the file is tampered with. 3.2.3. K*.KDI Kingdoms uses the special type of display file, the ones with the .KDI extension, for display. This is a more convenient and more efficient way of managing display information that by using ANSI files within Kingdoms. KDI files include things such as the opening screens, menus for fast display in this format and news files for display within the game. If you wish, you can also generate ANSI and ASCII versions of some of these files during Maintenance so you can display them on your BBS itself. See the section in this document on Maintenance Options. _____________________________________________________________ 10 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ 3.3. Generated Files The following files will not be in the Kingdoms archive, but are created and modified by Kingdoms as appropriate as people play the game. You should never attempt to modify any of these files yourself as the game will not function if checksums on the files do not match file data. ALL .DAT FILES SHOULD BE BACKED UP ON A REGULAR BASIS. 3.3.1. KMSGHEAD.DAT & KMSGTXT.DAT These are the Kingdoms message base files. They hold the Kingdoms indexed message headers information and the associated message text respectively. 3.3.2. KUSR.DAT This is your Kingdoms Player file. It holds all information pertaining to the users playing Kingdoms on your BBS. 3.3.3. KCFG.DAT This file your Kingdoms Configuration file. There will only ever be one of these per system (unless a Sysop is running multiple Kingdoms network games on the one BBS) and it is maintained by KM.EXE. When Kingdoms starts, it must start up in the SAME directory that this file resides in. 3.3.4. KTRANSIT.DAT This file holds information that is in transit (going to and from) between Kingdom Realms. It is processed and maintained primarily by KNETOUT and KNETIN. New data (eg, a Recon requested) is added to this file by the Kingdoms Realms options in KINGDOM.EXE so it can be tossed (exported) to the destination node by KNETOUT. 3.3.5. KSCORE?.KDI These files are the scoreboard files for Kingdoms. There are KSCOREL.KDI and a KSCORER.KDI files, which are the Local and Realm (InterBBS) score files respectively. The Local score file is calculated dynamically while the user is online and is therefore always up-to-date. The Realms score file is generated by KMNT when it runs, using data from the current Recon files to pick up the scores from remote Realms. For this reason, it will only be as up-to-date as of a) when Maintenance was last run and _____________________________________________________________ 11 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ b) depending on the currency of existing recons. As mentioned previously, KMNT can create ANSI and ASCII versions of these files should you want/require them. 3.3.6. K?.LOG Kingdoms produces several log files which should be obvious by name. All logs, should you want to see any, are written to the Game directory, as defined in the Manager. The logs generated include : KDOM.LOG - Kingdoms Player's log ... who's gone in and out of the game. KNET.LOG - Net processors logs, Knetout and Knetin update this. KERR.LOG - Any errors the game encounters are recorded here. Hopefully empty :-) KMNT.LOG - Maintenance log KCOORD.LOG - Only appears on the Coordinator node - see KCOORD.DOC. _____________________________________________________________ 12 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ Section 4 - Required Software/Kingdoms Environment Kingdoms is designed to run under any Bulletin Board system that supports the standard DORINFO1.DEF, DORINFOx.DEF and DOOR.SYS drop file formats. Ezycom, Remote Access and Wildcat all support one or more of these formats and doubtless many others do as well. If your BBS software does not, several utilities are available on many boards to convert one type of drop file (eg, DOORMASTER) to these standards. As discussed, Kingdoms have InterBBS capability. To operate these functions you must be a member of a network (which one, eg Fido, PodsNet, SigNet etc) does not matter to Kingdoms, only that you have a three dimensional address (points are not supported) and that you call someone (or they call you) who also has any 3D address. Kingdoms uses the .MSG format of mailer messages to manage its file routing. Kingdoms will run with FrontDoor or another mailer program that supports .MSG format netmail messages without difficulty. The Blinkey/Squish mailer format is also supported through the /S parameter on KNETOUT. If someone wants to send me a sample of another format, I'll look at putting it into Kingdoms depending on demand. Kingdoms requires a fossil communications driver to be resident in order to operate. It does NOT have it's own internal comms routines as I don't see why they're necessary, considering all BBS software I've seen requires a Fossil driver resident anyway. It has been tested and works well with both X00 by Ray Gwinn and BNU by David Nugent. Kingdoms requires MS-DOS or an MS-DOS environment/window. At startup, it will detect DOS, DesqView, Taskview, Windows (3.x) and/or OS/2. According to what it finds, it will automatically time slice away when Kingdoms is idle to give more processor time to other tasks that might be busy. Kingdoms has been tested on MS-DOS 3.3, MS-DOS 4.1, MS-DOS 5.0, MS-DOS 6.2 and DR-DOS 6.0. It has also been tested running under Desqview on a stand alone PC, on a net server running Novell Netware Lite and on a Client machine in a Netware Lite environment multi tasking with DesqView. It works well under both Windows 3.1 and `95. It has been tested on both MCA and EISA based machines. Kingdoms does not have a significant memory requirement (approx 400K runtime memory), but it is recommended you swap your BBS out (using the *M parm in EzyCom, RA and QBBS) before calling the game to give it as much as possible and avoid possible memory shortages while running. _____________________________________________________________ 13 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ Kingdoms supports multi-line operation. That is, users may play Kingdoms on more than one line concurrently. Up to and including 99 separate lines (logged on players) active are supported at any one time. _____________________________________________________________ 14 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ Section 5 - Installation 5.1. Overview Kingdoms can, in its simplest form, run as a local game on a single line BBS. Likewise, it can run in a complex multi-line, networked environment. Installation is, naturally enough, more time consuming for the latter, but you will still find it pretty easy if you follow the instructions below! Please DON'T think, if you've installed heaps of games before, that you don't need to read this documentation. Frankly, you'll probably miss something important if you don't at least read through them first, OK? RTFM! For those who REALLY want to get moving, and who won't listen to advice , Appendix B of this document gives a quick start procedure for getting the game up and running. The procedure described in this section describes installation for a BBS setting up a new game of Kingdoms. Instructions for upgrading Kingdoms from a previous version are supplied in Appendix C : Upgrading Kingdoms. 5.2 Installation Step 1 - The Basics Whatever environment you're installing Kingdoms in, you'll need to start with these steps. 5.2.1. Unpack the Archive Unpack the distribution archive into a directory the game will run from. For this document, we assume Kingdoms is unpacked in C:\KINGDOMS. 5.2.2. Setting up your Configuration File From C:\KINGDOMS, run KM.EXE, the Kingdoms Manager. This is where most of your Kingdoms setup will take place. Modify the defaults provided to whatever matches your system. At the bottom of your screen, a one line description of the field you're on will be displayed. If you need more information, please refer to the relevant section of the Kingdoms Manager documentation, KM.DOC. T choose the Network options in KM.EXE yet. The next section DON'' covers that. Just set up the `Paths' and `Other' sections in KM.EXE. If you are not part of a network, or you are going to be _____________________________________________________________ 15 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ the Coordinator for a Kingdoms network, leave the Self Correction Frequency in `Other' set to zero. If you're not participating in a Kingdoms network, you're finished this part of the setup. All that remains is to set up your menu commands and batch file to call Kingdoms from the BBS. If this is the case, press Esc now and save the configuration you've set up at this point. Before you head out, use the `Verify Paths' option to make sure the paths you've entered are correct. If any are missing or incorrect, create them now using the normal DOS MakeDir (MD) command or go back into Edit Paths to correct any you mistyped. When done, exit the Manager by pressing Esc and, if you're not in a Kingdoms network, skip straight to section 5.4, Getting it Running, now. Multiline setup is addressed in this section (5.4) also. If you are setting yourself up as part of a Network, continue on to section 5.3, Network Configuration. 5.3 Installation Step 2 - Network Configuration 5.3.1. The KIDX.DAT File To be a part of a network, you must have a valid Kingdoms KIDX.DAT file in your Kingdoms directory. This file holds information on all the BBS's in your Kingdoms net, including your own. The latest version should always be available from your net coordinator. Kingdoms won't let you into the Network/Routing configuration section, and you cannot therefore define your network address as that's where you define it, until it can find a KIDX.DAT file to use. 5.3.2. Network Setup 5.3.2.1. Defining your Node. Go into the Manager again and select the Network->Your Routing options. If this is the first time you've used this option, ie, your network address is not yet defined, a list of all the nodes in the Index will pop up and you'll be asked to identify which node YOU are in the nodelist. Using the up/down arrow keys, place the highlight bar over your node and press enter. If your node is NOT _____________________________________________________________ 16 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ listed, then press Esc to get out of there and get an updated KIDX.DAT file from your Coordinator that has you listed. Having identified your node on the Index, Kingdoms will intelligently evaluate the network links contained in the Index file itself and configure all your routing for you. There is nothing more you need to do. If you wish, re-enter N>etwork Y>our Routing and you can see what Kingdoms has done for you. Unless there is a major problem, such as one of your links going down for an extended period or offline alltogether, you should NEVER change the default routing Kingdoms has set up for you. The links specified are based on information supplied by your network Coordinator when s/he created the Index originally and changing your local node could seriously disrupt network traffic flow if you get it wrong. A far better course of action if something like this does happen, is for you to contact your Coordinator and inform him/her of the problem. The Coordinator can then issue commands from his/her Realm to alter the links appropriately network wide and bring everyone up-to-date with the new network flow. A LOT of effort has been put into the network intelligence in Kingdoms and I can say with a fair degree of confidence that it is considerably smarter and considerably more robust than any other InterBBS game you will have tried. Though the facilities are provided to change the defaults if you need to therefore, please don't do so without consulting your Coordinator! 5.3.2.2. Selecting Mail Flags & Type. As above, there should rarely, if ever, be a need for you to modify your routing definitions. You may, however, wish to activate (or deactivate) various mail flags on nodes you directly communicate with. Outbound packets can have their associated .MSG files set to HOLD (or not), to CRASH (or not), or you may wish to use compression on mail going to these nodes. These options can be configured using the Preferences option in the Network menu. If you've been running a BBS for a while, you probably already know what these things mean, but if not, a more detailed explanation of each option is provided in section 3.2 - Preferences - of the Sysop documentation, KSYSOP.DOC. 5.4. Installation Step 3 - Getting it Running At this point, you should have your configuration completed, including any Network setup you require. This last step involves getting Kingdoms up and running on your BBS, including setting it up to handle Multiline operation. 5.4.1. Logging on Locally _____________________________________________________________ 17 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ Log yourself onto Kingdoms locally using `` KINGDOM /L'', to check everything is working as it should be. If not, make sure all the directories you defined in KM.EXE exist. Misspelling directories are the most common cause of problems in this area. For a local logon, Kingdoms does not require a DORINFO or DOOR.SYS file. It will use the information provided in the Manager to log you onto the game. When Kingdoms detects a local logon, it will ask for a (real) name to logon as. This facility is provided so you can logon as one of your players to help out if problems occur. If you press Enter on the first name without entering anything, you'll be logged on as the User name you defined as the Sysop in the Kingdoms Manager. 5.4.2. Starting Kingdoms Depending on your preference, you can run Kingdoms directly from your BBS or by shelling to a batch file. 5.4.2.1. Using a Batch File This is the recommended means of running Kingdoms. If you call KINGDOM.EXE directly from a menu command, you'll have more to maintain. Create a batch file that can be called from your BBS which changes to C:\KINGDOMS, places your door file into (if it is not already) the directory you defined in KM.EXE, and executes KINGDOM.EXE. A sample batch file is : CD\KINGDOMS ` Change to the Kingdoms directory KINGDOM ` Run Kingdoms CD\EZY ` Change back to the BBS directory EXIT ` and go back to the BBS. This is a very simple example of a batch file that will start a single line Kingdoms game. If you're a multiline setup, the next section has a sample setup for you to use. 5.4.2.2. Calling Kingdoms directly If you prefer not to use batch files, then you can call KINGDOM.EXE straight from your BBS but KCFG.DAT must exist in the directory you're in when you shell out to Kingdoms in this case. If KINGDOM.EXE can't find your configuration file when it loads, it will terminate with an appropriate message. 5.4.2.3. Menu commands _____________________________________________________________ 18 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ A type 7 (Ezycom, RA, QBBS etc) menu command which will execute Kingdoms will look like : C:\COMMAND.COM /C C:\KINGDOMS\KINGDOM.EXE *M Create a menu command from a menu on your BBS to call the batch file which starts Kingdoms. Alternatively you can execute Kingdoms straight from the BBS command line, but keep in mind the configuration file must be found as described in 5.4.2.2. Kingdoms operates fine from a type 7 (Ezycom/RA/QBBS) command, but you should specify the *M command line switch (or equivalent) to swap the BBS out when Kingdoms runs to give it plenty of breathing space. 5.4.3. Maintenance, Network Tasks 5.4.3.1. Batch Commands Add the Kingdoms maintenance program (KMNT.EXE) to your BBS nightly maintenance. If you're in a net, also add the in and outbound mail processors KNETIN and KNETOUT respectively to your BBS maintenance. If adding all three (ie, you're in a net), then run them in the order KMNT, KNETIN then KNETOUT. Your batch file commands for nightly maintenance will, when you're in a Kingdoms Net, look like : ... REM : Kingdoms Nightly Maintenance CD\KINGDOMS KMNT KNETIN KNETOUT REM : More Maintenance Tasks ... ... You should always run these utilities while in the main Kingdoms directory where KCFG.DAT is located. 5.4.3.2. Maintenance Options - KMNT.EXE KMNT will only run once per day and carries out numerous, essential operations like reset user daily stats, resurrect dead characters, trim the log and news files, pack the user and message bases, poll other nodes for transit times, generate recon requests for nodes with outdated recons. Normally when KMNT runs, the messages about what it's doing fly by so fast you don't get time to read them. If you wish to slow them down so you can make sure it's working as it should, KMNT will accept the /Dn (delay) command line parameter. Using this _____________________________________________________________ 19 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ parameter will make Kingdoms pause for `n' seconds after each section of the Maintenance completes. For example, `KMNT /D10' will run KMNT and after all major operations, KMNT will pause for 10 (ten) seconds. You can delay it for anything from 1 to 240 seconds between each operation. While paused, you can press a key and it will immediately continue processing rather than waiting the allotted time. The default is no delay between operations. As already noted, KMNT should only run once per day. It will, in fact, halt processing if this is attempted. It is possible however, that you want to force it to run more than once. For example, you may want to test or force a network poll. To accommodate this, KMNT will also accept the /O parameter. If KMNT runs with /O provided, it will ignore the once-per-day-run limit and process maintenance regardless. While running KMNT with the override active (ie, for the second (or more) time in one day will process most options again such as resurrecting players and resetting their fight couts, it will NOT process incremental amounts to the advantage of players on the Realm. For example, KMNT /O will bypass the processing that gives players interest on vault balances. An abbreviated list of parameters KMNT will accept can be displayed at any time by doing `KMNT /?' at the command prompt. KMNT also accepts the /S parameter. If this is present, KMNT will start (several times a day if desired) and ONLY create the scoreboard files. Once done it will terminate and no other processing (ie, no other maintenance) will take place. This facility has been provided so it can be run after the inbound and outbound processors finish to bring local scoreboards up to date with, for example, incoming Recon information. /A with /S will also produce ASC/ANS versions of these files. You are now set up to run Kingdoms on a single line BBS, with or without a Kingdoms network depending on what you've done so far. The following section discusses the setup for Multi-Line BBS's and the additional steps you need to take to get it running in these environments. 5.5. Installation Step 4 - Multiline Configuration Kingdoms fully supports multiple line, concurrent users. In this environment a user may also display from within Kingdoms who else is in Kingdoms and, generally, what they're doing. Through the Courier Guild, players may also chat one-on-one in real time while in the game. Kingdoms will accept the `/Nn' parameter at startup. Should it be present, Kingdoms will operate as node `n'. A maximum of 99 concurrent nodes are supported. For example, `KINGDOM /N3' will _____________________________________________________________ 20 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ start Kingdoms with the player playing on node 3. If /Nn is not present, Kingdoms will assume single line (Node 1) operation. Kingdoms uses the same configuration file for multiline operation as it does for single line. Unlike a LOT of doors there is no need to create a config file in the Manager for each line Kingdoms will run on. Obviously however, you need to tell Kingdoms where it can find the drop file (DORINFO?.DEF or DOOR.SYS) for each line. This is done by use of the /D parameter when you load KINGDOM.EXE rather than having to create and look after numerous configuration files. Using /D simply overrides the BBS path you defined in the Manager, allowing Kingdoms to pick up the drop file from a separate place for each line that's running. The /D parameter is followed by the path and file name of the appropriate drop file. Usually the /Nn parameter just discussed will accompany the /D parameter. For example, if you start Kingdoms with `KINGDOM /N2 /Dc:\ezy\line2\dorinfo1.def', then the DORINFO1.DEF file in \ezy\line2 will be used for this session rather than whatever is specified in the Kingdoms configuration file. If /D\path\filename is not present, it will default to using a DORINFO1.DEF file in the path specified in the Manager. Should the /D parm be used without the /N parm, a warning will be issued to the Sysop when Kingdoms starts, but it will honor the /D override and keep operating, assuming that Kingdoms is running node 1. The same procedure applies if you're using DOOR.SYS - just use that with the /D parameter instead of DORINFO?.DEF. Please note you do NOT need to tell the Manager what type of drop file you're using as you do in many other BBS games. Once again, Kingdoms is that bit smarter and will work it out for itself based on the name of the dropfile supplied. :-) Assuming you're using a batch file to run Kingdoms, your commands to run Kingdoms will look something like ... MENU Command : c:\command.com /c c:\batch\kingdom.bat *N *M The *M under Ezycom and similar packages will swap the BBS out of memory while the game runs. This is highly recommended! The *N will pass the current node number to the batch file as variable 1 (Check your DOS manual) which is very simple ... KINGDOM.BAT ----------- CD\KINGDOMS KINGDOM /N%1 /DC:\RA\LINE%1\DORINFO%1.DEF CD\RA\LINE%1 EXIT ----------- Neither the order nor the case of parameters provided, as with all Kingdoms parameters, is significant. Parameters must be _____________________________________________________________ 21 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ separated by at least one space. Data associated to a parameter, eg the /D and the C:\... above, must immediately follow each other, no spaces between. Depending on your BBS software, you don't always need the 3rd line to return you to the BBS directory after someone exits Kingdoms. You also don't generally need the EXIT anymore either, but it doesn't hurt to have both there. That's it! For whatever your system setup, you are now ready to play the latest and best Inter-BBS game around! Enjoy! _____________________________________________________________ 22 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ Section 6 - Maintenance Options In addition to the Maintenance functions described above in the installation procedures, KMNT can do a few other things. Runtime paramaters that KMNT will accept include : 6.1. Game Reset KMNT will accept the /RESET parameter (KMNT /RESET). Rather than performing normal maintenance functions, this will force a complete game reset, removing all players and resetting all data files. You are given some chances to back out of this should you not be sure, as a reset cannot be reversed, except by restoring all data files to their state before the reset was issued. 6.2. Override Reset If you're in a network game, you are probably aware that the Network Coordinator can issue a network wide reset command, which will automatically reset all nodes in the network. There MAY be a reason you do not want to be included in this, in which case you can force Maintenance to ignore the Coordinator Reset instruction by adding the /NORESET parameter to Maintenance when it runs. Note if you do this however, that a few things : A message will be sent to your Network Coordinator informing him/her of your override. If you don't have a good reason for doing it (and it should have been agreed with the Coordinator in the first place for you to do so), the Coordinator has the ability to simply remove your node from the network until you do so, or to physically delete your node if he/she is annoyed enough. In short, don't use this unless the Coordinator is aware you're going to, and he/she agrees. The Reset will NOT be cancelled, just overridden for that run. Unless the Coordinator issues a directive to the network to cancel any pending resets (which he/she can do), then Maintenance will continue indefinately to try to honor the reset request. You would have to leave your /NORESET in place permanently if you don't want your node getting reset. 6.3. Delay Processing Maintenance performs it's tasks in blocks, informing you on screen of progress. Often the status information flies by quickly however, and you don't get a chance to read it. If you want to slow it down a little, you can add the /Dxx parameter to KMNT when it runs. Doing this will make KMNT pause for xx (1 to 240) _____________________________________________________________ 23 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ seconds between processing each block (eg, user maintenance, then news file packing, then scoreboard generation, etc) so you have time to read what's on the screen. In my nightly maintenance I have /D5 in place permanently so if I happen to be around at 3am when it runs, I can see what's going on. It means maintenance takes about 30 seconds extra to run (there being 6 logical processing blocks to a run) but for the few times I want to see it, who cares about the extra few seconds taken the rest of the time at 3am? :-) If you do happen to be watching it and want it to not wait for the full duration of a Delay, just hit a key and the next block will be processed immediately. 6.4. Same-Day Run Override Normally, Maintenance will only run once a day. If you attempt to run it more than once, it will terminate immediately with a message to that effect. Should you need to for some reason, you can run Maintenance with the /O parameter, which will override this and continue processing normally for that day. 6.5. Create ACS/ANS Files The News and Scoreboard files created and displayed within the game are .KDI files, which is a special file format created for the game to speed up processing and, in particular, reduce the overhead involved with interpreting and displaying ANSI files in color on the local screen when a player views them. This is all very nice, but it means these files can't be displayed outside the game, such as on a BBS menu as you may wish to do. If you run KMNT with the /A parameter, an extra processing block will be enabled which will create ASC and ANS versions of your existing news (Knewst & Knewsy) and scoreboard (kscore?) files. The files will be created in the directories you have defined as your ASC and ANS paths in the Manager. 6.6. Create Scoreboards Running KMNT with the /S parameter will invoke ONLY the processing to create the .KDI scoreboard (local and remote) files. NO other maintenance processing will take place if you run _____________________________________________________________ 24 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ KMNT with this option and, unlike a normal maintenance run, KMNT can be run with /S as many times a day as desired. This option is available to allow the Sysop (if desired) to do a `scoreboard run' of KMNT after inbound and/or outbound processing. This will bring the remote scoreboards up-to-date after any score changes that may have resulted from inbound or outbound traffic processing. The /A paramater may also be used in conjunction with the /S parameter. No other parameters will be recognised or processed if /S is provided. Using /A as well will also generate .ASC and .ANS versions of the new score files if desired. _____________________________________________________________ 25 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ Section 7 - Registration When you register, you will receive a registration number that will remove the `Level 10' restriction in Kingdoms. Kingdoms is not crippled in any way except to, in unregistered versions, restrict a player from gaining a level greater than level 10. See the accompanying file KREG.DOC (or the text version, KREG.TXT) for more information on Registration. Section 8 - Contact Information You can contact me and/or pick up the latest version of Kingdoms by the following means : THE WEB BBS Line 1 : 61-2-9528-5941 - 28800, 24hrs Mail, FREQ `KINGDOMS' Line 2 : 61-2-9528-2235 - 14400 Line 3 : 61-2-9528-4250 - 9600 Kingdoms is a `Free File' download if logged onto the Web directly. BETA & REGISTRATION SITES KINGDOMS is available for FREQ at the following sites : Way Out West, Willmont, NSW, Australia 61-2-9628-8888 Restless (NRFTW) BBS, Glossodia, NSW, Australia 61-45-76-6185 ZZap BBS, Eleebana, NSW, Australia 61-49-42-8176 Blue Marlin, Castlereagh, NSW, Australia 61-47-76-1211 The RUNWAY BBS, Stanmore, NSW, Austraia 61-2-9550-9335 The Dead Zone, Cincinnati, Ohio, USA 1-513-521-0705 INTERNET The latest version of Kingdoms, Online Registration forms and info and more can be found on the Kingdoms home page on the Net at http://www.magna.com.au/~davec/kingdom.htm. This is the primary support page/site for Kingdoms worldwide. The latest version of Kingdoms is also available via FTP on the Internet at ftp://ftp.ros.com.au/pub/bbs_doors. I can also be contacted as dave.chapman@ibm.net, or davec@magna.com.au. _____________________________________________________________ 26 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ _____________________________________________________________ 27 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ Section 9 - FAQ This section of the documentation will be updated with new releases to include any Frequently Asked Questions that come up regularly from Sysops. 9.1. Where do I specify my locked port? You don't. Kingdoms requires a fossil driver which you should have already defined as locked if you want it that way. It uses that quite happily without further specification/definition. 9.2. Kingdoms thinks someone is online when there isn't. In the Manager, File menu, select the `User on Flag' option. This will scan your user file and turn off any `online' flags which are `on'. 9.3. Kingdoms thinks Maintenance is running when it isn't. In the Manager, File menu, select the `Maint Flag' option. This will turn off the flag that indicates to Kingdoms that maintenance is running. 9.4. I have an Index file, but the Manager is telling me I don't! When you get an Index file from your Coordinator, it is probably called KIDX.nn, where `nn' is the Network ID for your Kingdoms game. You need to rename it KIDX.DAT, and it needs to be in your Game directory (as defined in the Manager) for Kingdoms to find it. While you're there, make sure also that your NetId in the F>ile, O>ther section of the Manager is set to the correct NetId! 9.5. Realms on my Index are numbered differently to my uplink! This doesn't matter! Kingdoms ALWAYS does Index searches based on actual address information contained in the Index. It never searches by physical Index record number. Thus, you can have nodes 1:2/3, 2:3/4 and 3:4/5 numbered (physically as they appear in an Index Dump) records 1, 2 a 3 and other nodes can have them numbered 3, 2 and 1 physically and it will make no difference whatsoever to Kingdoms. _____________________________________________________________ 28 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ Appendix A : Error Codes The following codes are some of those you may get reported in KERR.LOG. The ones provided are those you can generally do something about. If you get an error that isn't covered here, please contact the Author immediately with ALL POSSIBLE DETAIL of the problem including, of course, the KERR.LOG message! Error Code Description Explanation/Possible Solutions 7 Out of memory Are you using *M to swap the BBS out before running Kingdoms? Give it more memory in which to run. 24 Device Timeout An I/O device (probably your COM port) is not responding. 25 Device Fault A device has returned a hardware fault condition. 27 Out Of Paper I hope you never get this, cos Kingdoms isn't supposed to print anything :-) 53 File Not Found Do you have your paths defined correctly? Do you have your .KDI files from the distribution archive in the Game directory defined in the Manager? Can Kingdoms find DORINFO#.DEF or DOOR.SYS? Are you in the Kingdoms directory when you try to execute Kingdoms? Have you renamed or deleted anything accidentally? 57 Device I/O Possible interrupt conflict on your error system or hardware error. 61 Disk Full I hope you notice this BEFORE Kingdoms picks it up! :) 64 Bad File Name Possible Kingdoms error, but check the options in error 53 before reporting! 67 Too many files Kingdoms has tried to open or save a file and the DOS 255 file-directory maximum has been exceeded. Clean up your hard drive ... 70 Permission Your drive is write protected or a file Denied is locked that Kingdoms is trying to access. Rebooting will often fix the latter as this may happen if network software becomes unstable. Please report it if you can't solve it or if it persists as it may be a Kingdoms problem. If you're running a multitasker, check your other tasks! 72 Disk Media Drive hardware has detected a physical error error on your disk media. I STRONGLY suggest you backup your system if you get this one! _____________________________________________________________ 29 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ 75/76 Path/File Possible Kingdoms error, but check the access errors options in error 53 before reporting! _____________________________________________________________ 30 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ Appendix B : QuickStart Installation I suggest you read Section 5, the Installation documentation in full before you install the game, but for those feeling brave, here's a quickstart setup! Unpack the archive into a separate directory. If you're in a Kingdoms network, get an Index file (KIDX.nn, where nn is your NetId) off your Network Coordinator. Place it in your game directory and rename it KIDX.DAT. Run KM, the Kingdoms Manager. Define your Paths and Other information under the File menu. Make sure your NetId is correct if you're playing in a Network, othewise leave it blank. If you're in a network, go into Network>Your Routing and select your node on the Index to let Kingdoms know who you are. It will automatically configure the correct routing definitions for all other nodes in your network. Run Kingdoms locally to check all is well using KINGDOM /L Set up a batch file to call Kingdoms from your BBS. Swap the BBS out of memory (normally using *M) when you call Kingdoms. If you're running multiline, start Kingdoms with two parameters. 1 ... /Nx, where x is the node number and 2 ... /Ddrive:path/dorfile, where drive:path/dorfile is the full path and filename to your dorinfo?.def or door.sys file for the respective node. Add KMNT, the Kingdoms maintenance program, to your nightly batch file. If you're in a network, add KNETIN and KNETOUT also. Run them in the order KNETIN, then KNETOUT, then KMNT. That's it! If you have any problems, read the documentation fully! _____________________________________________________________ 31 KINGDOMS v2.18 System Operator Documentation ____________________________________________________________ Appendix C : Upgrading from Prior Releases Kingdoms 2.18 is the first public release of Kingdoms after version 2.17. To upgrade from 2.16 or 2.17 is a copy-over upgrade. No game reset is required. To upgrade from 2.15 or prior releases, you must run the 215to216.exe utility provided in the distribution archive as 2.16 and onwards use new (expanded) file formats compared to previous versions. This utility will reformat your files for you automatically. To Upgrade from 2.16 or 2.17 : 1. Backup your existing Kingdoms game. 2. Unpack the Kingdoms 2.18 archive into your Kingdoms directory. Overwrite all existing files when prompted. You HAVE backed them up, right??? :-) 3. From the game directory, start the Manager, KM.EXE. A version update note will be issued. Respond es to commit to the upgrade. 4. Your upgrade is complete. Start Kingdoms as per normal with KINGDOM /L and ensure everything is operating normally. New features and fixes in 2.18 can be seen within the game from the M>isc menu, or in the whatsnew.218 text document in the distribution archive. - End of Sysop Documentation - _____________________________________________________________ 32