dusk/src/dusk/rpg/entity/entity.h

/**
 * Copyright (c) 2025 Dominic Masters
 * 
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */

#pragma once
#include "entitydir.h"
#include "anim/entityanim.h"
#include "interact/entityinteract.h"
#include "entitytype.h"
#include "npc/npc.h"
#include "rpg/overworld/tile.h"

typedef struct map_s map_t;

typedef uint16_t entityglobalid_t;

#define ENTITY_GLOBAL_ID_NULL 0
#define ENTITY_GLOBAL_ID_START 1
#define ENTITY_GLOBAL_ID_PLAYER 1

typedef struct entity_s {
  uint8_t id;
  entityglobalid_t globalId;
  entitytype_t type;
  entitytypedata_t data;

  // Movement
  entitydir_t direction;
  worldpos_t position;
  worldpos_t lastPosition;
  vec3 renderPosition;

  entityanim_t animation;
  float_t animTime;
  float_t walkEndCooldown;

  entityinteract_t interact;

  chunkindex_t chunkIndex;
} entity_t;

extern entity_t ENTITIES[ENTITY_COUNT];

/**
 * Initializes an entity structure.
 * 
 * @param entity Pointer to the entity structure to initialize.
 * @param type The type of the entity.
 */
void entityInit(entity_t *entity, const entitytype_t type);

/**
 * Updates an entity.
 * 
 * @param entity Pointer to the entity structure to update.
 */
void entityUpdate(entity_t *entity);

/**
 * Returns true if the entity is in a state where it can turn.
 *
 * @param entity Pointer to the entity to check.
 * @return True if the entity can turn.
 */
bool_t entityCanTurn(entity_t *entity);

/**
 * Returns true if the entity is in a state where it can walk.
 *
 * @param entity Pointer to the entity to check.
 * @return True if the entity can walk.
 */
bool_t entityCanWalk(entity_t *entity);

/**
 * Returns true if the entity is in a state where it can run.
 *
 * @param entity Pointer to the entity to check.
 * @return True if the entity can run.
 */
bool_t entityCanRun(entity_t *entity);

/**
 * Returns true if the entity is allowed to be unloaded. By default this is
 * true for entities whose global ID falls within the randomly assigned
 * range below ENTITY_GLOBAL_ID_START.
 *
 * @param entity Pointer to the entity to check.
 * @return True if the entity can be unloaded.
 */
bool_t entityCanUnload(entity_t *entity);

/**
 * Turn an entity to face a new direction.
 *
 * @param entity Pointer to the entity to turn.
 * @param direction The direction to face.
 */
void entityTurn(entity_t *entity, const entitydir_t direction);

/**
 * Checks whether an entity standing on a ramp tile can walk up it towards
 * newPos. If so, tileNew is cleared to TILE_NULL so the caller treats the
 * move as a raise rather than a normal walk onto whatever tile is there;
 * if the tile above isn't walkable, tileNew is restored to its original
 * value.
 *
 * @param tileCurrent The tile the entity is currently standing on.
 * @param direction The direction the entity is moving in.
 * @param newPos The world position the entity is moving to.
 * @param tileNew In/out: the tile at newPos, possibly cleared to TILE_NULL.
 * @return True if the entity should be raised up onto the ramp.
 */
bool_t entityWalkCheckRampUp(
  const tile_t tileCurrent,
  const entitydir_t direction,
  const worldpos_t newPos,
  tile_t *tileNew
);

/**
 * Checks whether an entity moving onto an empty tile should fall down onto
 * a ramp one z-level below that faces back towards where it came from.
 *
 * @param tileNew The tile at the position the entity is moving to.
 * @param newPos The world position the entity is moving to.
 * @param direction The direction the entity is moving in.
 * @return True if the entity should fall to the tile below newPos.
 */
bool_t entityWalkCheckFall(
  const tile_t tileNew, const worldpos_t newPos, const entitydir_t direction
);

/**
 * Checks whether any other loaded entity already occupies a world position.
 *
 * @param entity The entity that is moving (excluded from the check).
 * @param newPos The world position to check for occupancy.
 * @return True if another entity occupies newPos.
 */
bool_t entityWalkIsBlockedByEntity(entity_t *entity, const worldpos_t newPos);

/**
 * Make an entity walk in a direction.
 *
 * @param entity Pointer to the entity to make walk.
 * @param direction The direction to walk in.
 */
void entityWalk(entity_t *entity, const entitydir_t direction);

/**
 * Make an entity run in a direction.
 *
 * @param entity Pointer to the entity to make run.
 * @param direction The direction to run in.
 */
void entityRun(entity_t *entity, const entitydir_t direction);

/**
 * Gets the entity at a specific world position.
 *
 * @param map Pointer to the map to check.
 * @param pos The world position to check.
 * @return Pointer to the entity at the position, or NULL if none.
 */
entity_t *entityGetAt(const worldpos_t pos);

/**
 * Gets the entity with the given global ID, if one is currently loaded.
 *
 * @param globalId The global ID to search for.
 * @return Pointer to the matching entity, or NULL if none is loaded.
 */
entity_t *entityGetByGlobalId(const entityglobalid_t globalId);

/**
 * Gets an available entity index.
 *
 * @return The index of an available entity, or 0xFF if none are available.
 */
uint8_t entityGetAvailable();

/**
 * Assigns an entity to a chunk, removing it from its current chunk first.
 * Pass CHUNK_INDEX_INVALID as chunkIndex to detach the entity from any
 * chunk. If the target chunk has no free entity slots, the entity is
 * left detached (chunkIndex CHUNK_INDEX_INVALID) rather than assigned to
 * a chunk that isn't actually tracking it - entityUpdateChunk will keep
 * retrying on subsequent moves.
 *
 * @param entity Pointer to the entity.
 * @param chunkIndex Index of the chunk to assign to, or
 * CHUNK_INDEX_INVALID for none.
 */
void entitySetChunk(entity_t *entity, const chunkindex_t chunkIndex);

/**
 * Resolves the chunk that an entity's current position falls into and
 * assigns the entity to it via entitySetChunk. Leaves the entity's chunk
 * unchanged if its position doesn't fall within any loaded chunk.
 *
 * @param entity Pointer to the entity to update.
 */
void entityUpdateChunk(entity_t *entity);

/**
 * Instantly moves an entity to a world position, resetting movement state.
 *
 * @param entity Pointer to the entity to move.
 * @param pos The world position to place the entity at.
 */
void entityPositionSet(entity_t *entity, const worldpos_t pos);