The World of Computer Software/World_Of_Computer_Software-02-386-Vol-2of3.iso/c/ctkit11.zip/CTKIT11.DOC

Text File | 1992-04-06 | 22KB | 534 lines

The Crunchterm Programming Kit v1.1
Brought to you by Crunchware!

BBSENDU.DOC:  Writing Doors with Crunchterm Support

Introduction

     This is a brief text file which will hopefully make it a
little easier to understand just how to write a door that
supports Crunchterm.  Writing a game that supports graphics can
be complicated enough in itself, but writing one that works over
a modem is even worse.  This package attempts to make the process
easier by doing some of the nitty-gritty work for you.
     Included in this package are several Turbo Pascal v5.5
units, but the only one that it is necessary to be concerned with
is BBSENDU.  The other units act only as support for BBSENDU,
although they too may be worth modifying once you've figured out
how they work.
     The scary thing is that this is a "brief" text file.  Hope
you can figure it out.

Well, What Do You Do?

     To get started with Crunchterm support, all you have to do
is include BBSENDU as one of the units in your program.  Below is
a description of the major commands in BBSENDU which may be
necessary or helpful.
     It may be helpful to clarify some terminology first.
"Door," or chain, is a program, like Crunch League Football and
all other programs which support Crunchterm, meant specially to
be run as a subprogram from a BBS.  "Local" refers to the
computer on which the program you are writing will be running.
In most cases, that would also be the computer running a BBS.
"Remote" refers to a computer which has called the BBS and has
selected to run the program.
     NOTE: Any of the following functions that have anything to
do with input and output automatically determine where to act.
For example, if the program is only being run locally, the
procedures will only do stuff with the local computer.  If it's
only running remotely, the program'll only send commands over the
modem for Crunchterm to interpret on the other side.  If the
program is running on both ends, believe it or not, the program
does both those things.

Function KeyPressed: boolean;

     Equivalent of crt's KeyPressed.  It must be a leftover from
the days when BBSENDU didn't use the crt unit.

Function KeyCheck: boolean;

     Like KeyPressed, except it also checks the COM port to see
if a character is waiting there.  If, of course, either local or
remote play has been disabled, KeyCheck will not check that
location.

Procedure MakeTime (var T: longint; var D: word);

     Used by a couple other procedures, MakeTime enters the
number of seconds that have passed in the current day in T and
the day of the week in D.

Procedure SendStr(s: string);

     Equivalent of Write in TP, although you must supply only one
string of characters.  So with a setup like this:

var
   butthead: integer;
   name, ts: string;

you'd have to do something like:

...
Str(butthead,ts);
Write (name+', your butthead quotient is '+ts+'.');

     It might help to write a function that performs the same
things as Str.  I use one, but it seems I didn't include it in
BBSENDU.

Procedure SendLine(s: string);

     Just like SendStr except adds a carriage return and line
feed at the end of the string.

Procedure ExitProg;

     Returns to graphics mode, closes the modem connection
(EXTREMELY IMPORTANT) and Halts.  Be sure to call this as the
last thing in your program instead of a plain old Halt.

Function WaitForChar: char;

     Like crt's readkey except that it allows for modem input as
well.  It also tells the program to abort if no key has been
pressed during the last predefined number of minutes (in the
variable WaitMin).  Also, any time the procedure is idling, a
person on the local computer can press F10 to make the program
abort immediately.  As it is now, the program doesn't save
anything when aborted, so you might want to make some
modifications here.  Note that F10 will work even when the
program is only running for the remote computer.

Procedure RdLn (var s; l: byte);

     Read a string, s, of maximum length l and stick a carriage
return at the end.  Works in graphics and text modes.
Procedure Initialize;

     BBSENDU has one major procedure, Initialize, which sets up
