Next: GetInstanceMember

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

The function returns AURIE_SUCCESS on success, otherwise returns a matching error code. If the internal runner function needed for accessing variables, the AURIE_MODULE_INTERNAL_ERROR status code is returned. If an invalid kind of RValue is specified, the function returns AURIE_INVALID_PARAMETER.

Remarks

This function may at first glance seem similar to using the variable_instance_get engine function on the given instance. The difference between GetInstanceMember and variable_instance_get is that GetInstanceMember retrieves a pointer to the actual RValue structure used by the instance object. This means that any modifications of this variable will be reflected in the instance's variable without the need for a writeback. When using the variable_instance_get engine function, the engine silently copies the variable, meaning your changes will not be reflected in the instance's variable unless they are written back via variable_instance_set. Holding onto RValues returned by variable_instance_get is generally considered safe (though the contents of the variable, particularly the pointed-to objects, may still not be safe to access) while holding onto pointers-to-RValues returned by GetInstanceMember is considered unsafe.