Utilities for querying and manipulating game instances. More...

Classes
union	AERLocal
	A dynamic member variable of an instance. More...

Typedefs
typedef void	AERInstance
	Opaque type for instance of an object. More...

Functions
size_t	AERInstanceGetAll (size_t bufSize, AERInstance **instBuf)
	Query all instances in the current room. More...

size_t	AERInstanceGetByObject (int32_t objIdx, bool recursive, size_t bufSize, AERInstance **instBuf)
	Query all instances of an object in the current room. More...

AERInstance *	AERInstanceGetById (int32_t instId)
	Query the instance with a specific ID in the current room. More...

AERInstance *	AERInstanceCreate (int32_t objIdx, float x, float y)
	Create an instance of an object. More...

void	AERInstanceChange (AERInstance *inst, int32_t newObjIdx, bool doEvents)
	Convert an instance of one object into an instance of another object in-place. More...

void	AERInstanceDestroy (AERInstance *inst)
	Destroy an instance and call its destroy event. More...

void	AERInstanceDelete (AERInstance *inst)
	Destroy an instance but do not call its destroy event. More...

float	AERInstanceGetDepth (AERInstance *inst)
	Query the render depth of an instance. More...

void	AERInstanceSetDepth (AERInstance *inst, float depth)
	Set the render depth of an instance. More...

void	AERInstanceSyncDepth (AERInstance *inst)
	Set the render depth of an instance based on its position in the current room. More...

int32_t	AERInstanceGetId (AERInstance *inst)
	Query the ID of an instance. More...

int32_t	AERInstanceGetObject (AERInstance *inst)
	Query the object of an instance. More...

bool	AERInstanceCompatibleWith (AERInstance *inst, int32_t objIdx)
	Query whether an instance's object is or inherits from another object. More...

bool	AERInstanceGetDeactivated (AERInstance *inst)
	Query whether or not an instance is deactivated. More...

void	AERInstanceSetDeactivated (AERInstance *inst, bool deactivated)
	Set the deactivation state of an instance. More...

bool	AERInstanceGetPersistent (AERInstance *inst)
	Query the persistence of an instance. More...

void	AERInstanceSetPersistent (AERInstance *inst, bool persistent)
	Set the persistence of an instance. More...

void	AERInstanceGetPosition (AERInstance inst, float x, float *y)
	Query the position of an instance in the current room. More...

void	AERInstanceSetPosition (AERInstance *inst, float x, float y)
	Set the position of an instance in the current room. More...

void	AERInstanceAddPosition (AERInstance *inst, float x, float y)
	Add to the existing position of an instance in the current room. More...

void	AERInstanceGetBoundingBox (AERInstance inst, float left, float top, float right, float *bottom)
	Query the axis-aligned bounding box of an instance. More...

float	AERInstanceGetFriction (AERInstance *inst)
	Query the friction of an instance. More...

void	AERInstanceSetFriction (AERInstance *inst, float friction)
	Set the friction of an instance. More...

void	AERInstanceGetMotion (AERInstance inst, float x, float *y)
	Query the motion of an instance. More...

void	AERInstanceSetMotion (AERInstance *inst, float x, float y)
	Set the motion of an instance. More...

void	AERInstanceAddMotion (AERInstance *inst, float x, float y)
	Add to the existing motion of an instance. More...

int32_t	AERInstanceGetMask (AERInstance *inst)
	Query the collision mask of an instance. More...

void	AERInstanceSetMask (AERInstance *inst, int32_t maskIdx)
	Set the collision mask of an instance. More...

bool	AERInstanceGetVisible (AERInstance *inst)
	Query the visibility of an instance. More...

void	AERInstanceSetVisible (AERInstance *inst, bool visible)
	Set the visibility of an instance. More...

int32_t	AERInstanceGetSprite (AERInstance *inst)
	Query the sprite of an instance. More...

void	AERInstanceSetSprite (AERInstance *inst, int32_t spriteIdx)
	Set the sprite of an instance. More...

float	AERInstanceGetSpriteFrame (AERInstance *inst)
	Query the current frame of sprite animation of an instance. More...

void	AERInstanceSetSpriteFrame (AERInstance *inst, float frame)
	Set the current frame of sprite animation of an instance. More...

