This is the merging Quake2 MultiModule API and Quake2 Cluster Project 
distribution. 

Author: Justin "Logic" Randall, logic@logic.columbus.oh.us
Primary Distribution: http://www.planetquake.com/logic

The examples in this directory demonstrate how to write game modifications 
that conform to the Quake2 MultiModule API (Q2MMAPI). The 1998 March 30 
release does not include an example that uses the function import/export 
support in Q2MMAPI.

What is the Quake2 MultiModule API?

This interface to the game permits authors to write game modifications that 
will coexist with other compliant game mods. In addition to concurrent 
execution, the API also provides functionality for exporting routines so that 
one author can write routines for use by other authors. A good example may be 
a logging-standard plugin, which is called by another plugin to extend the 
game overall.

Why should authors use this API, rather than code directly against the game 
sources?

One of the worst limitations of the original Quake engine, and prior to this Q2 
modification, was that efforts were often duplicated just to make a game that 
offered functionality that was in demand by players and server operators. Server 
administration mods might not have Runes or CTF support, etc... Code had to be 
hacked or merged and only a single game modification could run at a time. 
Rather than have the ability to call certain functions (say for Runes) in a 
pre-existing progs.dat or gamexxx library, an author would have to reinvent 
the wheel with each new mod, just to provide gameplay similar to what is popular 
in other mods.

With the new API, an author that creates a Rune mod can run his library on 
servers that also run CTF, or Coop, or Server Administration, etc... The 
author, if he were so inclined, could also share his own routines with others 
via the API (rather than merging sources) so that other authors could expand 
on his mod. As these dependancies grow, the provider (the author exporting 
routines) gains a wider deployment in exchange for his efforts helping other 
coders in the community.

Why should server operators run this library?

Q2MMAPI servers provide a smorgasborg of gameplay options. Operators can mix 
and match libraries simply by copying them to the game directory, and create 
a whole new game environment. Rather than having to wait for someone to code 
Runes and Homing Missiles into a single game library, they can take Rune and 
Homing Missile plugins and copy them to the game directory --or any other 
combination for a truly unique server configuration.

How does the API perform?

The plugins are lightweight, typically < 25% the size of the game dll, and 
efficient. All functions are accessed using pointers --there's no thrashing VM 
or moving data around. It all sits in memory just as data and functions in the 
main game library would. 

It is all strictly C, and standard C wherever possible. C is a high performance
language. It compiles and optimizes very well.

Plugins have the ability to totally override internal game routines, meaning
that "performance" plugins are possible, bypassing any unnecessary routines
(monster code comes to mind), or replacing game functions with more efficient
code.

How portable is the API?

Where OS specific optimizations are warranted, or necessary, an abstraction
has been added to protect the author from porting nightmares moving code from
one environment to another. As long as the new plugin is standard C, it should
cross compile anywhere. The included Makefile is configured for Linux, but 
should work with other ELF platforms (UN*X) and workspace files are included
for Microsoft VC++ 5.0 projects.

Moving existing mods to the plugin API consists mostly of altering how the
new modifications store and retreive data. Since it is not possible to
directly extend game internal structures, a reference system is provided to
associate instances of game data with the plugin code so that each author
can arbitrarily extend data without interfering with the game or other plugins.