all the necessary modem connections.  It requires, however, that
the name of a chain information file from one of several BBS
selections be supplied as the first parameter of the command line
to the program.  It is for that reason that Crunch League
Football requires "FB %1" in WWIV, which WWIV in turn converts to
"FB \WWIV\CHAIN.TXT."  Initialize, when called by your program,
will try to open the file named in the first parameter and, if it
recognizes the file type, loads the necessary information about
the current user's name, COM port, and baud rate.  If you have
some other way of supplying information necessary for the program
to connect with the modem, you may opt to modify Initialize to
work some other way.  It is important, however, to somehow
establish a connection with the COM port before you try to do
ANYTHING else.
     Initialize also supplies the current user's name in the
variable PName and more detailed information about the user if
the current BBS is WWIV.

Procedure SendCommand (R: byte; ComStr, ExStr: string);

     This is the procedure that determines where to send
"Crunchterm" commands (i.e., specially coded strings which
Crunchterm decodes and follows) you have given the computer.  If
you're connected to a remote computer, it sends the necessary
codes over the modem.  If you're displaying locally, it performs
the command in CodeStr locally too.  You would rarely, if ever,
call this procedure itself.  Usually you would call one of the
procedures listed below which in turn creates the necessary
strings for SendCommand and calls it.
     In order to use any of the procedures that use SendCommand,
Crunchterm must be active on the remote end.  Before you do
anything else, use TestResp (see below) to make sure the other
end has Crunchterm.  Otherwise, the remote computer will have no
idea what to do with these bizarre characters it's receiving over
the modem.

Procedure PutPic(num: byte; x, y: word; how: byte);

     Equivalent of the unit Graph's PutImage except that you must
refer to a picture number rather than variable name.  Stored both
locally and in Crunchterm at the other end, are 200 slots (which
are really just pointer variables) for graphics.  These must be
loaded from data files or GetPic-ed earlier in the program.
Refer to LoadPic and GetPic for a clearer idea of what's going
on.

Procedure LoadPic(num: byte; place, length: word; fn: string);

     Load a picture from a data file available where the program
is being run.  If, for example, you want to be able to load a
picture from MAIN.CT, it must be located both on the local
computer and on any remote computer that runs the program.  Num
specifies the slot in memory where you want to load the picture
(1-200).  Place specifies the byte location (starting at 0 in the
file) of the picture you want to load, and Length specifies its
length in bytes.  Fn is the name of the file from which you wish
to load the picture.  Note that when you pass a blank Fn,
Crunchterm will assume you want to load a picture from the file
you most recently loaded from.  That way, you can save a few
extra bytes for each graphic you load, and that can come in handy
when you've got 70 or so.  Just make sure you specify the proper
file name the first time you load a graphic.
     One important thing:  The graphic you load must be stored in