float	AERInstanceGetSpriteSpeed (AERInstance *inst)
	Query the sprite animation speed of an instance. More...

void	AERInstanceSetSpriteSpeed (AERInstance *inst, float speed)
	Set the sprite animation speed of an instance. More...

float	AERInstanceGetSpriteAlpha (AERInstance *inst)
	Query the sprite alpha (transparency) of an instance. More...

void	AERInstanceSetSpriteAlpha (AERInstance *inst, float alpha)
	Set the sprite alpha (transparency) of an instance. More...

float	AERInstanceGetSpriteAngle (AERInstance *inst)
	Query the sprite offset angle of an instance. More...

void	AERInstanceSetSpriteAngle (AERInstance *inst, float angle)
	Set the sprite offset angle of an instance. More...

void	AERInstanceGetSpriteScale (AERInstance inst, float x, float *y)
	Query the sprite scale of an instance. More...

void	AERInstanceSetSpriteScale (AERInstance *inst, float x, float y)
	Set the sprite scale of an instance. More...

uint32_t	AERInstanceGetSpriteBlend (AERInstance *inst)
	Query the sprite blend color of an instance. More...

void	AERInstanceSetSpriteBlend (AERInstance *inst, uint32_t color)
	Set the sprite blend color of an instance. More...

bool	AERInstanceGetTangible (AERInstance *inst)
	Query the tangibility of an instance. More...

void	AERInstanceSetTangible (AERInstance *inst, bool tangible)
	Set the tangibility of an instance. More...

int32_t	AERInstanceGetAlarm (AERInstance *inst, uint32_t alarmIdx)
	Query the state of an alarm of an instance. More...

void	AERInstanceSetAlarm (AERInstance *inst, uint32_t alarmIdx, int32_t numSteps)
	Set the state of an alarm of an instance. More...

size_t	AERInstanceGetHLDLocals (AERInstance inst, size_t bufSize, const char *nameBuf)
	Query the names of all vanilla local variables of an instance. More...

AERLocal *	AERInstanceGetHLDLocal (AERInstance inst, const char name)
	Get a reference to a specific vanilla local variable of an instance. More...

AERLocal *	AERInstanceCreateModLocal (AERInstance inst, const char name, bool public, void(destructor)(AERLocal local))
	Create a new mod local variable for an instance. More...

void	AERInstanceDestroyModLocal (AERInstance inst, const char name, bool public)
	Destroy a mod local variable and call its destructor. More...

AERLocal	AERInstanceDeleteModLocal (AERInstance inst, const char name, bool public)
	Destroy a mod local variable but do not call its destructor. More...

AERLocal *	AERInstanceGetModLocal (AERInstance inst, const char name, bool public)
	Get a reference to a specific mod local variable of an instance. More...

Detailed Description

Utilities for querying and manipulating game instances.

Copyright: 2021 the libaermre authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Typedef Documentation

◆ AERInstance

typedef void AERInstance

Opaque type for instance of an object.

Since: 1.0.0

See also: object.h

Function Documentation

◆ AERInstanceAddMotion()

void AERInstanceAddMotion	(	AERInstance *	inst,
		float	x,
		float	y
	)

Add to the existing motion of an instance.

Parameters

[in]	inst	Instance of interest.
[in]	x	Relative horizontal motion.
[in]	y	Relative vertical motion.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

See also: AERInstanceSetMotion

◆ AERInstanceAddPosition()

void AERInstanceAddPosition	(	AERInstance *	inst,
		float	x,
		float	y
	)

Add to the existing position of an instance in the current room.

This is effectively a relative translation.

Parameters

[in]	inst	Instance of interest.
[in]	x	Relative horizontal position.
[in]	y	Relative vertical position.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.1.0

See also: AERInstanceSetPosition

◆ AERInstanceChange()

void AERInstanceChange	(	AERInstance *	inst,
		int32_t	newObjIdx,
		bool	doEvents
	)

Convert an instance of one object into an instance of another object in-place.

Warning: Once this function has been called on and instance, no further queries or actions should be performed on this instance until the next in-game step.

