PROGRAMMING BASICS

(for C++ users only)

Open your compiler and visualize the code in the 3impactDLL.cpp file. Follow this tutorial to know
how to do so.

If you have never programmed before, consider the lines of text on your screen as the steps of a
recipe. The engine will read each line of code from the top to the bottom, and will perform the
action specified by each line.

In some cases, it will execute a sequence of lines again and again, in a loop. It can also execute
sections of the code only if certain conditions are met.

Read this document for an overview of what the engine does with the 3impactDLL.cpp code (DLL
code).

Note that text lines preceded by // are comments, not code lines. They are completely invisible to
the engine. They are only meant to provide the human reader additional information about the
code.

Also note that each code line must terminate with a semicolon (;). Forgetting to do so when
writing your own code is a very common mistake.

The only quick way to understand the DLL code is to try modifying it a little bit and then compile
and run the DLL to see what the engine does.

This document provides some basic concepts that will help you understand how the DLL code
works in general and learn how to write your own.

INCLUDES

The code starts with some include lines like

#include <windows.h>
#include <stdio.h>
#include <math.h>
#include "..\common\3impactDLL_defs.h"

Include lines are not lines of code. Instead they specify additional files that include lines of code
written by others. Such external code allows you to call specific functions in your custom DLL
code. For example, you can call the function named iCameraCreate() because you have included
the 3impactDLL_defs.h external file.

Includes are used to enable access to common C functions, Windows interfaces, 3Impact-specific
functions and even custom written function libraries and DirectX® functions not directly supported
by the engine.

VARIABLE DEFINITION

The second section of the DLL code is a sequence of variable definitions, like

CAMERA* Camera;
SPRITE* LoadingMessage;
SKYBOX* SkyBox;
BODY* Terrain;
MESH* TerrainMesh;
BODY* Ball;
MESH* BallMesh;
MESH* BallMeshShadow;
BODYBODY* BallTerrain;

Each line defines a variable. Each definition is made of a type specifier, like for example MESH*,
followed by a custom name, for example BallMesh.

Defining a variable means assigning a type and a name to a small portion of system memory
(Ram). For example

float MyValue;

gives the name MyValue to a block (4 bytes) of memory, and assigns the type float to it.

It basically means that when the engine executes a line of code like

MyValue = 17.379f;

the value 17.379 is put into the memory associated with MyValue. Note that the f at the end of the
value is needed. It tells the compiler that the constant value specified is a floating point number.

Because MyValue is of type float, you can only put floating point numbers in it.

Variables of specific types can store specific types of data only. For example

CAMERA* MyCamera;

defines a variable named MyCamera that can only be used to store a camera object, as returned
by iCameraCreate() function. For example

MyCamera = iCameraCreate(0,0,100,100);

VARIABLE TYPES

The primary variable types you will use in your DLL code are object variables. Object variable
types include CAMERA*, SKYBOX*, BODY*, MESH*, etc.

They are used to store the handles of created objects (cameras, meshes, etc), so that they can
be passed as parameters, elsewhere in your code, to object-manipulation functions, like for
example iCameraLocationSet().

Another very common type of variable is float (see above). It is used to store values and can be
used in expressions, like

ValueA = (ValueB + 2.3f) * ValueC;

The D3DXVECTOR3 type is very common too. It is used to store a set of 3 floats so that they can
be efficiently manipulated as if they were one single variable. This type is used to store vectors.

Each single element of a vector variable can be accessed by using a special syntax, which wants
the variable name, followed by a dot, followed by x, y, or z. For example

D3DXVECTOR3 MyVector;
MyVector.x = 1.4f;
MyVector.y = 0.0f;
MyVector.z = 2.0f;

The D3DXQUATERNION type is similar, but it is made of a set of 4 floats. It is used to store 3d
object orientations.

ARRAYS

You can define any number of variables of the same type with one single definition. For example,
you can define a list (array) of 100 variables of type float as follows:

float MyValue[100];

where MyValue is the name of the array.

You can access each variable in the array with something like

MyValue[76] = 11.371f;

Note that the first variable of the array is MyValue[0] and that the last one, in this case, is
MyValue[99].

Accessing (e.g. trying to put a value into) variables past the last one defined produces strange
bugs that are hard to find and fix, and is a very common mistake.

Other valid array definitions are

D3DXVECTOR3 MyVector[120];
MESH* MyMesh[20];

VARIABLE SCOPE

