sprite_add_ext 함수 설명 및 활용 예제
sprite_add_ext 함수는 외부 파일이나 URL에서 이미지를 비동기적으로 로드하고 새로운 스프라이트로 추가하는 기능을 제공합니다. 이 함수는 sprite_add의 비동기 버전으로, 코드 실행을 차단하지 않고 게임의 코드 실행을 계속 진행합니다. 스프라이트가 완전히 로드되면 asyncImage Loaded 이벤트가 발생합니다.
지원하는 이미지 파일 형식
- PNG
- JPEG
- GIF
- QOIF
- Spine JSON 파일 (Spine JSON 파일은 관련된 아틀라스 및 이미지 파일이 함께 있어야 함)
Spine JSON 파일은 로컬에 저장된 파일만 지원하며, HTTP를 통해 요청된 파일은 지원하지 않습니다.
async_load DS 맵 필드
asyncImage Loaded 이벤트에서 사용할 수 있는 필드는 다음과 같습니다:
| 필드명 | 설명 |
|---|---|
| filename | 함수에 처음 전달된 파일의 경로 |
| id | 함수가 반환한 스프라이트 ID |
| http_status | HTTP 요청의 상태 값 (요청이 없으면 200 "OK") |
| status | 로드가 성공했음을 나타내는 값 (0 이상) 또는 오류 코드 |
오류 코드 설명
| 상수 | 설명 | 값 |
|---|---|---|
| sprite_add_ext_error_unknown | 다른 오류 코드가 적용되지 않을 때의 일반 오류 코드 | -1 |
| sprite_add_ext_error_cancelled | 요청이 진행 중 취소되었음을 나타냄 | -2 |
| sprite_add_ext_error_spritenotfound | 스프라이트가 로드 과정 중 제거되었음을 나타냄 | -3 |
| sprite_add_ext_error_loadfailed | 파일 로드 작업이 실패했음을 나타냄 | -4 |
| sprite_add_ext_error_decompressfailed | 이미지 압축 해제가 실패했음을 나타냄 | -5 |
| sprite_add_ext_error_setupfailed | 데이터가 모두 로드되고 압축 해제되었지만 스프라이트 리소스 생성이 실패했음을 나타냄 | -6 |
함수 구문
sprite_add_ext(fname, imgnum, xorig, yorig, prefetch);
인자 설명
| 인자명 | 타입 | 설명 |
|---|---|---|
| fname | String | 스프라이트로 추가할 이미지 파일의 경로 (로컬 파일 경로 또는 웹 주소) |
| imgnum | Real | 파일의 서브 이미지 수 (단일 이미지, GIF 또는 Spine 스프라이트의 경우 1) |
| xorig | Real | 새로운 스프라이트의 원점 x 위치 |
| yorig | Real | 새로운 스프라이트의 원점 y 위치 |
| prefetch | Boolean | 스프라이트를 즉시 GPU 메모리에 로드할지 여부 |
반환값
- 스프라이트 자산
활용 예제
1. 스프라이트 추가 및 비동기 로드
// Create Event
sprite_index = -1;
new_sprite = sprite_add_ext("my_new_sprite_index.png", 1, 0, 0, true);
2. 비동기 이미지 로드 이벤트 처리
// Async Image Loaded Event
var _sprite_id = async_load[?"id"];
if (_sprite_id == new_sprite) {
sprite_index = _sprite_id;
}
3. 스프라이트 그리기
// Draw Event
if (sprite_index != -1) {
draw_self();
}
이 예제는 세 가지 객체 이벤트에서 코드를 정의합니다. Create 이벤트에서 인스턴스의 sprite_index를 -1로 설정하고 sprite_add_ext 함수를 호출하여 이미지를 로드합니다. asyncImage Loaded 이벤트에서 로드된 스프라이트 ID를 확인하고, 일치할 경우 sprite_index에 할당합니다. 마지막으로 Draw 이벤트에서 sprite_index가 -1이 아닐 경우 스프라이트를 그립니다.