  Software Development Kit: power overwhelming
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. INTRODUCTION

From release 19052002 onwards, Liero-AI supports dynamic linking. This means
that you can enter your own binary code into the program. You may create it
using nasm or anything that produces Windows COFF format files, but the most
recommended and guaranteed-to-work is the Free Pascal Compiler. The Liero-AI
binary is coded in Free Pascal so there will be fewest matching problems, for
instance with strings.
 Note that even under Linux, you need Windows COFF files.
This enables cross-platform DLs.

I'd recommend using FPC version at least 0.99.14a (this is the one I use). It
is known that FPC 1.0.4 works OK as well (tested myself). It can be downloaded
from many sites, probably more than one in your country, as it's quite popular.
The headquarters FPC site is at http://www.freepascal.org/. You should get the
Win32 version, of course.

2. FORMAT

You have to create a Pascal unit. I think you would like to use the LieroSDK
unit that provides access to most of Liero-AI binary internals. You can do
almost everything with it. Oh, and yes, it will give off a strange warning when
compiling. You may safely ignore it.

Please name your unit in a sensible way or the names might clash (strange
errors occur). For instance, naming the unit 'Weapons' is a bad idea because
Liero-AI has a built-in of this name.

Any functions / procedures that happen to be in the interface section will be
visible to other parts of Liero-AI.

After compilation, take the '.OW' file, rename it to '.VDL'. If you are going
to release, please make 'stripw --strip-debug something.vdl' so that the file
is smaller. If you include the '.VDL' file in a '.VPK', it will be loaded when 
the game starts. You can call your procedure using 'BinCall' (see the WCK docs).
The '.PPW' file can be discarded.

Because FPC mangles procedure names somewhat, you may use the 'LISTSYM.EXE'
program in the SDK to list all symbols declared by your unit. Note that the
BinCall is case-sensitive (usually everything is uppercase). In most cases it
will be something like that: '_UNITNAME$$_PROCNAME' if you don't have any
parameters. If you take, for instance, a LongInt and a string, it would be
probably '_UNITNAME$$_PROCNAME$LONGINT$STRING' or something like that.

3. RESTRICTIONS

You can use only the following standard units: Windows, Dos, SDL, SDL_Keyboard,
SDL_Video, SDL_Mouse, SDL_Events, SDL_Timer, SDL_Audio, Winsock2, LieroSDK.
Try to make your code fit in a single '.VDL' file. If you are determined to use
some other unit, you will have to deliver it in the same '.VPK' package, and
make sure it is before the unit which uses it on the '.VLF' list file.
Otherwise, the unit will not be loaded (unresolved external references will
occur). For instance:

unit TestA;
interface
uses TestB;
implementation
end.

unit TestB;
interface
implementation
end.

Then the '.VLF' list file should look like this:

TESTB.VDL
TESTA.VDL

Note that you can't have mutual references. What a pity.

You can use the initialize/finalize constructs. You should never use ExitProc
to ensure something happens when the program exits. Put it in the finalization
section instead.

4. LIEROSDK DOCS

Note that most procedures have fairly self-explanatory names, just as some of
their parameters.

4.1. GRX13H

Many procedures, functions and variables prefixed with 'g' belong to the Grx13h
unit. It provides graphics services for both the low-res and hi-res mode. Now,
you are going to familiarize yourself with the layout of virtual screens in
both modes.

The low-res screen, addressed by 'gVS' is 3072x1024 in 256 colors (1 byte per
pixel). Xels Y>=2560 are occupied by sprites and can't be used for your dark
purposes. The screen is basically partitioned into parts of 512x512 xels. The
first part at (0,0) is the full-size screen. It contains current view of the
game (less or more). A bit lower, at (0,512) is the terrain at its whole. The
part at (512,0) contains the collision map for worms and bonuses, while the
parts at (512,512), (512,1024), (512,1536) and (512,2048) contain projectile
collisions for worms 1, 2, 3, 4 respectively (if the projectile belongs to the
worm number 2, it will appear only on the 2nd collision screen, and so on).
The part at (0,1024) contains the 320x200 screen to be copied to the monitor.

The hi-res screen, addressed by 'gHS' is 3574x1024 in 65536 colors (2 bytes pr
pixel). Xels Y>=2560 are also occupied by sprites. The screen is partitioned
into parts of 1024x1024 xels. The first part at (0,0) is the full-size screen.
And the part at (0,1024) contains the terrain. If the bit 5 is set in a color,
it is considered non-diggable and if bit 0 is set, the color contains air. The
last part is only 512 xels high, but it contains actually only a 640x480 screen
to be displayed.

Stanislaw Skowronek, thesis@elementy.pl
