<commit_before>This file documents pud Components and properties, and their default values.

Component Hierarchy
===================
|- ModelComponent
 `|- CollisionComponent
  |- CombatComponent
  |- HealthComponent
  |- MotionComponent
  |- TimeComponent
|- ViewComponent
 `|- GraphicsComponent
|- ControllerComponent
 `|- InputComponent
   `|- PlayerInputComponent
    |- AIInputComponent


Component Properties
====================
* ModelComponent
    This is a parent to most data-oriented components. It does not have any
    properties of its own. You won't normally specify this in an entity file.

* ViewComponent
    This is a parent to most drawing components. It does not have any
    properties of its own. You won't normally specify this in an entity file.

* ControllerComponent
    This is a parent to most deterministic components. All child components of
    this component share its properties.  You won't normally specify this in
    an entity file.

    "CanOpenDoors": false
        If true, the entity can open doors. If false, the entity cannot.

* CollisionComponent
    This component decides whether the entity has collided with something when
    it attempts to move (or teleport, or anything else that changes its
    position).

    "BlockedBy": {"Wall": "ALL", "Door": "shut"}
        This is a list of MapNode types that will block this entity when it
        tries to change position. Possible values are:
            Wall:       - wall tiles
                ALL         - all walls
                normal      - normal (horizontal) walls
                vertical    - vertical walls
                worn        - worn (horizontal broken) walls
                torch       - walls with torches
            Floor:      - floor tiles
                ALL         - all floors
                normal      - normal floors
                worn        - worn (broken) floors
                interior    - interior floors
                rug         - rug tiles
            Door:       - door tiles
                ALL         - all doors
                open        - open doors
                shut        - shut doors
            Stair       - stair tiles
                ALL         - all stairs
                up          - up stairs
                down        - down stairs
            Trap        - trap tiles
                ALL         - all traps
                normal      - normal traps

* CombatComponent
    This component determines the outcome of combat between entities.

    "Attack": 1
        The base attack value of the entity.

    "Defense": 1
        The base defense value of the entity.

    "AttackBonus": 0
        Bonus Attack value for the entity (will be added in most
        calculations). This is generally not supplied on heros or enemies, but
        might be found on items.

    "DefenseBonus": 0
        Bonus Defense value for the entity (see AttackBonus for notes).

* GraphicsComponent
    This component defines the visual representation of the entity (i.e. its
    Tile).

    "TileSet": "dungeon"
        This property provides a string that describes a png filename in the
        image/ directory. The default, "dungeon" is actually
        "image/dungeon.png". You can provide your own png file, if you like
        (though keep in mind that tilesets with many tiles in one image are
        much more efficient than single tile files).

        Say you make a whole new set of enemies, and call it killerfish.png.
        Make sure the file exists as "pud/image/killerfish.png", and then you
        can specify it here with "TileSet": "killerfish".

    "TileSize": 32
        The size of tiles within the TileSet. All tiles are square.

    "TileCoords": {"front": {1, 1}}
        This property provides a list of frames for the entity, and
        coordinates for each frame within the TileSet. Note that coordinates
        start at 1, and are multiples of TileSize (in other words, the
        x coordinate describes the number of tiles to count right from the
        left side of the TileSet, and the y coordinate describes the number
        tiles to count down from the top of the TileSet).

        Notice that each coordinate pair is itself enclosed in curly braces.

        Pud treats the following frame names as directional frames (for the
        eight cardinal directions): "front", "back", "left", "right",
        "frontleft", "frontright", "backleft", "backright". If any of the left
        or right frames are missing, Pud will simply flip its counterpart (for
        example, if "left" is missing, Pud will flip "right" to make left...
        if "backright" is missing, Pud will flip "backleft" to make
        "backright", etc).

        Pud will also use the first frame it finds, if it cannot find a frame
        for a particular direction. So if you only supply "front", for
        example, Pud will use "front" for every direction.

        An example of how to specify multiple frames:
            "TileCoords": {
                "left": {2, 5},
                "frontleft": {3, 5},
                "front": {4, 5},
            }

    "Visibility": 6
        This is the radius of visibility for the entity (i.e. how many tiles
        away from its position can it see).

