Using the sdk
We all know that C-Script is a powerful programming language; I have managed to write the code for several games without touching the sdk at all! However, sometimes you might want to use the sdk, which means that you have bought the sdk and one of these IDEs: Visual C++, C++ Builder or Delphi. You will want to use the sdk if:
- A particular function isn't available in C-Script and you need it really bad;
- You want to wrap some intelligent piece of C-Script code like "my.ambient = 100" because you are afraid that somebody else will steal your code if you don't pack it;
- You are a professional C++ / Delphi programmer and you don't want to use C-Script because it is way too simple for you;
- You have a few critical functions that would run faster if you would write them in C++ or Delphi;
- You want to create some impressive, never seen before effects, or maybe a new rendering sub-system.
Create a new folder named MyDlls in the root of your hard drive.
Start your IDE (I'll use Microsoft Visual C++ 6.0) and then choose to create a new dll project:
Press "OK" and you will see the following window:
Select "A simple DLL project".
Press "Finish" and then "OK". Exit the IDE and explore the newly created folder named \first inside \MyDlls.
Copy the following files from your sdk to \first: a5dll.h, a5funcs.h, a5dll.lib. The result should look like in the picture below:
Double click "first.dsw" to load the project again. Make sure that you have selected "FileView", open "Source Files" and then double click "first.cpp".
Include the two header files:
Time to link the a5dll.lib file to the project; click "Project" and then "Settings":
Select "Category: Input", click "Object / library modules", press the "End" key on your keyboard to move at the end of the row and type "a5dll.lib" without the quotes.
Press "OK" and then build the project:
Congratulations! You've just built your first dll! Take a look at the \debug or \release folders that were created inside your \first folder and you will see a brand new "first.dll" file!
Ok, so we've built a dll that works ok but it doesn't do anything useful! What would be really simple to code and impossible to create with C-Script? Hmm... (about 10 minutes later) I know! Let's create a function that can delete any file on the hard disk! C-Script allows us to delete any file from the "savedir" folder, but our new function would be really useful for a copy protection system, or if we want to delete some temporary files left by the installer used for our game, maybe that annoying scandisk.log file that appears in the root of the hard drive, etc.
We are going to use the C++ function named "remove", which needs <stdio.h> or <io.h> so we have to "include" one of these files. The function that deletes the files consists of only three lines of code (well, it only needs two lines, but we'll be getting there soon). Here's the modified first.cpp file:
Make sure that your first.cpp file looks exactly like this and then build the project; you will get your own first.dll file, which must be copied inside your main game folder (\work if you are using the templates).
The first line of code in the function doesn't do anything useful for us: it gets the variable named "temp" from C-Script and makes it available for our function as "temp". I'm not going to use temp in this function, so why did I do that?
The engine will not work with "standard" dlls; you need to buy the sdk if you want to create them. The a5dll.lib library must be linked to your project even if your functions aren't using any C-Script object; that's why I have decided to grab "temp", although I don't need it. You should use a dummy function or you should add a line of code that looks like mine every time you create a new dll; otherwise you will get an error message that looks like this when you will want to use your dll:
Let's take a look at the last two lines of code inside function KillFile: we get a pointer to the string passed to the function, and then we try to remove the file, returning the result of the operation as an INT2FIX.
That was all the C++ part! Let's see the C-Script file now:
var success = 0;
var_nsave dll_handle;
font std_font = <ackfont.pcx>, 6, 9;
text deletion_txt
{
pos_x = 200;
pos_y = 200;
font = std_font;
flags = visible;
}
I have defined two variables: a variable named success, and one that will be used as a handle to the first.dll file; I chose a var_nsave this time because its value isn't saved to the disk when we use "game_save", so it won't be altered by a "game_load" instruction. I have also defined a simple font and a text that will use it.
dllfunction KillFile(x);
Every function from your dll must be defined inside your C-Script file; the line above does just that.
starter terminate_file
{
dll_handle = dll_open ("first.dll");
while (key_t == 0) {wait (1);}
success = KillFile ("c:\\somefile.txt");
if (success == 0)
{
deletion_txt.string = "The file was deleted successfully";
}
else // success = -1 here
{
deletion_txt.string = "Error while trying to delete the file!";
}
sleep (3);
deletion_txt.visible = off;
dll_close (dll_handle);
}
I have used a "starter" function, a special function that runs by itself at game start; it opens the dll and then it waits until the player presses the "T" key on the keyboard. As soon as that happens, function KillFile from the dll is run and its result is stored in the variable named "success". If the file was deleted, success is set to 0; otherwise, if the file couldn't be deleted, success it set to -1. Where did these values came from? Read the info about "remove" in the MS Visual C++ help.
If the file can be deleted, we set a confirmation string for deletion_txt; otherwise, we set an error string for deletion_txt.The text will be visible for three seconds, and then it will disappear. The last line of code closes the dll; we need to do that whenever we finish our job with it.
That's all! Copy somefile.txt to the root folder of your c:\ drive, run the level and then press "T"; you should see the following image:
Exit the engine, and then run the level again. Press the "T" key and you will see the following image:
The function has tried to delete somefile.txt, but that file couldn't be deleted because it wasn't there anymore! Of course that you can use function KillFile with any file, regardless of its name and extension. Don't forget to use two backslashes when you specify the path of the file.
Use a line of code that looks like the one below if you want to remove a file from the main game folder; that's the folder that contains the first.dll file and it doesn't have to be the "savedir" folder.
success = KillFile ("somefile.txt");