Under the hood, this function creates a new instance of the new object, copies various properties such as position from the old instance to the new instance, and then finally destroys the old instance.

Parameters

[in]	inst	Instance of interest.
[in]	newObjIdx	Object to convert argument `inst` into.
[in]	doEvents	If `true`, then the engine will call the destroy event of the old instance and the create event of the new instance.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.
AER_FAILED_LOOKUP	if argument `newObjIdx` is an invalid object.

Since: 1.0.0

See also: AERObjectAttachCreateListener; AERObjectAttachDestroyListener

◆ AERInstanceCompatibleWith()

bool AERInstanceCompatibleWith	(	AERInstance *	inst,
		int32_t	objIdx
	)

Query whether an instance's object is or inherits from another object.

Parameters

[in]	inst	Instance of interest.
[in]	objIdx	Object to compare against.

Returns: Whether instance's object is compatible with other object or false if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.
AER_FAILED_LOOKUP	if argument `objIdx` is an invalid object.

Since: 1.5.0

See also: AERObjectCompatibleWith

◆ AERInstanceCreate()

AERInstance * AERInstanceCreate	(	int32_t	objIdx,
		float	x,
		float	y
	)

Create an instance of an object.

Parameters

[in]	objIdx	Object to create an instance of.
[in]	x	Horizontal position at which to create instance.
[in]	y	Vertical position at which to create instance.

Returns: New instance or NULL if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_FAILED_LOOKUP	if argument `objIdx` is an invalid object.

Since: 1.0.0

See also: AERObjectAttachCreateListener

◆ AERInstanceCreateModLocal()

AERLocal * AERInstanceCreateModLocal	(	AERInstance *	inst,
		const char *	name,
		bool	public,
		void()(AERLocal local)	destructor
	)

Create a new mod local variable for an instance.

Warning: The reference returned by this function should be considered highly unstable.

Namespace of Mod Local Variables

When an instance is given a mod local in the public namespace, this local is accessible by all mods loaded. If, on the other hand, the local is created in a private namespace, then only the mod that created it can access and destroy it.

Multiple mods may each assign a private mod local with the same name to the same instance without interfering with one another.

Parameters

[in]	inst	Instance of interest.
[in]	name	Name of mod local. Must be 24 characters or less (not including null-character).
[in]	public	Whether to use the public or private local namespace. For more information see Namespace of Mod Local Variables.
[in]	destructor	Callback function executed when local is destroyed. May be `NULL` if local does not need special cleanup.

Returns: Reference to newly created mod local or NULL if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if either argument `inst` or `name` is `NULL`.
AER_BAD_VAL	if argument `name` is greater than 24 characters in length (not including null-character).
AER_FAILED_LOOKUP	if instance already has a mod local with given name in given namespace.

Since: 1.0.0

◆ AERInstanceDelete()

void AERInstanceDelete ( AERInstance * inst )

Destroy an instance but do not call its destroy event.

Parameters

[in] inst Instance of interest.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

See also: AERInstanceDestroy; AERObjectAttachDestroyListener

◆ AERInstanceDeleteModLocal()

AERLocal AERInstanceDeleteModLocal	(	AERInstance *	inst,
		const char *	name,
		bool	public
	)

Destroy a mod local variable but do not call its destructor.

Parameters

[in]	inst	Instance of interest.
[in]	name	Name of mod local. Must be 24 characters or less (not including null-character).
[in]	public	Whether to use the public or private local namespace. For more information see Namespace of Mod Local Variables.

Returns: Value of deleted local or (AERLocal){0} if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if either argument `inst` or `name` is `NULL`.
AER_BAD_VAL	if argument `name` is greater than 24 characters in length (not including null-character).
AER_FAILED_LOOKUP	if instance does not have a mod local with given name in given namespace.

Since: 1.0.0

See also: AERInstanceDestroyModLocal

◆ AERInstanceDestroy()

void AERInstanceDestroy ( AERInstance * inst )

Destroy an instance and call its destroy event.

Parameters

[in] inst Instance of interest.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

See also: AERInstanceDelete; AERObjectAttachDestroyListener

◆ AERInstanceDestroyModLocal()

void AERInstanceDestroyModLocal	(	AERInstance *	inst,
		const char *	name,
		bool	public
	)

