This document contains all information about scripting in the PteroEngine for the games Vietcong and Vietcong Fist Alpha you need for creating your own scripts.

But first, be warned: pteroscripts are based on the standard ANSI C language. They essentialy ARE the ANSI C with the big library exported from the game engine used for the controlling of the game behavior. I won’t teach you here how to do standard C codes – if you never did this before, go buy some book about standard C syntax, or download some tutorial from the web – there should be no problem at finding something like this, as C and it’s more advanced version C++ are used everywhere and almost for everything.

You won’t need any hi-tech coder skills, just basic knowledge about C syntax and coding and some text editor. Everything else is described in this document or included in the Vietcong.

NOTE:

This beta version of the SDK contains information about multiplayer scripting ONLY – and only about non cooperative modes (MP modes without AI characters). Next version of this SDK will also contain information about using the AI and single player specific functions. Check http://www.pterodon.com for new updates.

If you have any questions or problems, post them at our forum, or send me a mail at shigor@volny.cz.

BASICS OF THE SCRIPTS

What are the scripts?

Scripts are used to modify and control most of the aspects of the game. They are written in a C like code, which is then compiled and interpreted by the game engine.

Execution of the scripts

Game engine executes the scripts according their type and the situation, which can be initialization of the scene, it’s release, at various callback functions (for example when the speech playing is finished or when the dynamic object was hit) and periodically at the time specified (level and player scripts) or at each frame rendering (dynamic objects scripts). For the exact specification see the detailed description of given type of the script.

Types of the scripts

There are several types of the script. Every script MUST contain the int ScriptMain() function. Exact parameters for the every type of the script is specified at the detailed description of the script type.

NOTE: this version of the SDK contains information only about level script, dynamic object script, sound script and multiplayer script. All other including player scripts will be discussed in the next version.

Most important script (well, it’s arguable ;o) is the Level Script. It’s called at the initialization and release of the scene, at the time specified and during the various callbacks. It also defines a lot of things for other entities, like player sides and groups etc. The level script is usually used to coordinate game during the whole level. Think about it as a master script controlling all others :o). Every game scene MUST have a level script else it won’t be executed (unless you specifically disabled execution of the level script in the settings dialog (CTRL+E)). For detailed description see here.

Dynamic object script is the script for anything physical that moves, can be clicked upon, players can ride in etc. Somewhat specific types of the dynamic object scripts are car scripts, ship scripts and helicopter scripts. For detailed description see here.

Sound script is called just once – after the execution of the level and it is used to set various sound stuff like setting the ambient sounds etc – it’s for the comfort of the sound and script designers, so the sound designer can change the sound stuff without bothering the script writer. For detailed description see here.

Multiplayer script is used to coordinate the multiplayer games, it has code for both the server and the client. For detailed description see here.

Coordination of the scripts and communication between them

Every object and player has it’s own script, so there’s a need to communicate between them. Most common way to do so is the use of the game global variables. Level script and player’s script can receive message using the specialized functions.

Adding the scripts to the game

Level and sound scripts are added automatically – they just need to be in the correct place, which is the scripts directory for the current level (so the path to the scripts is something like levels/stream/data/stream/scripts).

The multiplayer scripts are usually placed in the ini/multiplayer/scripts directory, but they can be anywhere, as the path to the script is defined in the map definition file. For the custom made games, the multiplayer script MUST be placed in the scripts directory for the current level.

Object scripts can either have their scripts at the same place where the .bes file containing the object exists (the .c file must have same name as the object, for example if there’s an object called box.bes in one directory and there’s also a file called box.c, it will be loaded automatically), or there is a possibility to assign any object script to any object in the level.c during the initialization of the scene using the SC_SetObjectScript function. This is usually used for the objects which need specific scripts for the specific levels, like helicopter script. In this case the script can be located anywhere, you just have to assign correct path to it.

Writing your own scripts

You can use any text editor you like for the writing of the scripts, including the windows notepad.exe, but I recommend you use some editor with programming features, like showing the source code using the C color convention or editor designed especially for the C programming, like very good editor included in Microsoft Visual Studio. Very good choice is shareware editor called Ultraedit (available at the http://www.ultraedit.com). The source code in the file .c is compiled to the .scr file, which is then used by the game, so every time you finish the writing or modifying of the script you should try to compile it first before trying it in the game – having uncompilable scripts in the game scene may cause crashes. Ultraedit and other similar programs allows the definition of the tool for compiling, so it’s good idea set the compiler as one of these tools.

Include files and headers

For this version of the SDK there is only one standard include file – sc_MPglobal.h in the dev/compiler/inc directory. It contains exported functions, definition and structures from the engine to the script for normal scripts. DO NOT ALTER THIS FILE!

You can use the header or include files as much as you wish to. It is often useful and efficient way to do the scripts – prepare some libraries or standard include files and then just change some parameters for them. For example if you have 30 Vietnamese superkillers in the level, create include file called vcsuperkiller.inc and place all the code there. Then include it in every script for each killer and just change some parameters. So the superkiller11.c will look just like this:

#define MEMBERID 11

#define GROUP 0

#define WEAPON 2

#include “vcsuperkiller.inc”

You will save a lot of time when the need to change something in the vcsuperkillers behavior arises. You’ll just change the include file and all is done. Comparing to manually rewriting every of 30 scripts just because you decided the VC shouldn’t be so precise with their guns it’s lightning fast.

Using the script compiler

The script compiler is located at the DEV/COMPILER directory of the Vietcong. It consist of four programs – scmp.exe, spp.exe, scc.exe and sasm.exe. You can compile any script by executing the scmp.exe with three parameters: name of your script, name for the compiled script and name for the header file. I am using simple .bat file for the test compilings called the compile.bat:

"scmp" "%1" "test.scr" "test.h"

if exist spp.err uedit32 spp.err

if exist scc.err uedit32 scc.err

if exist sasm.err uedit32 sasm.err

Batch file calls the compiler and tells him to save the finished script in the test.scr (as I don’t need the compiled script file yet, I just need to try if it’s compilable). Compiling process is the same as with any standard C compiler. SCMP calls the preprocessor spp.exe, which prepares the .c for the actual compiler scc. SCC produces the assembler like code, which is then compiled into the .SCR file readable by pteroengine script system. If any of those three programs encounter an error, it creates error file and batch file automatically opens it in my favorite editor, so I can see where I missed the semicolon or forget the correct syntax for some function.

There can be only one running instance of the compiler at one time, as the programs are transmiting data between themselves using the temporary files in this directory. So executing a compiler while it already runs (either when the game compiles the scripts before running the game level, or if the compiler wasn’t yet finished with compiling of the previous scripts) will probably made the compiler report error.

Everytime this happens, press the ctrl+alt+delete and look at the running processes – if there’s any scmp.exe or any other compiler file running, kill it. The delete any temporary files in the compiler directory, leaving just the .exe files and any files you added there personally. Then try to compile the file again.

Script compiler creates a .scr file, which contains a compiled script, a .cmp file used to store information about source files (so the game won’t compile all scripts every time the level is executed unless the source files changed).

Using the ingame debugger

Pteroengine contains simple yet helpful ingame script debugger. Once the level is executed, any time you press the CTRL+F12, you will pause the game and open the list of all runing scripts. Use the cursor keys to select the script you want to look into and press enter. The debugger will then open the selected .c file. In the left window you’ll see the source code, in the right window you can define variables to watch. Switching between the windows is done by pressing the TAB.

Source code window

You can add the breakpoints at any place by just left click of the mouse, or by positioning the current line with cursor keys and pressing the SPACE. When you’ll exit the debugger by pressing the ESC key, the debugger will pop up once the script will reach the breakpoint. Pressing the enter key will open the list of all source files included in the script – headers and includes, so you can switch to other part of the code. For other possibilities of the debugger press F1 – you’ll get short online help.

Variables window

By pressing the enter you can change or add the name of the variable – you cannot enter the array members or variables inside the structure here – just the master variable. You can then use INS and DEL key to expand the data structure. Pressing F4 will give you a chance to change the value of the variable. Press F1 to show the help for other functions. The value of the variables will be shown only if the debugger was popped up by a breakpoint!

Debugger creates a .sdb file in the directory of the running script which contains debug information – placement of the breakpoints etc. If the debugger starts to behave weirdly, try to delete all sdb files in the current directory, it should help.

Multiplayer map definition

For the custom made missions the definition is done via the MP game editor.

Description of the multiplayer scripts is here.

Game global variables

Global variables are stored in the array with the size of 4096. Each variable is long four bytes and they can be accessed either as a double word or a float number. These variables are same for all the scripts and they are used for the cooperation of scripts and also for storing various information about the game and especially about the campaign. Variables accessed directly by the engine are defined in the sc_MPglobal.h file:

SGI_DIFFICULTY (value 10) contains the game difficulty set in the game.

Other global variables are used for the storing info for the debriefing, etc. All used global variables should be defined in the sc_def.h with the naming convection SGI_variable for the integer/dword variable and SGF_variable for the float variables. For the set of functions working with the global variables see here.

Note: global variables are also used to coordinate the game in the multiplayer game. SC_MP_Gvar_SetSynchro function is used to set which global variables are synchronized – everytime the synchronized global variable changes on one machine, it changes on all machines.

Game texts

Game texts are stored in the directory ini/txt in the directory of the language (ame for the US version). Text file contains #text_id_number: and #ame text. (#ame is the identifier for the language). Texts are from the range of 0-9999 (for the original Vietcong) and from the 50000-59999 (for the Fist Alpha) . As most of them are already used, you must be careful to not use the already used ID! Best way is to use the editor function texts/log space which will log the empty places to the text files.

The Level Script

Overview

Most important things first. Every level MUST have level script level.c located in it’s data/scripts directory. It can be almost clean, but there should be at least few things prepared, like the initialization of the game sides and groups. The level.c must contain function int ScriptMain(s_SC_L_info *info). s_SC_L_info is described here. Pure level.c can be found in the SDK directory scripts/level scripts/pure_level.c. Level script is usually used for the coordination of other scripts, it is also the script controlling the flow of the game. Lot of special callbacks are directed to the level script, as the finishing of the speech, usage of the radio, pointman handling etc.

Good idea is to use the gphase variable storing the actual phase of the level and at every change change also the global variable SGI_LEVELPHASE, for example with the macro like this:

#define SetLevelPhase(newphase)\

{gphase=newphase; SC_sgi(SGI_LEVELPHASE,newphase);\

SC_Log(3,"Levelphase changed to %d",newphase);\

SC_Osi("Levelphase changed to %d",newphase);}

Other scripts can access this value and they can find out in what stage the game is. Level phase at 0 means the level script still hadn’t time to organize itself. 1 means the level made basic initializations and is waiting for the next time tick, change to 2 or higher should happen only when was finished the initialization of other scripts and some values (like setting the AI) were changed.

The level script can be called by the engine in these situations (NOTE: single player callback are removed from this version of the document): scene initialization, scene release, timetick, view animation callback, event (ie some other script sent message to the level.c), artillery usage. The information about the type of the callback is defined in the message variable in the info structure.

Level script should return 1 if it handled the message or 0 if it didn’t.

For more information about the level scripts for the multiplayer missions see here.

Level script messages

The information about the message is defined in the info structure passed to the function ScriptMain. NOTE: this version of document contains information only about generic or MP related callbacks.

SC_LEV_MES_ INITSCENE - Scene initialization

This is the first call the level script gets at the start of the scene, either with new game or after the load. No other script is initialized yet, keep that in mind! This callback is designed for these functions: SC_SetObjectScript (forcing script for the object), SC_PreloadBES (preloading bes objects for the equipments, see adding special equipment to players), SC_PreloadWeapon (preloading weapons for the faster initialization) and SC_PreloadSound (preloading sounds). You can also store the initial values of certain objects, but it’s better to do so in the object script.

SC_LEV_MES_RELEASE SCENE - Scene Release

This is the call to the level script at the release of the scene – closing engine, loading another mission etc. Just in case you need to move some object back. Again, it’s better to do so in the object script.

SC_LEV_MES_TIME – Time Tick

This is the most important callback to the level script. It is called after the initialization of the script in zero time and then always in the time the script will specify in the parameter info->next_exe_time. Script also sets the time from the last call in the info->elapsed_time, as the timing is not 100 percent complete.

In the absolutely first time tick you should set some basic things, you must especially initialize the sides and groups. Also it is good idea to prepare the follow order for the teams, set the global variables, set on or off the artillery support etc. Then you should wait at least one second (usually it’s good idea to black the screen with the SC_FadeTo), check if the players are already created and then do some changes in the setting of the AI (if it wasn’t already done in the player scripts). Then the script “just” controls the flow of the game.

NOTE: for level script for MP usually only prepares the scene and creates sides and groups for the players.

SC_LEV_MES_VIEWANIMCALLBACK - View Animation finished

This callback is initiated when the view animation ends and it is used mostly for the creating of the cutscenes. The id number of the callback is stored in the info->param1.

SC_LEV_MES_EVENT - Message Sent by Other Script

Every time some script sends message to the script using the SC_LevScr_Event function, the message will be received in this callback. Messages are stored in the info->param1 and the info->param2 variables.

SC_LEV_MES_ARTILLERY - Artillery Usage

This message is invoked when player marks the artillery place for the bombardment (can be used to reduce number of possible attempts for example). The centre of the bombardment is in the variable info->param4.

Initialization of the game sides and groups

The Vietcong needs to have the sides and groups correctly set. Forgetting to set the groups and sides can even cause the game to crash!

Side 0 is used for the US, 1 for the Vietcong.

Sides are initialized with SC_InitSide function. Sides 0 and 1 are enemies by default. If you will work with additional sides, you can set their status by the SC_SetSideAlly function.

Groups are smaller groups of the players. Usually the group 0 0 (ie side 0, group 0) is used for the player and his team. Definition of the group can be done with the SC_InitSideGroup function.

Definition of the sides and groups should be done in the first time tick of the level script, later it’s usually too late as the players are already being created. Be especially careful when adding new groups later – be sure to have enough groups for the side specified! (Adding more groups than the side can have can cause the game to crash).

The Dynamic Object Script

Overview

Dynamic objects are everything which can be used, burned, destroyed, moved etc in the game except the players and the animals. Dynamic object must be created, exported and marked as such, unless you risk the crash of the game if you try to work with nondynamic object. Usage of the dynamic objects is slowing the game down, so keep their number low.

Scripts can be added to the object with two possible ways:

A) The directory with the object file (.bes) contains script with the same name as the object, in this case will be the script loaded automatically. When changing the script with the game engine running, don’t forget to reload these scripts with the reload wizard!

