pyxen.Sprite

Entity에 할당되는 렌더링 가능한 이미지를 나타냅니다.

스프라이트는 불변 객체입니다. 엔티티가 표시하는 것을 변경하려면 스프라이트를 교체하세요.

렌더링 개념은 스프라이트 및 렌더링을 참조하세요.

생성자

Sprite(
    image,
    *,
    tile=None,
    pivot=None,
    animation=None,
    loop=True
)

image를 위치 인수 또는 키워드로 전달할 수 있지만, 둘 다는 안 됩니다.

매개변수

image (필수)

Sprite("hero")

이미지가 존재하지 않으면:

ValueError: Failed to load image 'hero'

tile (선택)

텍스처의 하위 영역을 정의합니다.

Sprite(
    "tileset",
    tile=(0, 0, 16, 16)
)

지정하지 않으면 전체 이미지가 사용됩니다.

pivot (선택)

스프라이트의 원점을 정의합니다.

Sprite(
    "hero",
    pivot=(8, 8)
)

지정하지 않으면: (0, 0) (좌상단 모서리).

animation (선택)

스프라이트 에디터의 애니메이션 타임라인에서 정의한 이름 있는 애니메이션을 재생합니다. 엔진이 이미지 메타데이터에서 애니메이션 데이터(프레임 시퀀스, FPS)를 읽고 프레임을 자동으로 진행합니다.

Sprite("hero", animation="walk")

tile과 함께 사용할 수 없습니다 — 둘 중 하나만 사용하세요.

애니메이션은 엔티티에 할당되면 즉시 재생을 시작합니다. 기본적으로 반복됩니다. 한 번만 재생하려면 loop=False를 사용하세요:

Sprite("hero", animation="death", loop=False)

애니메이션 상태를 확인하려면 엔티티의 e.animation 컴포넌트를 사용하세요.

loop (선택)

애니메이션의 반복 여부를 제어합니다. animation과 함께만 사용됩니다. 기본값: True.

Sprite("hero", animation="jump", loop=False)

예시

hero_sprite = Sprite(
    image="hero",
    tile=(0, 0, 16, 16),
    pivot=(8, 8)
)

애니메이션 스프라이트:

hero_sprite = Sprite(
    image="hero",
    animation="walk",
    pivot=(8, 8)
)

Sprite 할당

생성 시 할당할 수 있습니다:

player = world.spawn(
    sprite=Sprite("hero"),
    x=32,
    y=32
)

또는 나중에:

player.sprite = Sprite("hero_idle")

Sprite 불변성

스프라이트는 불변입니다 — 생성 후 수정할 수 없습니다.

대신 엔티티의 스프라이트를 교체합니다:

player.sprite = Sprite("hero_jump")

색상

엔티티는 스프라이트를 교체하지 않고 틴팅하는 color 속성을 노출합니다:

entity.color = (r, g, b, a)

예시:

player.color = (1.0, 0.5, 0.5, 1.0)

기본 색상: (1.0, 1.0, 1.0, 1.0)

color를 읽으면 Color 객체를 반환합니다:

c = player.color
print(c.r, c.g, c.b, c.a)

애니메이션

스프라이트 애니메이션에는 animation 매개변수를 사용하는 것이 권장됩니다. 스프라이트 에디터에서 이름 있는 애니메이션을 정의한 후 이름으로 재생합니다:

player.sprite = Sprite("hero", animation="walk")

새 스프라이트를 할당하여 애니메이션을 전환합니다:

player.sprite = Sprite("hero", animation="idle")

원샷 애니메이션의 경우 엔티티의 animation 컴포넌트를 통해 완료를 확인합니다:

player.sprite = Sprite("hero", animation="attack", loop=False)

def update():
    if player.animation and player.animation.finished:
        player.sprite = Sprite("hero", animation="idle")

수동 애니메이션

매 프레임 스프라이트의 타일을 교체하여 수동으로 애니메이션할 수도 있습니다:

player.sprite = Sprite(
    "atlas",
    tile=(frame * 16, 0, 16, 16)
)

일반적인 에러

이미지 누락

Sprite()

ValueError: Sprite must have an image

이미지 인수 중복

Sprite("hero", image="hero")

TypeError: image specified both positionally and as keyword

타일과 애니메이션 충돌

Sprite("hero", tile=(0, 0, 16, 16), animation="walk")

TypeError: cannot specify both tile and animation

애니메이션을 찾을 수 없음

Sprite("hero", animation="fly")

ValueError: Animation 'fly' not found in 'hero'