Destroy a mod local variable and call its destructor.

Parameters

[in]	inst	Instance of interest.
[in]	name	Name of mod local. Must be 24 characters or less (not including null-character).
[in]	public	Whether to use the public or private local namespace. For more information see Namespace of Mod Local Variables.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if either argument `inst` or `name` is `NULL`.
AER_BAD_VAL	if argument `name` is greater than 24 characters in length (not including null-character).
AER_FAILED_LOOKUP	if instance does not have a mod local with given name in given namespace.

Since: 1.0.0

See also: AERInstanceDeleteModLocal

◆ AERInstanceGetAlarm()

int32_t AERInstanceGetAlarm	(	AERInstance *	inst,
		uint32_t	alarmIdx
	)

Query the state of an alarm of an instance.

Parameters

[in]	inst	Instance of interest.
[in]	alarmIdx	Alarm index.

Returns: Number of alarm steps or -1 if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.
AER_FAILED_LOOKUP	if argument `alarmIdx` is greater than `11`.

Since: 1.0.0

See also: AERObjectAttachAlarmListener

◆ AERInstanceGetAll()

size_t AERInstanceGetAll	(	size_t	bufSize,
		AERInstance **	instBuf
	)

Query all instances in the current room.

Warning: Argument instBuf must be large enough to hold at least bufSize elements.

Note: Argument bufSize may be 0 in which case argument instBuf may be NULL. This may be used to efficiently query the total number of instances in the current room.

Parameters

[in]	bufSize	Maximum number of elements to write to argument `instBuf`.
[out]	instBuf	Buffer to write instances to.

Returns: Total number of instances in current room or 0 if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `instBuf` is `NULL` and argument `bufSize` is greater than `0`.

Since: 1.0.0

◆ AERInstanceGetBoundingBox()

void AERInstanceGetBoundingBox	(	AERInstance *	inst,
		float *	left,
		float *	top,
		float *	right,
		float *	bottom
	)

Query the axis-aligned bounding box of an instance.

The bounding box of an instance describes the bounding volume of an instance's sprite or mask. It is relative to the room's origin.

If not all four of the components of the bounding box are needed, then the arguments for the unneeded components may be NULL.

Parameters

