costumes.h File Reference

Sprite Costumes API for managing sprite states. More...

#include "cmdfx/core/sprites.h"

Go to the source code of this file.

Classes
struct	CmdFX_SpriteCostumes
	Represents the holder for sprite costumes. More...

Macros
#define	MAX_SPRITE_COSTUMES   128
	The maximum amount of costumes a sprite can have.

Typedefs
typedef struct CmdFX_SpriteCostumes	CmdFX_SpriteCostumes
	Represents the holder for sprite costumes.

Functions
CmdFX_SpriteCostumes *	Sprite_createCostumes (CmdFX_Sprite *sprite, int costumeCount)
	Creates a sprite costumes holder.
CmdFX_SpriteCostumes *	Sprite_getCostumes (CmdFX_Sprite *sprite)
	Gets the sprite costumes.
int	Sprite_setCostumeAt (CmdFX_Sprite *sprite, int index, char **costume, char ***ansiCostume)
	Sets a costume at the specified index.
char **	Sprite_getCharCostume (CmdFX_Sprite *sprite, int costumeIndex)
	Gets the sprite costume at a specific index.
char ***	Sprite_getAnsiCostume (CmdFX_Sprite *sprite, int costumeIndex)
	Gets the ANSI costume for a sprite.
int	Sprite_switchCostumeTo (CmdFX_Sprite *sprite, int costumeIndex)
	Switches the sprite costume to a specific index.
int	Sprite_addCostume (CmdFX_Sprite *sprite, char **costume, char ***ansiCostume)
	Adds a sprite costume.
int	Sprite_removeCostume (CmdFX_Sprite *sprite, int costumeIndex)
	Removes a sprite costume.
int	Sprite_resetCostumes (CmdFX_Sprite *sprite)
	Resets the sprite costumes.
int	Sprite_getCurrentCostumeIndex (CmdFX_Sprite *sprite)
	Gets the current index of the sprite costume.

Detailed Description

Sprite Costumes API for managing sprite states.

Author

Gregory Mitchell (me@gm.nosp@m.itch.nosp@m.215.x.nosp@m.yz)

Version

0.1.3

Date

2025-03-17

Copyright

Copyright (c) 2025

Macro Definition Documentation

MAX_SPRITE_COSTUMES

#define MAX_SPRITE_COSTUMES   128

The maximum amount of costumes a sprite can have.

This defines the maximum number of costumes a sprite can have in its SpriteCostumes holder.

Typedef Documentation

CmdFX_SpriteCostumes

typedef struct CmdFX_SpriteCostumes CmdFX_SpriteCostumes

Represents the holder for sprite costumes.

This struct is used to hold sprite costumes. A sprite costume is a state of a sprite. For example, a sprite costume could be a sprite with a different color, or a sprite with a different shape.

This is automatically constructed and freed along with the sprite using Sprite_create and Sprite_free.

Function Documentation

Sprite_addCostume()

int Sprite_addCostume	(	CmdFX_Sprite *	sprite,
		char **	costume,
		char ***	ansiCostume )

Adds a sprite costume.

This method adds a sprite costume to the sprite. The costume will be added to the costumes and the ansiCostumes arrays. If the costume already exists, the method will return -1.

Parameters

sprite	The sprite to add the costume to.
costume	The costume to add.
ansiCostume	The ANSI code for the costume.

Returns

0 if successful, -1 if an error occurred.

Sprite_createCostumes()

CmdFX_SpriteCostumes * Sprite_createCostumes	(	CmdFX_Sprite *	sprite,
		int	costumeCount )

Creates a sprite costumes holder.

This method creates a sprite costumes holder with a specific number of costumes. The costumes are automatically freed with Sprite_free.

The default costume is the current sprite data itself at index 0. If costumeCount is less than 1, the method will return NULL. If costumeCount is greater 1, the rest of the costumes will be initialized to 0.

