• Abstract and Figures
• Public Full-text

3D Gamestudio Programmer's Manual © Conitec May 2001 1 3D GameStudio Programmer's Manual for A5 engine 5.10 Johann C. Lotter / Conitec May 2001 3D Gamestudio Programmer's Manual © Conitec May 2001 2 This manual is protected under the copyright laws of Germany and the U.S. Acknex 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 May 2001 3 Contents The A5 DLL interface.....................................................................................................4 Getting started with the SDK...............................................................................................4 Implementing new WDL functions......................................................................................5 Writing to the screen buffer.................................................................................................5 Using Direct3D functions.....................................................................................................5 Programming a game in VC++.............................................................................................6 WDL object structures.........................................................................................................7 DLL interface structures......................................................................................................9 DLL functions......................................................................................................................10 The A5 Client/Server Protocol....................................................................................12 Client Messages..................................................................................................................12 Server Messages................................................................................................................12 The MDL model format................................................................................................14 MDL file header...................................................................................................................14 MDL skin format..................................................................................................................14 MDL skin vertices...............................................................................................................15 MDL mesh triangles............................................................................................................15 MDL frames.........................................................................................................................16 MDL bones..........................................................................................................................17 3D Gamestudio Programmer's Manual © Conitec May 2001 4 The A5 DLL interface DLLs can be used as extensions to the engine and to the WDL language, as well as for programming a game in VC++ instead of WDL. The DLL interface is available on all A5 editions. For creating an A5 DLL, the SDK (source development kit) and its DLL interface library is required. SDK owners can create arbitrary DLLs for adding new effects, actor AI or WDL instructions, and distribute or sell them to other 3D GameStudio users. The Microsoft Visual C++ 6.0 development system is used for creating DLL extensions. The DLL SDK contains an interface library that must be linked to any DLL. An example VC++ project with a DLL template is also provided, which makes it easy to create extensions even for not-so-experienced C programmers who have never used DLLs before. DLL extensions work bidirectionally: WDL instructions can access DLL functions, and DLL functions can access essential engine functions and variables. 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 WDL 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. 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. Getting started with the SDK The SDK comes with a DLL ackdll.dll that contains just a few typical example functions. For testing one of those DLL functions, just copy the compiled ackdll.dll into the work folder, and insert the following WDL instructions into a function assigned to a key: dll_open("ackdll.dll"); dll_exec("PaintScreenWhite",0); // or any other DLL function dll_close(dll_handle); For creating a new DLL, just unzip the SDK into any directory and open it as a VC++ 6.0 project. The source code of ackdll.dll is included. It contains typical examples for all sorts of DLL functions. In the following, some typical DLL uses are described. All exported DLL functions must be of type DLLFUNC fixed func(long) or DLLFUNC fixed func(fixed), while fixed is a long integer interpreted by WDL as 22.10 fixed point value. The engine structs and functions accessible from DLL functions are described at the end of this chapers. All DLL functions can be accessed from WDL script through the dll_open, dll_close, dll_exec, and dll_exec_vec instructions that are described in the WDL manual. 3D Gamestudio Programmer's Manual © Conitec May 2001 5 Implementing new WDL functions A DLL can contain a library of new arithmetic or other functions that can be accessed by WDL. The following example implements an exp function (which is already available in WDL) just for demonstration purpose: // returns e power n DLLFUNC fixed Exp(fixed var) { return (FLOAT2FIX(exp(FIX2FLOAT(var)))); } After having openend the DLL, the new function can be used this way: x = dll_exec("Exp",y); // calculates x = e power y 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 WDL, activate this function through dll_exec("PaintScreenWhite",0).You'llseeashort white flash when you call this function once. If you call it in a wait(1)-loop, the screen will become all white. DLLFUNC fixed PaintScreenWhite (long unused) { // retrieve the pointer to the screen buffer FRAME_INTERFACE *a5fb = a5->fb; // lock the screen buffer to get access to it (*a5fb->Lock)(); // paint it all white; note the use of a5fb->pitch here 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; } 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. 3D Gamestudio Programmer's Manual © Conitec May 2001 6 The example paints a multicolored triangle onto the screen. From WDL, activate this function through dll_exec("PaintD3DTriangle",0).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 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);

Load more

  17

Copy Link