Đọc hiểu chữ ký hàm trong tài liệu Craftland

Mỗi mục trong tài liệu API Craftland có một dòng khai báo — gọi là chữ ký. Đọc được chữ ký là bạn biết khối đó cần gì và trả lại gì, trước cả khi kéo nó vào Studio.

Tài liệu chính thức viết chữ ký theo cú pháp giống ngôn ngữ Go. Trong Craftland Studio bạn thường lắp các khối có cùng tên tiếng Việt; chữ ký chỉ là cách mô tả chính xác khối đó.

1. Hàm đơn giản: tên và tham số

func LogInfo(content object)

• func: đây là một hàm (một hành động).
• LogInfo: tên hàm. Trong Studio là khối In thông báo.
• content object: một tham số tên content, kiểu object — nghĩa là nhận gần như mọi loại giá trị.
• Không có gì sau dấu ngoặc đóng → hàm không trả về giá trị.

2. Hàm có giá trị trả về

func GetAllPlayers() List<entity<Player>>

Phần sau dấu ngoặc là kiểu trả về: một List (danh sách) mà mỗi phần tử là entity<Player> — một thực thể người chơi. Bạn có thể đưa kết quả này thẳng vào các khối của module Danh sách, ví dụ Length để đếm số người chơi.

3. async func: hàm cần thời gian

async func WaitForMillisecond(duration int)
async func WaitForNextFrame()

async báo hiệu hàm này không xong ngay: kịch bản sẽ dừng ở đó cho tới khi chờ đủ. duration int là số mili giây (1000 = 1 giây). Đây là cách tạo đếm ngược, nhịp spawn quái, v.v.

4. out var: kết quả trả qua biến

func CreateFromPrefab(out var createdEntity entity<Entity>, prefab PrefabID)
func JoinTeam(target entity<Entity>, targetTeam entity<Team>, out var statusCode StatusCode)

Một số hàm không "trả về" theo kiểu thường mà ghi kết quả vào biến bạn chỉ định — đánh dấu bằng out var. Với CreateFromPrefab, thực thể vừa tạo nằm trong biến createdEntity. Với JoinTeam, biến statusCode cho biết thao tác thành công hay gặp lỗi — nên kiểm tra nó thay vì giả định mọi thứ ổn.

5. Kiểu có tham số: entity<…> và List<…>

• entity — một thực thể bất kỳ trong cảnh.
• entity<Player>, entity<Team> — thực thể chỉ thuộc loại người chơi / đội. Đưa nhầm loại vào là khối không lắp được.
• List<object> — danh sách phần tử bất kỳ; List<string> — danh sách chuỗi.

6. Không phải hàm: từ khoá và giá trị đặc biệt

Vài mục trong Thư viện STD không phải hàm mà là cấu trúc ngôn ngữ: break (thoát vòng lặp), continue (bỏ qua lượt hiện tại), ! (phủ định — khối KHÔNG), if(value==nil) (khối Kiểm tra trống), thisEntity (thực thể đang chạy kịch bản), globalEntity (thực thể toàn cục của thế giới).

Thử đọc một chữ ký khó

func FilterEntity(must TypeOrTypeList, not TypeOrTypeList, any TypeOrTypeList) List<entity<Entity>>

Đọc từng phần: nhận ba bộ lọc kiểu — phải có, không được có, có ít nhất một — và trả về danh sách thực thể khớp. Tra từng kiểu lạ (như TypeOrTypeList) ở mục Kiểu trong trang tra cứu.