Defined variables can only be used in the lines of code that follow the definition. Trying to use a
variable in the lines that precede the definition, will result in an 'undefined variable' error
message, when the DLL code is compiled.

Variables defined inside a {...} section, like for example inside a callback function as follows

void Run()
{
float temp;
...
}

cannot be used outside that section. It means, for example, that the temp variable defined above
is not available (not defined) in the Init() {...} section.

Note, however, that the temp variable IS defined in any nested {...} section within the Run() {...}
section. For example

void Run()
{
float temp;
temp = Timer + 3.5f;
if (temp > 10.0f)
{
 temp = 0.0f;
}
...
}

the temp variable CAN be used in the if() {...} section.

EXECUTABLE CODE

Executable DLL code is inside the {...} big sections of the callback functions only. You cannot
write executable code outside callback functions' {...} sections. Only include lines and variable
definitions can live outside all {...} sections.

FUNCTION CALLS

The executable code is basically made of just variable expressions and function calls. They are
commands for the engine like create a mesh, place it there, apply this force to it, and so on.

You can recognize a function call because it is a custom name followed by round parentheses.
For example

iMeshShow(BallMesh);

The parentheses can enclose one or more parameters, separated by commas, or no parameters
at all.

Each function wants a specific list of variables (or constants) as parameters. For example,
iParticleAirResistanceSet() wants a PARTICLE* variable as first parameter and a float variable as
second parameter.

So a typical function call for it will look like

iParticleAirResistanceSet(Fire,ResistFactor);

where Fire was defined with

PARTICLE* Fire;

and ResistFactor was defined with

float ResistFactor;

Or it can look like

iParticleAirResistanceSet(Fire,0.75f);

Where 0.75f is a constant data of type float.

Function parameters can also be expressions, like

iParticleAirResistanceSet(Fire,(Base+User)*0.5f);

The engine will compute the (Base+User)*0.5f expression and will pass the result to the function
as a parameter.

The name for all 3Impact-specific function calls starts with a lower-case i. All 3Impact functions
are described in the Reference document.

NOTE: void PreInit(), void Init(), void Run(), void Exit() and void PostExit() are not function calls.
Instead they are [callback] function definitions because they appear outside all {...} sections. They
are actually formed by the void XXX() line and the whole {...} section that follows it.

THE "IF" STATEMENT

You can have a piece of code executed only if a certain condition is met by using the if statement.
For example

if (temp == 10.0f)
{
//this {...} section is only executed
//when 'temp' contains 10.0f
}

where the parentheses following the if statement enclose an expression and the {...} section
below the if statement line encloses the piece of code to be executed if the expression is TRUE.

The if statement can also be used as follows:

if (temp == 10.0f)
{
//this {...} section is only executed
//when 'temp' contains 10.0f
}
else
{
//this {...} section is only executed
//when 'temp' does NOT contain 10.0f
}

NOTE: two == are used to compare. For example to compare the variable named temp with
10.0f. The whole thing constitutes an expression that can be TRUE or FALSE.

Instead, one single = is used to put something into a variable.

Confusing the two concepts is a common mistake which causes bugs that may be difficult to
understand and fix.

THE "WHILE" STATEMENT

You can have a piece of code executed again and again until a certain condition is met by using
the while statement. For example

temp = 0.0f;
while (temp < 10.0f)
{
...
temp = temp + 1.0f;
}

where the parentheses following the while statement enclose an expression and the {...} section
below the while statement line encloses the piece of code to be executed again and again while
the expression is TRUE.
In the example above, the {...} section is executed 10 times, because at every execution the temp
variable is increased by 1, thus failing to be less than 10 after ten loops (the expression becomes
FALSE).

THE "FOR" STATEMENT

You can have a piece of code executed a specified number of times by using the for statement.
For example

for (int i=0;i<10;i++)

{
...
}

will execute 10 times the lines of code within the the {...} section below the for statement.

There is much more to know about C statements. Try seeking the Web for keywords like 'C
language for statement' or 'C language switch statement'.

REMARKS

The DLL code is ANSI C++. It means that you can use ALL the power provided by C++
syntax when coding your DLL!

Still, with 3Impact, you don't have to understand all that complex stuff coming with typical
C++ code. The simple information provided in this document and a little bit of practice should be
all you need to write your own DLL!

Don't hesitate to seek for help at the forum if you need it. Keep in mind that ALL the guys and
gals at the forum were beginners once!