Runtime API ko

Runtime API

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

이 페이지에서는 BIT8_CLI 0.1.0에서 제공하는 Runtime 스크립트 API를 소개합니다.

BIT8_CLI는 Lua 5.4를 사용하며 스크립트 확장자는 .b8입니다. 또한 function 대신 func를 사용할 수 있습니다.

Runtime 개요

항목	사양
Framebuffer	64 × 64 픽셀
시뮬레이션	고정 30 Hz
Tile 크기	8 × 8 픽셀
Map 크기	최대 256 × 256 Tiles
스크립트 언어	Lua 5.4
확장자	.b8

라이프사이클 함수

init()

게임 초기화 시 호출됩니다.

func init()
    x = 32
    y = 32
end

update()

게임 시뮬레이션 로직을 처리합니다.

func update()
    x = x + 1
end

시뮬레이션은 고정 30 Hz로 업데이트됩니다.

draw()

현재 게임 상태를 그립니다.

func draw()
    cls(0)
    pix(x, y, 7)
end

그리기 API

cls(color)

지정한 팔레트 색상으로 framebuffer를 지웁니다.

cls(0)

별칭 clear()도 사용할 수 있습니다.

pix(x, y, color)

지정한 화면 좌표에 픽셀을 그립니다.

pix(32, 32, 7)

별칭 pixel()도 사용할 수 있습니다.

rectfill(...)

채워진 사각형을 그립니다.

rectfill(10, 10, 20, 20, 7)

spr(...)

등록된 Asset에서 Tile을 그립니다.

BIT8_CLI는 안정적인 Asset ID를 지원합니다.

spr(A4, 16, 16)

호환성을 위해 기존 숫자 Sprite 참조도 계속 지원합니다.

map(...)

프로젝트에 등록된 Tile을 사용하여 Map을 그립니다.

func draw()
    cls(0)
    map()
end

Map 그리기는 활성 Camera의 영향을 받을 수 있습니다.

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

입력 API

btn(button)

버튼이 현재 계속 눌려 있는지 확인합니다.

if btn(LEFT) then
    x = x - 1
end

사용할 수 있는 버튼 상수:

UP
DOWN
LEFT
RIGHT
A
B

btnp(button)

버튼이 새롭게 눌렸는지 확인합니다.

if btnp(A) then
    print("A pressed")
end

btn()과 달리 한 번의 누름 이벤트를 처리하는 데 적합합니다.

Map API

mget(...)

Map에서 Tile 값을 읽습니다.

mset(...)

Runtime Map의 Tile 값을 변경합니다.

Map 좌표, Tile ID 및 편집 동작에 대해서는 Map 페이지를 참고하세요.

Node API

Node Script에서는 self를 사용하여 연결된 Runtime Node에 접근할 수 있습니다.

func update()
    self.x = self.x + 1
end

Node 속성

속성	설명
self.id	안정적인 Node ID
self.name	Node 이름
self.x	월드 X 좌표
self.y	월드 Y 좌표
self.enabled	Node 활성화 상태

self:collide(dx, dy)

지정한 거리만큼 Node를 이동했을 때 지원되는 충돌 지오메트리와 충돌하는지 확인합니다.

if self:collide(1, 0) then
    print("Blocked")
end

이 함수는 충돌 여부만 확인하며 Node를 이동시키지 않습니다.

충돌 판정에는 활성화된 Node Box Collider와 Solid Tile이 사용됩니다.

self:move(dx, dy)

충돌을 고려하면서 Node 이동을 시도합니다.

self:move(1, 0)

이동은 X축을 먼저 처리하고 그다음 Y축을 처리합니다.

BIT8_CLI 0.1.0은 기본적인 충돌 대응 이동을 제공하지만 완전한 물리 엔진은 아닙니다.

Sprite 및 Animation API

self:sprite(name)

등록된 Sprite Definition을 Node에 연결합니다.

self:sprite("Player")

self:play(animation)

현재 Sprite에 정의된 Animation을 재생합니다.

self:play("walk")

같은 Animation을 반복해서 요청해도 불필요하게 처음부터 다시 시작하지 않습니다.

self:spr()

Node의 현재 Sprite Animation Frame을 그립니다.

func draw()
    self:spr()
end

Sprite 정의는 다음 파일에 저장됩니다.

bit8.sprites.toml

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

Camera

BIT8_CLI는 Camera Node를 지원합니다.

활성 Camera는 지원되는 월드 좌표 기반 그리기 작업에 영향을 줍니다.

Camera 좌표는 64 × 64 Viewport의 중심을 나타냅니다.

cls(), pix(), rectfill() 같은 화면 좌표 기반 그리기 작업은 Camera 이동의 영향을 받지 않습니다.

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

예제: Node 이동과 애니메이션

다음 예제는 Sprite가 연결되어 있고 해당 Animation이 정의된 Node를 가정합니다.

func update()
    if btn(LEFT) then
        self:move(-1, 0)
        self:play("walk")
    elseif btn(RIGHT) then
        self:move(1, 0)
        self:play("walk")
    else
        self:play("idle")
    end
end

func draw()
    self:spr()
end

Animation 이름은 Sprite Definition에 존재해야 합니다.

관련 문서

• 언어 기초
• Asset 및 Tilesheet
• Map
• Node
• Sprite 및 Animation
• Collision
• Camera

이 페이지는 BIT8_CLI 0.1.0에서 확립된 API 기능을 정리한 문서입니다. 전체 함수 시그니처와 특수한 동작은 해당 릴리스의 소스 코드를 기준으로 확인해야 합니다.