3D Gamestudio Programmer's Manual © Conitec July 2002 3D GameStudio Source Development Kit Programmer's Manual for A5 Engine 5.230 Johann C.
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.
D 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...................................................
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.
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.
3D Gamestudio Programmer's Manual © Conitec July 2002 6 for (int j=0; jheight; j++) { byte *buffer = a5fb->bytes + j*a5fb->pitch; for (int i=0; iwidth*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.
3D Gamestudio Programmer's Manual © Conitec July 2002 7 Particle functions 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.
3D Gamestudio Programmer's Manual © Conitec July 2002 8 // rolls the given entity by 180 degrees DLLFUNC fixed FlipUpsideDown(long entity) { if (!entity) return 0; // retrieve the pointer to the given entity A4_ENTITY *ent = (A4_ENTITY *)entity; // set the entity's roll angle to 180 degrees ent->roll = FLOAT2FIX(180); return 0; } This would be called by C-Script through FlipUpsideDown(my).
3D Gamestudio Programmer's Manual © Conitec July 2002 9 An A5_INTERFACE object named a5 is initialized on startup of each DLL and can be used for accessing the screen buffer, the Direct3D Device and the MY and YOU entity pointers. For directly accessing any C-Script object from a DLL, the a5dll.lib can be used in a way described in the following chapter. DLL functions Some functions in the a5dll.lib provide DLL access to internal C-Script variables, objects and functions.
3D Gamestudio Programmer's Manual © Conitec July 2002 10 // get the address of some script variables and functions fixed *tracemode = (fixed *)a5dll_getwdlobj("trace_mode"); wdlfunc2 vecrotate = (wdlfunc2)a5dll_getwdlfunc("vec_rotate"); wdlfunc2 trace = (wdlfunc2)a5dll_getwdlfunc("trace"); if (!tracemode || !trace || !vecrotate) return 0; fixed target[3] = { FLOAT2FIX(1000.
3D Gamestudio Programmer's Manual © Conitec July 2002 11 A4_ENTITY *a5dll_entnext(A4_ENTITY *entity); This function enumerates local entities, and can be used to access all entities in a level. If called with NULL, it returns a pointer to the first entity in the level. If called with a level entity pointer, it returns a pointer to the next level entity. If called with a pointer to the last entity or no entity at all, it returns NULL.
3D Gamestudio Programmer's Manual 12 © Conitec July 2002 The A5 Client/Server Protocol The protocol is optimized for using as less bandwidth as possible. Only parameters that have changed are sent over the network. Sending a player's changed XYZ coordinate from the server to the client, for instance, needs only 12 bytes (including header). A dead reckoning mechanism is used for extrapolating positions and angles between cycles.
3D Gamestudio Programmer's Manual Command Bytecode cls_skill 0x0e cls_skill3 0x0f 13 © Conitec July 2002 Arguments Description Long Entity_DPID Short Struct_Offset Fixed Skill Send Long Entity_DPID Short Struct_Offset Fixed Skill[3] Send an entity vector skill (TCP). an entity skill (TCP). Struct_Offset gives the byte offset of the skill in the A4_ENTITY struct.
3D Gamestudio Programmer's Manual Command svc_update3 Bytecode 14 © Conitec July 2002 Arguments 0xc0..0xff Short Entity_Index (Parameters see below) Description Update entity parameters 3 (UDP). For the 3 entity parameter update messages, bits 0..5 of the svc_update bytecode give the parameter combination to be sent or received, in the order given below. All parameters are sent through the UDP protocol. Parameter Update.Bit Arguments Remarks position 1.0 CPosition Pos[3] pan 1.
3D Gamestudio Programmer's Manual © Conitec July 2002 15 The MDL5 model format Despite the engine uses model files with .MDL extension, it's internal MDL5 format differs from the Quake .MDL format. A wireframe mesh, made of triangles, gives the general shape of a model. 3D vertices define the position of triangles. For each triangle in the wireframe, there will be a corresponding triangle cut from the skin picture.
3D Gamestudio Programmer's Manual © Conitec July 2002 16 MDL skin format The model skins are flat pictures that represent the texture that should be applied on the model. There can be more than one skin. You will find the first skin just after the model header, at offset baseskin = 0x54. There are numskins skins to read. Each of these model skins is either in 8-bit palettized (type == 0), in 16-bit 565 format (type == 2) or 16-bit 4444 format (type == 3).
3D Gamestudio Programmer's Manual © Conitec July 2002 17 u and v are the pixel position on the skin picture. The skin vertices are stored in a list, that is stored at offset basestverts = baseskin + skinsize. skinsize is the sum of the size of all skin pictures. If they are all 8-bit skins, then skinsize = (4 + skinwidth * skinheight) * numskins. If they are 16-bit skins without mipmaps, then skinsize = (4 + skinwidth * skinheight * 2) * numskins.
3D Gamestudio Programmer's Manual © Conitec July 2002 18 The lightnormalindex field is an index to the actual vertex normal vector. This vector is the average of the normal vectors of all the faces that contain this vertex. The normal is necessary to calculate the Gouraud shading of the faces, but actually a crude estimation of the actual vertex normal is sufficient. That's why, to save space and to reduce the number of computations needed, it has been chosen to approximate each vertex normal.
3D Gamestudio Programmer's Manual © Conitec July 2002 19 typedef struct { long type; // 0 for byte-packed positions, and 2 for word-packed positions mdl_trivertx_t bboxmin,bboxmax; // bounding box of the frame char name[16]; // name of frame, used for animation mdl_trivertx_t vertex[numverts]; // array of vertices, either byte or short packed } mdl_frame_t; The size of each frame is sizeframe = 20 + (numverts+2) * sizeof(mdl_trivertx_t), while mdl_trivertx_t is either mdl_trivertxb_t or mdl_trivertxs_t,
3D Gamestudio Programmer's Manual © Conitec July 2002 20 The HMP5 terrain format A terrain is basically a rectangular mesh of height values with one or several surface textures. It is a simplified version of the GameStudio Model format, without all the data structures that are unnecessary for terrain. HMP file header Once the file header is read, all the other terrain parts can be found just by calculating their position in the file. Here is the format of the .
3D Gamestudio Programmer's Manual word skin1[skinwidth/2*skinheight/2]; word skin2[skinwidth/4*skinheight/4]; word skin3[skinwidth/8*skinheight/8]; } mdl5_skin_t; © Conitec July 2002 21 // the 1st mipmap (if any) // the 2nd mipmap (if any) // the 3rd mipmap (if any) The 565 and 4444 pixel formats are described in the mdl format description. HMP height values A terrain contains a set of animation frames, which each is a set of height values.
