Archive Maintainer      : Please replace utils/misc/ctrlapi.zip with this
                          updated version.
===========================================================================
Advanced engine needed  : Vanilla Doom
Primary purpose         : No levels included
===========================================================================
Title                   : Doom External Control API
Filename                : ctrlapi.zip
Author                  : Simon Howard
Email Address           : fraggle@gmail.com
Other Files By Author   : greenfish.wad, statdump.zip

Description             : This is some example code that uses Doom's
                          external control API (the -control command line
                          parameter).

                          Vanilla (DOS) Doom supports a little-known
                          command line parameter named -control. This
                          parameter allows an external program to inject
                          movement events into the game. The most likely
                          explanation is that it was intended to allow
                          companies manufacturing game controllers
                          (joystick, gamepad, etc) to provide their own
                          custom drivers to control the game. As far as
                          I know, no such driver was ever written before
                          now.

                          Full source code (requires Borland Turbo C) is
                          included. This version is a second release that
                          fixes the construction of the '-control'
                          parameter so that the programs work correctly
                          on Windows.

Additional Credits to   : James Haley (Quasar) for the reverse engineered
                          information that he provided about how the
                          external control API works.

                          Miguel Folatelli (myk helnyte) for testing the
                          fixed version on Windows for me.

===========================================================================
* What is included *

Three demo programs are included that demonstrate the sort of things that
the external control API can be used for:

  forward.exe

    - The most simple (and most boring) example. This program simply
      makes the player move forward constantly. To run:

        forward.exe doom2.exe -warp 1

  replay.exe

    - This program replays a previously recorded demo. This is useful
      because it allows a demo to be partially recorded and then
      continued at a later date. To run:

        replay.exe -playdemo olddemo.lmp doom2.exe -warp 1

      Or to continue recording:

        replay.exe -playdemo olddemo.lmp doom2.exe -warp 1 -record newdemo

      Playback of Strife demos is also supported with the '-strife'
      parameter, eg.

        replay.exe -playdemo strdemo.lmp -strife strife1.exe -warp 2

  statdump.exe

    - This is a refactored version of my external statistics driver
      which I previously released as statdump.zip. Problems were reported
      with that program because it replaced the mouse interrupt, and
      as a result, worked under DOSbox but not under real DOS systems.
      Hopefully this should work better.

      This does not actually make use of the control API to inject any
      events, it just take advantage of the fact that it provides a
      regular interrupt. To run:

        statdump.exe doom2.exe -warp 1

      Or for statistics for a demo:

        statdump.exe -o mydemo.txt doom2.exe -playdemo mydemo

      Hint: You can get the results of this really quickly using
      -timedemo and -nodraw, eg.

        statdump.exe -o mydemo.txt doom2.exe -timedemo mydemo -nodraw

* Boring technical commentary *

See control.c/control.h in the source code for details of the interface
between the calling program and Doom. The calling program must set up
an interrupt vector which is invoked by Doom. When the interrupt handler
is invoked, it fills a ticcmd_t structure with details about how the
player should move. Doom adds to this structure, adding keyboard,
mouse and joystick movement on top, and filling in the consistancy and
chatchar fields (see G_BuildTiccmd in the Doom source).

The demo programs above also support a -cvector parameter to manually
specify the interrupt vector to use. This shouldn't normally be needed.
It's analogous to the -vector parameter used by ipxsetup/sersetup.
eg.

   forward.exe -cvector 0x65 doom.exe -warp 1

The control API is also supported by Strife, although not Heretic or
Hexen (which were presumably forked from an older version of the source
code before the control API was added). The Strife version of the
ticcmd_t structure is used here as it is a compatible extension of the
Doom structure.

* Copyright / Permissions *

GNU GPL.  See the file COPYING.txt inside the archive.

* Where to get the file that this text file describes *

The Usual: ftp://archives.3dgamers.com/pub/idgames/ and mirrors