There is an internal limit of 128 costumes per sprite. If costumes were already created for the sprite, this will return the pointer to the costumes.

Parameters

sprite	The sprite to create the costume for.
costumeCount	The number of costumes to create.

Returns

The sprite costumes, or NULL if an error occurred.

Sprite_getAnsiCostume()

char *** Sprite_getAnsiCostume	(	CmdFX_Sprite *	sprite,
		int	costumeIndex )

Gets the ANSI costume for a sprite.

This method gets the ANSI costume for a sprite. If the costume index is out of bounds, the method will return NULL.

Parameters

sprite	The sprite to get the ANSI costume for.
costumeIndex	The index of the costume.

Returns

The ANSI costume, or NULL if not valid.

Sprite_getCharCostume()

char ** Sprite_getCharCostume	(	CmdFX_Sprite *	sprite,
		int	costumeIndex )

Gets the sprite costume at a specific index.

This method gets the sprite costume at a specific index. If the index is out of bounds, the method will return NULL.

Parameters

sprite	The sprite to get the costume for.
costumeIndex	The index of the costume.

Returns

The sprite costume, or NULL if not valid.

Sprite_getCostumes()

CmdFX_SpriteCostumes * Sprite_getCostumes

(

CmdFX_Sprite *

sprite

)

Gets the sprite costumes.

This method gets the sprite costumes from a sprite. It needs to be created if not already created, but is automatically freed with Sprite_free.

The default costume is the current sprite data itself at index 0.

Parameters

sprite

The sprite to get the costumes for.

Returns

The sprite costumes, or 0 if not created.

Sprite_getCurrentCostumeIndex()

int Sprite_getCurrentCostumeIndex

(

CmdFX_Sprite *

sprite

)

Gets the current index of the sprite costume.

This method gets the current index of the sprite costume. If the sprite costumes are not created, the method will return -1.

Parameters

sprite

The sprite to get the current costume index for.

Returns

The current costume index, or -1 if not valid.

Sprite_removeCostume()

int Sprite_removeCostume	(	CmdFX_Sprite *	sprite,
		int	costumeIndex )

Removes a sprite costume.

This method removes a sprite costume from the sprite. The costume will be removed from the costumes and the ansiCostumes arrays. If the costume does not exist, the method will return -1.

Parameters

sprite	The sprite to remove the costume from.
costumeIndex	The index of the costume to remove.

Returns

0 if successful, -1 if an error occurred.

Sprite_resetCostumes()

int Sprite_resetCostumes

(

CmdFX_Sprite *

sprite

)

Resets the sprite costumes.

This method resets the sprite costumes to the default costume, and removes all of the other costumes. The default costume is the current sprite data itself at index 0 that it was initialized with.

Parameters

sprite

The sprite to reset the costumes for.

Returns

0 if successful, -1 if an error occurred.

Sprite_setCostumeAt()

int Sprite_setCostumeAt	(	CmdFX_Sprite *	sprite,
		int	index,
		char **	costume,
		char ***	ansiCostume )

Sets a costume at the specified index.

This will set a costume at the specified index, changing the data and ANSI data the index and freeing it if available.

If the index is out of bounds, this method will return -2. If another error occurs, this method will return -1.

Parameters

sprite	The sprite to set the costume for.
index	The index to set the costume at.
costume	The data to use for the costume.
ansiCostume	The ANSI data to use for the costume.

Returns

0 if successful, otherwise an error occured.

Sprite_switchCostumeTo()

int Sprite_switchCostumeTo	(	CmdFX_Sprite *	sprite,
		int	costumeIndex )

Switches the sprite costume to a specific index.

This method switches the sprite costume to a specific index. If the index is out of bounds, the method will return -1. The costume will switch the data and the ansiData inside the sprite, and set the old data and ANSI data to the costume index.

Parameters

sprite	The sprite to switch the costume for.
costumeIndex	The index of the costume to switch to.

Returns

0 if successful, -1 if an error occurred.