* HealthComponent
    This component defines health properties for the entity.

    "Health": 1
        The base current health value.

    "MaxHealth": 1
        The base maximum health value.

    "HealthBonus": 0
        Bonus Health value for the entity (see AttackBonus for notes).

    "MaxHealthBonus": 0
        Bonus Maximum Health value for the entity (see AttackBonus for notes).

* InputComponent
    This component handles input given to the entity. It is usually not
    specified in an entity file, since its child components
    (PlayerInputComponent, AIInputComponent) are more specific.  This
    component has no properties of its own, but it accepts the same properties
    as its parent components (namely, ControllerComponent).

* PlayerInputComponent
    This component monitors keyboard and mouse input and determines what the
    entity should do based on this input. This component has no properties of
    its own, but it accepts the same properties as its parent components
    (namely, ControllerComponent).

* AIInputComponent
    This component uses various algorithms to determine what the entity should
    be doing. This component has no properties of its own, but it accepts the
    same properties as its parent components (namely, ControllerComponent).

* MotionComponent
    This component keeps track of the entity's position and provides the means
    for it to move (as opposed to CollisionComponent, which just determines
    whether or not the entity *can* move).

    "Position": {1, 1}
        The map coordinates of the entity. Usually not provided in the entity
        file, but rather determined by the game after map creation.

    "CanMove": true
        If true, the entity is allowed to move. If false, it is not.

* TimeComponent
    This component determines how long each action taken by the entity takes.

    "DefaultCost": 1
        This is the default cost (in Action Points) of an action, which is
        used if a more specific cost cannot be found.

    "AttackCost": 1
        How many Action Points it costs for this entity to make an attack.

    "MoveCost": 1
        How many Action Points it costs for this entity to move.

    "WaitCost": 1
        How many Action Points it costs for this entity to skip a turn.

    "Speed": 1
        This is the number of Action Points the entity earns each turn.
        Higher numbers mean the entity will have more Action Points to spend
        on every turn, therefore making the entity accomplish more and appear
        to be faster.

    "SpeedBonus": 0
        Bonus value for Speed (see AttackBonus for notes).

    "IsExhausted": false
        If true, the entity has become exhausted and will be removed from the
        TimeSystem altogether (and will have no more turns). This is generally
        not specified in the entity file.

    "DoTick": true
        If true, the entity will have its turn every time the TimeSystem
        "ticks". If false, the TimeSystem will wait until this property is
        true. This is mostly used to wait for human input, and is generally
        not specified in the entity file.


Default Components
==================
These are the components that will be created for each kind of entity, whether
you specify them in the entity file or not. (In other words, if
MotionComponent is missing from an enemy entity, Pud will create a default
MotionComponent for the entity.)

Hero:
    GraphicsComponent
    HealthComponent
    CombatComponent
    CollisionComponent
    MotionComponent
    TimeComponent
    InputComponent

Enemy:
    GraphicsComponent
    HealthComponent
    CombatComponent
    CollisionComponent
    MotionComponent
    TimeComponent
    AIInputComponent

Item:
    MotionComponent
    GraphicsComponent

<commit_msg>update docs<commit_after>This file documents pud Components and properties, and their default values.

Component Hierarchy
===================
|- ModelComponent
 `|- CollisionComponent
  |- CombatComponent
  |- HealthComponent
  |- MotionComponent
  |- TimeComponent
  |- ContainerComponent
  |- *AttachmentComponent
|- ViewComponent
 `|- GraphicsComponent
|- ControllerComponent
 `|- InputComponent
   `|- PlayerInputComponent
    |- AIInputComponent


