libakgl/include/akgl/character.h

/**
 * @file character.h
 * @brief Declares the public character API.
 */

#ifndef _AKGL_CHARACTER_H_
#define _AKGL_CHARACTER_H_

#include <SDL3/SDL_properties.h>
#include "types.h"
#include "sprite.h"

#define AKGL_SPRITE_MAX_CHARACTER_NAME_LENGTH  128
#define AKGL_MAX_HEAP_CHARACTER                256

/** @brief Defines reusable movement parameters and actor-state sprite bindings. */
typedef struct akgl_Character {
    uint8_t refcount;
    char name[AKGL_SPRITE_MAX_CHARACTER_NAME_LENGTH];
    SDL_PropertiesID state_sprites;
    uint64_t speedtime;
    float32_t ax;
    float32_t ay;
    float32_t az;
    float32_t sx;
    float32_t sy;
    float32_t sz;
    akerr_ErrorContext AKERR_NOIGNORE *(*sprite_add)(struct akgl_Character *, akgl_Sprite *, int);
    akerr_ErrorContext AKERR_NOIGNORE *(*sprite_get)(struct akgl_Character *, int, akgl_Sprite **);
} akgl_Character;


/**
 * @brief Character initialize.
 * @param basechar Character whose state-to-sprite map is accessed.
 * @param name Registry key or human-readable object name.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_KEY When the corresponding validation or operation fails.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_character_initialize(akgl_Character *basechar, char *name);
/**
 * @brief Character sprite add.
 * @param basechar Character whose state-to-sprite map is accessed.
 * @param ref Sprite reference to associate with the character.
 * @param state Actor-state bit mask used as a sprite-map key.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_character_sprite_add(akgl_Character *basechar, akgl_Sprite *ref, int state);
/**
 * @brief Character sprite get.
 * @param basechar Character whose state-to-sprite map is accessed.
 * @param state Actor-state bit mask used as a sprite-map key.
 * @param dest Output destination populated by the function.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_KEY When the corresponding validation or operation fails.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_character_sprite_get(akgl_Character *basechar, int state, akgl_Sprite **dest);

// This is an SDL iterator so we can't return our error state from it.
/**
 * @brief Character state sprites iterate.
 * @param userdata Caller data supplied to the SDL property iterator.
 * @param props SDL property collection being iterated.
 * @param name Registry key or human-readable object name.
 */
void akgl_character_state_sprites_iterate(void *userdata, SDL_PropertiesID props, const char *name);

/**
 * @brief Character load json.
 * @param filename Path to the source asset or JSON document.
 * @return `NULL` on success, otherwise an error context owned by the caller.
 * @throws AKERR_NULLPOINTER When the corresponding validation or operation fails.
 */
akerr_ErrorContext AKERR_NOIGNORE *akgl_character_load_json(char *filename);

#endif // _AKGL_CHARACTER_H_