Ez a hasznos kis program a Game Maker (GM) honlapján található (http://www.gamemaker.nl/resource.html), amelynek segítségével saját játékainkat is alkalmassá tehetjük MOD típusú zenék lejátszására.
Mivel a leírásban jópár helyen előfordulnak szakkifejezések (pl. "zxx parancsok"), ez néhol ronthatja a fordítás érthetőségét is. Ezért, és a jórészt ebből fakadó esetleges félrefordításokért előre is elnézést kérek.

granit2@freemail.hu - 2004. május 27-28. (a 2.0-s változattal frissítve: 2005. május 11-12.)

JBFMOD 2.0

Modul lejátszó kiterjesztés a Game Maker 5 és 6 számára (M. Rijks, 2005 március)

A JBFMOD egy eljárás MOD-ok és MOD típusú hangok lejátszására a GM játékokban.

Mi újság?

- 2.0-s változat:

A 2-es változat egy újraírás a semmiből az elsőhöz képest, köszönhetően az eredeti forrásállomány elvesztésének. A változtatások nagy száma miatt nem lehet csak úgy egyszerűen kicserélni a régi JBFMOD DLL fájlokat a jelenlegivel, ezért tanácsos átnézned a régi GMD vagy GM6 forrásfájljaidat az új parancsok tekintetében.

• Megváltozott függvénynevek - most mindegyikük kisbetűs, hogy megfeleljen a GML stílusnak, és jbfmod-dal kezdődnek, utalva az eljáráskönyvtárra.
• jbfmod_load_song_pack() függvény hozzáadása modulok betöltéséhez egy zenecsomag fájlból.
• jbfmod_init_spectrum(), jbfmod_get_spectrum(), jbfmod_get_spectrum_mean() és jbfmod_close_spectrum() függvények hozzáadása a valódi spektrum (színkép) működéshez.
• jbfmod_get_instrument_played() és jbfmod_get_instrument_playedonce() függvények hozzáadása annak leellenőrzésére, hogy egy bizonyos hangszer lejátszva volt-e.
• jbfmod_get_zxx(), jbfmod_get_zxx_played() és jbfmod_get_zxx_playedonce() függvények hozzáadása a Zxx parancsok kiolvasására a modulokban.
• jbfmod_is_finished() függvény hozzáadása annak leellenőrzésére, hogy egy dal lejátszása befejeződött-e.
• jbfmod_set_looping() függvény hozzáadása egy MOD ismétlésének be- vagy kikapcsolására.
• jbfmod_get_current_song() függvény hozzáadása annak megtekintésére, hogy jelenleg melyik helyen játszódik zene.
• jbfmod_get_song_exists() függvény hozzáadása annak leellenőrzésére, hogy egy bizonyos hely tartalmaz-e dalt.
• A jbfmod_set_paused() függvénynek most van egy paramétere a szüneteltetés be- vagy kikapcsolására.
• jbfmod_get_errorcode() és jbfmod_get_errormessage() függvények hozzáadása annak megtekintésére, hogy miért volt sikertelen egy előző függvény hívása.
• A memóriában lévő MOD-ok legnagyobb számának megnövelése 128-ra.
• A visszajátszási (playback) csatornák legnagyobb számának megnövelése 512-re.
• Jobb megbízhatóság SoundBlaster Live hangkártyákon, köszönhetően a frissített FMOD.DLL-nek.
• Új bemutatók (csak Game Maker 6-nál).
• Eltávolítva: JukeBox_GetVU() és JukeBox_GetVUPerFreq() függvények, melyek a spektrummal lettek kicserélve.

- 1.0-s változat:

Az eredeti kiadás (a GM 4-es változatához készült, ezért az ennél újabb GM változatokban való használatához először át kell alakítani a Conv4to5 programmal, mely a http://www.gamemaker.nl/old.html oldalról tölthető le).

Mik a MOD-ok?

A modulok vagy MOD-ok a MIDI (digitális hangszerillesztő) állományokra hasonlítanak. Hangjegyek sorozatát tartalmazzák, melyek egy zenedarabot alkotnak. De ahol a MIDI hangszerszintézist alkalmaz a hangkártyán, a MOD-ok mintavételezéssel állítják elő a hangot. Az előny a szabad választás a hangszerek között, és a pillanatnyi hang fölötti teljes ellenőrzés. Ezenkívül a tracker-ekkel (MOD-okat létrehozó alkalmazások) készített zene ugyanúgy hangzik minden számítógépen, míg a MIDI-k a hangkártya tulajdonságától függenek. Némi hátrány, hogy a MOD-ok és a MOD-szerű formátumok (S3M, XM és IT) nagyobbak, mint a MIDI-k, mert a visszajátszáshoz használt mintavételeket is tartalmazzák. A MOD-ok lejátszása több processzoridőt is használ.

Ha érdekel a MOD-ok készítése, kitűnő tájékoztatást találhatsz a http://www.modplug.com címen. Itt ingyenes lejátszókat, tracker-eket, zenéket, stb. találhatsz.

Mi az FMOD?

Az FMOD a Firelight Multimedia egy terméke. Ez egy futásidőben kapcsolódó eljáráskönyvtár (DLL), mely egy általános függvényhalmaz a programfejlesztők számára, hogy alkalmazásaikban hangokat is használhassanak. Jelenleg a Protracker, Fasttracker(2), Scream Tracker 3 és Impulse Tracker modultípusokat támogatja.

Mi a JBFMOD?

A JBFMOD a JukeBox FMOD rövidítése. Biztosítja az FMOD eljáráskönyvtárhoz való hozzáférést, és arra íródott, hogy lehetővé tegye MOD, S3M, XM és IT formátumú zenék visszajátszását a GM-ben. Az egész két DLL állományból, leírásból, a ToPack alkalmazásból (2.0-tól), két bemutatóprogramból és egy eljáráskönyvtárból áll. A JBFMOD egyszerre 128 (az 1.0-ban 32) dal betöltését teszi lehetővé. Minden alapvető dolgot tud, ami egy zenelejátszótól elvárható (lejátszás, megállítás, szünet, számok átugrása, hangerő állítása, információk kiírása a dalról).

Jogi tudnivalók

Az FMOD.DLL-t a Firelight Multimedia készítette, és nem kereskedelmi célú termékekkel szabadon használható és terjeszthető, de ha már árusítod a játékodat, akkor az engedélyért vedd fel a kapcsolatot a Firelight Multimedia-val. Olvasd el a mellékelt FMODLICENSE.TXT-t, vagy látogasd meg a honlapjukat a http://www.fmod.org címen.

A JBFMOD.DLL eljáráskönyvtárat és a hozzá társított függvényeket én készítettem. Ez az állomány és a belőle származók szabadon használhatók ingyenes és kereskedelmi célú programokban, feltéve, hogy csak a játékodban való hangkeltésre használatos, de nem árusítható mint önállóan működő kiterjesztése a GM-nek.

A JBFMOD-ot a saját felelősségedre használd. Semmi sem romolhat el, de ha mégis, az a te felelősséged.

A bemutatókról

Ez a csomag két bemutatóprogramot tartalmaz. Mindkettő a GM 6 számára íródott, bár a JBFMOD eljáráskönyvtárak és a függvény használható a GM 5-ben is. A bemutatók kódját és grafikáját én készítettem, az általuk használt dalok pedig különböző eredetűek.

A PLAYER.GM6 egy kis, Winamp-szerű lejátszó, ami tartalmazza majdnem az összes JBFMOD funkciót. A 8 demó dalt a MUSIC.PAK fájl tartalmazza, amelynek mérete mindössze 463 kilobájt. A 8-ból hét dal 100 kilobájt alatt van.

A ZXXDEMO.GM6 egy spektrum demó, ami használja a Zxx visszahívásokat. Dőlj hátra, és élvezd a Dire Straits klasszikusokat IT formátumban. 1 GHz-es PC szükséges hozzá.

A csomagfájlokról

64 MOD zeneszámot csomagolhatsz egy egyszerű csomagfájlba. Egy csomagfájlnak számos előnye van azontúl, hogy MOD fájlok elkülönítésére használható. A részletekért nézd át a TOPACK.RTF fájlt, amit megnyithatsz a TOPACK.EXE alkalmazásban is. Ezzel kapcsolatos parancs, amellyel a csomagfájlból kiolvashatjuk a dalokat, a jbfmod_load_song_pack(), melynek leírása a parancsok ismertetésében található.

Rendszerigény

Az alábbi lista a JBFMOD és FMOD használatához szükséges rendszerjellemzőket tartalmazza. Ezek némelyike feltételezés, és a többi a GM gépigénye.

- Pentium 233+ MHz processzor
- 16 MB memória
- Windows 98
- DirectX 5.0 (8.0 a GM 6-nak)
- a GM 5.x vagy 6-os regisztrált változata

Hogyan kezdjük

Hogyan tudod lejátszani a MOD-okat a játékodban?

1. Mindenekelőtt a JBFMOD.DLL és FMOD.DLL állományoknak a játékod mellett kell lenniük, ugyanabban a mappában. A Windows mappájába (ez rendszerint a C:\WINDOWS) is bemásolhatod őket, ezesetben minden GM állomány számára elérhetőek lesznek, de ha másnak is oda akarod adni a játékot, akkor el kell helyezned ezeket az állományokat is mellé.
2. Nyisd meg a játékodat a GM-ben, és csatold hozzá a JBFMOD.GML (az 1.0-ban Jukebox_Fmod szerepel itt és a parancsokban, ahol a 2.0-ban csak jbfmod van) eljáráskönyvtárt (GM 5-től ez a Scripts/Import scripts-szel történik).
3. Válassz egy tárgyat, amely csak egyszer jön létre a játék során. Erre a feladatra rendszerint egy vezérlő a megfelelő tárgy. A tárgynak nem kell ismétlődőnek (persistent) lennie. A Létrehozás (Create) eseményéhez válaszd az Execute a script-et, ennek listájából pedig a jbfmod_init-et. 0. argumentumához a 3, 1. argumentumához pedig a 16 értéket add meg. Ez beállítja az FMOD-ot 16 csatornára 44 Khz-en.
4. Válaszd ismét az Execute a script-et, a listából pedig a jbfmod_load_song-ot. Az argument0 azt a helyet határozza meg, ahová a dal betöltődjön. Ide az 1-et add meg. Az argument1 a betölteni kívánt dal teljes elérési útja, vagy csak az állomány neve, ha ugyanabban a mappában van, mint a GMD állományod. Gépeld be a megfelelőt egyszeres vagy kétszeres idézőjelek közé.
5. Végül ismét válaszd az Execute a script-et, a listából pedig a jbfmod_play_song-ot. A 0. argumentumban add meg a lejátszani kívánt dal számát. Mi most csak az első helyre töltöttünk be dalt, ezért az 1-es számot adjuk meg.

A 3-5 lépések kódban is megvalósíthatók. Helyezd el a következőt egy csak egyszer végrehajtódó eseményben:
jbfmod_init(3,16);
jbfmod_load_song(1,'mymusic.mod');
jbfmod_play_song(1);

Ennyi. Amint elkezdődik a játékod és létrejön a tárgy, a dal lejátszása megkezdődik. Jegyezd meg, hogy ha másnak is odaadod a játékot, akkor az FMOD.DLL-t és a JBFMOD.DLL-t is mellékelned kell.

A függvények használata

Nem muszáj felhasználnod a mellékelt szkripteket, hacsak nem szeretsz játszadozni a külső meghatározásokkal és parancshívásokkal.

Kétféle módon használhatod a JBFMOD függvényeket. Vagy a fogd és vidd módszerrel (vagyis az Execute a script ikonon keresztül), vagy parancsként a saját kódjaidban, mint ahogy fentebb volt.

A függvények mindig visszaadnak egy értéket. Ezt nem muszáj mindig használni, csak amikor szükséges, tehát ha kell, akkor el lehet menteni egy változóba, mint más GM függvénynél is, pl.:

ertek=jbfmod_play_song(1);

... de akár érvényes így is ...

jbfmod_play_song(1);

Némely függvénynél a visszaadott értéknek van egy célja (például a dal nevét megkapni vele), míg a többiek csak egy vizsgálat eredményét adják vissza, hogy egy cselekvés sikeresen végrehajtódott-e (amely értéknél az 1 jelentése az igen / igaz / sikeres és a 0 jelentése a nem / hamis / sikertelen). Ha a függvény visszaadja ezen értékek közül az egyiket, akkor a jbfmod_get_errorcode() vagy jbfmod_get_errormessage() függvényeket használhatod további információk szerzésére bármilyen hiba esetén.

Tanácsok

Itt egy rövid listája azon dolgoknak, amelyeket észben kell tartanod a JBFMOD használata közben.

• Korábban a JBFMOD használói említést tettek a SoundBlaster Live hangkártyával való összeférhetetlenségről: a játékok leálltak az inicializáláskor. Ez valójában egy állandó hiba a SB Live meghajtóprogramokban, és lehet, hogy megoldódott a SB Live hangkártya meghajtók legújabb változattal való frissítésével. Ezt megjegyzésként beleírhatod a játékod tájékoztatójába is.
• Ha egy JBFMOD parancs egy vagy több paramétert használ, akkor bizonyosodj meg ezek pontos megadásáról, mert a GM hajlamos a külső függvények helytelen számú paraméterekkel való hívására.
• A hangkimenet és a MOD visszajátszó nem biztos, hogy tökéletesen egyezik a hangerőt illetően. Gondoskodj a játékodban a hanghatások és a zene hangerejének elkülönített beállításának, vagy a zeneszámok lejátszása kikapcsolásának lehetőségéről.
• A hangszer és Zxx parancs ellenőrzések csak ismétlődő események (pl. Lépés (Step) vagy Rajzolás (Draw)) esetén adnak megfelelő értékeket. A zene valójában gyorsabb lehet, mint a szoba sebessége, ami a játékban a hangszerek vagy a Zxx parancsok tévesztését okozhatja. Ez többnyire a szoba sebességének növelésével megoldható.
• A mester hangerő és a hangszórókhoz való elkülönítés visszaállítják az alapértelmezett értékeiket egy dal (újra)kezdésekor, tehát ezeket újra be kell állítanod, ha minden dal számára ugyanazt a hangerőt és elkülönítést akarod megtartani.
• Bár a spektrum értéktartománya 512 bemenet, MOD visszajátszáshoz csak az első 16-tól 64-ig tűnik érdekesnek, ennyi elég a látványelemek létrehozásához.
• Ha nem hallod az összes csatornát a zenében, akkor lehet, hogy nem inicializáltál elég csatornát a jbfmod.init-tel. Az XM és IT típusú dalok több csatornát igényelnek a visszajátszáskor, mint amennyit a dal valójában tartalmaz (pl. a visszhangzásoknak).
• Bár az FMOD a leggyorsabb MOD visszajátszó rendszernek van kijelentve, tartsd észben, hogy a MOD-ok lejátszása lelassíthatja a játékodat. Ha szükséges, csökkentsd a kimeneti minőséget, és / vagy a visszajátszási csatornák számát az inicializáláskor. Ellenőrizd a jbfmod_get_cpu_usage() függvénnyel, hogy hány százalékban terheli le a CPU-t egy modul a visszajátszással - a jó teljesítmény nem megy 5% fölé. Gondolj a lassabb rendszerekre is, amikor terjeszted a játékodat.

A JBFMOD parancsok

jbfmod_close() - az FMOD hangrendszer leállítása. A hangrendszer mindig leáll, mikor a játék futása befejeződik. Ez a parancs csak akkor szükséges, ha a hangrendszert újra akarjuk indítani a jbfmod_init()-tel.

Pl. jbfmod_close();

A visszaadott érték mindig 1.

jbfmod_close_spectrum() - a színkép leállítása. A spektrum többlet számítási időt igényel, és lelassítja a játékodat, amikor elindul, ezért zárd be, amikor a játék nem használja.

Pl. jbfmod_close_spectrum();

A visszaadott érték mindig 1.

jbfmod_get_bpm() - az éppen játszott MOD percenkénti ütemét adja.

Pl. draw_text(0,0,'BPM: '+string(jbfmod_get_bpm()));

Egy 0 és valószínűleg 2500 közötti értékkel tér vissza.

jbfmod_get_channels_playing() - a csatornák száma, melyek pillanatnyilag lejátszanak egy dalt.

Pl. draw_text(0,0,'Lejátszó csatornák: '+string(jbfmod_get_channels_playing()));

Egy 0 és 128 közötti értékkel tér vissza.

jbfmod_get_cpu_usage() - az FMOD által használt processzoridőt adja százalékban.

Pl. draw_text(0,0,'Használt CPU idő: '+string(jbfmod_get_cpu_usage()));

Ez csak az FMOD, és nem a játék által használt processzoridőt adja.

A visszaadott érték 0 és 100 közötti lehet.

jbfmod_get_current_song() - az éppen lejátszás alatt lévő dal indexét adja.

Pl. draw_text(0,0,'Lejátszás alatt: '+string(jbfmod_get_current_song()));

1 és 128 közötti értéket ad vissza, vagy 0-t, ha nem játszódik dal.

jbfmod_get_errorcode() - visszaadja a legutóbbi hiba kódját. Némely függvény értesít, hogy a hívás sikeres volt-e vagy sem. Ha nem volt sikeres, akkor hívd ezt a függvényt ahhoz, hogy megkapd a hibakódot.

Pl. if jbfmod_load_song(1,'zene.mod')=false
show_message('Hiba: '+string(jbfmod_get_errorcode()));

A következő értékeket adja vissza, vagy 0-t, ha eddig még nem történt hiba:

Megjegyzés: a hibakód nem törlődik, és mindig a legutóbbi hiba, nem pedig a legutóbbi függvényhívás állapota lesz jelezve. A jelenlegi hibaüzenethez a jbfmod_get_errormessage() függvény használható.

jbfmod_get_errormessage() - a legutóbbi hiba üzenetét adja. Némely függvény értesít, hogy a hívás sikeres volt-e vagy sem. Ha nem volt sikeres, akkor hívd ezt a függvényt ahhoz, hogy megkapd a hibaüzenetet.

Pl. if jbfmod_load_song(1,'zene.mod')=false
show_message(jbfmod_get_errormessage());

A hibaüzenetek teljes listája a jbfmod_get_errorcode() függvénynél található.

jbfmod_get_frequency(csatorna) - az adott csatorna (1-128) frekvenciáját adja.

Pl. draw_text(0,0,'A 8-as csatorna frekvenciája: '+string(jbfmod_get_frequency(8)));

A frekvencia ténylegesen a hangmagasság vagy sebesség, melyen a mintavételezés lejátszódik az FMOD által. Ez teljesen eltér a pillanatnyi hang 'valós-idejű' frekvenciájától. Például felvehetünk egy magas és egy alacsony hangot ugyanazon sebességgel. Ezek azonos sebességű visszajátszásakor a frekvencia az FMOD szerint egyenlő lesz, bár a hangok frekvenciában nagyon eltérően mutatkoznak.

0, vagy annál nagyobb értékkel tér vissza.

jbfmod_get_info(jelzőszám) - a JBFMOD változatát és tájékoztatást ad. A jelzőszám a visszaadott szöveg jele, a következő értékekkel: 1: a JBFMOD állományneve, 2: verziószám, 3: állomány dátum, 4: szerző, 5: az FMOD állományneve, 6: az FMOD változata.

Pl. show_message('A JBFMOD készítője: '+jbfmod_get_info(4));

jbfmod_get_instrument_played(hangszer) - visszaadja, hogy vajon a jelzett hangszer (IT formátum) vagy minta (MOD, S3M és XM formátumok) lejátszva volt-e a jelenleg játszott zenében. A hangszer egy 1 és 199 közötti szám.

Pl. if jbfmod_get_instrument_played(1) draw_text(0,0,'Ütem!');

A visszatérési érték 0 ha nem, 1 ha igen.

Megjegyzés: ez a függvény a zene teljes időtartama alatt tájékoztat a jelölt hangszer lejátszásáról, ami nem hasznos, ha hangszerhívásonként csak egyszer akarod vezérelni az eseményeket a játékodban. Egyszeri tájékoztatáshoz használd a jbfmod_get_instrument_playedonce() függvényt.

jbfmod_get_instrument_playedonce(hangszer) - visszaadja, hogy vajon a jelzett hangszer (IT formátum) vagy minta (MOD, S3M és XM formátumok) lejátszva volt-e a jelenleg játszott zenében. A hangszer egy 1 és 199 közötti szám.

Pl. if jbfmod_get_instrument_playedonce(1) instance_create(random(640),random(480),villam);

A visszatérési érték 0 ha nem, 1 ha igen.

Megjegyzés: ez a függvény csak egyszer ellenőriz egy hangszert zenénként. Ez hasznos a vezérlő események számára, amelyeknek a zene lejátszása alatt nem kell folyamatosan irányítaniuk, ellentétben a jbfmod_get_instrument_played() függvénnyel, amely a zene teljes időtartama alatt közli az értéket.

jbfmod_get_master_volume() - a jelenleg játszott MOD hangerejét adja.

Pl. draw_text(0,0,'Fő hangerő: '+string(jbfmod_get_master_volume()));

Egy 0 és 256 közötti értékkel tér vissza.

jbfmod_get_name(hely) - az adott helyen (1-128; 1.0-ban 32-ig ennél és a többi hasonló függvénynél) lévő dal nevét tartalmazó szöveget adja.

Pl. show_message('A 4. dal neve: '+jbfmod_get_name(4));

Ha a megadott hely üres, akkor a '(No song)' szöveget adja. A dal neve a modulban van megadva, ami nem azonos a modul fájlnevével, és a MOD szerzője üresen is hagyhatta a név mezőt.

jbfmod_get_num_channels(hely) - az adott helyen (1-128) lévő dal által használt csatornák teljes száma.

Pl. show_message('A 4. dal összesen '+string(jbfmod_get_num_channels(4))+' csatornát használ.');

A visszaadott érték 1 és 128 közötti, vagy 0, ha a megadott hely üres.

jbfmod_get_num_instruments(hely) - az adott helyen (1-128) lévő dal hangszereinek teljes száma.

Pl. show_message('A 4. dal '+string(jbfmod_get_num_instruments(4))+' hangszert tartalmaz.');

A visszaadott érték 1 és 128 közötti, vagy 0, ha a megadott hely üres. Ez a függvény csak az Impulse Tracker típusú MOD-okra vonatkozik.

jbfmod_get_num_orders(hely) - az adott helyen (1-128) lévő dal sorrendjeinek teljes száma.

Pl. show_message('A 4. dalnak '+string(jbfmod_get_num_orders(4))+' sorrendje van.');

A visszaadott érték 1 és 255 közötti, vagy 0, ha a megadott hely üres.

jbfmod_get_num_patterns(hely) - az adott helyen (1-128) lévő dal mintavételezéseinek teljes száma.

Pl. show_message('A 4. dalnak '+string(jbfmod_get_num_patterns(4))+' mintavételezése van.');

A visszaadott érték 1 és 128 közötti, vagy 0, ha a megadott hely üres.

jbfmod_get_num_samples(hely) - az adott helyen (1-128) lévő dal mintavételezéseinek teljes száma.

Pl. show_message('A 4. dalnak '+string(jbfmod_get_num_samples(4))+' mintavételezése van.');

A visszaadott érték 1 és 128 közötti, vagy 0, ha a megadott hely üres.

jbfmod_get_order() - az éppen játszott MOD rendezési helyzetét adja.

Pl. draw_text(0,0,'Jelenlegi rend: '+string(jbfmod_get_order()));

Egy 0 és 255 közötti értékkel tér vissza.

jbfmod_get_packinfo() - visszaadja a csomag tájékoztatószövegét.

Pl. show_message('Csomag információ: '+jbfmod_get_packinfo());

Visszaad minden csomag információt, ami a legutóbbi olyan csomagba volt elhelyezve, ahonnan egy dal betöltődött. A ToPack alkalmazással adhatsz ilyen tájékoztatót a csomagodhoz. Ez hasznos a fájlokban tulajdonjogi információk elhelyezésére, mintegy aláírásként a csomagban.

Megjegyzés: ezt a függvényt csak a jbfmod_load_song_pack() függvény sikeres használata után lehet hívni.

jbfmod_get_pattern() - az éppen játszott MOD jelenlegi mintavételezését adja.

Pl. draw_text(0,0,'Jelenlegi mintavételezés: '+string(jbfmod_get_pattern()));

Egy 0 és 255 közötti értékkel tér vissza.

jbfmod_get_pattern_length() - az éppen játszott minta sorainak teljes számát adja.

Pl. draw_text(0,0,'A jelenlegi minta sorai: '+string(jbfmod_get_pattern_length()));

Egy 0 és 255 közötti értékkel tér vissza.

jbfmod_get_paused() - a jelenlegi dal lejátszása szünetel-e vagy sem.

Pl. if jbfmod_get_paused() show_message('A lejátszás szünetel.');

A 0-t adja ha nem, 1-et, ha igen.

jbfmod_get_row() - az éppen játszott minta sorát adja.

Pl. draw_text(0,0,'Sor: '+string(jbfmod_get_row()));

Egy 0 és 255 közötti értékkel tér vissza.

jbfmod_get_song_exists(hely) - jelen van-e egy dal a megadott helyen.

Pl. if jbfmod_get_song_exists(4) show_message('A 4. helyen van egy dal!');

A 0-t adja ha nem, 1-et, ha igen.

jbfmod_get_spectrum(sáv) - a megadott sáv (0-511) frekvenciasáv amplitúdóját adja.

Pl. draw_text(0,0,'Sáv 1: '+string(jbfmod_get_spectrum(1)));

Egy 0 és 1 közötti értékkel tér vissza.

Megjegyzés: a teljes színkép határértéke 512 sáv, de a legélénkebb részt az első 64 (0-63) alkotja. A határérték a keverési arány/2-vel van osztva, tehát ha 44100 Hz-re vaninicializálva a JBFMOD, akkor a határérték 0-22050 Hz lesz, ahol a 0 sáv jelenti a 0 Hz-et, az 511-es sáv pedig a 22050 Hz-et, és mindegyik sáv kb. 43 Hz-et jelent.

jbfmod_get_spectrum_mean(sáv1,sáv2) - a megadott frekvenciasáv (mindkettő 0-511) határérték középfrekvenciáját adja.

Pl. draw_text(0,0,'Sáv 0-19: '+string(jbfmod_get_spectrum_mean(0,19)));

Egy 0 és 1 közötti értékkel tér vissza.

Megjegyzés: ez a függvény némely esetben hatásosabb lehet a jbfmod_get_spectrum()-nál, mivel a GM egy kicsit lassú lehet az elkülönített sávok határértékének egyenkénti feldolgozásában és kiolvasásában.

jbfmod_get_speed() - az éppen játszott MOD sebességét adja.

Pl. draw_text(0,0,'A dal sebessége: '+string(jbfmod_get_speed()));

Egy 0 és 15 közötti értékkel tér vissza.

jbfmod_get_time() - azt az időt adja ezredmásodpercben, amióta a jelenlegi dal lejátszás alatt van.

Pl. draw_text(0,0,'A dal ideje: '+string(jbfmod_get_time()));

0, vagy annál nagyobb értékkel tér vissza.

Megjegyzés: ez az idő nem áll vissza alaphelyzetbe amikor a MOD megismétlődik, és nem áll a megfelelő időre a jbfmod_set_order() használatakor.

jbfmod_get_timeformat() - azt az időt adja, amióta a MOD lejátszás alatt van. A szöveg formátumú érték a PP:MM:EE alakban tér vissza, ahol PP a perceket, MM a másodperceket, EE pedig az ezredmásodperceket jelenti.

Pl. draw_text(0,0,'A dal ideje: '+string(jbfmod_get_timeformat()));

Megjegyzés: ez az idő nem áll vissza alaphelyzetbe amikor a MOD megismétlődik, és nem áll a megfelelő időre a jbfmod_set_order() használatakor.

jbfmod_get_type(hely) - a megadott helyen (1-128) lévő modul típusa.

Pl. if jbfmod_get_type(4)=4 show_message('A 4. egy Impulse Tracker dal.');

A visszatérési értékek a következők lehetnek: 0: ismeretlen típus vagy nincs dal betöltve, 1: Protracker / Fasttracker, 2: ScreamTracker, 3: Fasttracker 2, 4: Impulse Tracker.

jbfmod_get_zxx() - visszaadja, hogy melyik Zxx parancs van működésben a jelenlegi zenében.

Pl. if jbfmod_get_zxx()=1 draw_text(0,0,'Az 1-es parancs van működésben.');

1 és 255 közötti értéket ad.

Megjegyzések: - a 0 jelű Zxx parancsot nem lehet használni ezzel, mivel ez a függvény mindig 0-t ad, ha éppen nincs működésben Zxx parancs.
- ha több mint 1 Zxx parancs van működésben, akkor a függvény a legnagyobb csatornaszámmal rendelkezőt adja.
- ez a függvény a zene teljes időtartama alatt tájékoztat a Zxx parancsról, ami nem hasznos, ha Zxx hívásonként csak egyszer akarod vezérelni az eseményeket a játékodban. Egyszeri tájékoztatáshoz használd a jbfmod_get_zxxonce() függvényt.

jbfmod_get_zxx_played(parancs) - visszaadja, hogy a megadott Zxx parancs (0-255) működésben van-e a zenében.

Pl. if jbfmod_get_zxx_played(1) draw_text(0,0,'Az 1-es parancs működésben van.');

0 a visszatérési érték ha nem, 1 ha igen.

Megjegyzés: ez a függvény a zene teljes időtartama alatt tájékoztat a Zxx parancsról, ami nem hasznos, ha Zxx hívásonként csak egyszer akarod vezérelni az eseményeket a játékodban. Egyszeri tájékoztatáshoz használd a jbfmod_get_zxx_playedonce() függvényt.

jbfmod_get_zxx_playedonce(parancs) - visszaadja, hogy a megadott Zxx parancs (0-255) működésben van-e a zenében.

Pl. if jbfmod_get_zxx_playedonce(1) draw_text(0,0,'Az 1-es parancs működésben van.');

0 a visszatérési érték ha nem, 1 ha igen.

Megjegyzés: ez a függvény zenénként csak egyszer ellenőrzi az adott parancsot. Ez hasznos a vezérlő események számára, amelyeknek a zene lejátszása alatt nem kell folyamatosan irányítaniuk, ellentétben a jbfmod_get_zxx_played() függvénnyel, amely a zene teljes időtartama alatt közli az értéket.

jbfmod_get_zxxonce() - visszaadja, hogy melyik Zxx parancs van működésben a jelenlegi zenében.

Pl. if jbfmod_get_zxxonce()=1 instance_create(10,10,robbanas);

1 és 255 közötti értéket ad.

Megjegyzések: - a 0 jelű Zxx parancsot nem lehet használni ezzel, mivel ez a függvény mindig 0-t ad, ha éppen nincs működésben Zxx parancs.
- ha több mint 1 Zxx parancs van működésben, akkor a függvény a legnagyobb csatornaszámmal rendelkezőt adja.
- ez a függvény csak egyszer tájékoztat a Zxx parancsról zenénként, ami hasznos a vezérlő események számára, amelyeknek a zene lejátszása alatt nem kell folyamatosan irányítaniuk, ellentétben a jbfmod_get_zxx() függvénnyel, amely a zene teljes időtartama alatt közli az értéket.

jbfmod_init(keverési arány, maximum csatornák) - az FMOD hangrendszer beállítása. Keverési aránynál az 1-3 értékek használhatók: 1: 11025 Hz (nagyon gyenge hangminőség), 2: 22050 Hz, 3: 44100 Hz (csúcsminőség). Jegyezd meg, hogy a magasabb frekvenciák nagyobb CPU használatot okoznak. A maximum csatornák a lejátszáshoz használt szoftveres csatornák száma; 1-től 512-ig (1.0-ban 128-ig) bezárólag adhatunk meg értéket. Ha úgy tűnik, hogy egy MOD nem játszódik le minden csatornán, valószínűleg nem adtunk meg elég csatornát a kimenetnek. A csatornák ajánlott száma 8 és 16 közötti.

Ezt a parancsot bármely más JBFMOD parancs használata előtt hívni kell, és csak egyszer, kivéve, ha a hangrendszer előzőleg bezáródott a jbfmod_close()-zal. A kimenet mindig sztereó, bár a modulok lehetnek monók.

Pl. jbfmod_init(44100, 16);

Sikeressége esetén 1 a visszaadott érték, egyébként 0.

jbfmod_is_finished() - a jelenlegi dal lejátszása befejeződött-e.

Pl. if jbfmod_is_finished() jbfmod_stop_song();

0 ha nem, 1 ha igen.

Megjegyzés: a függvény eredménye 1, miután a dal elérte a végét, és 1 marad még akkor is, ha újrakezdődött a lejátszása. Ezenkívül, az ismétlődő mintavételezésnek köszönhetően, néhány dal egyáltalán nem áll meg.

jbfmod_is_playing() - egy dal jelenleg játszódik-e.

Pl. if jbfmod_is_playing() show_message('Jelenleg egy dal játszódik.');

Az 1-et adja ha igen, 0-t ha nem.

jbfmod_load_song(hely, MOD elérési út) - egy MOD állomány betöltése a megadott helyre. A hely egy 1 és 128 (1.0-ban 32) közötti szám. Az állomány teljes vagy részleges elérési útját egyszeres vagy kettős idézőjelek között kell megadni.

Ha a megadott helyen már van egy dal, akkor áthelyeződik. Ha már játszódik, akkor először megáll. Bár a játék ideje alatt bármikor betölthető egy dal egy helyre, a lelassulás elkerülése végett jobb, ha az összes zene modul a játék kezdeti részén töltődik be, mivel ez a függvény bizonyos számítási időt igényel.

Pl. jbfmod_load_song(2, "zene.mod");

A visszatérési érték 1, ha sikerült, míg 0, ha nem.

jbfmod_load_song_pack(hely, index, csomag elérési útja) - egy MOD állomány betöltése egy csomagból a megadott helyre. A hely egy 1 és 128 közötti szám. Az index a dal sorszáma a csomagfájlban, ahonnan betöltődik; 1 és 64 közötti szám. Az állomány teljes vagy részleges elérési útját egyszeres vagy kettős idézőjelek között kell megadni.

Ha a megadott helyen már van egy dal, akkor áthelyeződik. Ha már játszódik, akkor először megáll. Bár a játék ideje alatt bármikor betölthető egy dal egy helyre, a lelassulás elkerülése végett jobb, ha az összes zene modul a játék kezdeti részén töltődik be, mivel ez a függvény bizonyos számítási időt igényel. Csomagfájlokat a JBFMOD csomagban mellékelt ToPack programmal lehet létrehozni.

Pl. for (i=1; i<16; i+=1) jbfmod_load_song_pack(i,i,'zene.pak');

A visszatérési érték 1 ha sikeres és 0 ha sikertelen.

jbfmod_play_song(hely) - a dal lejátszása a megadott helyről. A hely 1 és 128 (1.0-ban 32) közötti érték lehet. A jelenleg játszott dal megáll. Ha a megadott helyen nincs dal, akkor nem játszik le semmit.

Pl. jbfmod_play_song(2);

A visszatérési érték 1, ha sikerült, míg 0, ha nem.

jbfmod_set_looping(kapcsoló) - a jelenlegi dal ismétlésének be- vagy kikapcsolása. A kikapcsolás a dal egyszeri lejátszását eredményezi.

Pl. jbfmod_set_looping(false)

1 ha sikeres, 0 ha sikertelen.

jbfmod_set_master_volume(hangerő) - a jelenleg játszott dal hangerejének beállítása. A hangerő értéke 0 és 256 között lehet. Az alapértelmezett érték a 256. A dal (újra)kezdésekor a hangereje visszaáll 256-ra.

Pl. jbfmod_set_master_volume(64);

A visszatérési érték 1, ha sikerült, míg 0, ha nem.

jbfmod_set_order(jel) - ugrás az adott jelű dalra. A jel egy szám 0 és a jelenleg játszott dal száma között.

Pl. jbfmod_set_order(12);

A visszatérési érték 1, ha sikerült, míg 0, ha nem.

Megjegyzés: a sorrend megváltoztatása nem befolyásolja a dal lejátszási idejét. Lásd még a jbfmod_get_time és jbfmod_get_timeformat függvényeket. Ezenkívül a kihagyások a zenében azt eredményezik, hogy az FMOD a dalban parancs és hangszerváltás kihagyásokat okoz, így néhol a hang a vártnál eltérőbb lehet.

jbfmod_set_pan_seperation(elkülönítés) - a hangszórókhoz való elkülönítés (0 és 1 közötti szám; 1 az alapértelmezett) beállítása a jelenlegi dalnál. Egy dal (újra)indulásakor visszaáll 1-re.

Pl. jbfmod_set_pan_seperation(0.3)

A visszatérési érték 1, ha sikerült, míg 0, ha nem.

jbfmod_set_paused(kapcsoló) - szünetelteti (1) vagy folytatja (0) a jelenlegi dal lejátszását.

Pl. jbfmod_set_paused(1);

A visszatérési érték 1, ha sikerült, míg 0, ha nem.

jbfmod_stop_song() - a jelenleg játszott dal leállítása.

Pl. jbfmod_stop_song();

A visszaadott érték mindig 1.

JukeBox_GetVU(csatorna) - az adott csatorna (1-128) VU-ját adja. (a JBFMOD 2.0-ban már nincs benne!)

Pl. VU = JukeBox_GetVU(8);

A VU a megadott csatornán lejátszott hang hullámforma amplitúdója. Az adott csatornán lévő hangerőnél nagyobb vagy kisebb értékként is kiolvasódhat.

Egy tizedes értékkel tér vissza 0-tól 1-ig bezárólag.

JukeBox_GetVUperFreq(alacsonyfrek,magasfrek) - a megadott frekvencia-értéktartomány teljes VU-ját adja. (a JBFMOD 2.0-ban már nincs benne!)

Pl. VUfrek = JukeBox_GetVUperFreq(8000,10000);

Ez a parancs VU-méterek létrehozásának lehetővé tételére lett megalkotva. Ez a parancs nagyon pontatlan.

Egy 0 és annál nagyobb szám közötti tizedes értékkel tér vissza.

Kapcsolatfelvétel

Bár a JBFMOD-ot tartalmazó csomag a GM hivatalos oldaláról tölthető le, elkészítésében Mark Overmars, a GM szerzője nem vett részt, ezért ne hozzá fordulj kérdésekkel ezzel kapcsolatban, hanem hozzám: forge@dds.nl. Kérdezz és nézelődj először a GM fórumán (http://forums.gamemaker.nl), ahol az Extending Game Maker részleg tartalmaz egy fórumot a JBFMOD-ról, amit én gyakran megnézek, és lehet, hogy ott már valaki tudja a választ a kérdésedre.
Ha valamiért nekem küldesz levelet, akkor ne csatolj mellékleteket, mert a postafiókom mérete korlátozott. Ne kérd tőlem a JBFMOD forráskódját - nem fogom odaadni. Abban nem fogok segíteni, hogy a játékodban hogyan használd a JBFMOD-ot; erről a fórumokon kérj segítséget.