DESIGN AND IMPLEMENTATION OF A TCBSCRIPT COMPILER FOR THE THECELLBEYOND GAME ENGINE - PART A: COMPILER CORE

Abstract

Context: TheCellBeyond is an open-source 2D game engine written entirely in Java. Architecturally it is complete - a GameObject–Component object model, a 2D physics loop, a resource system, and a graphical editor - but adding gameplay logic to it still requires the user to write Java, to invoke Gradle by hand from a terminal to produce a jar, and to wait for ScriptLoader to pick that jar up. Those three manual steps raise the entry barrier for anyone without a Java background and lengthen the write–run loop that game development depends on. Embedding an existing scripting language such as Python or Lua is not the answer either, because the very thing that makes those languages valuable - their own runtimes and library ecosystems - cannot cross to the JVM, and bridging to them costs a marshalling layer on every single API call. Purpose: This thesis designs and implements TCBScript, a Python- and GDScriptflavored scripting language that is transpiled to Java source and fed into the engine's existing build-and-load pipeline. The report covers Part A, the compiler core: refactoring the engine's lifecycle API so that generated code never needs a super call; generating an API manifest at build time; an indentation-aware lexer base class and an ANTLR4 grammar; a dedicated abstract syntax tree; a two-pass semantic analyzer that resolves and translates every identifier against that manifest; a code generator written from scratch; and five language expansions, EX0 through EX4. Method: Collect, analyze and study the literature on compiler construction and on scripting in game engines; survey the four models of scripting integration and the available Java code-generation libraries in order to reduce the technology stack to what is genuinely needed; design the language and the compiler architecture; then implement and verify the result through sequential milestones (M1–M5, EX0–EX4), each shipping with a JUnit 5 suite that is required to stay green when a later milestone extends the same code. Findings: The compiler takes a .tcbs file and produces valid .java that compiles and loads directly into the running engine. Pushing all identifier lookup into a static manifest and all name collisions into a fail-fast semantic pass makes sophisticated codegeneration libraries redundant: a hand-written primitive of about fifty lines is sufficient, which leaves ANTLR4 as the compiler's only third-party dependency. The compiler core is validated by a suite of 178 unit tests (216 across the whole project), whose codegeneration cases compile the emitted Java with an in-memory javac rather than merely 5 matching strings; the generated code contains no super call anywhere and is byteidentical across repeated runs. Conclusion: The transpile-to-Java approach has been implemented successfully for TheCellBeyond. Because the generated code is plain Java compiled to bytecode like any other engine class, the runtime cost is essentially zero, and the entire JVM toolchain is reused for free. The editor integration and the demonstration game are the work of Le Huynh Nhat Nam, presented in the companion Part B thesis and summarized in Section 3.6 here. Keywords: compiler, transpiler, ANTLR4, generative grammar, abstract syntax tree, semantic analysis, code generation, game engine scripting, domain-specific language, 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, đã hoàn thiện về kiến trúc vớ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, để tạo logic gameplay người dùng vẫn phải viết script bằng Java, tự mở terminal gọi Gradle để biên dịch thành tệp jar, rồi chờ ScriptLoader nạp vào engine. Ba bước thủ công này đặt ngưỡng tiếp cận rất cao đối với người không có nền tảng Java, đồng thời kéo dài vòng lặp "viết script - chạy thử" vốn cần càng ngắn càng tốt trong phát triển game. Nhúng một ngôn ngữ scripting sẵn có như Python hay Lua cũng không phải lời giải tối ưu cho một engine viết bằng Java: chính điều làm nên sức mạnh của các ngôn ngữ đó - runtime và hệ sinh thái thư viện riêng - lại không mang sang được JVM, còn bắc cầu sang chúng thì phải trả giá bằng một lớp marshalling ở mọi lời gọi API. Mục tiêu: Đề tài thiết kế và cài đặt TCBScript, một ngôn ngữ scripting mang phong cách Python/GDScript được biên dịch sang mã nguồn Java, rồi đưa vào đường ống build và nạp script sẵn có của engine. Báo cáo này trình bày Phần A - lõi trình biên dịch: tái cấu trúc API vòng đời để mã sinh ra không bao giờ cần gọi super; manifest API sinh tại thời điểm build; lớp cơ sở xử lý thụt lề và văn phạm ANTLR4; cây cú pháp trừu tượng riêng; tầng phân tích ngữ nghĩa hai pha phân giải và dịch mọi định danh dựa trên manifest; tầng sinh mã tự viết; cùng năm cột mốc mở rộng ngôn ngữ EX0–EX4. Phương pháp: Thu thập, phân tích và nghiên cứu tài liệu về lý thuyết trình biên dịch và về scripting trong game engine; khảo sát bốn mô hình tích hợp scripting cùng các thư viện sinh mã Java hiện có để chắt lọc công nghệ; thiết kế ngôn ngữ và kiến trúc trình biên dịch; sau đó hiện thực và kiểm chứng theo các cột mốc tuần tự (M1–M5, EX0– EX4), mỗi cột mốc đi kèm một bộ kiểm thử JUnit 5 bắt buộc phải giữ xanh khi cột mốc sau lấn vào cùng vùng mã. Kết quả: Trình biên dịch nhận tệp .tcbs và sinh ra tệp .java hợp lệ, biên dịch được và nạp thẳng vào engine đang chạy. Kiến trúc "đẩy mọi tra cứu định danh về một manifest tĩnh và mọi xung đột tên về một tầng phân giải dừng-sớm" khiến các thư viện sinh mã phức tạp trở nên dư thừa: một primitive tự viết khoảng năm mươi dòng là đủ, nhờ đó ANTLR4 là phụ thuộc thứ ba duy nhất của trình biên dịch. Lõi trình biên dịch được xác thực bằng bộ 178 ca kiểm thử đơn vị (toàn dự án 216 ca), trong đó các ca sinh mã biên dịch mã Java sinh ra bằng javac chạy trong bộ nhớ thay vì chỉ so khớp chuỗi; mã sinh ra không chứa bất kỳ lời gọi super nào và có tính tất định qua các lần chạy. 3 Kết luận: Mô hình transpile-to-Java đã được hiện thực thành công cho TheCellBeyond: chi phí thời gian chạy gần như bằng không vì mã sinh ra là Java thuần, đồng thời toàn bộ hệ sinh thái JVM được tái sử dụng. Phần tích hợp editor và game minh hoạ được trình bày trong luận văn Phần B của sinh viên Le Huynh Nhat Nam và được tóm tắt trong Mục 3.6 của báo cáo này. Từ khoá: trình biên dịch, transpiler, ANTLR4, văn phạm sinh, cây cú pháp trừu tượng, phân tích ngữ nghĩa, sinh mã, scripting cho game engine, ngôn ngữ chuyên biệt miền, TCBScript, TheCellBeyond.