B) By forcing the script to the specific object in the scene initialization call to the level script with function SC_SetObjectScript – object will always use this specified script instead the existed one.

The information about the callback is stored in the s_SC_OBJ_info structure. Variable info->event_type contains the type of the message. The dynamic object script can be called in these situations: object is initializing, object is being released, the game was just loaded, time tick, object was hit, object was used.

NOTE: For MP mode the dynamic objects and their scripts are used only for “usable” objects – like ammo box, bomb place etc. Using dynamic objects for anything else (moving, destructions, etc) may produce unexpected results! Every change must be synchronized on all client machines by hand!

Script messages

SC_OBJ_INFO_EVENT_INIT – object initializing

This message is passed to the script during the initialization of the object. It can be used to store some initial values like current transformation of the object and for the initial settings.

SC_OBJ_INFO_EVENT_RELEASE – object releasing

This message is passed to the script during the scene release. The script should return the object to it’s initial place if it was moved through the script and release any data it created like object animations etc.

SC_OBJ_INFO_EVENT_JUSTLOADED – saved game loaded

NOTE: this messsage is valid only for the single player mode.

SC_OBJ_INFO_EVENT_DOTICK – time tick

This message is passed to the script each frame. Info->time contains time from the last execution. Time tick can be used for lot of things like animating or moving the object. If you want the “usable” object, you should use the SC_ACTIVE_Add function, which will add the interaction text for this object. For more information about using the object see here.

SC_OBJ_INFO_EVENT_HIT – object hit

When the object will be hit by shot or the explosion, this message will be sent to the object script. info->hit_by contains information what caused the damage (it can be missile = normal shot, human PC shot or the explosion), info-> new_hp_obtained contains information about the overall damage the object has taken. Hiding or destroying the object usually happens in this callback.

SC_OBJ_INFO_EVENT_USED – object used

If the object was enabled for the using with SC_ACTIVE_Add function and the player pressed the USE key, this message will be passed to the script. For more information about usable objects see here.

Moving the object

If you want to move some object, there are few possible ways to do so:

A) Physical objects - if it is dynamic object with the physics, it will fall/move by itself. You can just freeze it in the space and unfreeze it when you need the stone to fall etc. Freezing can be done with the SC_DOBJ_SetFrozenFlag function. Alternatively you can add the dynamics (speed, rotation) manually using the SC_NOD_AddDynamic function.

B) Manual movement – you can manually change the transformation of specified nod with the SC_NOD_SetTransform function. In this case you should remember to store the initial value of the object in the initialization and than move it to it’s correct place during the release and after the loading the game! You can move, rotate or scale object using the transformation.

C) Using the camera animation – camera animations can be used not just for the movement of the view, but also for any other object. This can be done using the SC_NOD_SetFromANM function. See more in the description of the helicopter scripts. In this case you should store the original transformation of the object during the initialization and during the release/after load set the correct position, see B) manual movement.

NOTE: for MP mode you must synchronize this movement on all client machines!

Hiding the object

If you don’t want the object to be visible in the level (for example it will be there after something happens, like destroying some other object), you can do it two possible ways:

A) hiding the object, so it won’t be rendered, can be used for any object as a way to fasten the game, this can be done with the SC_DUMMY_Set_DoNotRenHier or SC_DUMMY_Set_DoNotRenHier2 functions. Information about the rendering are not stored in the saved game, so you must always handle this way in the SC_OBJ_INFO_JUSTLOADED. Also keep in mind that the object is still physically there, it just won’t be rendered, so if it has collisions, the player could bump into it!

B) Setting the destroyed variant of the dynamic object to zero. It will disappear completely.

C) Hiding the object under the scene – use SC_NOD_GetTransform to get the current transformation of the object. Substract 1000 from the z coordinate of the position and then set the transformation back with the SC_NOD_SetTransform.

Do not forget to handle the hiding in the initialization, release and after loaded callbacks of the script!

NOTE: for MP mode you must synchronize this on all client machines!

Destroying the object

Destroying of the object can be done by few different ways. You can use particles to mask the destruction, then just hide the object and then maybe move some other on it’s place, but the “clear way” to do so is create the object with the destroyed variants. These variants are linked to their master object and they are named with the “&” sign at the beginning. These objects are not used or rendered until you change the destruction properties of the master object with the SC_NOD_SetDSTR function. You can also switch the destruction object to zero, it will disappear completely. Reset to the first variant can be done with the SC_NOD_ResetDSTR function.

Do not forget to handle the destruction setting in the after load callback for the single player mode!

Using the object

If you want usable object, ie object player can point the cursor at and then use it pressing the USE key, you must add the object to the interaction texts buffer with function SC_ACTIVE_Add. Object closest to the player will write it’s interaction text to the screen and will be called after player presses the USE key. If the player is currently looking at the object can be found out using the SC_DOBJ_CameraLooksAt or SC_DOBJ_CameraLooksAtCollision functions. Warning! The nod specified in the SC_DOBJ_CameraLooksAt MUST be dynamic NOD!

The Sound Script

The sound script is used for the setting of some of the sound data – usually for the setting of the ambient sound (SC_SND_Ambient_Play) and creating of the curve sounds (SC_SND_CreateCurveSound) for the sounds of the rivers and streams. It has only one message (SC_SOUND_MESSAGE_INIT) and is called only once at the beginning of the level. Sound script must be names sound.c and placed in the level directory data/Levelname/scripts. Information to the ScriptMain are stored in the structure s_SC_SOUND_info;

The Multiplayer Script

Overview

Multilplayer script is the heart of the multilplayer game – it defines and controls game rules, player respawning, it shows the icons and text information etc. Multiplayer script is running on each computer, but it contains server specific and client specific callbacks. Server specific callbacks including the time tick are used ONLY on the server machine. Client messages are used on ALL machines including the server.

Callbacks are used at – level preinitialization, level initialization, for the HUD rendering, for server and client timetick, map restart, changing of the rules, for the user message sent from the other script and for the server only messages about player killed, player requesting recover time and recover place.

Multiplayer scripts are usually placed in the directory ini/multiplayer/scripts as they are shared for various levels (each script is another type of the game), but they can be placed anywhere. For the custom made games the MP script must be placed in the scripts subdirectory of the level – ie levels/myscene/data/mymission/scripts/.

Multiplayer script messages

The information about the message and it’s parameters are stored in the info structure.

SC_NET_MES_LEVELINIT

This message is passed to the script every time the level initializes. Param1 can be either TRUE (this is the server script) or FALSE (this is the client script). Param2 is TRUE if this is first time init, FALSE if this is subsequent reinitialization (after the mission was restarted). This callback is used to set few basic settings, like which sides can be chosed by players with SC_MP_SRV_SetForceSide and SC_MP_SetChooseValidSides functions, for setting class limits with SC_MP_SRV_SetClassLimit function, for setting up the HUD (heads up display) with SC_MP_HUD_SetTabInfo function, and for various preloads and other script initialization.

SC_NET_MES_RENDERHUD

This message is passed to the script every frame rendered and can be used to write to the HUD. If the param1 is TRUE, this is the script running on the dedicated server. This is usually used for writing simple text messages to the screen using SC_Fnt_WriteW function.

SC_NET_MES_SERVER_TICK

This is the time tick for the server script. It’s the heart of the multiplayer script – this is the place where the script controls the game, adds points, guards the time etc.

