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 jätetty lähinnä aiempien versioiden yhteensopivuuden takia.

Silloin, kun GML ei enää riitä toteuttamaan haluamaasi, voit laajentaa mahdollisuuksia käyttämällä lisäosia. Lisäosat ovat muodoltaan DLL-tiedostoja (Dynamic Link Library, dynaaminen linkkikirjasto). DLL-tiedostossa voidaan määrittää funktioita, jotka voidaan ohjelmoida millä tahansa DLL-kirjastojen luomista tukevalla ohjelmointikielellä (esim. Delphi, C, C++, jne.). Niiden tekemiseen tarvitaan tosin ohjelmointitaitoja. Lisäfunktioiden on noudatettava tietynlaista muotoa. Niillä voi olla 0-16 argumenttia, joista jokainen voi olla joko reaaliluku (C:ssä tietotyyppi double) tai null-katkaisumerkkiin päättyvä merkkijono. (Jos argumentteja on enemmän kuin neljä, tällä hetkellä kaikkien argumenttien on tällöin oltava reaalilukutyyppisiä.) Funktioiden on palautettava joko reaaliluku tai null-katkaisumerkkiin 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 niistä pienemmän, sekä DoubleString, joka kaksinkertaistaa merkkijonon. Muistinkäsittelyn kanssa on oltava varuillaan. Siksi palautuva merkkijono on asetettu globaaliksi. Huomaa myös cdecl-kutsumistapa. Voit käyttää joko cdecl tai stdcall -kutsumistapaa. Kun teet DLL-tiedoston Delphillä, syntyvän tiedoston nimi on MyDLL.DLL. Tämä tiedosto on sijoitettava pelin 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.

Voit siis esimerkiksi kirjoittaa:

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

Kun et enää tarvitse DLL:ää, vapauta se.

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

Saatat ihmetellä, miten DLL:ään tehdään funktio, joka vaikuttaa jotenkin pelin kulkuun. Haluat ehkä esimerkiksi luoda DLL:n, joka lisää objektien instansseja peliisi. Helpoin tapa on määrittää DLL-funktion ulostuloarvoksi merkkijono, 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 määrittää 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 voi olla tarpeen välittää DLL-tiedostolle pelin ikkunan kahvan tunnus. Tämä saadaan selville seuraavalla funktiolla ja 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ä niitä kuitenkin vain, jos tiedät, mitä olet tekemässä.