Legacy: Handling events

You are reading the documentation of YYToolkit Legacy (v2.x.x) - for documentation on current-gen YYTK, see the Homepage.

---

Events are a substantial part of making plugins, as they allow you to run code in-sync with the game.

All events are handled by a callback, the prototype of which can be seen below.

A plugin may register it's event handler routine by calling the PmCreateCallback routine.

Syntax

YYTKStatus MyCallback(
    YYTKEventBase* Event
);

Parameters

Event

This object is a pointer to a base class. The actual type is determined by the return value of Event->GetEventType(), which returns a member of the EventType enum.

Here is a table of conversions:

Event Type	Conversion	Value
EVT_CODE_EXECUTE	dynamic_cast<YYTKCodeEvent*>	1
EVT_YYERROR	dynamic_cast<YYTKErrorEvent*>	2
EVT_ENDSCENE	dynamic_cast<YYTKEndSceneEvent*>	4
EVT_PRESENT	dynamic_cast<YYTKPresentEvent*>	8
EVT_RESIZEBUFFERS	dynamic_cast<YYTKResizeBuffersEvent*>	16
EVT_WNDPROC	dynamic_cast<YYTKWindowProcEvent*>	32
EVT_DOCALLSCRIPT	dynamic_cast<YYTKScriptEvent*>	64

Return Value

The function must return YYTK_OK if it succeeds. Otherwise, it returns a matching YYTKStatus to help with debugging.

The YYTKEventBase object

Events, in their most basic form (ie. before they are converted to a full type), provide only two pure virtual functions.

Thus, you cannot instantiate objects of type YYTKEventBase - the YYTKEvent templated class should be used instead.

The available functions only provide ways of identifying the event, they DON'T allow you to interact with the event itself.

GetEventType()

virtual EventType GetEventType() const = 0;

This function returns an EventType variable, which you can then use to cast the object to it's rightful type (see the table below).

The YYTKEvent object

Events, once converted from their basic type (refer to the table above), have several functions available.

As of SDK version 2.0.0, the list is as follows:

Call()

_ReturnValue& Call(
    _FunctionArgs... Arguments
);

This function calls the function the game intended to call. You may change the call arguments as you wish, but make sure they remain valid, or else the game may freak out and crash / error in other ways.

The function returns a reference to the returned value, thus making stuff like Event->Call(...) = true; possible.

Function()

_Function Function() const;

This function returns a pointer to the original function the game intended to call.

The function is marked as unsafe, due to the fact that calling it directly doesn't set any of the event's internal flags, like if you called the original yet.

This may be useful in-case you want to call the function after cancelling the event with Cancel().

Arguments()

std::tuple<_FunctionArgs...>& Arguments();

This function returns a reference to a tuple, storing the original function arguments for the call.

You may extract these arguments by using a structured binding or a function like std::tie.

See the example plugin for an example.

Cancel()

void Cancel(
    const _ReturnValue& Value // The value that should be returned by the game function
);

This function cancels the event by dismissing the call (the original function is never reached, unless explicitly called with Function()).

• Warning: Calling Call() after cancelling the event may affect the return value. Using Function() is thus recommended here.

This function is equivalent to doing:

Event->CalledOriginal() = true;
Event->GetReturn() = Value;