role

Role (Component) base class definition.

This module defines the Role base class, the fundamental building block of the BAM-ECS architecture. Roles are dataclasses containing NumPy arrays that represent specific aspects of agent behavior.

Design Notes

• All Roles auto-register via __init_subclass__ hook

• Each Role has a name (ClassVar) set automatically

• Roles should be immutable containers; use system functions for mutations

• NumPy array fields enable vectorized operations across all agents

Auto-Registration

When a class inherits from Role, __init_subclass__ automatically:

1. Sets the role name (cls.name) to class name if not provided

2. Registers the role class in the global _ROLE_REGISTRY

3. Makes the role retrievable via get_role(name)

This eliminates manual registration boilerplate and ensures all roles are discoverable at runtime.

See also

Event

Base class for events (systems) in BAM-ECS

registry

Global role and event lookup system

role()

Simplified decorator for defining roles

Classes

Role	Base class for all roles (components) in the BAM-ECS architecture.