DESIGN AND IMPLEMENTATION OF A TCBSCRIPT COMPILER FOR THE THECELLBEYOND GAME ENGINE - PART B: EDITOR INTEGRATION AND GAME DEMONSTRATIO

Abstract

Context: TheCellBeyond is an open-source 2D game engine written entirely in Java, already complete in its essentials - a GameObject–Component object model, a 2D physics loop, a resource system, and a graphical editor. Getting a gameplay script into a game, however, still requires the user to write Java and then leave the editor, open a terminal, and invoke Gradle by hand. The barrier is not only the language: the user must know what Gradle is, how the gradlew wrapper works, and how to interpret an error about a missing JDK - none of which has anything to do with making games - and every edit–run cycle costs a context switch between the editor and a terminal. More seriously still, the editor as distributed to end users bundles only a stripped runtime with no javac, so on a clean machine Gradle has nothing to compile with at all. Purpose: The project introduces TCBScript, a scripting language compiled to Java source and fed into the engine's existing build pipeline. This report covers Part B, the editor integration and the demonstration: turning that compiler into a one-click tool inside the editor and validating the whole system with a real game. Four milestones are delivered: M6, an asynchronous Gradle runner; M6-B, an IDE-style JDK manager; M7, the transpile–build–reload chain behind a single action; and M8, an updated project template. Method: Collect, analyze and study the literature on supervising an external process from a real-time graphical application, on jlink runtime images, and on Java toolchain provisioning; analyze the problem in order to propose a solution; then implement and verify milestone by milestone, combining JUnit 5 unit tests run on a three-platform Windows, Linux and macOS CI matrix with manual end-to-end acceptance testing performed inside the editor itself. 5 Findings: The pipeline is closed behind a single button, and the editor never freezes for the duration of a build, because the expensive work is moved off the render thread and the interface reads only an immutable status snapshot once per frame. The chain stops at the earliest stage that cannot succeed, so a TCBScript error is reported as a TCBScript error with a file and a line rather than surfacing later as a javac message about a generated file the user has never seen. The editor infrastructure is covered by 21 unit tests (216 across the whole project). A complete Flappy Bird written entirely in TCBScript - three scripts, about 77 statements - serves both as evidence of usability and as the end-to-end acceptance test, and in the course of being written it exposed two genuine compiler defects that the unit tests had not. Conclusion: The one weakness of the transpile-to-Java model, that it requires a compilation step where an interpreter would not, has been reduced to a matter of tooling rather than of experience: the user writes .tcbs, presses one button, and has classes running inside the game without opening a terminal, without knowing Java, and without even having to install a JDK. The compiler core that underpins this work is presented in the companion Part A thesis by Le Nguyen Bao and summarized in Section 3.3 here. Keywords: game engine, scripting language, transpiler, editor integration, build pipeline, JDK provisioning, foojay Disco API, Gradle, acceptance testing, TCBScript, TheCellBeyond. Bối cảnh: TheCellBeyond là một game engine 2D mã nguồn mở viết hoàn toàn bằng Java, đã có đầy đủ các thành phần cốt lõi: hệ thống GameObject – Component, vòng lặp vật lý 2D, hệ thống tài nguyên và một editor đồ hoạ. Tuy vậy, để đưa một kịch bản gameplay vào game, người dùng vẫn phải viết Java rồi rời khỏi editor, mở terminal và tự gọi Gradle. Rào cản ở đây không chỉ là ngôn ngữ: người dùng buộc phải biết Gradle là gì, dùng wrapper gradlew ra sao và xử lý lỗi thiếu JDK thế nào - những kiến thức không liên quan gì đến việc làm game - đồng thời mỗi vòng lặp sửa–chạy đều phải chuyển ngữ cảnh giữa editor và terminal. Nghiêm trọng hơn, bản editor phân phối tới người dùng cuối chỉ đóng gói một runtime rút gọn không có javac, nên trên máy sạch Gradle không có gì để biên dịch. Mục tiêu: Đề tài giới thiệu TCBScript, một ngôn ngữ scripting được biên dịch sang mã nguồn Java rồi đưa vào đường ống build sẵn có. Báo cáo này trình bày Phần B - tích hợp editor và game minh hoạ: biến trình biên dịch thành công cụ "một nút bấm" bên trong editor và xác thực toàn hệ thống bằng một trò chơi thực. Bốn cột mốc được thực hiện: M6 - trình gọi Gradle không đồng bộ; M6-B - trình quản lý JDK kiểu IDE; M7 - nối chuỗi transpile → build → reload sau một nút bấm; M8 - cập nhật template dự án. Phương pháp: Thu thập, phân tích và nghiên cứu tài liệu về giám sát tiến trình ngoài từ một ứng dụng đồ hoạ thời gian thực, về cơ chế runtime image jlink và về cung cấp bộ công cụ JDK; phân tích để đề xuất giải pháp; sau đó hiện thực và kiểm chứng theo từng cột mốc, kết hợp kiểm thử đơn vị JUnit 5 chạy trên ma trận CI ba nền tảng Windows/Linux/macOS với kiểm thử chấp nhận end-to-end thực hiện thủ công ngay trong editor. 3 Kết quả: Toàn bộ đường ống được khép kín sau một nút bấm, và editor không hề bị treo trong suốt thời gian build nhờ tách hẳn công việc nặng khỏi luồng vẽ và chỉ đọc ảnh chụp trạng thái bất biến mỗi khung hình. Chuỗi xử lý dừng ở giai đoạn sớm nhất không thể thành công, nên lỗi TCBScript được báo đúng là lỗi TCBScript kèm tên tệp và số dòng, thay vì hiện ra dưới dạng thông báo javac trên tệp sinh ra. Hạ tầng editor được phủ bởi 21 ca kiểm thử đơn vị (toàn dự án 216 ca). Một game Flappy Bird viết hoàn toàn bằng TCBScript (ba script, khoảng 77 câu lệnh) vừa minh chứng tính khả dụng vừa đóng vai trò kiểm thử chấp nhận - và trong quá trình viết đã phát hiện hai lỗi thật của trình biên dịch mà kiểm thử đơn vị không tìm ra. Kết luận: Điểm yếu duy nhất của mô hình transpile-to-Java - bắt buộc phải có bước biên dịch - đã được hạ xuống thành vấn đề công cụ chứ không còn là vấn đề trải nghiệm: người dùng viết .tcbs, bấm một nút, và có class chạy trong game mà không cần mở terminal, không cần biết Java, thậm chí không cần tự cài JDK. Lõi trình biên dịch được trình bày trong luận văn Phần A của sinh viên Le Nguyen Bao và được tóm tắt trong Mục 3.3 của báo cáo này. Từ khoá: game engine, ngôn ngữ scripting, transpiler, tích hợp editor, đường ống build, quản lý JDK, foojay Disco API, Gradle, kiểm thử chấp nhận, TCBScript, TheCellBeyond.