Assets and Tilesheets ko

Asset 및 Tilesheet

English | 繁體中文 | 日本語 | 한국어

BIT8_CLI는 등록된 PNG Tilesheet를 사용하여 게임 그래픽 리소스를 관리합니다.

각 Tilesheet는 8×8 픽셀 크기의 Tile로 나뉩니다. 등록된 Tile에는 안정적인 Asset ID가 부여되며 Script, Map, Sprite 및 Collision 시스템에서 참조할 수 있습니다.

이 가이드에서는 BIT8_CLI 0.1.0의 Asset 시스템을 소개합니다.

1. Tilesheet

Tilesheet는 여러 Tile이 포함된 PNG 이미지입니다.

BIT8_CLI는 고정된 Tile 크기를 사용합니다.

8 × 8 픽셀

예를 들어 32×16 픽셀 PNG에는 다음이 포함됩니다.

• 4열
• 2행
• 8개의 Tile

Tile은 왼쪽에서 오른쪽, 위에서 아래 순서로 번호가 지정됩니다.

32 × 16 PNG

+------+------+------+------+
|  A1  |  A2  |  A3  |  A4  |
+------+------+------+------+
|  A5  |  A6  |  A7  |  A8  |
+------+------+------+------+

각 Tile은 정확히 8×8 픽셀입니다.

2. Asset Registry

BIT8_CLI는 Asset Registry를 사용하여 등록된 Tilesheet를 관리합니다.

Registry는 다음 파일에 저장됩니다.

bit8.assets.toml

Registry는 Tilesheet를 안정적인 Group ID와 연결합니다.

예를 들어 Tilesheet에 Group A가 지정되었다면 해당 Tile을 다음과 같이 참조할 수 있습니다.

A1
A2
A3
A4

Asset Registry는 Asset 식별 정보의 기준이 되는 공식 데이터입니다.

PNG를 프로젝트에 배치하는 것만으로 자동 등록된다고 가정하지 마세요.

프로젝트에서 지원하는 Asset 등록 기능을 사용하여 Registry 항목을 만들거나 업데이트해야 합니다.

3. Stable Asset IDs

BIT8_CLI는 다음 형식의 안정적인 식별자를 사용합니다.

Group + Tile Number

예:

A1
A4
B12
C3

Group은 등록된 Tilesheet를 식별합니다.

숫자는 해당 Tilesheet 내부의 Tile을 식별합니다.

이 구조를 사용하면 Script와 Map이 전역 숫자 순서에 의존하지 않고 Tile을 참조할 수 있습니다.

예를 들어:

spr(A4, 16, 16)

은 지정된 좌표에 Tile A4를 그립니다.

Stable ID가 중요한 이유

여러 Tilesheet가 있는 프로젝트를 생각해 봅시다.

Asset이 전역 목록의 위치에만 의존한다면 Tilesheet를 추가하거나 순서를 변경할 때 기존 참조가 달라질 수 있습니다.

Stable Asset ID는 이러한 문제를 방지하기 위해 설계되었습니다.

BIT8_CLI는 사용이 종료된 Group ID도 기록하여 실수로 다시 사용하지 않도록 합니다.

4. 등록된 PNG 파일 이름

등록된 Tilesheet는 다음과 같은 표준 파일 이름 형식을 사용합니다.

<name> (<GROUP>).png

예:

terrain (A).png
characters (B).png
items (C).png

Group ID는 등록된 Asset 식별 정보의 일부입니다.

그러나 최종 기준은 Asset Registry입니다.

Registry를 업데이트하지 않고 등록된 PNG 파일의 이름을 직접 변경하면 Asset 참조가 깨질 수 있습니다.

5. Tile 그리기

등록된 Tile을 그리려면 spr()을 사용합니다.

func draw()
    cls(0)
    spr(A4, 16, 16)
end

이 코드는 화면을 지우고 Tile A4를 그립니다.

참조하는 Tile은 프로젝트의 Asset Registry에 존재해야 합니다.

BIT8_CLI는 이전 프로젝트와의 호환성을 위해 기존 숫자 Sprite 참조도 계속 지원합니다.

새 프로젝트에서는 Stable Asset ID를 사용하는 것이 좋습니다.

6. 투명도와 팔레트