SC_NET_MES_CLIENT_TICK

This is the time tick for the client script. It is called on each machine in the game including the server machine! It can be used to change the values of the HUD, playing sound effects, making some changes which are not shared automatically for all clients like gfx changing (hiding/showing flags for example), adding flags to player equipment etc.

SC_NET_MES_SERVER_RECOVER_TIME

This is the request from the engine to the script to fill the fval1 with the recover time for the player with the pointer stored in the param1. For special cases you can use the SC_NET_SERVER_RECTIME_NEVER value (never recover the player) or SC_NET_SERVER_RECTIME_ENDOFROUND (recover at the end of the round). Param2 contains the information about the type of the recover, if 0 the player was just killed, if 1 the player just entered the game. Each human player sends this message after he is killed or he just joined the game.

SC_NET_MES_SERVER_RECOVER_PLACE

This is the request from the engine for the recover place of the player specified by pointer in the param3. Param1 contains the side which will be used for the player after the recover. Recover place is filled to the param2 as a pointer to the structure s_SC_MP_Recover *. There is a simple function to help with this task -SC_MP_SRV_GetBestDMrecov.

SC_NET_MES_SERVER_KILL

This is the information to the server script about death of player specified in the param1, param2 contains pointer to the player who made the kill. It can be used for scoring the points, or for example for dropping the flag to the ground.

SC_NET_MES_MESSAGE

This is the message to the network script from other script using the SC_MP_ScriptMessage function. Param1 and param2 contains the specified parameters. This message is used ONLY on the client machine which used the SC_MP_ScriptMessage!

SC_NET_MES_LEVELPREINIT

This is the level preinitialization message (the level was not loaded yet). Param1 contains the type of the end rule, param2 the end value. This message is invoked even before the level starts loading. It is usually used to set the type of the mission into the global variable, so level script can set some things (like hiding unused flags etc) after it’s own initialization. This message is also used to enable or disable AI characters placed in the scene for cooperative modes of the game with the SC_MP_EnableBotsFromScene function.

End rule type can be:

SC_MP_ENDRULE_TIME – mission should end after the specified time.

SC_MP_ENDRULE_POINTS – mission should end after one side has specified points.

SC_NET_MES_RESTARTMAP

This means the map will be restarted, used to clear statistics, end rules and for recovering the players.

SC_NET_MES_RULESCHANGED

This is the message about changing of the rules. Param1 contains the type of the end rule, param2 the end value.

End rule type can be:

SC_MP_ENDRULE_TIME – mission should end after the specified time.

SC_MP_ENDRULE_POINTS – mission should end after one side has specified points.

Handling various situations and scripts

This chapter shows various ways how to work with game elements.

Working with the particles

Particles are sprite effects used for the fire, shot effects, water, smoke and so on. Sometimes you will need to use the particles manually, for example for showing the smoke over the destroyed car etc. ID number of the particles can be found in the game engine in the particle editor. Manual using of the ptc in the script can be done with the SC_CreatePtc, SC_CreatePtc_Ext (which allows to change some particle parameters), SC_CreatePtcVec_Ext (same as previous, only in the space, not in some object) and SC_CreatePtcInNodSpace_Ext (this will create the particle in the space of the specified object, useful for moving stuff like jet fighters).

Working with the sound

Most of the ingame sounds should be placed in the editor as events, but sometime you will need to play the sounds directly from the script.

There are two types of the sound – 2D and 3D.

2D sounds will be just played to the speakers, these can also be stereo. Use the SC_SND_PlaySound2D for playing 2D sounds.

3D sounds are player from some place, so you will hear them differently from different places. Use SC_SND_PlaySound3D (normal 3d sound), SC_SND_PlaySound3Dex (sound with timeout, will play after specified time), SC_SND_PlaySound3Dlink (will play sound linked to some moving object). You can also use the SC_SND_PlaySound3DSpec, SC_SND_PlaySound3DexSpec or SC_SND_PlaySound2DSpec if you want to use different sound players (there are few sound players in the game, specific for the game, nature, music etc.. sometimes you will need to play the sounds in other volume than all other sounds, normal sound functions plays this sound in the game sound player).

For the changing of volume of various sound players use the SC_FadeSoundPlayer function.

You can also manually change overall sound settings (usually done in the sound script).

Working with the players

How to get information about the players

Player can be identified by two ways: by pointer to it’s object, which is stored in the dword variable. Most of the functions deal with this pointer, also the player script is passed this pointer. For the human player you can use the SC_PC_Get(), which will return the pointer to the human PC - the one playing on the machine which executed the script.

The other way is to use the identifier side/group/memberid, which should be unique for each player (by convention side 0 is US, 1 Vietcong, group 0/0 is the PC’s team, the human PC himself is 0/0/0). You can use the SC_P_GetBySideGroupMember to acquire dword pointer to the specified player. In the multiplayer all PC’s have identifier 255, group 0 and side 0 or 1.

If you want to get the information about the side from the pointer, you must use the SC_P_GetInfo. This function will fill the data structure containing the player’s identifiers, and his health.

There is a set of function designed to get information about the position of the players and other various information. Most simple function is SC_P_GetPos (or it’s special version valid only for the human PC – SC_PC_GetPos), which will return the position in the 3d space, where the legs of the AI touch the ground. SC_P_GetHeadPos can be used to get exact position of the players head (for the headshots :o), SC_P_GetRot will return the rotation of the player around the z axis. SC_P_GetDir will return the information about player “speed” – how he moves in axis, this can be used to get information if the player is stationary, or if he is moving, like in this function:

BOOL P_IsMoving(dword pl_id){

c_Vector3 pos;

float len;

SC_P_GetDir(pl_id,&pos);

len = SC_VectorLen(&pos);

if (len>1.0f) return TRUE;

return FALSE;

}

One simple way to acquire information about the player’s position is to use the SC_P_GetDistance, this function will return the distance between two specified players.

Changing of the players stance can be done by force also with SC_P_SetPhase, usually used for the cutscenes or forcing the human PC to change the stance. For the AI it’s better to use AI functions to change the stance, SC_P_Ai_SetMovePos.

Adding special equipment to players

