# Entities Internals

## Purpose

Explain the core entity contract used across examples and games.

## Core file

- `packages/mini-arcade-core/src/mini_arcade_core/engine/entities.py`

## Entity structure

`BaseEntity` combines:

- identity:
  `id`, `name`, `codename`, `tags`
- transform:
  position, size, rotation
- visual data:
  `shape`, `style`, `sprite`, `anim`
- simulation data:
  `kinematic`, `life`
- optional collision data:
  `collider`

## `from_dict(...)`

`BaseEntity.from_dict(...)` is the main plain-data entrypoint. It parses:

- `transform.center`
- `transform.size`
- `transform.rotation_deg`
- `shape.kind`
- `style.fill` / `style.stroke`
- `kinematic.velocity` / `kinematic.acceleration` / `kinematic.max_speed`
- `sprite.texture`
- `anim.frames` / `anim.fps` / `anim.loop`

That makes it a good fit for:

- examples
- YAML-driven scene bootstrap
- test fixtures
- runtime spawn templates

`kinematic` data by itself does not move anything. A scene system has to consume
it, either through custom gameplay code or the built-in movement systems.

`tags` are preserved and normalized as lowercase unique strings. They are the
preferred way to express gameplay-facing categories such as `ship`, `bullet`,
`alien`, or `paddle`.

## World queries and id domains

`BaseWorld` is the query surface scenes should use around entities.

Preferred query model:

- `find_entity(tag="ship")`
- `find_entities(tag="bullet")`
- scene-local helpers like `world.ship()` or `world.aliens()`

For scenes that still need constrained runtime allocation, `BaseWorld` also
supports named entity-id domains:

- `entity_id_domains = {"bullet": EntityIdDomain(...)}`
- `get_entities_in_domain("bullet")`
- `allocate_entity_id_for("bullet")`
- `compact_tracked_entity_ids_for(attr_name="bullets", domain_name="bullet")`

Practical rule:

- use `tags` and world helper methods for gameplay logic and rendering
- use named id domains only for allocation, cleanup, or compatibility with
  fixed-content layouts

## Render precedence

The built-in queued renderer uses this priority:

1. `anim.texture`
2. `sprite.texture`
3. `shape` + `style`

That is why sprite/animation examples can use the same entity transform data as
shape examples.

## Tutorial references

- `docs/source/tutorials/entity/base_entity_from_dict.md`
- `docs/source/tutorials/entity/sprite_texture_basics.md`
- `docs/source/tutorials/entity/animation_frames_basics.md`