bit-map format.  (It can actually be in a slightly compressed
format that I used for CLFB, but it'd probably just confuse you
more to try to mess with that.  You'll note that there's a file
called SCStuff.PAS whose function is to decode the compressed
format.  If you feel adventurous, you can try to figure out how
that compression works.  Maybe I'll be able to release a utility
that'll actually do the conversion for you someday.)
     I'm distributing in the Crunchterm Programming Kit a utility
which I found useful called CTFILE.  CTFILE allows you to create
and edit CT files just like MAIN.CT and CLFB.CT.  CT files are
composed of several chunks of data which were at one time
separate files.  If you've got fifty 100-byte files, you can
combine them into one 5000-byte file.  In .INF files, CTFILE
stores the information that you'll need for such procedures as
LoadPic and LoadSong.  I've also included MAIN.CT and MAIN.INF
(.INF files are used by CTFILE but don't need to be distributed
with your program) as a demonstration.  Valid commands for CTFILE
are as follows:

A: Add file to the end of the current list.
D: Delete one of the chunks of data in the file.
N: Write a new description of one of the chunks of data.
R: Replace a chunk of data in the middle of the .CT file with a
new file.
Q: Quit and save.

When you run CTFILE, be sure not to include the .CT extension at
the file name prompt.  It's pretty confusing at first.  Using
bit-mapped graphics really is the hardest thing to get used to
with Crunchterm, but it isn't really that bad once you get used
to it.

Procedure DoText(x, y: word; tx: string);

     Displays a string at the specified coordinates, either in
text or graphics modes.  X and y in text mode simply must be in
the range 1-80 and 1-25, while they designate pixel locations in
graphics modes.

Procedure GrInfo(var gd, gm: word);

     Returns the maximum graphical capability of the active
computers.  If, for example, the remote computer has VGA while
the local has only CGA, GrInfo will return gd equal to 1 and gm
equal to 3.  Refer to your TP docs to understand what the gd and
gm codes mean.

Procedure InitGr(d, m: word);

     Just like InitGraph.  Note the all the video drivers have
been compiled into the unit rdrivers, so you don't have to
specify a path to the BGI files.  That also makes it unnecessary
to distribute BGI files with your program.

Procedure ScreenPage (apage, vpage: byte);

     In EGA and VGA modes, change the virtual page of the
graphics mode you're in.  Check out SetVisualPage and
SetActivePage in your TP documentation.

Procedure DoLine (x1, y1, x2, y2: word; color: byte);

     Just like Line in Graph except color will change the current
active color to itself (take a look at SetFg...).

Procedure DoCircle (x, y, rad: word; color: byte);

     Like Circle in Graph.  Color has the same effect here as in
DoLine.

Procedure DoRect (x1, y1, x2, y2: word; color: byte);

     Duh.  "Rect," maybe that has something to do with drawing a
rectangle.

Function TestResp: boolean;

     TestResp sends a special code over the modem to the remote
terminal.  If Crunchterm is running on that terminal, TestResp
will return true.  Otherwise, it will return false.  You pretty
much always want to use the expression:

...
CTOn := TestResp;
...

where CTOn is a global variable found in BBSENDU.  CTOn must be
true anyways for any Crunchterm commands to have any effect.

Function MemFree: longint;

     Memory available in the remote computer unless you're only
playing locally, in which case, it returns the memory free in the
local computer.

Procedure LeaveCT;
     Send the command (if you're connected to a remote computer)
to have the remote computer exit Crunchterm.  You'd usually do
this at the end of the program.

Procedure ClearScr;

     Clear the screen, either in text or graphics mode.

Procedure SetCol (fore, back: byte);

     In text mode, set the color that text will be displayed in
(Check your TP documentation for color codes).  In graphics mode,
SetCol sets the foreground color for anything that will be
displayed and the whole background is set to back.

Procedure InLineXY(len: byte; x, y: word; var thestring: string);

     Input a string at coordinates (x,y) of maximum length len.
X and y are units corresponding either to graphics or text mode.

Procedure FillStyle (pattern, color: word);

     Just like SetFillStyle in Graph.

Procedure GetPic (num: byte; x1, y1, x2, y2: word);

     Similar to GetImage in Graph, although, as with PutPic and
LoadPic, you must specify a picture number rather than variable
name.

Procedure DefSeries(Ser,Step,Command,ExNum: byte;StrStr: string);

     If you've got an extensive series of Crunchterm commands
that you use frequently, you can speed up the process by defining
a series of commands on the remote computer.  To do it, you must
first execute a Crunchterm "SendCommand" command with the
variable Stringing set to true.  Any command that is called will
then have its code saved in the global variable StrungStr.  You
can then send StrungStr, the command number (which you can find
in BBSENDU's source), and if necessary the number of an extra
string.  See DefExStr for more on that.  There can be three
series containing up to nine commands each.  This procedure can
be helpful at times, but don't kill yourself worrying about
trying to get it to work.  The number of steps in the series will
be defined by the Step number of the last command you define.
Thus you would normally want to define the series in the order it
happens.

Procedure DoSeries (Ser: byte);

     Perform a predefined series of commands (see above), 1-3.

Procedure DefExStr (num: byte; exstr: string);

     If a command in a series needs a string--for example,
DoText--you can define and extra string for use with DefSeries.

Procedure SetGD(gd: byte);

     This may seem a little bizarre, but bear with me.  The
conversion procedure I wrote needs to know the graphics mode that
the picture it is uncompressing is for.  If, however, you want to
convert pictures before you've entered graphics mode, you need to
specify the graphics mode in gd for that.  In other words, this
command is pretty darn useless.  Unless you have pictures stored
in that compressed format.

Procedure LoadSong (SongNum: byte; Place: word; FN: string);

     Works much like LoadPic, although songs must always be the
same size and format.  Don't ask me why.  I'm just too lazy to
make it easier to use.  Anyways, songs are stored in a format
found in CTSOUNDU.  You might recognize the note/octave format
from TP samples.  It's a little confusing at first, but MAIN.CT
begins with 10 "sound effects," including the theme to CLFB.
Each song is 150 bytes long, so to load the first song from
MAIN.CT, you'd call LoadSong(1,0,'MAIN.CT');  (the second would
be LoadSong(1,150,'MAIN.CT'), etc.)  That'll load the song into
the first song slot.  I believe there are ten slots available in
memory.

Procedure DoSong (SongNum: byte);

     Play a song that you've loaded in the background as you do
something else.  Pretty nifty as long as it doesn't conflict with
some other memory resident thing.  But sound can be disabled with
/Q.  It was a pain to figure out, so enjoy.  Maybe I'll figure
out how an Adlib card works someday.

Procedure DefAnim (Flm, Frame, PicN: byte; pause, x, y: word;
Way: byte);

     Even with pretty short commands, animation can be slow with
Crunchterm.  This works sort of like DefSeries, except only with
pictures.  You can define Flm 1-30 and each can have up to 10
frames.  Pause is the number of milliseconds to wait before
displaying the next frame.  Way is the way the picture is
displayed (eg. "NormalPut" or "NotPut" or "OrPut" in TP dialect).

Procedure ShowAnim (Flm: byte; AuxX, AuxY: word);

     ShowAnim displays a film with the defined X and Y relative
to AuxX and AuxY.  So if a picture in the film is defied to be at
(10,20) and you call ShowAnim(..,20,20), the picture will appear
at (30,40).

Procedure TextStyle (Size, font: word);

     Sorta like SetTextStyle in TP, although you can't turn text
sideways, and the only fonts you can use are Default and Triplex
(0 and 1, I think).  If you'd like me to compile in some others,
please tell me.  You can always distribute a .CHR file with your
program, and Crunchterm'll find it if it's in the proper
directory.

Procedure FillCircle (x, y, rad: word);

     Draw a filled circle in the current pattern, etc.

Procedure FillBar (x1, y1, x2, y2: word);

     Draw a bar, filled with whatever pattern you've defined.

Procedure FillFlood (x, y: word; BorderCol: byte);

     Just like TP's FloodFill.  I must just be dyslexic.

Procedure DefNote (Song, Note, l, n, o: byte);

     Aha!  If you don't feel like using 150 bytes for a two note
sound effect, you can define notes individually.  I think there
are ten songs.  Fifty notes each.  L is the length of the note in
milliseconds and n and o correspond to the codes defined in the
TP music demo.

Procedure ChPalette(ColorNum: word; Color: shortint);

     If you're in an EGA mode, you can edit your palette.  I
believe there's a Graph command much like this.

Procedure DoArc (x, y, stangle, endangle, rad: word);

     Draw a segment of a circle.  I think there's a TP command
like this too.

Procedure VirtWind (x1, y1, x2, y2: word; Clip: boolean);

     Believe it or not, I think there's a TP command equivalent
to this sucker as well.  Just sets up a virtual window to act as
the whole screen.

Procedure HighLight (x1, y1, x2, y2: word);

     Inverts (i.e. white to black and black to white) a section
of the screen.  This is great for bar menus and stuff.  You've
probably seen this command in action many times in CLFB.

Procedure UnHighLight;

     Uninverts the section of the screen that has been most
recently HighLighted.  Note that you could just call HighLight a
second time to unhighlight, but this command saves sending 8
extra bytes over the modem.

Procedure DefScroll (x1, y1, x2, y2, scramt: word);

Define a section of the screen that you want to scroll up and
down.  The x coordinates may have to be divisible by eight.  I'm
not quite sure.  ScrAmt is the number of pixels that the section
will scroll on each call.

Procedure ScrollUp;

     Scroll up ScrAmt pixels in the predefined area (see above).

Procedure ScrollDown;

     Scroll down (see above).

Procedure SetFg (fore: byte);

     Just like SetColor except only for the foreground.  Helpful
especially in graphics mode because it saves a byte when you'd
rarely want to change the background color.

     Whew!  That's it for BBSENDU's commands.  Hope you can
figure it all out.  Once you get the hang of things, you might
wonder what some of those global variables are there for.  Well,
to explain some of them...

(From BBSENDU.PAS...)

var
   ComStr, The string where various CT commands assemble codes
   lastpress,  Used by WaitForChar to hang up if a key hasn't
been pressed for a while.
   TrueUK, If CHAIN.TXT is used, the value of a person's upload K
credit on the BBS according to CHAIN.TXT.
   lastd, The last day of the week when a key was pressed.  Don't
worry about it.
   WaitMin, Number of minutes the program'll wait for a key to be
pressed.
   BaudRate, Duh.
   ComPort, Another toughy.
   FillPat, FillCol, Used by FillStyle.
   UserNum, If it's WWIV, the user number found in CHAIN.TXT
   stringing, Whether or not you're defining strings for
DefSeries.
   SysAllowed, If true, display locally.
   ModemOn, If true, display remotely.
   Local, If the last character input was local.
   DoTimeCheck, Whether or not TLim means anything.
   CTOn, Whether or not Crunchterm has been detected, I think.
   SoundOn, True if sound is allowed.
   StrungStr, Used with DefSeries.
   PName, User name read in from the door info file.
   BBSName, The name of the BBS read in from the door info file.
   DataDir, the location of the directory holding USER.LST on a
WWIV board.
   TrueSL, Sec Level read from CHAIN.TXT on a WWIV BBS.
   BkCol, FgCol, Current color settings.
   Ver, No real use until we hit newer versions of CT.
   TrueGold, WWIV gold (if CHAIN.TXT has been read).
   DLim, Day of the week when time will run out.

     With this package, I included a short program (CTDEMO.PAS)
which demonstrates some of the basic functions of Crunchterm-
supporting programs.  That should give you a basic idea exactly
how to use some of the basic commands descirbed above.

That Better Be It!

     So there you have it:  How to write a Crunchterm-supporting
program in a nutshell.  Have fun.  If you've got any questions
please contact me...

Stephen V. David
6030 Fort Hunt Road
Alexandria, VA  22307

or Infinity #27 on Lankhmar BBS (703 360-4973), #27 @ 7309
WWIVNet, or #80 @ 17310 WWIVLink.
     Whenever I get a new version of Crunchterm out, I'll be sure
to release a new version of this kit to use with it.   Be on the
lookout for an update one of these days.  It should be pretty
easy to upgrade.  All you'll have to do will be recompile your
program with the new BBSENDU and implement any nifty new commands
(if there are any... :)...).
     This Programming Kit is public domain, and I don't endorse
anything written with it and am not responsible for any nasty
thing that some idiot might want to use it for.  If you like it
and DO use it for a legitimate program, I'd love to hear about
it.  If you get rich using it, please remember the poor
programmer who helped you along the way.  Thanks for any
contributions, but I don't require a fee for using this stuff.
     I hope this gets people started writing some more graphical
on-liners.  Enjoy!

<< Addendum by Joel Slovacek: >>

The files *.TP6 are TPU files for TP 6.0.  The other .TPUs are for 5.5.
The Pascal files are *not* included, but if it is important, they can be
transported in a second file.