If you want the player to have some special equipment for a time during the game (like axe, which will be hided after the player gets to the fight, you can use SC_P_Link3pvEqp and SC_P_UnLink3pvEqp functions. Specified bes file must be preloaded during the initialization of the scene in the level script like this:

SC_PreloadBES(1, "g\\weapons\\Vvh_Knife\\VvH_Knife_fpv.bes")

Creating Multiplayer missions

There are few sources of the scripts available in the SDK in the directory scripts/MP scripts. Be sure to check them and look more closely at how it is done.

Level Script for the MP missions

Level script for the MP missions are quite simple – they just need to handle few basic functions, most of the game is handled in the multiplayer script. Level script should initialize the game sides and also hide unnecessery GFX and initialize dynamic object scripts – most of the missions contain all flags, ammo crates etc for all modes, so you need to disable parts of the GFX you don’t need according to the mission type. Mission type is specified in the global variable GVAR_MP_MISSIONTYPE (it is set in preinit callback of the MP script.

Sample level script can be found in the SDK directory scripts/MP scripts/level.c.

You can also use the include file dev/compiler/include/mplevel.inc – see dev/compiler/default/level.c to see how to use it.

Multiplayer script

Only server machine gets the server messages, but it also gets the client messages, do not forget about it. Variables used in the server part of the script do NOT contain proper values for the client ticks, you must always synchronize them.

Multiplayer script – messages for both server and client machines

These messages are sent on both client and server machines.

SC_NET_MES_LEVELPREINIT

In this callback you should set basic global variables, especially game type to GVAR_MP_MISSIONTYPE, and enable or disable AI characters with SC_MP_EnableBotsFromScene. You should also store the end rule and it’s value here to some variable, as they are parsed as messages in this callback. This message is invoked as first, even before loading the level.

SC_NET_MES_LEVELINIT

This is the actual level initialization. Parameters specify if this is the server initialization and if it is first time init or if the mission was restarted. You should set some basic settings here, like class limit with SC_MP_SRV_SetClassLimit, valid sides with SC_MP_SetChooseValidSides and TAB info settings with SC_MP_HUD_SetTabInfo function.

For the first time init you should preload items (like items 145 and 146 – flags) with SC_Item_Preload. You should also get the position of the flags from the scene here.

Server should also get the recover places (simplest done with SC_NET_FillRecover).

SC_NET_MES_RESTARTMAP

This callback means the map was restarted – it should be used to clear statistics of the players etc.

SC_NET_MES_RULESCHANGED

This callback just sets the new end rules – store the values from the parameter.

SC_NET_MES_MESSAGE

This callback means some other script running on the same machine used the SC_MP_ScriptMessage function. This is used by the dynamic object scripts to inform the script about their usage, or by AI player scripts. Warning, this information is ALWAYS sent only to the one machine! This callback can be used to synchronize information about the event with all other clients a server via global variables.

SC_NET_MES_RENDERHUD

This message is used on all computers in the game everytime the engine renders a frame – it can be used to write some additional information on the screen.

SC_NET_MES_CLIENT_TICK

This is the time tick for the client. For a lot of game modes it can be void, usually it is used only for showing additional information like showing the icons with time etc. For the CTF mode it is also used to change equipment for the players carrying the flag – this is one of the things which are not synchronized automatically. Other possibilites for the client script is handling the dynamic objects (like hiding or showing specific things).

Multiplayer script – server messages

These messages are sent ONLY to the server machine.

SC_NET_MES_SERVER_RECOVER_TIME

This is the request of the player for the recover time – how long it will have to wait before recovering itself. You can just simply set him some fixed value, but most modes use spawning of whole teams at once, so you may need to use some timers to get thing right. Do not forget that this message is used both when player is killed and when he joins the game for the first time!

SC_NET_MES_SERVER_RECOVER_PLACE

This message means player is trying to recover and it is asking where exactly it should recover. Server script must have prepared places for the recover and send him one suitable. You can use the SC_MP_SRV_GetBestDMrecov function for easy choosing of suitable place.

SC_NET_MES_SERVER_KILL

This mesage is sent to the server anytime someone dies. It can be used for counting the points for team games, or in the CTF mode for dropping the flag out of the player.

SC_NET_MES_SERVER_TICK

This is the most important part of the server script – it handles the rules of the game type, for example the end rules. What exactly is in this part of the script depends on the type of the game. For the deathmatch is just guarding of the end rule. For CTF it’s much more complicated as the game itself can be in two states (waiting for more players and actual game), script must check if someone takes or places the flag, synchronize this information with clients etc. See example scripts.

Dynamic objects in the MP

There are few uses for the dynamic objects in the multiplayer – ammo crates, bomb places, actually anything you want. Actual adding of the dynamic object must be done in the initscene callback of level script. Every computer in the game has it’s own script running, so you must synchronize the results if it is for example the bomb place.

Most of the missions in the Vietcong contain the ammo crate – this is very simple script which will only add the crate as a clickable object for the player playing on his machine. If player uses the box, it will give him the ammunition with SC_P_AddAmmoNoGrenade(SC_PC_Get());

This is standard script is located in the ini/multiplayer/scripts/ and is called addammo_dobj.c – it can be assigned to any dynamic object.

For the ATG modes with bombing there is a script ini/multiplayer/scripts/atg_dobj.c which works essentially the same – it allows the object to be used and shows the interaction text according to the side of the player (if he is VC or US) and if the bomb is already placed, or can be placed. If player uses the object, DOBJ script will send a message to the MP script with SC_MP_ScriptMessage – MP script will then set the synchronized global variables for all clients informing them about the change.

WARNING: using dynamic objects in MP for anything else than simple clicklable object may cause unexpected results!

Using AI in the MP

This part will be discussed in the next version of the Vietcong script SDK.

Description of all types, structures and functions in the Vietcong

Structures – for various 3d data

c_Vector3 – 3D information data

Declaration:

typedef struct {

float x,y,z;

}c_Vector3;

c_Vector3 is basic structure used for storing information about 3d position.

s_sphere – 3D sphere data

Declaration:

typedef struct{

c_Vector3 pos;

float rad;

}s_sphere;

Structure s_sphere is structure used for storing the information about the sphere placed in the game – it’s position and radius.

Structures – script info structures

Structure s_SC_L_info – level script

Declaration:

typedef struct{

dword message,param1,param2,param3;

float elapsed_time;

float next_exe_time;

c_Vector3 param4;

}s_SC_L_info;

This structure is used for storing the information sent to the level script. Message contains the information about what callback is sent, param1 – param3 contain specific parameters, param4 is used for the artillery callback. elapsed_time is the time from the last time execution of the script, next_exe_time is used to specify the time when the time tick of the script should be executed again.

Type of the messages:

SC_LEV_MES_TIME

The time tick. Parameters are not used

SC_LEV_MES_RADIOUSED

Radio was used, param1 contains id of the radio set in SC_Radio_Enable

SC_LEV_MES_SPEACHDONE

Speech finished playing, param1 contains id specified in the speech function. Warning, cannot be 0!

SC_LEV_MES_VIEWANIMCALLBACK

View animation executed with SC_SetViewAnim or SC_SetViewAnimEx finished playing, param1 contains defined callback id. Warning, callback ID cannot be 0!

SC_LEV_MES_EVENT

Some other script sent a message to the level script with the SC_LevScr_Event function. param1 and param2 contain values sent in the SC_LevScr_Event.

SC_LEV_MES_POINTINTERACT

Human PC used the interaction with the pointman. param1 contains status of the pointman (0 is in hold or follow mode, 1 is moving as a pointman, 2 is moving, but stays on the place, either waiting for the rest of the team or doesn’t have the checkpoints specified). param2 contains player id (pointer) to the pointman player object.

If the script returns FALSE in this callback, the engine will do the default action.

SC_LEV_MES_POINTINTERACTINFO

PC aims a cursor to the pointman, engine is requesting the text id for the interaction text, this interaction text is filled to the param3. If the param3 is set to 1, no interaction text will be shown. param1 contains status of the pointman (0 is in hold or follow mode, 1 is moving as a pointman, 2 is moving, but stays on the place, either waiting for the rest of the team or doesn’t have the checkpoints specified). param2 contains player id (pointer) to the pointman player object.

SC_LEV_MES_INITSCENE

Scene was loaded and is being initialized.

SC_LEV_MES_RELEASESCENE

The game scene is being closed and released.

SC_LEV_MES_ARTILLERY

Artillery support is used, the bombs are falling, param4 contains coordinates of the centre of the explosions.

SC_LEV_MES_LOUDSHOTCALLBACK

This is callback for the SC_GetLoudShot(). param1 – contains pl_id of player who has shot, param4 is the position of the shot

SC_LEV_MES_JUSTLOADED

The game was loaded from the savegame.

SC_LEV_MES_MUSICDONE

The music finished playing, param1 contains music id.

SC_LEV_MES_LIGHTSTICK_USED

Human PC used the lightstick.

SC_LEV_MES_STORYSKIP

Story skip was enabled with the SC_StorySkipEnable and PC pressed the ESC, SPACE or RETURN key.

SC_LEV_MES_GETMUSIC

Callback from the music system requesting setting of the new music. param1 contains the music id from the script, param2 is used to set the sound music id.

For more information about callbacks click on their ID or see here.

Structure s_SC_SOUND_info – sound script

Declaration

typedef struct{

dword message;

}s_SC_SOUND_info;

This structure is used for the sound script. Message can contain only SC_SOUND_MESSAGE_INIT – sound script is being initialized.

Structure s_SC_OBJ_info – dynamic object script

Declaration:

typedef struct{

dword event_type;

void *master_nod;

void *nod;

float new_hp_obtained;

dword hit_by;

c_Vector3 *world_pos;

c_Vector3 *world_dir;

float time;

}s_SC_OBJ_info;

This structure is used for storing the data for the callbacks to the object scripts. Event_type contains type of the callback, master_nod is the pointer at the master object (which has the script assigned to itself), nod is used for some callbacks as a specified subobject. If the message deals with the damage, new_hp_obtained contains the information about how much damage was already dealt to the object, hit_by can be either SC_OBJ_HIT_BY_MISSILE (object hit by generic shot), SC_OBJ_HIT_BY_EXPLOSION (object hit by the explosion) or SC_OBJ_HIT_BY_MISSILE_PC (object was hit by PC’s shot). world_pos and world_dir contain the information about the world position and rotation of the object. Float variable time contains time in second from the last execution.

Type of the messages:

SC_OBJ_INFO_EVENT_HIT

The object was hit. Variable hit_by specifies type of the damage dealt, new_hp_obtained contains overall damage dealt to the object inluding this hit. nod is the pointer to the hit sub object.

SC_OBJ_INFO_EVENT_INIT

This is the callback during the scene initialization (after the level script received the init message, all object scripts receive theirs). This is useful for storing basic default information about the transformation of the object.

SC_OBJ_INFO_EVENT_DOTICK

This is the time tick of the object. Engine calls the object script time tick every frame, variable time contains time in seconds from the last execution.

SC_OBJ_INFO_EVENT_RELEASE

This callback is executed during the release of the game – useful for reseting the object to it’s original transformation.

SC_OBJ_INFO_EVENT_USED

The object has enabled interaction with the SC_ACTIVE_Add function and was used by the PC.

SC_OBJ_INFO_EVENT_JUSTLOADED

This callback is executed just after the game was loaded from the saved game. Some of the data about objects are not stored, so this callback is usually used to set them correct, see example scripts.

SC_OBJ_INFO_EVENT_MOUNTEDSHOT

This is specific callback for the object defined as the mounted weapon platform – every time the player shoots, this message is sent to the script.

Structure s_SC_NET_info – network script

Declaration:

typedef struct{

dword message,param1,param2,param3;

float elapsed_time;

float fval1;

}s_SC_NET_info;

This structure is used to pass the data to the multiplayer network script. message contains type of the message, param1-param3 are dword parameters specific for each message, fval1 is float parameter variable, elapsed_time contains time from the last time tick. See here for details on each message here.

Type of the messages:

SC_NET_MES_UNDEFINED

Undefined message.

SC_NET_MES_LEVELINIT

SC_NET_MES_RENDERHUD

This message is passed to the script every frame rendered and it is used to write to the HUD. If the param1 is TRUE, this is the script running on the dedicated server.

SC_NET_MES_SERVER_TICK

This is the time tick for the server script.

SC_NET_MES_CLIENT_TICK

This is the time tick for the client script.

SC_NET_MES_SERVER_RECOVER_TIME

SC_NET_MES_SERVER_RECOVER_PLACE

SC_NET_MES_SERVER_KILL

This is the information to the server script about death of player specified in the param1, param2 contains pointer to the player who made the kill.

SC_NET_MES_MESSAGE

This is the message to the network script from other script using the SC_MP_ScriptMessage function. Param1 and param2 contains the specified parameters.

SC_NET_MES_LEVELPREINIT

This is the level preinitialization message (the level was not loaded yet). Param1 contains the value of the end rule, param2 the end value.

SC_NET_MES_RESTARTMAP

This means the map will be restarted, used to clear statistics, end rules and for recovering the players.

SC_NET_MES_RULESCHANGED

This is the message about changing of the rules.

Structures – player data structures

Structure s_SC_P_Create

Declaration

typedef struct{

dword type;

dword side;

dword group;

dword member_id;

dword name_nr;

dword debrief_group;

char *inifile;

void *recover_pos;

char *icon_name;

dword flags;

dword weap_knife;

dword weap_pistol;

dword weap_main1;

dword weap_main2;

dword weap_slot1;

dword weap_slot6;

dword weap_slot7;

dword weap_slot8;

dword weap_slot9;

dword weap_slot10;

dword force_sel_slot;

dword eqps;

s_SC_P_CreateEqp *eqp;

dword aeg_valid_head_bes[SC_P_CREATE_AEG_VALID_MAX];

dword aeg_valid_body_bes[SC_P_CREATE_AEG_VALID_MAX];

}s_SC_P_Create;

This structure is used for the player creation with SC_P_Create. In this version of the SDK it is used only for the SC_P_GetWeapons function, which will fill the data weap_xxx with player’s inventory.

Structure s_SC_P_CreateEqp

Declaration:

typedef struct{

char *bes;

char *eqp;

}s_SC_P_CreateEqp;

This is the data structure used to store the data about equipment linked to the player. Bes is pointer to the string containing path to the bes gfx file, eqp is string with the path to the eqp file.

Structure s_SC_P_getinfo

Declaration:

typedef struct{

float cur_hp,max_hp;

dword side;

dword group;

dword member_id;

}s_SC_P_getinfo;

This data structure is used to acquire basic information about player with the SC_P_GetInfo function.

cur_hp contains current hit points of the player, max_hp is maximum hit points of the player. Side, group and memberid are unique identifiers of the player.

Structures – dynamic object structures

Structure s_SC_OBJ_dynamic

Declaration:

typedef struct{

c_Vector3 velocity;

float rot_speed;

c_Vector3 rot_axis;

}s_SC_OBJ_dynamic;

This structure is used to set the dynamics to the dynamic object with the function SC_NOD_AddDynamic. velocity is a speed vector, rot_speed specifies the speed of the rotation while rot_axis specifies the rotation axis.

Structure s_SC_NOD_transform

Declaration:

typedef struct{

c_Vector3 loc;

c_Vector3 rot;

c_Vector3 scale;

}s_SC_NOD_transform;

This is the transformation data structure used for the SC_NOD_GetTransform and SC_NOD_SetTransform functions. loc is the location of the object, rot it’s rotation and scale it’s scale.

Structures – multiplayer data

Structure s_SC_MP_EnumPlayers

Declaration:

typedef struct{

dword id;

dword side;

dword status;

char *name;

}s_SC_MP_EnumPlayers;

This structure is used to enumerate all players in the game with the SC_MP_EnumPlayers function. id is the pointer to the player, side is the side, name is the name of the player. Value status is valid only on the server machine, it can be:

SC_MP_P_STATUS_NOTINGAME – player is not in the game

SC_MP_P_STATUS_INGAME - player is in the game

SC_MP_P_STATUS_INGAMEDEATH - player is dead

Structure s_SC_MP_Recover

Declaration:

typedef struct{

c_Vector3 pos;

float rz;

}s_SC_MP_Recover;

This structure is used to store the data about recover place. Vector pos is the position, rz is the rotation around the z axis.

Structure s_SC_MP_hud

Declaration:

typedef struct{

dword title;

BOOL use_sides;

BOOL disableUSside;

BOOL disableVCside;

dword side_name[2];

dword side_color[2];

dword pl_mask;

dword side_mask;

dword sort_by[5];

}s_SC_MP_hud;

This structure is used for the SC_MP_HUD_SetTabInfo function and is used to set what is shown on the screen when the player presses the MP info key (TAB by default).

title is the text identifier for the title of the window. Possible default values are:

1071 Vietcong: Capture the flag

1072 Vietcong: Assault Team Game

1048 Vietcong: ATG, search and destroy!

1179 Vietcong: Real War

1050 Vietcong: DeathMatch

1051 Vietcong: Team DeathMatch

1052 Vietcong: Last Man Standing is King of the jungle

1098 Vietcong: Cooperative

1083 Vietcong: Capture the Radio

1090 Vietcong: Save the Pilot

5100 TurnTable

use_sides can be used to enable or disable sorting the players by their side.

disableUSside or disableVCside can be set to TRUE if you do not want to list the players from US or VC side.

side_name is array with size 2 containg the text identifiers for the name of the sides (use 1010 and 1011 for default names).

side_color is the RGB color for the sides

pl_mask are the flags for what should be shown for the player. Use | operator for more flags. Flags can be:

SC_HUD_MP_PL_MASK_CLASS - show class

SC_HUD_MP_PL_MASK_POINTS - show points

SC_HUD_MP_PL_MASK_FRAGS - show frags

SC_HUD_MP_PL_MASK_KILLS - show kills

SC_HUD_MP_PL_MASK_DEATHS - show deaths

SC_HUD_MP_PL_MASK_PINGS - show ping|

side_mask is the mask for what to show for each side. Possible values are:

SC_HUD_MP_SIDE_MASK_POINTS - show points

SC_HUD_MP_SIDE_MASK_FRAGS - show frags

sort_by is the array with sort options for the players. Game will first sort the players according the value at the sort_by[0], then by sort_by[1] etc. Possible values are:

SC_HUD_MP_SORTBY_NONE - no sort

SC_HUD_MP_SORTBY_POINTS - sort by points

SC_HUD_MP_SORTBY_FRAGS - sort by frags

SC_HUD_MP_SORTBY_KILLS - sort by kills

SC_HUD_MP_SORTBY_DEATHS - sort by deaths

SC_HUD_MP_SORTBY_PINGS - sort by ping

You can also aply flag SC_HUD_MP_SORT_DOWNUP to any value with logical or operator and the sorting will be done from least size to highest.

Structure s_SC_HUD_MP_icon

Declaration:

typedef struct{

dword icon_id;

dword type;

int value;

dword color;

}s_SC_HUD_MP_icon;

This structure is used for showing various icons on the screen, not just for multiplayer, with SC_MP_SetIconHUD function. This structure is used to define one icon.

icon_id – index to the array of the icons

type – type of the icon, can be

SC_HUD_MP_ICON_TYPE_NONE - none

SC_HUD_MP_ICON_TYPE_NUMBER - number

SC_HUD_MP_ICON_TYPE_TIME - time

value – four bytes with the value of the icon

color – this is the ARGB color for the icon.

Structure s_SC_MP_SRV_settings

Declaration:

typedef struct{

dword coop_respawn_time;

dword coop_respawn_limit;

dword dm_weap_resp_time;

dword atg_class_limit[6];

}s_SC_MP_SRV_settings;

This data structure is used to acquire information about the server settings in the multiplayer game with the function SC_MP_GetSRVsettings.

Structure s_SC_MP_SRV_AtgSettings

Declaration:

typedef struct{

float ATG_round_time;

float tt_respawntime;

float tt_timelimit;

}s_SC_MP_SRV_AtgSettings;

This data structure is used to acquire information about the server settings for the ATG in the multiplayer game with the function SC_MP_SRV_GetAtgSettings.

Structures – various data structures

Structure s_SC_systime

Declaration:

typedef struct{

int hours;

int minutes;

int seconds;

int msec;

}s_SC_systime;

This data structure is used to store the computer system time for the function SC_GetSystemTime.

Structure s_SC_FpvMapSign

Declaration:

typedef struct{

dword id;

dword color;

float scale;

c_Vector3 pos;

}s_SC_FpvMapSign;

This structure is used to place the signs on the FPV map with SC_MP_FpvMapSign_Set.

id is the identifier of the sign acquired with the SC_MP_FpvMapSign_Load function.

color is the ARGB color of the sign

scale is the scale of the sign (1 is default)

pos is the position for the sign in the scene.

Structure s_SC_initside

Declaration:

typedef struct{

dword MaxHideOutsStatus;

dword MaxGroups;

}s_SC_initside;

This data structure is used for the SC_InitSide function to create the game side. MaxGroups contain the maximum number of the groups which will be in the side, MaxHideOutStatus is the number of the hideouts the side AI will remember.

Structure s_SC_initgroup

Declaration:

typedef struct{

dword SideId;

dword GroupId;

dword MaxPlayers;

float NoHoldFireDistance;

float follow_point_max_distance;

}s_SC_initgroup;

This data structure is used for the SC_InitSideGroup function to create the player group. SideId is the identifier of the side, GroupId of the creating group, MaxPlayers is maximum player who will be in the group. NoHoldFireDistance is the maximum distance from the enemy the AI will shoot. follow_point_max_distance is valid for the group in the pointman mode, it’s the maximum distance between pointman and last member of the group, if the distance is bigger, the pointman will wait.

Functions – basic

These are the basic engine and C functions.

int sprintf(char , const char , ...);

This is the standard sprintf function. Refer to the standard C help files.

int swprintf(ushort , ushort, ...);

This is the standard sprintf function. Refer to the standard C help files.

int rand(void);

This function returns the random integer number.

float frnd(float max);

This function return random float number up to the specified maximum.

float sqrt(float val);

This function returns the radix of the value.

float fmod(float a, float b);

This function returns the remainder from division of the float numbers.

float sin(float a);

This function returns the sinus of the value a.

float cos(float a);

This function returns the sinus of the value a.

float atan2(float y, float x);

This function returns the atan.

ushort* SC_Wtxt(dword val);

This function will return pointer to the string from the text database with the specified id.

BOOL SC_StringSame(char a, char b);

This function will compare two strings and return true if they are same.

void SC_ZeroMem(void *ptr, dword size);

This function will fill the specified portion of the memory with zeroes. Used in the CLEAR macro.

float SC_GetLineDist(c_Vector3 pos, c_Vector3 line_a, c_Vector3 *line_b);

This function will return the distance of the vector pos from the line between vectors line_a and line_b.

float SC_GetLineDistXY(c_Vector3 pos, c_Vector3 line_a, c_Vector3 *line_b);

This function will return the distance of the vector pos from the line between vectors line_a and line_b limited to the 2d space (without z coordinate).

BOOL SC_IsNear2D(c_Vector3 a, c_Vector3 b, float dist);

This function will return TRUE if the vector a is at the distance dist from the vector b or closer, this function works only in the 2D space, no z coordinate.

BOOL SC_IsNear3D(c_Vector3 a, c_Vector3 b, float dist);

This function will return TRUE if the vector a is at the distance dist from the vector b or closer.

float SC_2VectorsDist(c_Vector3 a, c_Vector3 b);

This function returns the distance between vectors a and b.

float SC_VectorLen(c_Vector3 *vec);

This function returns the length of the vector vec.

float SC_VectorLen2(c_Vector3 *vec);

This function returns the (length of the vector vec)* (length of the vector vec).

BOOL SC_SphereIsVisible(s_sphere *sph);

This function will return TRUE if at least part of the sphere sph is visible on the screen.

void SC_GetPos_VecRz(void cpos, c_Vector3 pos, float *rz);

This function will fill the vector pos with the world position according to the transformation cpos and rz with the z rotation value.

ushort SC_AnsiToUni(char src, ushort *dest);

This function will convert ANSI text to UNICODE.

Functions - the debug functions

These functions are used during the script debuging.

void SC_message(char *txt,...);

This function will show the text with formated parameters in the dialog window.

void SC_Log(dword level, char *txt, ...);

This function will write the text with formated parameters to the log file. Variable level is used to determine the value of the log, 0 is fatal error, 1 is error, 2 is warning, 3 is information.

void SC_Osi(char *txt,...);

This function will show the text with formated parameters in the status line.

Functions – global variables

This set of functions is used to handle the engine global variables.

void SC_sgi(dword id, int a);

This function will set the global variable id to the integer value a.

int SC_ggi(dword id);

This function will return the integer value of the global variable id.

void SC_sgf(dword id, float a);

This function will set the global variable id to the float value a.

float SC_ggf(dword id);

This function will return the float value of the global variable id.

void SC_MP_Gvar_SetSynchro(dword id);

This function will mark the global variable id as a MP synchronized – all changes to the global variable will be synchronized for all clients.

Functions for the sound handling

These are the function used to handle the sound and music.

void SC_SND_MusicPlay(dword MusicID, dword StartVolume );

This function will play the music MusicID with the volume StartVolume.

void SC_SND_PlayMusic(dword music_id);

This is obsolete function and it should not be used.

void SC_SND_MusicStop(dword MusicID );

This function will stop playing of the music MusicID.

void SC_SND_MusicStopFade(dword MusicID, dword Time );

This function will fadeout the music MusicID in the Time and stop playing it.

void SC_SND_MusicFadeVolume(dword MusicID, dword Volume, dword Time );

This function will fade the volume of the MusicID to the Volume in Time.

BOOL SC_SND_SetEnvironment(dword env1_id, dword env2_id, float env_ratio);

This function will set the sound enviroment.

void SC_SND_Ambient_Play(dword snd_id);

This function will start the ambient sound snd_id.

void SC_SND_Ambient_Stop(void);

This function will stop the ambient soud.

void SC_SND_SetHearableRatio(float Ratio);

This function will set the hearable ratio to the Ratio.

void SC_SND_CreateCurveSound(char *anm_filename, dword snd_id, float max_play_dist, BOOL apply_env_volume);

This function will create the curve sound with sound snd_id to the cuve anm_filename, sound will be hear the to distance max_play_dist. If the apply_env_volume is TRUE, the enviroment sound volume will applied to the sound curve.

void SC_FadeSoundPlayer(dword snd_player_id, float final_volume, float fade_time);

This function will fade the sound player snd_player_id to the final_volume in time fade_time.

Possible sound playr id are:

SC_SNDPLAYER_GAME – game sound effects

SC_SNDPLAYER_SPEECH - speech

SC_SNDPLAYER_HELI – helicopter sounds

SC_SNDPLAYER_BEEP - beep sounds

SC_SNDPLAYER_NATURE – nature sounds

SC_SNDPLAYER_SCRIPT0 - special script sounds

SC_SNDPLAYER_SCRIPT1 - special script sounds

float SC_SND_GetSoundLen(dword snd_id);

This function will return the length of the sound snd_id in seconds.

void SC_SND_PlaySound3D(dword snd_id, c_Vector3 *pos);

This function will start playing 3d sound snd_id from the position pos.

void SC_SND_PlaySound3Dex(dword snd_id, c_Vector3 pos, float timeout);

This function will start playing 3d sound snd_id from the position pos in a time specified in the variable timeout and set the timeout to the time of the end of the sound from the time of the function call.

void SC_SND_PlaySound2D(dword snd_id);

This function will start playing 2d sound snd_id.

void SC_SND_PlaySound3Dlink(dword snd_id, void nod, float timeout);

This function will start playing 3d sound snd_id linked to the nod nod in a time specified in the variable timeout and set the timeout to the time of the end of the sound from the time of the function call.

void SC_SND_PlaySound3Dpl(dword snd_id, dword pl_id, dword flags);

This function will play the sound linked to the player. Flags are obsolete and are not used.

void SC_SND_PlaySound3DSpec(dword snd_id, c_Vector3 *pos, dword spec_id);

This function will start playing 3d sound snd_id from the position pos using the special sound player. Sound players can be:

SC_SNDPLAYER_GAME – game sound effects

SC_SNDPLAYER_SPEECH - speech

SC_SNDPLAYER_HELI – helicopter sounds

SC_SNDPLAYER_BEEP - beep sounds

SC_SNDPLAYER_NATURE – nature sounds

SC_SNDPLAYER_SCRIPT0 - special script sounds

SC_SNDPLAYER_SCRIPT1 - special script sounds

void SC_SND_PlaySound3DexSpec(dword snd_id, c_Vector3 pos, float timeout, dword spec_id);

SC_SNDPLAYER_GAME – game sound effects

SC_SNDPLAYER_SPEECH - speech

SC_SNDPLAYER_HELI – helicopter sounds

SC_SNDPLAYER_BEEP - beep sounds

SC_SNDPLAYER_NATURE – nature sounds

SC_SNDPLAYER_SCRIPT0 - special script sounds

SC_SNDPLAYER_SCRIPT1 - special script sounds

void SC_SND_PlaySound2DSpec(dword snd_id, dword spec_id);

This function will start playing 2d sound snd_id using the sound player spec_id, which can be:

SC_SNDPLAYER_GAME – game sound effects

SC_SNDPLAYER_SPEECH - speech

SC_SNDPLAYER_HELI – helicopter sounds

SC_SNDPLAYER_BEEP - beep sounds

SC_SNDPLAYER_NATURE – nature sounds

SC_SNDPLAYER_SCRIPT0 - special script sounds

SC_SNDPLAYER_SCRIPT1 - special script sounds

Functions for the objects

These are the basic functions used for handling the gfx objects.

void SC_NOD_Get(void master_obj, char *obj_name);

This function will return the pointer to the sub object with name “obj_name” in the object master_nod. If the sub object cannot be found, error message dialog will be shown.

void SC_NOD_GetNoMessage(void master_obj, char *obj_name);

This function will return the pointer to the sub object with name “obj_name” in the object master_nod.

void SC_NOD_GetNoMessage_Entity(char obj_name);

This function will return the pointer to the entity “obj_name”.

void SC_NOD_GetTransform(void obj,s_SC_NOD_transform trans);

This function will fill the transformation of the nod obj to the specified trans.

void SC_NOD_SetTransform(void obj,s_SC_NOD_transform trans);

This function will set the transformation of the nod obj according specified trans.

void SC_NOD_Hide(void *obj, BOOL hide);

This function will hide the nod obj, used only in the FPV weapon scripts.

void SC_NOD_GetPosInOtherSpace(void other_nod, void nod, c_Vector3 *vec);

This function will fill the vector vec with the position of the object nod in the space of the object other_nod.

void SC_DUMMY_Set_DoNotRenHier(char *dummy_name, BOOL do_not_render_hiearchy);

This function will enable or disable rendering of the object dummy_name and all it’s subobjects.

void SC_DUMMY_Set_DoNotRenHier2(void *nod, BOOL do_not_render_hiearchy);

This function will enable or disable rendering of the object nod and all it’s subobjects.

char SC_NOD_GetName(void nod);

This function will return the pointer to the name of the object nod.

void SC_NOD_GetPivotWorld(void nod,c_Vector3 vec);

This function will set the pivot of the object nod to the vector vec.

void SC_NOD_Detach(void nod, char name);

This function will be desribed in the later version of the document.

void SC_NOD_GetWorldPos(void nod, c_Vector3 pos);

This function will set the world position of the object nod to the vector pos.

float SC_NOD_GetWorldRotZ(void *nod);

This function will return the z rotation of the object nod.

BOOL SC_NOD_GetCollision(void master_nod, char name, BOOL clear_it);

This function will return TRUE if the object named “name” in the object master_nod collided with something. If the clear_it is TRUE, the information about collision will be cleared.

BOOL SC_NOD_GetCollision2(void *nod, BOOL clear_it);

This function will return TRUE if the object nod collided with something. If the clear_it is TRUE, the information about collision will be cleared.

void SC_NOD_GetDummySph(void master_nod, char dummy_name, s_sphere *sph);

This function will fill the sphere sph with the dummy sphere of the subobject named dummy_name of the object master_nod.

Functions for the dynamic objects

These functions are used to handle the dynamic objects.

void SC_NOD_SetDSTR(void nod, char obj_name, char *dstr_name);

This function will set the destroyed variant of the subobject named obj_name in the object nod to the destruction object named dstr_name.

void SC_NOD_ResetDSTR(void nod, char obj_name);

This function will reset the destroyed variant of the subobject named obj_name in the object nod to the default version.

float SC_DOBJ_CameraLooksAt(void *nod, float max_dist);

This function will determine if the camera is looking at the specified nod to the maximum distance of max_dist. This function will ignore possible collision with other object standing in the way!

float SC_DOBJ_CameraLooksAtCollision(void *nod, float max_dist);

This function will determine if the camera is looking at the specified nod to the maximum distance of max_dist.

void SC_ACTIVE_Add(void *nod, float cur_dist, dword info_txt);

This object will mark the object nod as possible object for the interaction with the interaction text info_txt. Value cur_dist should contain the distance of the object to the player and it is used to determine which object can be used if there are more possibilites (closest one will be used);

void SC_DOBJ_SetFrozenFlag(void *nod, BOOL frozen);

This function will set the frozen flag of the dynamic object nod to the frozen. Frozen dynamic object will not move untill collided with or further use of the SC_DOBJ_SetFrozenFlag.

void SC_NOD_AddDynamic(void master_nod, char name, s_SC_OBJ_dynamic *info);

This function will add the dymanics specified in the s_SC_OBJ_dynamic info to the subobject named name in the object master_nod.

BOOL SC_DOBJ_IsBurning(void *nod, float perc);

This function will return TRUE, if the dynamic object nod is burning at least from the perc percent.

BOOL SC_DOBJ_IsBurning2(void *nod);

This function will return TRUE if the dynamic object nod is burning.

void SC_DOBJ_StopBurning(void *nod, BOOL enable_future_burning);

This function will stop burning of the dynamic object nod. enable_future_burning should be set TRUE if you want the object to be able to burn again.

void SC_DOBJ_ClearDamagedHP(void *nod);

This function will reset the damage of the dynamic object nod to zero.

void SC_DOBJ_BurnCreateBlockers(void nod, s_sphere sph, dword items);

This function will create waypoint blockers enabled if the object nod will burn.Dara for blockers are stored in the array of spheres sph with item count of items.

Functions for the view animations

This set of functions is used to handle the view animations, used either for camera animation or for moving the object in the scene.

void SC_NOD_SetFromANM(char anm, float time, void nod);

This function will set the object nod to the position and rotation specified in the animation in filename anm at the time time (in seconds).

float SC_ANM_GetFrameTime(char *anm, int frame);

This function will return the time of the animation in the file anm at the frame frame.

BOOL SC_NOD_GetPosFromANM(char anm, float time, c_Vector3 pos);

This function will fill the vector pos with the position from the animation in file anm in the time time.

Functions for the visual effects

These functions are used to work with the events and particles and some other engine gfx effects.

void SC_EventImpuls(char *ev_name);

This function will send an impuls to the engine event object named ev_name. If the event is set to respond only to the impuls, it will be activated.

void SC_EventEnable(char *ev_name, BOOL enable);

This function will enable or disable engine event object ev_name.

void SC_SetMissileTrace(dword color, float alpha);

This function will set the missile tracers to color color with the alpha alpha.

void SC_CreatePtc(dword id, c_Vector3 *vec);

This function will create the particle with identifier id at the position specified in the vector vec.

void SC_CreatePtc_Ext(dword id, void *nod, float time, float interval, float scale, float time_mult);

This function will create the particle id at the position of the object nod for time times, with intervals interval, scaled to the scale and with the time multiplied by the time_mult.

void SC_CreatePtcVec_Ext(dword id, c_Vector3 *vec, float time, float interval, float scale, float time_mult);

This function will create the particle id at the position vec for time times, with intervals interval, scaled to the scale and with the time multiplied by the time_mult.

void SC_CreatePtcInNodSpace_Ext(dword id, void *nod, float time, float interval, float scale, float time_mult);

This function will create the particle id in the world of the object nod for time times, with intervals interval, scaled to the scale and with the time multiplied by the time_mult.

void SC_Fnt_Write(float x, float y, char *txt, float scale, dword color);

This function will write the text txt at coordinates x y, using the system font with scale scale and color color. This function can be used only in the network script message SC_NET_MES_RENDERHUD.

float SC_Fnt_GetWidth(char *txt, float scale);

This function will return the width in pixels of the text txt with system font of scale scale.

void SC_Fnt_WriteW(float x, float y, ushort *txt, float scale, dword color);

This function will write the unicode text txt at coordinates x y, using the system font with scale scale and color color. This function can be used only in the network script message SC_NET_MES_RENDERHUD.

float SC_Fnt_GetWidthW(ushort *txt, float scale);

This function will return the width in pixels of the unicode text txt with system font of scale scale.

void SC_GetScreenRes(float width, float height);

This function will set the width and height to the actual screen resolution.

void SC_SetSceneVisibilityMult(float vis_mult, float scene_fog_mult, float bckg_fog_mult);

This function will change the multipliers applied to the scene visibility settings.

Vis_mult is multiplier of the maximum visibility, scene_fog_mult and bckg_fog_mult are used to set the the fog and background fog.

void SC_FadeTo(BOOL black, float time);

This function will cause the view to fade to black (if black is true) or to the full visibility in the time time.

void SC_SwitchSceneSCS(char *fname, float time);

This function will fade the scene visual settings to the settings stored in the file fname in the time time.

void SC_SetMovieBorders(BOOL set_on);

This function will cause the black “movie” borders on the top and bottom of the screen to appear or disappear.

void SC_EnableBloodWhenHit(BOOL enable);

This function will enable or disable spray of the blood when some player is hit. For the most versions is this enabled for the default.

void SC_CreateLight(s_SC_light *info);

This function will create the in game light according to the settings in the s_SC_light info structure.

void SC_GetCameraPos(c_Vector3 *vec);

This function will get the world position of the current camera to the vector vec.

Functions for handling the items

Items are weapons/grenades/ammo and other things in the engine. Engine uses special id to handle this items. For the list of the items see here.

dword SC_Item_Create(dword id, c_Vector3 *vec);

This function will create the item with id on the position vec and will return the identifier of the item.

dword SC_Item_Create2(dword id, c_Vector3 vec, c_Vector3 movdir);

This function will create the item with id on the position vec with moving vector movdir and will return the identifier of the item.

void SC_Item_Preload(dword id);

This function will preload the item id (so when the item is created, game won’t stop for a while and load it’s data).

BOOL SC_Item_GetPos(dword netid, c_Vector3 *pos);

This function will get the position of the item with identifier netid and fill it to the position pos. The function returns TRUE if the engine found the specified object.

dword SC_Item_Find(dword item_type);

This function will look for the item of specified type item_type and returns the identifier of the first found item.

Function for handling the waypoints

These functions are used to work with the waypoints.

BOOL SC_GetWp(char wpname, c_Vector3 vec);

This function will set the position of the waypoint wpname to the vector vec. If the waypoint is found, it will return TRUE.

BOOL SC_GetRndWp(s_sphere sph, c_Vector3 wp);

This function will get the position of the random waypoint inside the sphere sph to the vector vec. If the waypoint is found, it will return TRUE.

Functions for handling the players

These are basic functions for creating and handling the players and groups.

void SC_InitSide(dword id, s_SC_initside *init);

This function will initialize the side with the id id according to the data in the s_SC_initside init.

void SC_SetSideAlly(dword s1, dword s2, float status);

This function will set the status between sides s1 and s2. Status can be:

0 – the sides are neutral

1 – sides are allies

-1 – sides are enemies

void SC_InitSideGroup(s_SC_initgroup *info);

This function will initialize player group according to the data in the structure s_SC_initgroup info.

Functions for getting the info about players

These functions are used to acquire information about the players in the game.

dword SC_GetGroupPlayers(dword side, dword group);

This function will return number of the players of side side in the group group.

void SC_GetPls(s_sphere sph, dword list, dword *items);

This function will fill the list with the players found in the sphere sph and set the number of the players to items. List must be array and items must be set to the size of the array before calling the function.

void SC_GetPlsInLine(c_Vector3 pos, c_Vector3 dir, dword list, dword items);

This function will fill the list with the players found in line from the pos to dir and set the number of the players to items. List must be array and items must be set to the size of the array before calling the function.

char *SC_P_GetName(dword pl_id);

This function will return the pointer to the name of the player pl_id.

BOOL SC_P_IsReady(dword pl_id);

This function will return TRUE if the player pl_id is ready – he is created and alive.

void SC_P_GetPos(dword pl_id, c_Vector3 *pos);

This function will return the position of the player pl_id in the vector pos. Returned position is the place where player’s legs touch the ground.

float SC_P_GetRot(dword pl_id);

This function will return the z rotation of the player pl_id.

void SC_P_GetHeadPos(dword pl_id, c_Vector3 *pos);

This function will return the position of the player pl_id ‘s head in the vector pos.

void SC_P_GetDir(dword pl_id, c_Vector3 *dir);

This function will return direction of the movement of the player pl_id in the vector dir.

void SC_P_GetInfo(dword pl_id, s_SC_P_getinfo *info);

This function will will the information about he player pl_id to the structure s_SC_P_getinfo info.

dword SC_GetNearestPlayer(c_Vector3 vec, float dist);

This function will return the pointer to the nearest player to the vector vec, value dist will be used to store the distance from the vector.

dword SC_P_GetBySideGroupMember(dword iside, dword igroup, dword imember);

This function will return the pointer to the player specified by his side iside, group igroup and member id imember.

float SC_P_GetPhase(dword pl_id);

This function will return the stance phase of the player pl_id. Return values are: 0 stand, 1 crouch, 2 lie.

float SC_P_GetDistance(dword pl_id, dword to_pl_id);

This function will return the distance from the player pl_id to the player to_pl_id.

BOOL SC_P_UsesBinocular(dword pl_id);

This function will return true if the player pl_id is using the binoculars.

Functions for changing the parameters of players

These functions are used to set or change some parameters of the generic players.

void SC_P_DoKill(dword pl_id);

This function will kill the player pl_id.

void SC_P_ChangeSideGroupMemId(dword pl_id, dword side, dword group, dword mem_id);

This function will force the change of the unique identifiers of the player pl_id to new side, group and mem_id. Useful when you need someone to become suddenly the enemy – just switch his side.

void SC_P_SetForceClassName(dword pl_id, dword name_nr);

This function will force the class name of the player pl_id to the text identifier name_nr. By default the class names in the singleplayer are according to the member id:

SC_P_MEMBERID_CAPTAIN = 0 = “captain”

SC_P_MEMBERID_POINT = 1 = “pointman”

SC_P_MEMBERID_MEDIC = 2 = “medic”

SC_P_MEMBERID_DEMOLITION = 3 = “engineer”

SC_P_MEMBERID_RADIO = 4 = “radioman”

SC_P_MEMBERID_MACHINEGUN = 5 = “machine gunner”

void SC_P_SetPos(dword pl_id, c_Vector3 *pos);

This function will teleport the player pl_id to the position pos.

void SC_P_SetRot(dword pl_id, float rz);

This function will set the rotation around the z axis of the player pl_id to the rz.

void SC_P_SetHp(dword pl_id, float hp);

This function will set the hit points of the player pl_id to the value hp. WARNING – this can be used only for damaging the health and player script of pl_id will receive callback about hit.

void SC_P_Heal(dword pl_id);

This function will heal some of the hit points of the player pl_id.

void SC_P_Link3pvEqp(dword pl_id, dword slot_id, dword plb_id, char *eqp_name);

This function will link special equipment with id plb_id with the eqp file named eqp_name on the slot slot_id of the player pl_id. Plb_id must be created with SC_PreloadBes.

void SC_P_UnLink3pvEqp(dword pl_id, dword slot_id);

This function will unlink the special equipment from the slot slot_id of the player pl_id.

void SC_P_SetPhase(dword pl_id, dword phase);

This function will set the stance phase of the player pl_id to phase, which can be either 0 for standing or 1 for crouching.

void SC_P_DoHit(dword pl_id, dword area_id, float hp);

This function will hit the player pl_id to the area area_id, SC_P_MESH_AREA_BODYFRONT, SC_P_MESH_AREA_BODYBACK, SC_P_MESH_AREA_LEFTARM, SC_P_MESH_AREA_RIGHTARM, SC_P_MESH_AREA_LEFTLEG, SC_P_MESH_AREA_RIGHTLEG, or SC_P_MESH_AREA_HEAD) for the damage hp.

void SC_P_SetRadarColor(dword pl_id, dword val);

This function will change the color of specified player pl_id on the PC’s radar to the color value val.

void SC_P_CloseEyes(dword pl_id, BOOL force_close);

This function will cause the player pl_id to close or open the eyes.

void SC_P_EnableBinocular(dword pl_id, BOOL enable);

This function will enable or disable binoculars for the player pl_id.

Functions for players and weapons

These are the functions for handling the weapons and inventories of the generic players.

BOOL SC_P_GetWeapons(dword pl_id, s_SC_P_Create *info);

This function will return TRUE if it can write the information about the inventory of the player pl_id to the data structurue s_SC_P_Create info.

BOOL SC_P_HasWeapon(dword pl_id, dword weap_type);

This function will return TRUE if the specified pl_id has weapon weap_type.

BOOL SC_P_GetHasShoot(dword pl_id);

This function will return TRUE if the pl_id has shot from the last use of this function.

dword SC_P_GetCurWeap(dword pl_id);

This function will return current selected weapon of the player pl_id.

void SC_P_AddAllAmmo(dword pl_id);

This function will add all ammo to the player pl_id (including grenades if the player has at least one).

void SC_P_AddAmmoNoGrenade(dword pl_id);

This function will add all ammo to the player pl_id except for the grenades.

void SC_P_ChangeWeapon(dword pl_id, dword slot_id, dword weap_type);

This function will change the weapon in the slot slot_id of the player pl_id to the weapon weap_type.

void SC_P_SetSelWeapon(dword pl_id, dword slot_id);

This function will change the selected weapon of the pl_id to the slot slot_id.

void SC_P_SetNoAmmo(dword pl_id);

This function will remove all ammo from the player pl_id.

void SC_P_SetAmmo(dword pl_id, dword ammo_type, dword amount);

This function sets the amount of the ammo ammo_type to the amount amount for the pl_id.

Functions for handling the human PC directly

This set of function are working directly with the human PC on actual machine.

dword SC_PC_Get(void);

This function will return the pointer to the human PC. It CAN be zero sometimes – means human PC is not yet created or disabled.

BOOL SC_PC_GetPos(c_Vector3 *pos);

This function will fill the position of the PC to the variable pos. It returns TRUE if the data in the pos are valid.

void SC_PC_SetControl(BOOL user_control);

This function will enable or disable PC control. If set to FALSE, no input will be used to handle the player and the camera will be set to default location, unless changed with the view animation. It is enabled by default.

void SC_PC_EnableMovementAndLooking(BOOL enable);

This function will enable or disable players movement and looking around – useful for fixing the player in one position. It is enabled by default.

void SC_PC_EnableMovement(BOOL enable);

This function will enable or disable PC movement – he can still look around, but cannot move. It is enabled by default.

void SC_PC_EnablePronePosition(BOOL enable);

This function is used to disable the prone position for the PC in some regions – underground for example. It is enabled by default.

void SC_PC_EnableWeaponsUsing(BOOL enable);

This function enables or disables usage of the PC’s weapon. It is enabled by default.

void SC_PC_EnableExit(BOOL enable);

This function will enable or disable possibility of PC’s exit from the vehicle. It is enabled by default.

void SC_PC_EnableEnter(BOOL enable);

This function will enable or disable possibility of PC’s enter to the vehicle. It is enabled by default.

float SC_PC_PlayFpvAnim(char *filename);

This function will force the players hands to play selected FPV animation. Function will return the time to the end of the animation.

float SC_PC_PlayFpvAnim2(char filename, dword plb_id, char eqp, char *anm);

This function will force the players hands to play selected FPV animation using the selected preloaded BES file plb_id attached with the equipment file eqp playing the animation anm. Function will return the time to the end of the animation.

void SC_PC_PlayFpvLooped(char *filename);

This function will force the players hands to play looped selected FPV animation.

void SC_PC_EnableFlashLight(BOOL enable);

This function will enable or disable usage of the flashlight for the player.

void SC_PC_EnablePickup(BOOL enable);

This function will enable or disable possibility of picking up objects for the PC. It is enabled by default.

float SC_GetPCZoom(void);

This function will return current zoom of the PC.

Functions for the multiplayer game

These functions are used for the multiplayer game.

BOOL SC_MP_EnumPlayers(s_SC_MP_EnumPlayers list, dword items, dword side);

This function is used to enumerate the MP players. It returns TRUE if it was succesfull and the data are valid.

list is the array of the s_SC_MP_EnumPlayers, which will be filled with the data.

items is the pointer to the variable, which will be filled with number of enumerated players. Before calling this function, set it to the size of the array!

side is the identifier of the side, which should be enumerated. Use SC_MP_ENUMPLAYER_SIDE_ALL for all sides.

BOOL SC_NET_FillRecover(s_SC_MP_Recover recov, char wpname);

This function will fill the variable s_SC_MP_Recover with data acquired from the waypoint named wpname.

void SC_MP_RestartMission(void);

This function will cause the restart of the multiplayer game.

void SC_MP_P_SetRecoverTime(dword pl_id, float time);

This function will set the recover time for the specified player with pointer pl_id to the time.

dword SC_MP_P_GetAfterRecoverSide(dword pl_id);

This function will return what side will be the player pl_id after the next recover.

dword SC_MP_P_GetClass(dword pl_id);

This function returns the actual class of the pl_id.

dword SC_MP_P_GetAfterRecoverClass(dword pl_id);

This function returns the class of the pl_id after next recover.

void SC_MP_SRV_SetForceSide(dword side);

Use to force all human players to be of specified side, or use 0xffffffff for any side.

void SC_MP_SRV_SetClassLimit(dword class_id, dword limit);

This function will set the class limit of the class class_id to the limit.

void SC_MP_SRV_SetClassLimitsForDM(void);

This function sets the class limits for the DeathMatch like game.

dword SC_MP_SRV_GetBestDMrecov(s_SC_MP_Recover list, dword items, float no_recov_time, float max_recov_time);

This function will return the position in the array of recover places list with size items, with no_recov_time and max_recov_time which is usable for the recover of the player.

void SC_MP_SRV_InitWeaponsRecovery(float time);

This function is used to set the recover time of the weapons placed manualy to the scene. Use 0 for immediate recover or any minus value to disable these weapons.

void SC_MP_HUD_SetTabInfo(s_SC_MP_hud *info);

This function is used to set the MP info table to the data specified in the s_SC_MP_hud structure.

void SC_MP_HUD_SelectPl(dword pl_id, dword color);

This function will cause the selected player pl_id to be visible on the HUD with ARGB color specified in the color.

void SC_GameInfo(dword text_id, char *text);

This function should not be used – use SC_GameInfoW instead.

void SC_GameInfoW(ushort *text);

This function will set the game info text shown on the screen to the text. Text is in the wide, unicode format.

void SC_P_MP_AddPoints(dword pl_id, int val);

This function will add points val to the player pl_id.

dword SC_MP_GetMaxPointsPl(int *points);

This function will return the pl_id of the player with most points, the points value will be filled to the points variable.

dword SC_MP_GetMaxFragsPl(int *frags);

This function will return the pl_id of the player with most frags, the points value will be filled to the frags variable.

dword SC_MP_GetHandleofPl(dword pl_id);

This function will return the multiplayer handle of the player pl_id.

dword SC_MP_GetPlofHandle(dword pl_handle);

This function will return the pointer to the player with multiplayer handle pl_handle.

void SC_MP_SRV_P_SetObtainedDamageMult(dword pl_id, float mult);

This function will set the damage multiplier to the player pl_id, to mult. 1 is normal, 2 is player takes twice as much damage, 0.5 takes only half of the damage.

void SC_MP_SetSideStats(dword side, int frags, int points);

This function will set the status of the side side to frags and points.

void SC_MP_ScriptMessage(dword param1, dword param2);

This function will send the script message to the multiplayer script running on the same machine as script using this function.

void SC_MP_AllowStPwD(BOOL enable);

This function can be used to enable or disable switching between players after the death.

void SC_MP_AllowFriendlyFireOFF(BOOL enable);

This function allows use of the friendly fire. Set TRUE for team based games, FALSE for death match like games.

void SC_MP_SetIconHUD(s_SC_HUD_MP_icon *icon, dword icons);

This function will set the icons to be visible on the heads up display. icon is the pointer to the array of s_SC_HUD_MP_icon, icons is the size of the array.

void SC_MP_SetInstantRecovery(BOOL enable);

This function can be used to allow instant recovery of the players.

void SC_MP_SetItemsNoDisappear(BOOL nodisappear);

This function can be used to disable disappearing of the items (dropped guns).

void SC_MP_EnableBotsFromScene(BOOL enable);

This function will enable or disable creation of the AI characters from the player objects in the scene. FALSE by default.

void SC_MP_SetChooseValidSides(dword mask);

This function will set the valid sides for the player to choose from. Use 0 for US only, 2 for VC, 3 for both.

void SC_MP_EnableC4weapon(BOOL enable);

This function will enable the C4 weapon for the players. (For the ATG bomb games).

void SC_MP_LoadNextMap(void);

This function will cause the engine to stop the current mission and load next from the server list.

void SC_MP_SetTeamGame(BOOL teamgame);

This function is used to set the team game (use FALSE for deathmatch like games).

void SC_MP_RecoverAllNoAiPlayers(void);

Valid only on the server, this function will cause forced recover of all human players in the game.

void SC_MP_RecoverAllAiPlayers(void);

Valid only on the server, this function will cause forced recover of all AI players in the game.

void SC_MP_EndRule_SetTimeLeft(float val, BOOL counting);

This function will set the information about the time left to the end of the game.

void SC_MP_GetSRVsettings(s_SC_MP_SRV_settings *info);

This function will get the server settings and place them to the s_SC_MP_SRV_settings structure.

BOOL SC_MP_SRV_P_SetSideClass(dword pl_id, dword side, dword class_id);

This function will set the class of the player pl_id to class class_id and will set him to the side side, valid only on the server.

BOOL SC_MP_SRV_GetAutoTeamBalance(void);

This function will return TRUE, if the auto team balance is enabled on the server.

int SC_MP_SRV_GetTeamsNrDifference(BOOL after_respawn);

This function will return the difference between the teams. If after_respawn is TRUE, the value will be valid after next respawn of the players.

void SC_MP_SRV_DoExplosion(c_Vector3 *pos, dword type);

Valid only on the server, this function will create the explosion of type (0,1,2) on the position pos.

void SC_MP_SRV_ClearPlsStats(void);

This function will clear the player statistics, valid only on the server.

void SC_MP_SRV_InitGameAfterInactive(void);

This function will initialize game after being inactive (in the state “Waiting for more players”, valid only on the server.

BOOL SC_MP_GetAmmoBoxesEnabled(void);

This function will return TRUE, if the server has enabled ammo boxes.

void SC_MP_SRV_GetAtgSettings(s_SC_MP_SRV_AtgSettings *info);

This function will get the ATG server settings and place them to the s_SC_MP_SRV_ATGsettings structure.

void SC_MP_SetSpectatorCameras(char character);

This function will set the spectator camera to file character.

void SC_MP_GetRecovers(dword type, s_SC_MP_Recover list, dword items);

This function will fill the array of s_SC_MP_Recover list with recovers of given type. Use items to specify the size of the array, function will return the number of the recover places.

Type can be:

#define SC_MP_RESPAWN_ALL 0 - all respawn points

#define SC_MP_RESPAWN_DM 1 - deathmatch

#define SC_MP_RESPAWN_WA 3

#define SC_MP_RESPAWN_WB 4

#define SC_MP_RESPAWN_WC 5

#define SC_MP_RESPAWN_WD 6

#define SC_MP_RESPAWN_WE 7

#define SC_MP_RESPAWN_WF 8

#define SC_MP_RESPAWN_CTF_US 9 - CTF for US

#define SC_MP_RESPAWN_COOP 10 -for cooperative mode

#define SC_MP_RESPAWN_ATG_US 11 -ATF for US

#define SC_MP_RESPAWN_ATG_PILOT 12 - ATG for pilot

#define SC_MP_RESPAWN_RW_US 13 - RW for US

#define SC_MP_RESPAWN_CTF_VC 14 - CTF for VC

#define SC_MP_RESPAWN_ATG_VC 15 - ATG for VC

#define SC_MP_RESPAWN_RW_VC 16 - RW for VC

#define SC_MP_RESPAWN_TT_DEF_0 17 - for TT defenders

#define SC_MP_RESPAWN_TT_DEF_1 18

#define SC_MP_RESPAWN_TT_DEF_2 19

#define SC_MP_RESPAWN_TT_DEF_3 20

#define SC_MP_RESPAWN_TT_DEF_4 21

#define SC_MP_RESPAWN_TT_ATT_1 22 - for TT attackers

#define SC_MP_RESPAWN_TT_ATT_2 23

#define SC_MP_RESPAWN_TT_ATT_3 24

#define SC_MP_RESPAWN_TT_ATT_4 25

#define SC_MP_RESPAWN_TT_ATT_5 26

void SC_MP_RecoverPlayer(dword pl_id);

This function will instantly recover the player pl_id.

dword SC_MP_FpvMapSign_Load(char *fname);

This function will load the FPV map sign fname and return it’s index.

BOOL SC_MP_FpvMapSign_Unload(dword id);

This function will unload the FPV map sign with id.

void SC_MP_FpvMapSign_Set(dword signs, s_SC_FpvMapSign *list);

This function will set the FPV map signs. Use signs to specify size of the array with signs stored in the s_SC_FpvMapSign structure list.

Functions – various functions

void SC_RadioSetDist(float max_dist_subtitle_write);

This function will set the maximum distance from the radio to the camera the subtitles will be shown.

void SC_SetObjectScript(char obj_name, char script_name);

This function can be used to force the specific object script to the dynamic object during the scene initialization callback of the level script.

void SC_DisplayBinocular(BOOL enable);

Enabled/disables displaying of the binocular.

void SC_PreloadBES(dword id, char *bes_name);

This function is used to preload the special equipment for the players during the scene initialization callback of the level script. See here.

void SC_PreloadWeapon(dword type, BOOL fpv_to);

This function will preload the selected weapon, if fpv_to == TRUE including the FPV model.

void SC_PreloadSound(dword snd_id, BOOL is3D);

This function will preload the selected sound.

void SC_LevScr_Event(dword param1, dword param2);

This function will send the message to the level script with the specified parameters.

BOOL SC_GetScriptHelper(char name, s_sphere sph);

This function will fill the sph with the size and position of the script helper name. It will return FALSE if the script helper doesnot exist.