Using DLL's

Please not that since version 7 there is a new extension mechanism in Game Maker. You are strongly encouraged to use that extension mechanism, rather than the functions described in this section. See http://www.yoyogames.com/extensions for details. These functions are mainly left in for compatibility with the past.

In those cases were the functionality of GML is not enough for your wishes, you can actually extend the possibilities by using plug-ins. A plug-in comes in the form of a DLL file (a Dynamic Link Library). In such a DLL file you can define functions. Such functions can be programmed in any programming language that supports the creation of DLL's (e.g. Delphi, C, C++, etc.) You will though need to have some programming skill to do this. Plug-in functions must have a specific format. They can have between 0 and 16 arguments, each of which can either be a real number (double in C) or a null-terminated string. (For more than 4 arguments, only real arguments are supported at the moment.) They must return either a real or a null-terminated string.

In Delphi you create a DLL by first choosing New from the File menu and then choosing DLL. Here is an example of a DLL you can use with Game Maker written in Delphi. (Note that this is Delphi code, not GML code!)

library MyDLL;

uses SysUtils, Classes;

function MyMin(x,y:double):double;  cdecl;
begin
  if x<y then Result := x else Result := y;
end;

var res : array[0..1024] of char;

function DoubleString(str:PChar):PChar; cdecl;
begin
  StrCopy(res,str);
  StrCat(res,str);
  Result := res;
end;

exports MyMin, DoubleString;

begin
end.

This DLL defines two functions: MyMin that takes two real arguments and returns the minimum of the two, and DoubleString that doubles the string. Note that you have to be careful with memory management. That is why I declared the resulting string global. Also notice the use of the cdecl calling convention. You can either use cdecl or stdcall calling conventions. Once you build the DLL in Delphi you will get a file MyDLL.DLL. This file must be placed in the running directory of your game. (Or any other place where Windows can find it.)

To use this DLL in Game Maker you first need to specify the external functions you want to use and what type of arguments they take. For this there is the following function in GML:

external_define(dll,name,calltype,restype,argnumb,arg1type,arg2type, ...) Defines an external function. dll is the name of the dll file. name is the name of the functions. calltype is the calling convention used. For this use either dll_cdecl or dll_stdcall. restype is the type of the result. For this use either ty_real or ty_string. argnumb is the number of arguments (0-16). Next, for each argument you must specify its type. For this again use either ty_real or ty_string. When there are more than 4 arguments all of them must be of type ty_real.

This function returns the id of the external function that must be used for calling it. So in the above example, at the start of the game you would use the following GML code:

{
  global.mmm = external_define('MyDLL.DLL','MyMin',dll_cdecl,
                                     ty_real,2,ty_real,ty_real);
  global.ddd = external_define('MyDLL.DLL','DoubleString',dll_cdecl,
                                     ty_string,1,ty_string);
}

Now whenever you need to call the functions, you use the following function:

external_call(id,arg1,arg2,...) Calls the external function with the given id, and the given arguments. You need to provide the correct number of arguments of the correct type (real or string). The function returns the result of the external function.

So, for example, you would write:

{
  aaa = external_call(global.mmm,x,y);
  sss = external_call(global.ddd,'Hello');
}

If you don't need to use the DLL anymore you had better free it.

external_free(dll) Frees the DLL with the given name. This is in particular necessary if the game should remove the DLL. As long as the DLL is not freed it cannot be removed. Best do this e.g. in an end of game event.

You might wonder how to make a function in a DLL that does something in the game. For example, you might want to create a DLL that adds instances of objects to your game. The easiest way is to let your DLL function return a string that contains a piece of GML code. This string that contains the piece of GML can be executed using the GML function

execute_string(str,arg0,arg1,...) Execute the piece of code in the string str with the indicated arguments.

Alternatively you can let the DLL create a file with a script that can be executed (this function can also be used to later modify the behavior of a game).

execute_file(fname) Execute the piece of code in the file.

Now you can call an external function and then execute the resulting string, e.g. as follows:

{
  ccc = external_call(global.ddd,x,y);
  execute_string(ccc);
}

In some rare cases your DLL might need to know the handle of the main graphics window for the game. This can be obtained with the following function and can then be passed to the DLL:

window_handle() Returns the window handle for the main window.

Note that DLLs cannot be used in secure mode.

Using external DLLs is an extremely powerful mechanism. But please only use it if you know what you are doing.