Next: GetInstanceMember - AurieFramework/YYToolkit GitHub Wiki

Accesses variables for a given instance / GameMaker struct.

[!NOTE] This function operates only on GameMaker structs or instance pointers, not on generic data structures.

To access members of other data structures (DS Maps, DS Lists, etc.), use built-in functions such as ds_map_find_value or ds_list_find_value.

Syntax

AurieStatus GetInstanceMember(
    [in]  RValue      Instance,
    [in]  const char* MemberName,
    [out] RValue*&    Member
);

Parameters

Instance

An object-typed RValue, containing the pointer to the instance the members of which will be enumerated. Given that RValues can be implicitely constructed from a CInstance*, it is possible for callers to pass a CInstance* directly.

MemberName

A pointer to an read-only buffer containing the name of the member which will be looked up. Note this lookup is case-sensitive.

Member

A reference to a pointer to an RValue. The RValue pointer retrieved from this routine may be invalidated at any time by the engine, and it is therefore not advised to hold onto pointers longer than absolutely necessary. The pointers retrieved by this routine point to not a copy, but the real variable, which means that access asynchronous from engine execution should be kept to a minimum. If the function fails, the address pointed-to by this variable is guaranteed to be preserved.

Return Value

Value	Description
AURIE_SUCCESS	The member was found, and the pointer to it was written into the buffer.
AURIE_INVALID_PARAMETER	Instance is not an object.
AURIE_OBJECT_NOT_FOUND	Instance does not contains the member variable.

Remarks

At first glance, this function may seem equivalent to variable_instance_get, however there is a clear distinction between the two.

• GetInstanceMember returns a direct pointer to the variable inside the instance.
  • Any modifications made through this pointer are directly reflected in the instance variable as they happen.
  • It is unsafe to hold onto pointers returned by GetInstanceMember, as they get invalidated when the instance is destroyed.
• variable_instance_get returns a copy of the variable inside the instance.
  • You have to write back using variable_instance_set for your changes to be reflected in the game's object.
  • It is safe to hold onto values returned by variable_instance_get, as they don't get invalidated when the instance is destroyed.

Requirements

Criterium	Value
Minimum YYTK Version	3.0.0
Context	Engine-synchronous