Conitec 3D GAMESTUDIO-SOURCE DEVELOPMENT User Manual
3D Gamestudio Programmer's Manual
3D GameStudio
Source Development Kit
Programmer's Manual
© Conitec July 2002
1
for A5 Engine 5.230
Johann C. Lotter / Conitec July 2002
3D Gamestudio Programmer's Manual
© Conitec July 2002
2
This manual is protected under the copyright laws of Germany and the U.S. Acknex, A4, A5, and 3D GameStudio
are trademarks of Conitec Corporation. Windows, DirectX and Direct3D are trademarks of Microsoft, Inc. Voodoo is
a trademark of 3dfx, Inc. Quake is a trademark of Id Software, Inc. Any reproduction of the material and artwork
printed herein without the written permission of Conitec is prohibited. We undertake no guarantee for the accuracy
of this manual. Conitec reserves the right to make alterations or updates without further announcement.
3D Gamestudio Programmer's Manual
© Conitec July 2002
3
Contents
The A5 DLL interface.....................................................................................................4
Getting started with the SDK...............................................................................................4
Implementing new C-Script functions................................................................................5
Writing to the screen buffer.................................................................................................5
Using Direct3D functions.....................................................................................................6
Particle functions..................................................................................................................7
Programming a game in C++...............................................................................................7
C-Script object and DLL interface structures.....................................................................8
DLL functions........................................................................................................................9
The A5 Client/Server Protocol....................................................................................12
Client Messages..................................................................................................................12
Server Messages................................................................................................................13
The MDL5 model format..............................................................................................15
MDL file header...................................................................................................................15
MDL skin format..................................................................................................................16
MDL skin vertices...............................................................................................................16
MDL mesh triangles............................................................................................................17
MDL frames.........................................................................................................................17
MDL bones..........................................................................................................................19
The HMP5 terrain format.............................................................................................20
HMP file header...................................................................................................................20
HMP texture format.............................................................................................................20
HMP height values..............................................................................................................21
3D Gamestudio Programmer's Manual
© Conitec July 2002
4
The A5 DLL interface
DLLs can be used as extensions (plugins) to the engine and to the C-Script language, as well as
for programming a game totally in C++ or Delphi, instead of C-Script. The DLL interface is
available on all A5 editions. For creating an A5 DLL, the SDK (source development kit) is
required. SDK owners can create DLLs for adding new effects, actor AI or C-Script instructions,
and distribute or sell them to other 3D GameStudio users.
The Microsoft Visual C++™ development (versions 6.0 or .NET) system normally is used for
creating DLL plugins. Borland C++™, C++ Builder™,orDelphi™ can also be used. The DLL
SDK contains an interface library that must be linked to any DLL. An example project with a
DLL template is also provided, which makes it easy to create extensions even for not-soexperienced C or Delphi programmers who have never used DLLs before. The SDK license
includes the right to freely distribute DLLs created with it, as long as the DLL functions only
provide application functionality. It is not allowed to distribute DLLs that work as a 'wrapper'
for the library by providing functions that allow direct access of the interface structures or the
library functions from outside the DLL.
DLL extensions work bidirectionally: C-Script instructions can access C++ or Pascal DLL
functions, and DLL functions can access engine and C-Script functions and variables. So you
can – if you want - arbitrarily mix C-Script, C++ and Pascal in your application. On opening a
DLL, the engine transfers the pointer to an internal interface structure to the interface library.
The interface contains pointers to engine variables and functions, like the frame buffer, the
DirectX interface, the network interface, the DirectInput interface, the level, the C-Script
functions and so on. Theoretically everything - MP3 or MOD players, a physics engine, another
3D engine or even another scripting language - could be added to the engine this way.
Note that the following documentation contains just the description of the DLL interface to the
C-Script API, and some examples. The API functions are described in the GameStudio Manual.
The same C-Script functions are used for the DLL as well as for C-Scripts, so you'll need both
manuals for creating DLL plugins.
Getting started with the SDK
You'll find the SDK either as a ZIP file on your key disk,oronaseparateSDK disk.Unzipor
copy the SDK into a directory of your choice, and open it as a VC++ 6.0 project. The code for
Borland C++ oder Delphi can be found in the BCPP and Delphi subfolders – read the readme
text files for more information about how to create Borland and Delphi projects. The SDK
comes with a DLL source,
ackdll.cpp
and
ackdll.pas,
that contains some typical examples
for DLL functions. Examine the examples carefully – it's the best way to see how to program
DLL functions and access engine parameters! You can use it as a 'template' for your own DLL.
On accessing system resources like sound, video, joystick and so on, the DLL must take care of
possible resource conflicts. The engine shares its resources and expects the same from the code
inside the DLL. For instance, code that requires exclusive access to the sound device (like some
old MOD players) won't work. Some resources (like the midi player) can't be shared - if midi
music is played by the DLL, the engine must not play a midi file at the same time and vice
versa. Also care must be taken that for writing something into the frame buffer it must be
locked before, and unlocked afterwards. The interface library provides functions for that.
3D Gamestudio Programmer's Manual
© Conitec July 2002
5
We are using VC++ for our following examples - you'll find the corresponding Pascal versions
in the Delphi folders. For testing one of those DLL functions, compile the DLL, copy it into your
work folder, and insert the following C-Script instructions into a function assigned to a key:
dllfunction PaintScreenWhite(x); // dll function declaration
...
dll_open("ackdll.dll");
PaintScreenWhite(0); // call a DLL function
dll_close(dll_handle);
All exported DLL functions must be of type
DLLFUNC fixed function(...)
, while
fixed
is a
long integer interpreted by C-Script as 22.10 fixed point value. Conversion functions to/from
float and integer are available in the
a5dll.h
header. The engine structs and functions
accessible from DLL functions are described at the end of this chapter. All DLL functions can be
declared and called in scripts just like each other C-Script function, after having activated the
DLL through the
dll_open
and
dll_close
instructions that are described in the script manual.
Implementing new C-Script functions
A DLL can contain a library of new arithmetic or other functions that can be accessed by CScript. The following example implements an Ldexp function (which is already available in CScript) just for demonstration purpose:
// returns the value of x * 2
DLLFUNC fixed ldexp(fixed x,fixed n)
{
return (FLOAT2FIX(FIX2FLOAT(x)*pow(2.0,FIX2FLOAT(n))));
}
Don'tforgetthe
FLOAT2FIX()
n
- all C-Script functions expect and return fixed point numbers.
This function can be added to the set of C-Script functions by declaring it in the script:
dllfunction ldexp(x,n); // declaration of a DLL function
After having openend the DLL, the new function can be used like each other function:
x = Ldexp(y,n); // calculates x = y * 2
n
Writing to the screen buffer
The following simple example shows how to lock the screen buffer, write into it and unlock it
again. It paints the screen all white for one frame. This works in D3D as well as in 8-bit mode.
From C-Script, activate this function through declaring it, and then executing
PaintScreenWhite(0)
call it in a
DLLFUNC fixed PaintScreenWhite (long unused)
{
// retrieve the pointer to the screen buffer
FRAME_INTERFACE *a5fb = a5->fb;
// lock the screen buffer to get direct access to it
(*a5fb->Lock)();
// paint it all white; note the use of a5fb->pitch here
wait(1)
. You'll see a short white flash when you call this function once. If you
-loop, the screen will become all white.
3D Gamestudio Programmer's Manual
for (int j=0; j<a5fb->height; j++) {
byte *buffer = a5fb->bytes + j*a5fb->pitch;
for (int i=0; i<a5fb->width*a5fb->bpp; i++)
*buffer++ = 255;
}
// unlock it so that A5 can use it again
(*a5fb->Unlock)();
return 0;
}
© Conitec July 2002
6
Using Direct3D functions
The following example shows how easy it is to use Direct3D functions for creating some effects
on the screen. As all initialization is done by the engine, it is sufficient just to call the draw
functions. All Direct3D functions are accessed through a
IDirect3DDevice7
pointer that is
available through the DLL. For details refer to the DirectX documentation that is available,
along with the DirectX 7 SDK, from the Microsoft site.
The example paints a multicolored triangle onto the screen. You'll see the triangle briefly
flashing in the upper left corner when you call this function once. If you call it in a
wait(1)
loop, the triangle will be permanently on the screen. This code only works in 16- or 32-bit mode
when Direct3D is activated.
-
#include <d3d.h> // from the DIRECTX7 sdk
DLLFUNC fixed PaintD3DTriangle (long unused)
{
// get the active D3D device
FRAME_INTERFACE *a5fb = a5->fb;
IDirect3DDevice7 *pd3ddev = (IDirect3DDevice7 *) a5fb->pd3ddev;
if (!pd3ddev) return 0; // no D3D device in 8 bit mode
// define three corner vertices
D3DTLVERTEX v[3];
v[0].sx = 10.0; v[0].sy = 10.0; v[0].color = 0xFFFF0000; // the red corner
v[1].sx = 310.0; v[1].sy = 10.0; v[1].color = 0xFF0000FF; // the blue corner
v[2].sx = 10.0; v[2].sy = 310.0; v[2].color = 0xFF00FF00; // the green corner
v[0].sz = v[1].sz = v[2].sz = 0.0; // z buffer - paint over everything
v[0].rhw = v[1].rhw = v[2].rhw = 1.0; // no perspective
// begin a scene - needed before any D3D draw operations
pd3ddev->BeginScene();
// set some render and stage states (you have to set some more for more complicated operations)
pd3ddev->SetRenderState(D3DRENDERSTATE_ALPHABLENDENABLE,FALSE);
pd3ddev->SetTextureStageState(0,D3DTSS_COLORARG2,D3DTA_DIFFUSE);
pd3ddev->SetTextureStageState(0,D3DTSS_COLOROP,D3DTOP_SELECTARG2);
// now draw the triangle
pd3ddev->DrawPrimitive(D3DPT_TRIANGLEFAN,D3DFVF_TLVERTEX,(LPVOID)v,3,0);
// Normally we had to store the old render and texture states before, and
// set them back here... but the simple states above do no harm
// do not forget to do a clean close of the scene
pd3ddev->EndScene();
return 0;
}
3D Gamestudio Programmer's Manual
Particle functions
© Conitec July 2002
7
DLL functions can also be used for particles, using the
A4_PARTICLE
struct defined in a5dll.h.
They can be used the same way as C-Script defined particle functions. A pointer to the particle
is the sole argument of a DLL particle function. Example:
// examples for a particle effect function
// dllfunction DLLEffect_Explo(particle);
// dllfunction DLLPart_Alphafade(particle);
// start the particle effect by
// effect(DLLEffect_Explo,1000,my.x,nullvector);
fixed *var_time = NULL;
long func_alphafade = 0;
// helper function: fades out a particle
DLLFUNC fixed DLLPart_Alphafade(long particle)
{
if (!var_time || !particle) return 0;
A4_PARTICLE* p = (A4_PARTICLE*) particle;
p->alpha -= *var_time * 2;
if (p->alpha <= 0) p->lifespan = 0;
return 0;
}
// helper function: return a random float
float random(float max)
{
return (float)(rand()*max)/(float)RAND_MAX;
}
// particle effect: generate a blue explosion
DLLFUNC fixed DLLEffect_Explo(long particle)
{
if (!particle) return 0;
// initialize time var and alphafade function (must only be done once)
if (!var_time)
var_time = (fixed *)a5dll_getwdlobj("time");
if (!func_alphafade)
func_alphafade = a5dll_getscript("DLLPart_Alphafade");
A4_PARTICLE* p = (A4_PARTICLE*) particle;
// initialize particle parameters
p->flags |= EPF_STREAK|EPF_MOVE|ENF_FLARE|ENF_BRIGHT;
p->vel_x = FLOAT2FIX(random(10) - 5);
p->vel_y = FLOAT2FIX(random(10) - 5);
p->vel_z = FLOAT2FIX(random(10) - 5);
p->red = 0;
p->green = 0;
p->blue = INT2FIX(255);
p->alpha = FLOAT2FIX(50 + random(50));
p->function = func_alphafade;
return 0;
}
Programming a game in C++
Using the
A4_ENTITY
object (see below), a DLL can implement complex AI functions that
would be harder to code in C-Script. Even the whole gameplay could be written in a DLL. The
following example shows how to change entity parameters through a DLL function.
Loading...