[in]	inst	Instance of interest.
[out]	left	X-intercept of the left side of the bounding box.
[out]	top	Y-intercept of the top side of the bounding box.
[out]	right	X-intercept of the right side of the bounding box.
[out]	bottom	Y-intercept of the bottom side of the bounding box.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL` or all four arguments `left`, `top`, `right` and `bottom` are `NULL`.

Since: 1.0.0

◆ AERInstanceGetById()

AERInstance * AERInstanceGetById ( int32_t instId )

Query the instance with a specific ID in the current room.

Parameters

[in] instId Instance ID.

Returns: Instance with provided ID or NULL if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_FAILED_LOOKUP	if argument `instId` is an invalid instance.

Since: 1.0.0

See also: AERInstanceGetId

◆ AERInstanceGetByObject()

size_t AERInstanceGetByObject	(	int32_t	objIdx,
		bool	recursive,
		size_t	bufSize,
		AERInstance **	instBuf
	)

Query all instances of an object in the current room.

Warning: Argument instBuf must be large enough to hold at least bufSize elements.

Note: Argument bufSize may be 0 in which case argument instBuf may be NULL. This may be used to efficiently query the total number of instances of an object in the current room.

Parameters

[in]	objIdx	Object to get instances of.
[in]	recursive	Whether to query instances of given object only (`false`) or both given object and direct and indirect children of given object (`true`).
[in]	bufSize	Maximum number of elements to write to argument `instBuf`.
[out]	instBuf	Buffer to write instances to.

Returns: Total number of instances of object in current room or 0 if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `instBuf` is `NULL` and argument `bufSize` is greater than `0`.
AER_FAILED_LOOKUP	if argument `objIdx` is an invalid object.

Since: 1.0.0

◆ AERInstanceGetDeactivated()

bool AERInstanceGetDeactivated ( AERInstance * inst )

Query whether or not an instance is deactivated.

Parameters

[in] inst Instance of interest.

Returns: Whether or not instance is deactivated or false if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.3.0

◆ AERInstanceGetDepth()

float AERInstanceGetDepth ( AERInstance * inst )

Query the render depth of an instance.

Parameters

[in] inst Instance of interest.

Returns: Render depth or 0.0f if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

◆ AERInstanceGetFriction()

float AERInstanceGetFriction ( AERInstance * inst )

Query the friction of an instance.

Instance Friction

The friction of an instance determines how much it decelerates by each step.

Parameters

[in] inst Instance of interest.

Returns: Friction or 0.0f if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

◆ AERInstanceGetHLDLocal()

AERLocal * AERInstanceGetHLDLocal	(	AERInstance *	inst,
		const char *	name
	)

Get a reference to a specific vanilla local variable of an instance.

Warning: The reference returned by this function should be considered highly unstable.

Parameters

[in]	inst	Instance of interest.
[in]	name	Name of vanilla local.

Returns: Reference to vanilla local or NULL if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if either argument `inst` or `name` is `NULL`.
AER_FAILED_LOOKUP	if instance does not have a vanilla local with given name.

Since: 1.0.0

See also: AERInstanceGetHLDLocals; Common Locals

◆ AERInstanceGetHLDLocals()

size_t AERInstanceGetHLDLocals	(	AERInstance *	inst,
		size_t	bufSize,
		const char **	nameBuf
	)

Query the names of all vanilla local variables of an instance.

Warning: Argument nameBuf must be large enough to hold at least bufSize elements.

Note: Argument bufSize may be 0 in which case argument nameBuf may be NULL. This may be used to efficiently query the total number of vanilla locals that an instance has.

Parameters

[in]	inst	Instance of interest.
[in]	bufSize	Maximum number of elements to write to argument `nameBuf`.
[out]	nameBuf	Buffer to write names to.

Returns: Total number of vanilla locals that the instance has or 0 if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL` or argument `instBuf` is `NULL` and argument `bufSize` is greater than `0`.

Since: 1.0.0

See also: AERInstanceGetHLDLocal; Common Locals

◆ AERInstanceGetId()

int32_t AERInstanceGetId ( AERInstance * inst )

Query the ID of an instance.

Note: A valid reference to an AERInstance one step may become invalid in a future step. To keep track of a specific instance across steps, use its ID.

Parameters

[in] inst Instance of interest.

Returns: Instance ID or -1 if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

See also: AERInstanceGetById

◆ AERInstanceGetMask()

int32_t AERInstanceGetMask ( AERInstance * inst )

Query the collision mask of an instance.

Parameters

[in] inst Instance of interest.

Returns: Collision mask index or AER_SPRITE_NULL if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

◆ AERInstanceGetModLocal()

AERLocal * AERInstanceGetModLocal	(	AERInstance *	inst,
		const char *	name,
		bool	public
	)

Get a reference to a specific mod local variable of an instance.

Parameters

[in]	inst	Instance of interest.
[in]	name	Name of mod local. Must be 24 characters or less (not including null-character).
[in]	public	Whether to use the public or private local namespace. For more information see Namespace of Mod Local Variables.

Returns: Reference to mod local or NULL if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if either argument `inst` or `name` is `NULL`.
AER_BAD_VAL	if argument `name` is greater than 24 characters in length (not including null-character).
AER_FAILED_LOOKUP	if instance does not have a mod local with given name in given namespace.

Since: 1.0.0

◆ AERInstanceGetMotion()

void AERInstanceGetMotion	(	AERInstance *	inst,
		float *	x,
		float *	y
	)

Query the motion of an instance.

If only one component of the motion is needed, then the argument for the unneeded component may be NULL.

Parameters