Component Properties
====================
* ModelComponent
    This is a parent to most data-oriented components. It does not have any
    properties of its own. You won't normally specify this in an entity file.

* ViewComponent
    This is a parent to most drawing components. It does not have any
    properties of its own. You won't normally specify this in an entity file.

* ControllerComponent
    This is a parent to most deterministic components. All child components of
    this component share its properties.  You won't normally specify this in
    an entity file.

    "CanOpenDoors": false
        If true, the entity can open doors. If false, the entity cannot.

* CollisionComponent
    This component decides whether the entity has collided with something when
    it attempts to move (or teleport, or anything else that changes its
    position).

    "BlockedBy": {"Wall": "ALL", "Door": "shut"}
        This is a list of MapNode types that will block this entity when it
        tries to change position. Possible values are:
            Wall:       - wall tiles
                ALL         - all walls
                normal      - normal (horizontal) walls
                vertical    - vertical walls
                worn        - worn (horizontal broken) walls
                torch       - walls with torches
            Floor:      - floor tiles
                ALL         - all floors
                normal      - normal floors
                worn        - worn (broken) floors
                interior    - interior floors
                rug         - rug tiles
            Door:       - door tiles
                ALL         - all doors
                open        - open doors
                shut        - shut doors
            Stair       - stair tiles
                ALL         - all stairs
                up          - up stairs
                down        - down stairs
            Trap        - trap tiles
                ALL         - all traps
                normal      - normal traps

* CombatComponent
    This component determines the outcome of combat between entities.

    "Attack": 0
        The attack value of the entity. On item entities, this will be added
        to the hero/enemy entity's value when equipped.

    "Defense": 0
        The defense value of the entity. On item entities, this will be added
        to the hero/enemy entity's value when equipped.

* GraphicsComponent
    This component defines the visual representation of the entity (i.e. its
    Tile).

    "TileSet": "dungeon"
        This property provides a string that describes a png filename in the
        image/ directory. The default, "dungeon" is actually
        "image/dungeon.png". You can provide your own png file, if you like
        (though keep in mind that tilesets with many tiles in one image are
        much more efficient than single tile files).

        Say you make a whole new set of enemies, and call it killerfish.png.
        Make sure the file exists as "pud/image/killerfish.png", and then you
        can specify it here with "TileSet": "killerfish".

    "TileSize": 32
        The size of tiles within the TileSet. All tiles are square.

    "TileCoords": {"front": {1, 1}}
        This property provides a list of frames for the entity, and
        coordinates for each frame within the TileSet. Note that coordinates
        start at 1, and are multiples of TileSize (in other words, the
        x coordinate describes the number of tiles to count right from the
        left side of the TileSet, and the y coordinate describes the number
        tiles to count down from the top of the TileSet).

        Notice that each coordinate pair is itself enclosed in curly braces.

        Pud treats the following frame names as directional frames (for the
        eight cardinal directions): "front", "back", "left", "right",
        "frontleft", "frontright", "backleft", "backright". If any of the left
        or right frames are missing, Pud will simply flip its counterpart (for
        example, if "left" is missing, Pud will flip "right" to make left...
        if "backright" is missing, Pud will flip "backleft" to make
        "backright", etc).

        Pud will also use the first frame it finds, if it cannot find a frame
        for a particular direction. So if you only supply "front", for
        example, Pud will use "front" for every direction.

        An example of how to specify multiple frames:
            "TileCoords": {
                "left": {2, 5},
                "frontleft": {3, 5},
                "front": {4, 5},
            }

    "Visibility": 0
        This is the radius of visibility for the entity (i.e. how many tiles
        away from its position can it see). On item entities, this will be
        added to the hero/enemy entity's value when equipped.

* HealthComponent
    This component defines health properties for the entity.

    "Health": 0
        The current health value of the entity. On item entities, this will be
        added to the hero/enemy entity's value when equipped.

    "MaxHealth": 0
        The maximum health value of the entity. On item entities, this will be
        added to the hero/enemy entity's value when equipped.

