`pyxen.world.spawn()`

Create a new Entity in the world and optionally attach components to it (sprite, sound, music, map, physics body, etc.).

This is the primary way to add objects to your scene.

Syntax

entity = pyxen.world.spawn(
    *,
    name=None,
    sprite=None,
    text=None,
    x=None,
    y=None,
    parent=None,
    layer=None,
    sound=None,
    music=None,
    map=None,
    body=None
)

All arguments are keyword-only.

Parameters

Parameter	Type	Description
`name`	`str`	Optional name for the entity. Useful for debugging or lookups.
`sprite`	`Sprite`	Attach a sprite component. Must be a Sprite instance.
`text`	`Text`	Attach a text component. Must be a Text instance.
`x`	`float`	Initial world X position. Default: `0.0`
`y`	`float`	Initial world Y position. Default: `0.0`
`parent`	`Entity`	Parent entity. Enables hierarchical transforms.
`layer`	`int`	Rendering layer. Defaults to parent’s layer or the default world layer.
`sound`	`Sound`	Attach a sound component.
`music`	`Music`	Attach a music component (streamed/decoded).
`map`	`GridMapInfo`	Create a GridMap component from map info.
`body`	`GridBody`	Attach a GridBody physics component.

Returns

Entity

A newly created entity instance.

Transform Behavior

Every spawned entity automatically receives a Transform:

x = 0.0
y = 0.0
scale_x = 1.0
scale_y = 1.0
rotation = 0.0

Currently, only x and y are configurable at spawn time.

Layer Resolution

Layer is determined in this order:

Explicit layer argument
Parent’s layer (if parent is set)
Default world layer

Examples

Spawn a Basic Entity

player = pyxen.world.spawn(x=32, y=16)

Spawn with a Sprite

player = pyxen.world.spawn(
    name="Player",
    sprite=assets.player_sprite,
    x=32,
    y=16
)

Spawn as a Child

weapon = pyxen.world.spawn(
    sprite=assets.sword,
    parent=player,
    x=8,
    y=0
)

Child entities inherit transform hierarchy and layer (unless overridden).

Spawn with Text

label = pyxen.world.spawn(
    text=Text("Score: 0"),
    x=10,
    y=10,
    layer=200
)

A Text component renders a string using a bitmap font.

Spawn with Sound

explosion = pyxen.world.spawn(
    sprite=assets.explosion,
    sound=assets.explosion_sfx,
    x=64,
    y=32
)

A Sound component is attached and ready for playback.

Spawn with Music

music_entity = pyxen.world.spawn(
    music=assets.background_theme
)

Music uses an internal decoder and is attached to the entity.

Spawn a Grid Map

level = pyxen.world.spawn(
    map=assets.level1_map
)

Creates a GridMap component initialized from the provided GridMapInfo.

Spawn with a Physics Body

player = pyxen.world.spawn(
    sprite=assets.player,
    body=GridBody.dynamic(),
    x=10,
    y=5
)

Attaches a GridBody component for grid-based collision.

Component Summary

Depending on the arguments provided, the entity may receive:

✅ Transform (always)
✅ Name (optional)
✅ Sprite
✅ Text
✅ Sound
✅ Music
✅ GridMap
✅ GridBody
✅ Parent relationship
✅ Layer assignment

Type Errors

The function will raise a TypeError if:

sprite is not a Sprite
parent is not an Entity
Component types do not match expected classes

Example:

pyxen.world.spawn(sprite="not a sprite")
# ❌ TypeError: spawn: sprite must be a Sprite

Notes

Entities are lightweight.
Components are optional.
The entity is immediately registered in the world.
Hierarchy and layering are resolved at spawn time.

Design Philosophy

spawn() is intentionally component-driven.

You don’t create subclasses. You compose behavior by attaching components.

This keeps Pyxen:

Predictable
Data-oriented
Beginner-friendly
ECS-consistent