[in]	inst	Instance of interest.
[out]	x	Horizontal motion.
[out]	y	Vertical motion.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL` or both arguments `x` and `y` are `NULL`.

Since: 1.0.0

◆ AERInstanceGetObject()

int32_t AERInstanceGetObject ( AERInstance * inst )

Query the object of an instance.

Parameters

[in] inst Instance of interest.

Returns: Object index or AER_OBJECT_NULL if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

◆ AERInstanceGetPersistent()

bool AERInstanceGetPersistent ( AERInstance * inst )

Query the persistence of an instance.

Parameters

[in] inst Instance of interest.

Returns: Persistence or false if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.3.0

◆ AERInstanceGetPosition()

void AERInstanceGetPosition	(	AERInstance *	inst,
		float *	x,
		float *	y
	)

Query the position of an instance in the current room.

If only one component of the position is needed, then the argument for the unneeded component may be NULL.

Parameters

[in]	inst	Instance of interest.
[out]	x	Horizontal position.
[out]	y	Vertical position.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL` or both arguments `x` and `y` are `NULL`.

Since: 1.0.0

◆ AERInstanceGetSprite()

int32_t AERInstanceGetSprite ( AERInstance * inst )

Query the sprite of an instance.

Parameters

[in] inst Instance of interest.

Returns: Sprite index or AER_SPRITE_NULL if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

◆ AERInstanceGetSpriteAlpha()

float AERInstanceGetSpriteAlpha ( AERInstance * inst )

Query the sprite alpha (transparency) of an instance.

Parameters

[in] inst Instance of interest.

Returns: Sprite alpha or -1.0f if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

◆ AERInstanceGetSpriteAngle()

float AERInstanceGetSpriteAngle ( AERInstance * inst )

Query the sprite offset angle of an instance.

Parameters

[in] inst Instance of interest.

Returns: Sprite offset angle in degrees or 0.0f if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

◆ AERInstanceGetSpriteBlend()

uint32_t AERInstanceGetSpriteBlend ( AERInstance * inst )

Query the sprite blend color of an instance.

Parameters

[in] inst Instance of interest.

Returns: Sprite blend color or 0 if unsuccessful. See Colors for more infomation.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.1.0

◆ AERInstanceGetSpriteFrame()

float AERInstanceGetSpriteFrame ( AERInstance * inst )

Query the current frame of sprite animation of an instance.

Sprite Animation Frame

The current sprite animation frame of an instance is stored as a floating-point value rather than an integer because it also encodes progress to the next frame.

The integer portion of this value represents the current frame. The fractional portion represents progress towards the next frame.

Parameters

[in] inst Instance of interest.

Returns: Frame of sprite animation or -1.0f if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

See also: AERObjectAttachAnimationEndListener

◆ AERInstanceGetSpriteScale()

void AERInstanceGetSpriteScale	(	AERInstance *	inst,
		float *	x,
		float *	y
	)

Query the sprite scale of an instance.

If only one component of the scale is needed, then the argument for the unneeded component may be NULL.

Parameters

