entity/base_entity_from_dict

Goal

Understand the minimum data contract needed to create a renderable entity with BaseEntity.from_dict(...).

Why this tutorial exists

Before introducing textures, animations, or system-heavy gameplay code, you need to understand the plain entity payload shape:

  • transform

  • shape

  • style

  • kinematic

  • collider

  • z_index

This tutorial keeps the example small and shows that one dictionary is enough to produce a moving world object. The courier motion itself now goes through the built-in movement helpers instead of ad hoc scene math.

Source map

  • Settings profile: examples/settings/entity/base_entity_from_dict.yml

  • Example builder: examples/catalog/entity/base_entity_from_dict/main.py

  • Scene: examples/catalog/entity/base_entity_from_dict/scenes/scene.py

  • Shared entity helpers: examples/catalog/entity/_shared.py

  • Entity core: packages/mini-arcade-core/src/mini_arcade_core/engine/entities.py

What to verify

You should see:

  1. a cyan rectangle moving and bouncing across the guide line

  2. a triangle rendered only from stroke data

  3. a circle rendered from shape + style

  4. the right-side panel updating the courier position and velocity

Run

mini-arcade run --example entity/base_entity_from_dict
mini-arcade run --example entity/base_entity_from_dict --pass-through --backend pygame
mini-arcade run --example entity/base_entity_from_dict --pass-through --backend native

Key idea

The moving courier is built from one plain dictionary:

entity = BaseEntity.from_dict(
    {
        "id": 1,
        "name": "Courier Block",
        "transform": {
            "center": {"x": 56.0, "y": 236.0},
            "size": {"width": 96.0, "height": 56.0},
        },
        "shape": {"kind": "rect"},
        "style": {"fill": [82, 193, 255, 255]},
        "kinematic": {
            "velocity": {"vx": 150.0, "vy": 0.0},
            "max_speed": 150.0,
        },
    }
)

That payload is enough for:

  • construction

  • simulation data attachment

  • built-in rendering

The example scene then hands the courier to the shared entity tutorial motion stack, which uses KinematicMotionSystem plus ViewportConstraintSystem for movement and bounds handling.

Next step