BIT8_CLI는 등록된 PNG Tilesheet의 투명 픽셀을 지원합니다.

투명 픽셀은 Tile을 그릴 때도 투명하게 처리됩니다.

PNG 색상은 Runtime에서 사용하는 팔레트 표현으로 변환됩니다.

Asset 처리 과정은 Runtime 렌더링 결과와 Editor 미리보기가 일치하도록 설계되어 있습니다.

예측 가능한 결과를 얻으려면 색상과 투명도가 명확한 Pixel Art 이미지를 사용하는 것이 좋습니다.

7. Solid Tile

Tile은 Collision 판정을 위해 Solid로 설정할 수 있습니다.

Solid Tile 정보는 Asset Registry에 저장됩니다.

예를 들어 Tilesheet의 여섯 번째 Tile을 Solid로 지정하려면:

solid = [6]

이 값은 등록된 Tilesheet Group 내부의 여섯 번째 Tile을 의미합니다.

Solid Tile은 Collision 판정에서 전체 8×8 픽셀 영역을 차지합니다.

Node는 다음 메서드를 사용하여 Solid Tile과의 Collision을 처리할 수 있습니다.

self:collide(dx, dy)

그리고:

self:move(dx, dy)

solid는 bit8.assets.toml의 해당 Asset 등록 항목 내부에 작성해야 합니다. 관련 없는 최상위 설정으로 배치하지 마세요.

자세한 내용은 Collision 페이지를 참고하세요.

8. Asset 및 Map

Map은 등록된 Asset ID를 참조합니다.

Map Cell에는 다음과 같은 Tile ID를 지정할 수 있습니다.

A1
A2
A3

이를 통해 하나의 Map에서 서로 다른 Group의 Tile을 사용할 수 있습니다.

Map Workspace에는 등록된 Tile을 선택하고 Map Cell에 배치하는 도구가 있습니다.

자세한 내용은 Map 페이지를 참고하세요.

9. Asset 및 Sprite

Sprite Definition도 등록된 Tile을 사용합니다.

Sprite는 Tile을 참조하여 다음 요소를 정의할 수 있습니다.

• 정적 미리보기
• Animation Frame
• 이름이 지정된 Animation

Sprite Definition은 다음 파일에 저장됩니다.

bit8.sprites.toml

예를 들어 Player라는 Sprite는 여러 등록된 Tile을 Animation Frame으로 사용할 수 있습니다.

Node Script에서는 다음 코드로 Animation을 제어할 수 있습니다.

self:play("walk")

현재 Frame을 그리려면:

self:spr()

자세한 내용은 Sprite 및 Animation 페이지를 참고하세요.

10. Asset 관리 가이드

Asset을 관리할 때는 다음 사항을 권장합니다.

1. 지원되는 Asset 등록 기능을 사용하여 PNG Tilesheet를 등록합니다.
2. 등록된 Group ID를 안정적으로 유지합니다.
3. 기존 Asset ID를 수동으로 다시 할당하지 않습니다.
4. 등록된 Asset 파일을 변경할 때 Registry도 업데이트합니다.
5. Asset을 삭제하기 전에 Map과 Sprite의 참조를 확인합니다.
6. 사용이 종료된 Group ID를 실수로 재사용하지 않도록 합니다.

Stable ID는 참조 관계를 보호하기 위한 기능이지만 Asset을 수정한 후에도 같은 그래픽이 유지된다는 것을 자동으로 보장하지는 않습니다.

예를 들어 등록된 PNG 내부에서 Tile의 위치를 바꾸면 기존 Asset ID가 다른 그림을 가리킬 수 있습니다.

11. 프로젝트 구조 예제

Tilesheet를 사용하는 프로젝트에는 다음과 같은 파일이 포함될 수 있습니다.

my-bit8-game/
├── main.b8
├── bit8.assets.toml
├── bit8.sprites.toml
└── assets/
    ├── terrain (A).png
    └── characters (B).png

이것은 예시 구조입니다. 실제 Asset 경로는 Asset Registry의 등록 정보와 일치해야 합니다.

다음 단계

다음 페이지:

Map

관련 문서:

• Sprite 및 Animation
• Collision
• Runtime API
• Map Workspace

Stable Asset ID를 통해 Script, Map, Sprite가 등록된 Tile을 일관되게 참조할 수 있습니다.