Tracer: Added a little summary to the modules

2022-06-17T16:20:29Z

Added a little summary to the modules

← Older revision		Revision as of 16:20, 17 June 2022
Line 129:		Line 129:

	Po kompilacji, jeżeli wywołamy naszą funkcję w skrypcie Lua: <syntaxhighlight lang="lua">naszaFunkcja("Parametr")</syntaxhighlight> to powinna się ona wykonać po stronie modułu.		Po kompilacji, jeżeli wywołamy naszą funkcję w skrypcie Lua: <syntaxhighlight lang="lua">naszaFunkcja("Parametr")</syntaxhighlight> to powinna się ona wykonać po stronie modułu.

			==Rozpiska==
			<syntaxhighlight lang="c++">
			lua_State* luaVM
			</syntaxhighlight>
			Status zasobu, w którym został uruchomiony moduł</br>

			<syntaxhighlight lang="c++">
			ILuaModuleManager10* pModuleManager
			</syntaxhighlight>
			Menedżer modułu oraz zasobów</br>

			<pre<includeonly/>>
			<span style='color:#D081C4'>void</span>* [[getRootElement]](<span style='color:#DBDDA4'>lua_State</span>*)
			</pre>
			Funkcja zwracająca [[PL/Element_tree#Elementy_drzewa\|root]]'a</br>

			<pre<includeonly/>>
			<span style='color:#D081C4'>void</span>* [[getResourceRootElement]](<span style='color:#DBDDA4'>lua_State</span>*)
			</pre>
			Funkcja zwracająca [[PL/Element_tree#Elementy_drzewa\|root]]'a zasobu,
			w którym został uruchomiony dany moduł</br>

Tracer: Created page with "W poprzedniej części wyjaśniliśmy sobie czym są moduły, jak pobrać szablon modułu oraz co on zawiera.
W tej części omówimy sobie poszczególne części naszego modułu (co dana rzecz robi). Nasz moduł w tym poradniku będzie się nazywał '''PrzykladowyModul''' ===./src/ml_przykladowymodul.cpp=== #include #include ILuaModuleManager10* pModuleManager = NULL; bool ms_b..."

2022-06-06T20:03:29Z

Created page with "W poprzedniej części wyjaśniliśmy sobie czym są moduły, jak pobrać szablon modułu oraz co on zawiera. W tej części omówimy sobie poszczególne części naszego modułu (co dana rzecz robi). Nasz moduł w tym poradniku będzie się nazywał '''PrzykladowyModul''' ===./src/ml_przykladowymodul.cpp=== <syntaxhighlight lang="c++"> #include <include/ml_przykladowymodul.hpp> #include <include/CFunctions.h> ILuaModuleManager10* pModuleManager = NULL; bool ms_b..."

New page

W poprzedniej części wyjaśniliśmy sobie czym są moduły, jak pobrać szablon modułu oraz co on zawiera. 
W tej części omówimy sobie poszczególne części naszego modułu (co dana rzecz robi).
Nasz moduł w tym poradniku będzie się nazywał '''PrzykladowyModul'''

===./src/ml_przykladowymodul.cpp===
<syntaxhighlight lang="c++">

#include <include/ml_przykladowymodul.hpp>
#include <include/CFunctions.h>

ILuaModuleManager10* pModuleManager = NULL;
bool ms_bInitWorked = false;

// Initialisation function (module entrypoint)
MTAEXPORT bool InitModule(ILuaModuleManager10* pManager, char* szModuleName, char* szAuthor, float* fVersion) {
pModuleManager = pManager;

// Set the module info
strncpy(szModuleName, MODULE_NAME, MAX_INFO_LENGTH); // set module name
strncpy(szAuthor, MODULE_AUTHOR, MAX_INFO_LENGTH); // set module author

*fVersion = MODULE_VERSION; // set module version

ms_bInitWorked = true;
return true;
}

MTAEXPORT void RegisterFunctions(lua_State* luaVM) {
if (!ms_bInitWorked) return;

if (pModuleManager && luaVM) {
// Register functions
pModuleManager->RegisterFunction(luaVM, "someFunction", CFunctions::someFunction);

// Add events
CFunctions::AddEvent(luaVM, "onSomeEvent");
}
}

MTAEXPORT bool DoPulse() {

return true;
}

MTAEXPORT bool ResourceStopped(lua_State* luaVM) {

return true;
}

MTAEXPORT bool ShutdownModule() {

return true;
}

</syntaxhighlight>

Musimy sobie na początek zaimportować potrzebne dla nas nagłówki. W tym przypadku jest to nasz główny nagłówek ('''ml_przykladowymodul.hpp''') oraz nagłówek do zarejestrowania naszych własnych funkcji w Lua ('''CFunctions.h'''). Zwróć uwagę na rozszerzenie pliku: '''.hpp'''. Pliki które będziemy tworzyć samodzielnie będziemy zapisywać z rozszerzeniem '''.hpp''', by nie mieszać ich z predefiniowanymi plikami MTA.

<syntaxhighlight lang="c++">ILuaModuleManager10* pModuleManager = NULL;</syntaxhighlight>
Tutaj predefiniujemy menedżer funkcji Lua, który przychodzi razem z plikami MTA. Tego nie ruszamy, jego wartość zmieni się przy inicjalizacji naszego modułu.

<syntaxhighlight lang="c++">bool ms_bInitWorked = false;</syntaxhighlight>
Tutaj definiujemy zmienną, która posłuży nam jako "przełącznik". W momencie gdy moduł się załaduje, to wartość tej zmiennej się zmieni na '''true''', dzięki czemu możliwe będzie załadowanie funkcji oraz zdarzeń (tak, by nie załadowały się przed inicjalizacją modułu).

<syntaxhighlight lang="c++">MTAEXPORT bool InitModule(ILuaModuleManager10* pManager, char* szModuleName, char* szAuthor, float* fVersion) {
// ...
}</syntaxhighlight>
W tym miejscu zaczyna się cała zabawa. Ta funkcja sprawia że nasz moduł się ładuje na serwer, ustawia jego nazwę, autora i wersję.

<syntaxhighlight lang="c++">MTAEXPORT void RegisterFunctions(lua_State* luaVM) {
// ...
}</syntaxhighlight>
W tej funkcji rejestrujemy nasze funkcje i zdarzenia, które będzie można użyć w skrypcie Lua. Jedynym parametrem tutaj jest tzw. status wirtualnej maszyny Lua. Zasadniczo serwer dzieli każdy zasób na oddzielne wirtualne maszyny, które podłączone są do jednego statusu globalnego. Parametrem w tej funkcji jest stan zasobu, który uruchomił moduł (wszystkie funkcje, zdarzenia dzieją się osobno na każdym zasobie). Do tego przejdziemy w późniejszej części poradnika.

<syntaxhighlight lang="c++">
MTAEXPORT bool DoPulse() {
return true;
}

MTAEXPORT bool ResourceStopped(lua_State* luaVM) {
return true;
}

MTAEXPORT bool ShutdownModule() {
return true;
}</syntaxhighlight>
1 funkcja wysyła informację o tym, że moduł jest aktywny. Podobny wynik możemy zyskać wpisując w wiersz poleceń <code>ping google.com</code> 
2 funkcja wywoła się jak zdarzenie. Jeżeli moduł zostanie z jakiegokolwiek powodu zatrzymany, to ta funkcja się wykona razem ze stanem tegoż modułu. 
3 funkcja wywoła się kiedy cały moduł zostanie zatrzymany (poprzez konsolowe komendy '''unloadmodule''', '''reloadmodule''' i '''loadmodule''').

===./include/ml_przykladowymodul.hpp===
Tutaj interesują nas właściwie tylko 3 linie:
<syntaxhighlight lang="c++">
#define MODULE_NAME "Example module" // Module name
#define MODULE_AUTHOR "Tracer" // Author of the module
#define MODULE_VERSION 1.0f // Module version (1.00)
</syntaxhighlight>
W pierwszej definiujemy nazwę naszego modułu, w drugiej autorów, a w trzeciej wersję naszego modułu

===./include/CFunctions.h===
Tutaj dzieje się nieco więcej.
<syntaxhighlight lang="c++">
extern ILuaModuleManager10* pModuleManager;

class CFunctions {
public:
static int someFunction(lua_State* luaVM);

static void AddEvent(lua_State* luaVM, const std::string& strEventName);
static void TriggerEvent(lua_State* luaVM, const std::string& strEventName,
void* baseElem, const std::initializer_list<VarTypes>& arg = {});
};
</syntaxhighlight>
W pierwszej kolejności mamy odniesienie do wcześniej zdefiniowanej zmiennej odpowiedzialnej za zarządzanie modułami.
Dalej mamy klasę, w której definiujemy nasze własne funkcje oraz zdarzenia. 
Zauważ, że każda funkcja jest definiowana statycznie a jako parametr przyjmuje status danego zasobu, który uruchomił nasz moduł. 
<code>AddEvent</code> pozwala nam na zarejestrowanie niestandardowego zdarzenia. <code>TriggerEvent</code> jak nazwa mówi wywołuje zdarzenie, którego nazwę podamy jako parametr. Warto zaznaczyć, że do wywołania zdarzenia potrzebny jest też element, do którego podłączona jest funkcja obsługi zdarzeń (event handler), oraz argumenty. Są one przedstawione jako lista <code>VarType</code>'ów, czyli typów zmiennych poza tablicą. 

Żeby zarejestrować naszą funkcję używamy metody
<syntaxhighlight lang="c++">
pModuleManager->RegisterFunction(luaVM, "naszaFunkcja", CFunctions::naszaFunkcja);
</syntaxhighlight>
Natomiast żeby zarejestrować zdarzenie używamy metody
<syntaxhighlight lang="c++">
CFunctions::AddEvent(luaVM, "naszePierwszeZdarzenie");
</syntaxhighlight>

Po kompilacji, jeżeli wywołamy naszą funkcję w skrypcie Lua: <syntaxhighlight lang="lua">naszaFunkcja("Parametr")</syntaxhighlight> to powinna się ona wykonać po stronie modułu.

Wstęp do pisania modułów 2 - Revision history

Tracer: Added a little summary to the modules