`pyxen.world.spawn()`

월드에 새 **Entity**를 생성하고 선택적으로 컴포넌트 (스프라이트, 사운드, 음악, 맵, 물리 바디 등)를 첨부합니다.

씬에 오브젝트를 추가하는 기본 방법입니다.

구문

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

모든 인수는 키워드 전용입니다.

매개변수

매개변수	타입	설명
`name`	`str`	엔티티의 선택적 이름. 디버깅이나 조회에 유용.
`sprite`	`Sprite`	스프라이트 컴포넌트 첨부. Sprite 인스턴스여야 함.
`x`	`float`	초기 월드 X 위치. 기본값: `0.0`
`y`	`float`	초기 월드 Y 위치. 기본값: `0.0`
`parent`	`Entity`	부모 엔티티. 계층적 트랜스폼 활성화.
`layer`	`int`	렌더링 레이어. 부모의 레이어 또는 기본 월드 레이어로 기본 설정.
`sound`	`Sound`	사운드 컴포넌트 첨부.
`music`	`Music`	음악 컴포넌트 (스트리밍/디코딩) 첨부.
`map`	`GridMapInfo`	맵 정보에서 GridMap 컴포넌트 생성.
`body`	`GridBody`	GridBody 물리 컴포넌트 첨부.

반환값

Entity

새로 생성된 엔티티 인스턴스.

Transform 동작

생성된 모든 엔티티는 자동으로 Transform을 받습니다:

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

현재 생성 시 x와 y만 구성 가능합니다.

레이어 결정

레이어는 다음 순서로 결정됩니다:

명시적 layer 인수
부모의 레이어 (parent가 설정된 경우)
기본 월드 레이어

예시

기본 엔티티 생성

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

Sprite와 함께 생성

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

자식으로 생성

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

자식 엔티티는 트랜스폼 계층과 레이어를 상속합니다 (재정의하지 않는 한).

Sound와 함께 생성

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

Sound 컴포넌트가 첨부되어 재생 준비 완료.

Music과 함께 생성

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

Music은 내부 디코더를 사용하며 엔티티에 첨부됩니다.

그리드 맵 생성

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

제공된 GridMapInfo에서 초기화된 GridMap 컴포넌트를 생성합니다.

물리 바디와 함께 생성

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

그리드 기반 충돌을 위한 GridBody 컴포넌트를 첨부합니다.

컴포넌트 요약

제공된 인수에 따라 엔티티가 받을 수 있는 것:

Transform (항상)
Name (선택)
Sprite
Sound
Music
GridMap
GridBody
부모 관계
레이어 할당

타입 에러

다음 경우 TypeError를 발생시킵니다:

sprite가 Sprite가 아닌 경우
parent가 Entity가 아닌 경우
컴포넌트 타입이 예상 클래스와 맞지 않는 경우

예시:

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

참고

엔티티는 경량입니다.
컴포넌트는 선택적입니다.
엔티티는 즉시 월드에 등록됩니다.
계층과 레이어링은 생성 시 해결됩니다.

설계 철학

spawn()은 의도적으로 컴포넌트 기반입니다.

서브클래스를 만들지 않습니다. 컴포넌트를 첨부하여 동작을 조합합니다.

이를 통해 Pyxen은:

예측 가능
데이터 지향적
초보자 친화적
ECS 일관적