클라이언트 스크립트

Chain2D

클라이언트 스크립트가 보는 뿌리. 로비(`client/boot/main.luau`)와 게임 화면(`client/main.luau`)이 같은 VM 에서 이 표를 봅니다. 단계가 맞지 않는 호출은 사라지는 대신 이유와 함께 거부됩니다 — 단계마다 다른 전역을 주면 창작자는 `attempt to index nil` 을 보게 되고, 그것은 무엇이 잘못됐는지 말해주지 않습니다. 단계 검사는 프리루드가 아니라 네이티브에 있습니다. 스크립트가 닿을 수 있는 파일에 둔 검사는 그 파일을 고칠 수 있는 누구든 지울 수 있고, 그러면 검사가 아니기 때문입니다. `Chain2D` 도 그 아래 표도 모두 얼려져 있어서 스크립트가 갈아끼울 수 없습니다.

joinonJoinFailedstageonTickAuthUpdateRealmsNetworkConnectionUI

Chain2D.join

선언
Chain2D.join(realmId: string, channelOrdinal: number?) -> (boolean, string?)
매개변수
realmIdstring들어갈 렐름의 id. `Chain2D.Realms.list()` 가 준 `id` 를 그대로 넘깁니다. 빈 문자열이면 기본 렐름으로 갑니다.
channelOrdinalnumber?들어갈 채널 번호. 생략하면 0 이 넘어가고, 0 은 고르지 않았다는 뜻입니다 — 어느 채널에 넣을지는 호스트가 정합니다.
반환

(boolean, string?)시도가 받아들여졌으면 `true`. 받아들여지지 않았으면 `false` 와 이유가 함께 옵니다. `true` 는 시작됐다는 뜻이고 들어갔다는 뜻은 아닙니다 — 그 뒤의 실패는 `Chain2D.onJoinFailed` 로 옵니다.

렐름을 골라 들어갑니다. 단계가 아직 아니어서 거부될 때도, 호스트가 거절할 때도 오류가 아니라 값으로 돌아옵니다 — 로비는 이것을 늘 부르고 어떤 답에도 보여줄 화면이 있습니다. 오류로 만들면 "아직 받는 중입니다" 가 게임의 버그처럼 보입니다. 값으로 돌아오지 않는 거절은 하나뿐입니다: 접속을 붙이지 않은 빌드에서 부르면 `this build cannot join` 이라는 오류가 납니다. 그것은 창작자가 쓴 것이 잘못된 것이 아니라 빌드가 덜 된 것이어서, 화면으로 안내할 답이 없습니다.

언제업데이트가 끝난 뒤(`Chain2D.stage()` 가 `"updated"` 이상)에만. 그 전에 부르면 `false` 와 `"the update is not finished"` 가 돌아옵니다.

local realms = Chain2D.Realms.list()
local ok, why = Chain2D.join(realms[1].id)
if not ok then
    print("들어가지 못했습니다: " .. why)
end

Chain2D.onJoinFailed

선언
Chain2D.onJoinFailed(handler: (reason: string) -> ())
매개변수
handler(reason: string) -> ()들어가려던 시도가 실패할 때마다 불립니다. 인자는 이유 한 줄입니다. 함수가 아닌 것을 넘기면 거부됩니다.

들어가려다 실패한 것을 듣습니다. 이것은 단계도 끊김도 아닙니다 — 닿은 것이 없으니 잃은 것도 없고 세션과 파일은 그대로여서, 다시 `Chain2D.join` 을 부르면 됩니다. 다만 실패했다는 사실을 들어야 다시 부를 수 있습니다. 알려주지 않으면 로비는 매 틱 물어보며 영영 기다리고, 이유를 아는 한 줄은 아무도 읽지 않는 로그로 갑니다. 여러 번 걸 수 있고 건 순서대로 불립니다. 핸들러가 오류를 내면 스크립트가 꺼지고 그 뒤의 핸들러는 불리지 않습니다.

local message = Chain2D.UI.Text({ text = "" })
Chain2D.onJoinFailed(function(reason)
    message:set({ text = "들어가지 못했습니다: " .. reason })
end)

Chain2D.stage

선언
Chain2D.stage() -> string
반환

string`"boot"`, `"authenticated"`, `"updated"`, `"joined"` 중 하나.

