Lesson 2: Using Script objects in a DLL

We have learned how to add new lite-C instructions, but how can we access lite-C variables, objects and functions from within a DLL? We have some library functions to do that. All library functions provided by the SDK are preceded by engine_. The most often used function is engine_getvar. This function returns the address of a lite-C struct or variable with the given name. It can be used to read or write to any lite-C object from inside a DLL plugin. If the object does not exist, NULL is returned and an error message will pop up. Examples for DLL functions that access lite-C objects:

// adds the given value to a lite-C vector
void AddToMyVector(var value)
{
// get the address of the vector
  static VECTOR* myvector = NULL;
  if (!myvector) myvector = (VECTOR*)engine_getvar("myvector",NULL);

// add the same value to the 3 components
  myvector->x += value;
  myvector->y += value;
  myvector->z += value;
}

var myvector[3] = { 1,2,3 };

engine_getvar returns a pointer to this vector, which is an array of var and thus can be cast to a VECTOR pointer defined in atypes.h. Why don't we have to convert to/from var here? Because value is already of type var and we can add two vars just as we add two integers. However we could not do this with multiplication and division.

It would not be wise to obtain the myvector pointer every time when calling this function. engine_getvar is slow because it has to find the address in a hash table. Therefore, the pointer to myvector is defined static here, so it's only initialized the first time. Normally you would have a global list of pointers to all lite-C objects that you need in your DLL, and obtain the pointers once at the beginning in a startup function by calling engine_getvar for any of them.

So now we know how to read and change a lite-C variable, but how about more complex objects, like panels, views or entities? Take a look at atypes.h - there you will find declared all structs known to lite-C, like STRING, ENTITY, PARTICLE, BMAP, TEXTURE etc. You can get a pointer to such a struct the same way as to a variable.

There are some variables and pointers already defined in the engine. We don't need engine_getvar for them - all engine variables can be accessed through the v() macro that is also defined in adll.h. For instance, v(camera) returns the predefined camera view:

// zooms the camera view
void Zoom(var value)
{
  v(camera)->arc -= value; // change the FOV
}

As you can see in the struct declarations in atypes.h, the VIEW struct contains all the parameters that you are used from lite-C, like arc, ambient etc., and once you have the pointer you can change and read all of them.

So now we know how to access all lite-C objects, and call DLL functions from lite-C. But how do we do the opposite - calling engine and lite-C functions from a DLL? You'll learn that in the next lesson.