comedot Documentation

Use these components to handle data and resource management:

• StatsComponent: Stores and indexes an entity's Stat resources (health, ammo, XP) by name and UID.
• StatModifierComponent: Modifies Stat resources over time using a child Timer (e.g., regeneration or mana drain).
• StatModifierOnDeathComponent: Modifies Stat resources when the entity's HealthComponent reaches death (e.g., awarding XP or score).

The Entity script is the foundation of the system. It is used with a default Node2D scene and provides the following capabilities:

• Manages component installation and lookup.
• Handles lifecycle notifications.
• Provides cached shortcuts to the primary area, body, sprite, and camera nodes.
• Provides deletion helpers.

Comedot uses an opinionated Entity-Component-System (ECS) inspired framework for 2D games. Unlike traditional ECS, it avoids complex 'systems' logic in favor of a Node-based workflow:

• Entities: Regular Godot Nodes used to represent gameplay objects.
• Components: Regular Godot Nodes attached to Entities that handle specific gameplay mechanics (movement, combat, inventory, etc.).

You build gameplay by attaching components to entities and tweaking their exported properties in the Inspector. This allows you to mix Comedot components with your own custom scripts or other Godot addons seamlessly.

Comedot provides several ways to handle weaponry:

• GunComponent: A cooldown-based projectile weapon. It includes an editable gun sprite, pivot, and bullet emission point. It processes unhandled input so UI can intercept firing.
• BulletlessGunComponent: A cooldown-based weapon that applies instant damage at a target position instead of spawning projectiles. Best used with DamageComponent and aiming components for towers or hitscan attacks.
• BulletModifierComponent: Modifies projectile Entities emitted by a GunComponent (e.g., changing damage or adding visual effects). Requirement: This must run after the GunComponent.

In Comedot, Entities serve primarily as "scaffolding" or base containers. They manage lifecycle notifications, component installation, and provide shortcuts to common nodes (like primary areas, bodies, or sprites).

To implement specialized gameplay behavior, you should use Components. Entities provide the structure, while Components provide the logic. For more details on logic implementation, refer to the Components Catalog.md.

Comedot uses specialized Resource classes to define gameplay data and mechanics:

• Ability: Represents a selectable action or skill, optionally with StatCost and target requirements.
• Stat: Represents integer values like health, ammo, or XP.
• StatCost: Represents the cost (in Stats) for interactions or abilities.
• InventoryItem: Represents an item held in an InventoryComponent.
• Upgrade: Represents permanent or repeatable upgrades and their costs.
• TextSequence: A collection of text entries for dialogue or tutorials.
• StateMachine: Implements a simple StringName state list with allowed transitions.

To implement a standard combat system, use a pair of components:

1. DamageComponent: An Area2D hitbox that applies damage. It supports optional faction filtering and hit chance.
2. DamageReceivingComponent: An Area2D hurtbox that accepts hits from a DamageComponent and forwards the damage to a HealthComponent. It also supports faction filtering.

Variants:

• DamageRayComponent: A DamageComponent variant using RayCast2D to report only the first physics contact in a frame.
• DamageRepeatingComponent: A timer-based DamageComponent variant for hazards or turrets that repeatedly damage opposing receivers in contact.
• DamageOverTimeComponent: Adds timed, repeated damage to a DamageReceivingComponent without requiring continuous collision contact (e.g., poison or burn).

Comedot offers different ways to handle Area2D signals depending on your requirements:

• One-off Detection: Use AreaCollisionComponent to detect Areas, PhysicsBody2Ds, or TileMapLayers without maintaining a persistent contact list.
• Persistent Contact Tracking: Use AreaContactComponent when you need to track all Areas, PhysicsBody2Ds, or TileMapLayers currently touching the component's Area2D (a live contact list).
• TileMap Specifics: Use TileCollisionComponent to report collisions specifically with TileMapLayers and the involved cell coordinates.
• Automated Reactions: Use ModifyOnCollisionComponent to add/remove nodes/components or remove the entity entirely when specific Area2D collision criteria are met (e.g., projectile impacts).

To create an ability-based system, compose the following components:

• AbilityComponent: Stores the gameplay abilities (skills, spells) an entity can perform. Use with StatsComponent for cost management.
• AbilityControlComponent: Converts input actions into AbilityComponent.performAbility() calls. It automatically creates an AbilityTargetingComponentBase subclass if the ability requires a target.
• AbilityTargetableComponent: Marks an entity as a valid target. Requires a Node2D-style component node to receive mouse events.
• AbilityTargetingComponentBase: An abstract base for components that prompt an entity to choose a target.
• AbilityReactionComponent: An AbilityTargetableComponent subclass that runs Payload reactions after the entity is chosen as a target (e.g., for 'talk' or 'activate' commands).