지금 어디까지 왔는지 묻습니다. 단계마다 그 전에는 될 수 없던 호출이 열립니다 — 로그인하기 전에는 이름 붙일 플레이어가 없고, 받기 전에는 가지고 놀 파일이 없고, 들어가기 전에는 보낼 연결이 없습니다. 단계는 오르기만 하고 내려가지 않습니다. 되감기로 다루면 방금까지 되던 호출이 실패하기 시작하고 창작자가 쓴 어떤 것도 그것을 설명하지 못하므로, 끊김은 단계가 아니라 별개의 축(`Chain2D.Connection`)에 있습니다.

local at = Chain2D.stage()
if at == "boot" then
    Chain2D.Auth.signIn(Chain2D.Auth.providers()[1])
elseif at == "authenticated" then
    Chain2D.Update.start()
end

Chain2D.onTick

선언
Chain2D.onTick(callback: (delta: number) -> ())
매개변수
callback(delta: number) -> ()프레임마다 불립니다. 인자는 지난 프레임부터 흐른 초입니다. 함수가 아닌 것을 넘기거나 인자를 하나보다 많이 넘기면 거부됩니다.

프레임마다 부를 것을 겁니다. 여러 번 걸 수 있고 건 순서대로 불립니다 — 로비와 게임 화면은 한 VM 에 든 두 스크립트이고 둘 다 같은 사건에 관심이 있습니다. 자리를 하나만 두었을 때는 나중에 건 것이 앞의 것을 조용히 지웠고, 사라지는 쪽은 먼저 로드된 화면 — 이를테면 로비의 재접속 패널 — 이었습니다. 핸들러가 오류를 내면 스크립트가 꺼지고, 그 프레임의 남은 핸들러는 불리지 않으며, 오류는 한 번만 보고됩니다: 그리기를 멈춘 로비는 사람이 끌 수 있지만, 초당 예순 번 죽는 클라이언트는 그럴 수 없습니다. 서버에도 같은 이름이 있지만 다른 VM 의 다른 호출입니다. 여기 적힌 것은 클라이언트 프리루드의 것뿐입니다.

local label = Chain2D.UI.Text({ text = "0.0" })
local elapsed = 0
Chain2D.onTick(function(delta)
    elapsed += delta
    label:set({ text = string.format("%.1f", elapsed) })
end)

Chain2D.Auth

선언
Chain2D.Auth: table

로그인. `providers`, `signIn`, `onFailed` 가 여기 있고, 각각은 `Chain2D.Auth` 페이지에 적혀 있습니다. 로그인이 실패한 것은 접속이 실패한 것과 따로 옵니다 — 접속 실패는 다시 눌러 볼 만하지만, 로그인 실패는 무언가 바뀌기 전에는 다시 눌러도 같은 자리에서 같은 이유로 멈춥니다.

Chain2D.Update

선언
Chain2D.Update: table

릴리스 파일 내려받기. `start`, `onProgress`, `state` 가 여기 있고, 각각은 `Chain2D.Update` 페이지에 적혀 있습니다. 넘기는 것은 언제 받을지뿐입니다 — 건너뛰는 방법도, 다 받았다고 말하는 방법도 없습니다.

Chain2D.Realms

선언
Chain2D.Realms: table

들어갈 수 있는 렐름의 목록. `list` 하나뿐이고 `Chain2D.Realms` 페이지에 적혀 있습니다. 거기서 얻은 `id` 가 `Chain2D.join` 에 그대로 넘기는 것입니다.

Chain2D.Network

선언
Chain2D.Network: table

서버와의 대화. `on` 과 `send` 가 여기 있고 `Chain2D.Network` 페이지에 적혀 있습니다. 양쪽 다 표를 주고받습니다 — 문자열을 건네고 파싱을 창작자에게 떠넘기면 게임마다 같은 파서를 다시 쓰고, 그중 하나는 반드시 서버와 다르게 읽습니다.

Chain2D.Connection

선언
Chain2D.Connection: table

연결이 붙어 있는지, 끊겼는지, 다시 이을지. `connected`, `onLost`, `retry` 가 여기 있고 `Chain2D.Connection` 페이지에 적혀 있습니다. 단계와 별개의 축인 이유는 `Chain2D.stage` 에 적어 두었습니다.

Chain2D.UI

선언
Chain2D.UI: table

화면. `Frame`, `Text`, `Image`, `Button` 과 릴리스가 들고 있는 화면을 여는 `load` 가 여기 있고, 각각은 `Chain2D.UI` 페이지에 적혀 있습니다. 만들면 손잡이가 돌아오고, 손잡이는 `set` 과 `destroy` 를 콜론으로 받습니다.