DLL-kirjastojen käyttäminen

Huomaa, että versiosta 7 lähtien Game Makerissa on uusi laajennusmekanismi. On erittäin suositeltavaa, että käytät tätä uutta laajennusmekanismia tässä osiossa esiteltyjen funktioiden sijaan. Katso lisätietoja seuraavalta sivulta: http://www.yoyogames.com/extensions (englanninkielinen). Nämä funktiot on pääasiassa jätetty aiempien versioiden yhteensopivuuden takia.

Niissä tapauksissa, kun GML ei enää riitä toteuttamaan haluamaasi, voit laajentaa mahdollisuuksia käyttämällä lisäosia. Lisäosat tulevat DLL-tiedostojen (Dynamic Link Library) muodossa. Tällaisessa DLL-tiedostossa voidaan määrittää funktioita. Nämä funktiot voidaan ohjelmoida millä tahansa ohjelmointikielellä, joka tukee DLL:ien luomista (esim. Delphi, C, C++, jne.). Tähän tarkoitukseen sinulla tulee tosin olla hieman ohjelmointitaitoja. Lisäfunktioilla täytyy olla tietty muoto. Niillä voi olla 0 - 16 argumenttia, joista jokainen voi olla joko reaaliluku (C:ssä double) tai null:iin päättyvä merkkijono. (Yli neljän argumentin funktioilla vain reaalilukuargumentteja tuetaan tällä hetkellä.) Funktioiden täytyy palauttaa joko reaaliluku tai null:iin päättyvä merkkijono.

Delphissä DLL luodaan valitsemalla ensin File-valikosta New ja valitsemalla sitten DLL. Tässä on esimerkki Delphillä kirjoitetusta DLL:stä, jota voit käyttää Game Makerin kanssa. (Huomaa, että tämä on Delphi-koodia, ei GML-koodia!)

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.

Tämä DLL määrittelee kaksi funktiota: MyMin, joka ottaa kaksi reaalilukuargumenttia ja palauttaa pienemmän näistä kahdesta, sekä DoubleString, joka kaksinkertaistaa merkkijonon. Huomaa, että sinun on oltava varovainen muistinkäsittelyn kanssa. Siksi palautuva merkkijono on asetettu globaaliksi. Huomaa myös cdecl kutsumistapa. Voit käyttää joko cdecl tai stdcall kutsumistapaa. Kun teet DLL:n Delphillä, saat tiedoston nimeltä MyDLL.DLL. Tämä tiedosto on sijoitettava pelisi suoritushakemistoon (tai muuhun paikkaan, mistä Windows löytää sen).

Käyttääksesi tätä DLL:ää Game Makerissa tulee ensin määrittää ulkoiset funktiot, joita haluat käyttää, sekä se, minkätyyppisiä argumentteja ne ottavat. Tätä varten GML:ssä on olemassa seuraava funktio:

external_define(dll,name,calltype,restype,argnumb,arg1type,arg2type, ...) Määrittää ulkoisen funktion. dll on dll-tiedoston nimi. name on funktion nimi. calltype on käytettävä kutsumistapa. Aseta sen arvoksi joko dll_cdecl tai dll_stdcall. restype on palautuksen tyyppi. Aseta sen arvoksi joko ty_real tai ty_string. argnumb on argumenttien lukumäärä (0-16). Seuraavaksi sinun on määriteltävä jokaiselle argumentille sen tyyppi. Aseta sen arvoksi jälleen joko ty_real tai ty_string. Kun funktiolla on enemmän kuin neljä argumenttia, kaikkien niistä on oltava tyyppiä ty_real.

Tämä funktio palauttaa ulkoisen funktion id:n, jota on käytettävä sen kutsumiseen. Yllä annetussa esimerkissä käyttäisit siis pelin alussa seuraavaa GML-koodia:

{
  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);
}

Kun haluat kutsua näitä funktioita, käytä seuraavaa funktiota:

external_call(id,arg1,arg2,...) Kutsuu ulkoista funktiota annetulla id:llä ja annetuilla argumenteilla. Oikeantyyppisiä (reaaliluku tai merkkijono) argumentteja on annettava oikea määrä. Funktio palauttaa ulkoisen funktion tuloksen.

Voisit siis esimerkiksi kirjoittaa:

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

Kun et enää tarvitse DLL:ää, on parasta vapauttaa se.

external_free(dll) Vapauttaa annetun indeksin mukaisen DLL:n. Tämä on erityisen tärkeää, jos pelin tulisi poistaa DLL. Niin kauan, kuin DLL:ää ei ole vapautettu, sitä ei voida poistaa. Tämä on parasta tehdä esim. pelitapahtuman lopussa.

Saatat ihmetellä, miten DLL:ään tehdään funktio, joka tekee jotain pelissä. Voit esimerkiksi haluta luoda DLL:n, joka lisää objektien instansseja peliisi. Helpoin tapa on laittaa DLL-funktio palauttamaan merkkijonon, joka sisältää GML-koodinpätkän. Tämä merkkijono, joka sisältää GML-koodia, voidaan suorittaa käyttämällä seuraavaa GML-funktiota:

execute_string(str,arg0,arg1,...) Suorittaa str-merkkijonon koodin annetuilla argumenteilla.

Vaihtoehtoisesti voit laittaa DLL:n luomaan skriptin sisältävän tiedoston. Tämä skripti voidaan suorittaa seuraavan funktion avulla (tätä funktiota voidaan käyttää myös pelin toiminnan myöhempään muunteluun):

execute_file(fname) Suorittaa koodinpätkän annetusta tiedostosta.

Voit nyt kutsua ulkoista funktiota ja sitten suorittaa palautuvan merkkijonon esim. seuraavasti:

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

Joissain harvoissa tapauksissa saatat haluta välittää DLL:llesi pelin pääikkunan kahvan tunnuksen. Tämä saadaan seuraavalla funktiolla ja se voidaan sitten välittää DLL:lle:

window_handle() Palauttaa pääikkunan kahvan tunnuksen.

Huomaa, että DLL:iä ei voi käyttää turvatussa tilassa (Secure mode).

Ulkoisten DLL:ien käyttö on erittäin tehokas mekanismi. Käytä sitä kuitenkin vain, jos tiedät, mitä olet tekemässä.