[in]	inst	Instance of interest.
[out]	x	Horizontal scale.
[out]	y	Vertical scale.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL` or both arguments `x` and `y` are `NULL`.

Since: 1.0.0

◆ AERInstanceGetSpriteSpeed()

float AERInstanceGetSpriteSpeed ( AERInstance * inst )

Query the sprite animation speed of an instance.

Parameters

[in] inst Instance of interest.

Returns: Sprite animation speed or -1.0f if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

See also: AERObjectAttachAnimationEndListener

◆ AERInstanceGetTangible()

bool AERInstanceGetTangible ( AERInstance * inst )

Query the tangibility of an instance.

Instance Tangibility

The tangibility of an instance represents whether or not the player can collide with it. This property is only meaningful for instances of AER_OBJECT_PATHFINDOBSTACLE and its children.

Parameters

[in] inst Instance of interest.

Returns: Tangibility or false if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

◆ AERInstanceGetVisible()

bool AERInstanceGetVisible ( AERInstance * inst )

Query the visibility of an instance.

Parameters

[in] inst Instance of interest.

Returns: Visibility or false if unsuccessful.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.1.0

◆ AERInstanceSetAlarm()

void AERInstanceSetAlarm	(	AERInstance *	inst,
		uint32_t	alarmIdx,
		int32_t	numSteps
	)

Set the state of an alarm of an instance.

Parameters

[in]	inst	Instance of interest.
[in]	alarmIdx	Alarm index.
[in]	numSteps	Number of alarm steps. Set to `-1` to disable the alarm without triggering the corresponding alarm event.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.
AER_FAILED_LOOKUP	if argument `alarmIdx` is greater than `11`.

Since: 1.0.0

See also: AERObjectAttachAlarmListener

◆ AERInstanceSetDeactivated()

void AERInstanceSetDeactivated	(	AERInstance *	inst,
		bool	deactivated
	)

Set the deactivation state of an instance.

Parameters

[in]	inst	Instance of interest.
[in]	deactivated	Deactivation state.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.3.0

◆ AERInstanceSetDepth()

void AERInstanceSetDepth	(	AERInstance *	inst,
		float	depth
	)

Set the render depth of an instance.

Parameters

[in]	inst	Instance of interest.
[in]	depth	Render depth.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

◆ AERInstanceSetFriction()

void AERInstanceSetFriction	(	AERInstance *	inst,
		float	friction
	)

Set the friction of an instance.

For more information about friction, see Instance Friction.

Parameters

[in]	inst	Instance of interest.
[in]	friction	Friction.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

◆ AERInstanceSetMask()

void AERInstanceSetMask	(	AERInstance *	inst,
		int32_t	maskIdx
	)

Set the collision mask of an instance.

By default, an instance will use its sprite as its collision mask. In this case, the instance's mask should be set to AER_SPRITE_NULL.

Parameters

[in]	inst	Instance of interest.
[in]	maskIdx	Collision mask index.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.
AER_FAILED_LOOKUP	if argument `maskIdx` is an invalid sprite.

Since: 1.0.0

◆ AERInstanceSetMotion()

void AERInstanceSetMotion	(	AERInstance *	inst,
		float	x,
		float	y
	)

Set the motion of an instance.

Parameters

[in]	inst	Instance of interest.
[in]	x	Horizontal motion.
[in]	y	Vertical motion.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

See also: AERInstanceAddMotion

◆ AERInstanceSetPersistent()

void AERInstanceSetPersistent	(	AERInstance *	inst,
		bool	persistent
	)

Set the persistence of an instance.

Parameters

[in]	inst	Instance of interest.
[in]	persistent	Persistence.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.3.0

◆ AERInstanceSetPosition()

void AERInstanceSetPosition	(	AERInstance *	inst,
		float	x,
		float	y
	)

Set the position of an instance in the current room.

Parameters

[in]	inst	Instance of interest.
[in]	x	Horizontal position.
[in]	y	Vertical position.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

See also: AERInstanceAddPosition

◆ AERInstanceSetSprite()

void AERInstanceSetSprite	(	AERInstance *	inst,
		int32_t	spriteIdx
	)

Set the sprite of an instance.

Parameters

[in]	inst	Instance of interest.
[in]	spriteIdx	Sprite index.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.
AER_FAILED_LOOKUP	if argument `spriteIdx` is an invalid sprite.

Since: 1.0.0

◆ AERInstanceSetSpriteAlpha()

void AERInstanceSetSpriteAlpha	(	AERInstance *	inst,
		float	alpha
	)

Set the sprite alpha (transparency) of an instance.

Parameters

[in]	inst	Instance of interest.
[in]	alpha	Sprite alpha.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.
AER_BAD_VAL	if argument `alpha` is less than `0.0f` or greater than `1.0f`.

Since: 1.0.0

◆ AERInstanceSetSpriteAngle()

void AERInstanceSetSpriteAngle	(	AERInstance *	inst,
		float	angle
	)

Set the sprite offset angle of an instance.

Parameters

[in]	inst	Instance of interest.
[in]	angle	Sprite offset angle in degrees.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

◆ AERInstanceSetSpriteBlend()

void AERInstanceSetSpriteBlend	(	AERInstance *	inst,
		uint32_t	color
	)

Set the sprite blend color of an instance.

Parameters

[in]	inst	Instance of interest.
[in]	color	Sprite blend color. See Colors for more information.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.1.0

◆ AERInstanceSetSpriteFrame()

void AERInstanceSetSpriteFrame	(	AERInstance *	inst,
		float	frame
	)

Set the current frame of sprite animation of an instance.

For more information about the meaning of the sprite frame, see Sprite Animation Frame.

Parameters

[in]	inst	Instance of interest.
[in]	frame	Frame of sprite animation.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

See also: AERObjectAttachAnimationEndListener

◆ AERInstanceSetSpriteScale()

void AERInstanceSetSpriteScale	(	AERInstance *	inst,
		float	x,
		float	y
	)

Set the sprite scale of an instance.

Note: The components of the scale may be negative to mirror the sprite about an axis.

Parameters

[in]	inst	Instance of interest.
[in]	x	Horizontal scale.
[in]	y	Vertical scale.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

◆ AERInstanceSetSpriteSpeed()

void AERInstanceSetSpriteSpeed	(	AERInstance *	inst,
		float	speed
	)

Set the sprite animation speed of an instance.

Parameters

[in]	inst	Instance of interest.
[in]	speed	Sprite animation speed.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.
AER_BAD_VAL	if argument `speed` is less than `0.0f`.

Since: 1.0.0

See also: AERObjectAttachAnimationEndListener

◆ AERInstanceSetTangible()

void AERInstanceSetTangible	(	AERInstance *	inst,
		bool	tangible
	)

Set the tangibility of an instance.

For more information about instance tangibility, see Instance Tangibility.

Parameters

[in]	inst	Instance of interest.
[in]	tangible	Tangibility.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

◆ AERInstanceSetVisible()

void AERInstanceSetVisible	(	AERInstance *	inst,
		bool	visible
	)

Set the visibility of an instance.

Parameters

[in]	inst	Instance of interest.
[in]	tangible	Visibility.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.1.0

◆ AERInstanceSyncDepth()

void AERInstanceSyncDepth ( AERInstance * inst )

Set the render depth of an instance based on its position in the current room.

Parameters

[in] inst Instance of interest.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_NULL_ARG	if argument `inst` is `NULL`.

Since: 1.0.0

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ AERInstance

Function Documentation

◆ AERInstanceAddMotion()

◆ AERInstanceAddPosition()

◆ AERInstanceChange()

◆ AERInstanceCompatibleWith()

◆ AERInstanceCreate()

◆ AERInstanceCreateModLocal()

Namespace of Mod Local Variables

◆ AERInstanceDelete()

◆ AERInstanceDeleteModLocal()

◆ AERInstanceDestroy()

◆ AERInstanceDestroyModLocal()

◆ AERInstanceGetAlarm()

◆ AERInstanceGetAll()

◆ AERInstanceGetBoundingBox()

◆ AERInstanceGetById()

◆ AERInstanceGetByObject()

◆ AERInstanceGetDeactivated()

◆ AERInstanceGetDepth()

◆ AERInstanceGetFriction()

Instance Friction

◆ AERInstanceGetHLDLocal()

◆ AERInstanceGetHLDLocals()

◆ AERInstanceGetId()

◆ AERInstanceGetMask()

◆ AERInstanceGetModLocal()

◆ AERInstanceGetMotion()

◆ AERInstanceGetObject()

◆ AERInstanceGetPersistent()

◆ AERInstanceGetPosition()

◆ AERInstanceGetSprite()

◆ AERInstanceGetSpriteAlpha()

◆ AERInstanceGetSpriteAngle()

◆ AERInstanceGetSpriteBlend()

◆ AERInstanceGetSpriteFrame()

Sprite Animation Frame

◆ AERInstanceGetSpriteScale()

◆ AERInstanceGetSpriteSpeed()

◆ AERInstanceGetTangible()

Instance Tangibility

◆ AERInstanceGetVisible()

◆ AERInstanceSetAlarm()

◆ AERInstanceSetDeactivated()

◆ AERInstanceSetDepth()

◆ AERInstanceSetFriction()

◆ AERInstanceSetMask()

◆ AERInstanceSetMotion()

◆ AERInstanceSetPersistent()

◆ AERInstanceSetPosition()

◆ AERInstanceSetSprite()

◆ AERInstanceSetSpriteAlpha()

◆ AERInstanceSetSpriteAngle()

◆ AERInstanceSetSpriteBlend()

◆ AERInstanceSetSpriteFrame()

◆ AERInstanceSetSpriteScale()

◆ AERInstanceSetSpriteSpeed()

◆ AERInstanceSetTangible()

◆ AERInstanceSetVisible()

◆ AERInstanceSyncDepth()