β2.1 - From Frames come Animations and From Animations come Entities

SpriteTools Beta 2.1

This is the addition that has caused me the most trouble both now and in the past: entities. Hopefully our efforts here will relieve those using SpriteTools!

Make sure you read the ReadME before asking questions. Many of them are answered there.

How to Use

NOTE: SpriteTools currently have the following dependencies that must be installed: ctrulib, citro3d, sf2d (sf2d will eventually not be needed, but for now it is)

Extract the Source listed below, copy the source and include folders into your project, then you can start using any of the functions in this project in your own. You can then access all functions and features of the library in your project.

Attached is an example.beta2.1.zip file as an example of how to use the library.

New to SpriteTools and/or programming? Check out the Tutorial on the Wiki. It's designed for beginners so even if you have no experience, you should get by fine. The tutorial for 2.1 will be released with the official release so if you need a tutorial, it's probably best to use an earlier official release rather than a beta.

New Features

Entities

• You can create and free entities using ST_EntityCreateEntity(s64 x, s64 y, u8 animCount) (returns a pointer to an entity) and ST_EntityFreeEntity(st_entity *entity)
• You can add an animation to an entity using ST_EntityAddAnimation(st_entity *entity, st_animation *anim, char *name)
• You can set the attributes of entities using the following functions:

Function	Description
ST_EntitySetXPosition(st_entity *entity, s64 x)	Sets the entity's X position to the given value
ST_EntitySetYPosition(st_entity *entity, s64 y)	Sets the entity's Y position to the given value
ST_EntitySetPosition(st_entity *entity, s64 x, s64 y)	Sets the entity's position to the given values
ST_EntitySetScale(st_entity *entity, double scale)	Sets the entity's scale to the given value
ST_EntitySetRotation(st_entity *entity, double rotation)	Sets the entity's rotation to the given value
ST_EntitySetRed(st_entity *entity, u8 red)	Sets the red of an entity's blending color
ST_EntitySetGreen(st_entity *entity, u8 green)	Sets the green of an entity's blending color
ST_EntitySetBlue(st_entity *entity, u8 blue)	Sets the blue of an entity's blending color
ST_EntitySetAlpha(st_entity *entity, u8 alpha)	Sets the alpha of an entity's blending color
ST_EntitySetColor(st_entity *entity, u8 red, u8 green, u8 blue, u8 alpha)	Sets the values of an entity's blending color
ST_EntitySetDirection(st_entity *entity, char *dir)	Sets the entity's direction by name ie: "west", "south", "north east"
ST_EntitySetDirectionId(st_entity *entity, u8 dir)	Sets the entity's direction by id ie: 0 for "east", 3 for "south west", 6 for "north"
ST_EntitySetAnimationName(st_entity *entity, char *name)	Sets the entity's current animation by name (if the animation exists)
ST_EntitySetAnimationId(st_entity *entity, u8 id)	Sets the entity's current animation by id (if the animation exists)

• If you just want to modify the entity's values rather than setting them (ie: add 5 to the x position) you can use these functions:

Function	Description
ST_EntityModifyXPosition(st_entity *entity, s64 x)	Adds the given value to the entity's x position
ST_EntityModifyYPosition(st_entity *entity, s64 y)	Adds the given value to the entity's y position
ST_EntityModifyPosition(st_entity *entity, s64 x, s64 y)	Adds the given values to the entity's position values
ST_EntityModifyScale(st_entity *entity, double scale)	Adds the given value to the entity's scale
ST_EntityModifyRotation(st_entity *entity, double rotation)	Adds the given value to the entity's rotation
ST_EntityModifyRotationNoWrap(st_entity *entity, double rotation)	Same as above, but will not wrap past 0 or 2*pi
ST_EntityModifyRed(st_entity *entity, u8 red)	Adds the given value to the red of an entity's blending color
ST_EntityModifyRedNoWrap(st_entity *entity, u8 red)	Same as above, but will not wrap past 0 or 255
ST_EntityModifyGreen(st_entity *entity, u8 green)	Adds the given value to the green of an entity's blending color
ST_EntityModifyGreenNoWrap(st_entity *entity, u8 green)	Same as above, but will not wrap past 0 or 255
ST_EntityModifyBlue(st_entity *entity, u8 blue)	Adds the given value to the blue of an entity's blending color
ST_EntityModifyBlueNoWrap(st_entity *entity, u8 blue)	Same as above, but will not wrap past 0 or 255
ST_EntityModifyAlpha(st_entity *entity, u8 alpha)	Adds the given value to the alpha of an entity's blending color
ST_EntityModifyAlphaNoWrap(st_entity *entity, u8 alpha)	Same as above, but will not wrap past 0 or 255
ST_EntityModifyColor(st_entity *entity, u8 red, u8 green, u8 blue, u8 alpha)	Adds the given values to the values of an entity's blending color
ST_EntityModifyColorNoWrap(st_entity *entity, u8 red, u8 green, u8 blue, u8 alpha)	Same as above, but will not wrap past 0 or 255
ST_EntityModifyDirection(st_entity *entity, s8 dir)	Modifies the entity's direction by the given value. Positive turns right, negative turns left

• Entities can also hold up to 32 unnamed flags which can be turned on or off using the functions ST_EntityFlagOn(st_entity *entity, u8 flag), ST_EntityFlagOff(st_entity *entity, u8 flag), andST_EntityFlagToggle(st_entity *entity, u8 flag)`.
• You can get these flags using the function ST_EntityFlagGet(st_entity *entity, u8 flag) which returns a 1 or a 0 if the flag is on (1) or off (0).
  • For example, you could use flag 0 as "walking"so if the entity's flag 0 is on, it will play the walking animation but if it is off, it will play the standing animation.
• You can render entities using ST_RenderEntity(st_entity *entity) which will display the current animation as set by ST_EntitySetAnimationName(st_entity *entity, char *name) or ST_EntitySetAnimationId(st_entity *entity, u8 id).

Frames

• There's a new function ST_AnimationCreateFrameOffset(st_spritesheet *spritesheet, unsigned int xleft, unsigned int ytop, unsigned int width, unsigned int height, unsigned int xoff, unsigned int yoff) which gives a frame an x and y offset when being rendered.
  • A positive x offset will render a frame to the left, while a negative x offset will render a frame to the right.
  • A positive y offset will render a frame higher, while a negative y offset will render a frame lower.

Debugger

• The debugger used to create issues (error or crash) if scrolled past the added variables (in certain situations) and show a ton of VOID variables with no name that all pointed to NULL. The debugger will now show UNK variables in these slots and will not show a name or value. This should also fix those obscure errors and crashes.