entities package

Submodules

models.entities.character module

class models.entities.character.Character(name, appearance, backstory, personality, languages, spellslots, spellcasting_ability, char_class, char_class_features, species, species_traits, subclass, feats, background, level, xp, armor_class, death_saves, hp, stats, inventory, training_proficiencies, spells, proficiency_bonus, hit_dice, saving_throws, skills, temporary_hp, inspiration, passive_perception, conditions, currency, exhaustion_level, armor, weapons, speed, initiative, resistances, immunities, vulnerabilities)

Bases: GameEntity

Class representing a character.

cast_spell(spell_name, target)

Cast a spell.

Parameters:

  • spell_name (str) – Name of the spell to cast

  • target (Any) – Target of the spell

heal(amount)

Heal the character.

Parameters:

amount (int) – Amount of healing to apply

save_to_db(db_conn)

Save the character to the database.

Uses the characters table schema from db_init.py: name, class, level, hp, stats, inventory, spells.

Parameters:

db_conn (sqlite3.Connection) – Database connection object

take_damage(damage)

Apply damage to the character.

Parameters:

damage (int) – Amount of damage to apply

models.entities.enemy module

class models.entities.enemy.Enemy(name, armor_class, hp, stats, saving_throws, attacks, speed, resistances, immunities, vulnerabilities, condition_immunities, challenge_rating, xp, conditions, initiative, spells)

Bases: GameEntity

Represents an enemy entity in the game.

Parameters:

  • name (str) – Name of the enemy

  • armor_class (int) – Armor class value

  • hp (int) – Hit points

  • stats (dict) – Dictionary of stats (e.g., {“Strength”: 10, …})

  • saving_throws (dict) – Dictionary of saving throw values

  • attacks (list) – List of attack dictionaries

  • speed (int) – Movement speed

  • resistances (list) – List of resistances

  • immunities (list) – List of immunities

  • vulnerabilities (list) – List of vulnerabilities

  • condition_immunities (list) – List of condition immunities

  • challenge_rating (float) – Challenge rating

  • xp (int) – Experience points

  • conditions (list) – List of current conditions

  • initiative (int) – Initiative value

  • spells (list) – List of spells

cast_spell(spell_name, target)

Cast a spell.

Parameters:

  • spell_name (str) – Name of the spell to cast

  • target (object) – Target of the spell

heal(amount)

Heal the enemy by a specified amount, up to its maximum hit points.

Parameters:

amount (int) – Amount to heal

save_to_db(db_conn)

Save the enemy to the database.

Parameters:

db_conn (sqlite3.Connection) – Database connection object

take_damage(damage)

Apply damage to the enemy, reducing its hit points.

Parameters:

damage (int) – Amount of damage to apply

models.entities.entity_type module

class models.entities.entity_type.EntityType(value)

Bases: Enum

Enumeration of possible entity types in the DnD project.

Variables:

  • PLAYER – Represents a player entity.

  • ENEMY – Represents an enemy entity.

  • NPC – Represents a non-player character entity.

  • OBJECT – Represents an object entity.

ENEMY = 'enemy'
NPC = 'npc'
OBJECT = 'object'
PLAYER = 'player'

models.entities.game_entity module

class models.entities.game_entity.GameEntity(name, entity_type, stats=None, inventory=None)

Bases: object

Represents a game entity with stats, inventory, and triggers.

Parameters:

  • name (str) – The name of the entity.

  • entity_type (str) – The type/category of the entity.

  • stats (dict, optional) – The stats dictionary for the entity.

  • inventory (list, optional) – The inventory list for the entity.

classmethod from_dict(data)

Create a GameEntity instance from a dictionary.

Parameters:

data (dict) – Dictionary containing entity data.

Returns:

A GameEntity instance.

Return type:

GameEntity

handle_event(event_type, data)

Handle a tile-based event by running any triggers matching event_type.

Parameters:

  • event_type (str) – The type of event to handle.

  • data (Any) – Data associated with the event.

register_trigger(trigger)

Register a trigger for this entity if not already registered.

Parameters:

trigger (Trigger) – The trigger to register.

to_dict()

Serialize the entity to a dictionary.

Returns:

Dictionary representation of the entity.

Return type:

dict

models.entities.named_enemy module

class models.entities.named_enemy.NamedEnemy(name, armor_class, hp, stats, saving_throws, attacks, speed, resistances, immunities, vulnerabilities, condition_immunities, challenge_rating, xp, conditions, initiative, spells, backstory, legendary_actions, lair_actions, regional_effects, spellcasting_ability, phases)

Bases: Enemy

Represents a named enemy with additional lore, actions, and spellcasting abilities.

Inherits from Enemy and adds properties such as backstory, legendary actions, lair actions, regional effects, spellcasting ability, and combat phases.

cast_spell(spell_name, target)

Cast a spell by name on a target.

Parameters:

  • spell_name (str) – Name of the spell to cast.

  • target (object) – Target of the spell.

heal(amount)

Heal the enemy, increasing its hit points up to max_hp.

Parameters:

amount (int) – Amount of hit points to restore.

save_to_db(db_conn)

Save the enemy’s data to the database.

Parameters:

db_conn (sqlite3.Connection) – Database connection object.

take_damage(damage)

Apply damage to the enemy, reducing its hit points.

Parameters:

damage (int) – Amount of damage to apply.

models.entities.npc module

class models.entities.npc.NPC(name, behavior)

Bases: GameEntity

Represents a Non-Player Character (NPC) in the game.

Inherits from GameEntity.

take_turn()

Defines the NPC’s behavior during their turn.

The action taken depends on the NPC’s behavior attribute: - “friendly”: May move around or interact with the player. - “neutral”: May idle or react passively. - “hostile”: May flee or attack.

models.entities.player

class models.entities.player.Player(character, db_conn, player_id)

Bases: GameEntity

Represents a player in the game.

Inherits from GameEntity and manages player-specific data and actions.

attack(target)

Perform a simple STR-based attack against a target and log the result in the combat log.

Parameters:

target (object) – The entity being attacked. Must have armor_class and take_damage() attributes.

Returns:

Tuple indicating if the attack hit and the damage dealt (hit: bool, damage: int).

Return type:

tuple

cast_spell(spell_name, target)

Cast a spell using the associated Character’s cast_spell method.

Parameters:

  • spell_name (str) – Name of the spell to cast.

  • target (object) – The target of the spell.

Returns:

Result of the Character’s cast_spell method.

interact(obj)

Interact with an object if it has an interact(player) method.

Parameters:

obj (object) – The object to interact with.

Returns:

The result of the object’s interact method, or None if not available.

investigate(location)

Perform a Wisdom-based investigation check (d20 + WIS modifier).

Parameters:

location (object) – The location or object being investigated.

Returns:

The total roll (d20 + WIS modifier).

Return type:

int

move(direction: str)

Move the player north, south, east, or west by one tile and persist the new position to the database.

Parameters:

direction (str) – Direction to move (‘north’, ‘south’, ‘east’, ‘west’).

Returns:

The new position as a tuple (x, y).

Return type:

tuple

take_turn()

Stub for the per-turn loop.

You’ll want to hook this into your UI or CLI.

Raises:

NotImplementedError – Always, as this should be implemented by the game loop or UI.

models.entities.trap module

class models.entities.trap.Trap(name, damage, trigger_range)

Bases: GameEntity

Represents a trap entity in the game.

Inherits from GameEntity.

take_turn()

Traps don’t take actions, but they may be triggered during movement.