* InputComponent
    This component handles input given to the entity. It is usually not
    specified in an entity file, since its child components
    (PlayerInputComponent, AIInputComponent) are more specific.  This
    component has no properties of its own, but it accepts the same properties
    as its parent components (namely, ControllerComponent).

* PlayerInputComponent
    This component monitors keyboard and mouse input and determines what the
    entity should do based on this input. This component has no properties of
    its own, but it accepts the same properties as its parent components
    (namely, ControllerComponent).

* AIInputComponent
    This component uses various algorithms to determine what the entity should
    be doing. This component has no properties of its own, but it accepts the
    same properties as its parent components (namely, ControllerComponent).

* MotionComponent
    This component keeps track of the entity's position and provides the means
    for it to move (as opposed to CollisionComponent, which just determines
    whether or not the entity *can* move).

    "Position": {1, 1}
        The map coordinates of the entity. Usually not provided in the entity
        file, but rather determined by the game after map creation.

    "CanMove": true
        If true, the entity is allowed to move. If false, it is not.

* TimeComponent
    This component determines how long each action taken by the entity takes.

    "DefaultCost": 0
        This is the default cost (in Action Points) of an action, which is
        used if a more specific cost cannot be found.

    "AttackCost": 1
        How many Action Points it costs for this entity to make an attack.

    "MoveCost": 1
        How many Action Points it costs for this entity to move.

    "WaitCost": 1
        How many Action Points it costs for this entity to skip a turn.

    "Speed": 1
        This is the number of Action Points the entity earns each turn.
        Higher numbers mean the entity will have more Action Points to spend
        on every turn, therefore making the entity accomplish more and appear
        to be faster. On item entities, this will be added to the hero/enemy
        entity's value when equipped.

    "IsExhausted": false
        If true, the entity has become exhausted and will be removed from the
        TimeSystem altogether (and will have no more turns). This is generally
        not specified in the entity file.

    "DoTick": true
        If true, the entity will have its turn every time the TimeSystem
        "ticks". If false, the TimeSystem will wait until this property is
        true. This is mostly used to wait for human input, and is generally
        not specified in the entity file.

* ContainerComponent
    This component allows the entity to contain other entities. This might be
    an inventory on a hero or enemy, and might turn an item into a bag.

    "MaxContainerSize": 0
        This is the maximum number of entities that this component can
        contain.

* *AttachmentComponent
    These components allow certain families of entities to be attached to the
    entity that has these components. Entities that are attached will add
    their properties to the host entity.

    For example, a hero might have a WeaponAttachmentComponent, which allows
    him to equip a weapon. Or, an item entity (say, a sword) might have a
    JewelAttachmentComponent which allows it to slot a jewel into the sword to
    provide some extra benefit.


Default Components
==================
These are the components that will be created for each kind of entity, whether
you specify them in the entity file or not. (In other words, if
MotionComponent is missing from an enemy entity, Pud will create a default
MotionComponent for the entity.)

Hero:
    GraphicsComponent
    HealthComponent
    CombatComponent
    CollisionComponent
    MotionComponent
    TimeComponent
    InputComponent
    ContainerComponent
    WeaponAttachmentComponent
    ArmorAttachmentComponent
    RingAttachmentComponent

Enemy:
    GraphicsComponent
    HealthComponent
    CombatComponent
    CollisionComponent
    MotionComponent
    TimeComponent
    AIInputComponent

Item:
    MotionComponent
    CollisionComponent
    GraphicsComponent


{'fraction_non_alphanumeric': 0.05146327417412701, 'fraction_numerical': 0.0027223705565153655, 'mean_word_length': 2.3665844201621433, 'pattern_counts': {'":': 60, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4508843', 'n_tokens_mistral': 4637, 'n_tokens_neox': 4397, 'n_words': 2441}