Callisto is a lightweight and powerful 📦 that integrates LuaJIT scripting into Delphi, enabling you to easily add a scripting layer to your Delphi apps. Whether you're building dynamic software 🖥️, adding mod support 🛠️, or simply looking for a way to make your apps more flexible and customizable, Callisto makes this possible through simple, straightforward APIs.

📑 Table of Contents

• 📘 Introduction
• ✨ Key Features
• 🔧 Potential Uses
• 🚀 Getting Started
• 📥 Installation
• 📄 Usage Examples
• ⚙️ Advanced Features
• 📚 API Overview
• 🤝 Contributing
• 📜 License

Introduction

Callisto offers a bridge 🌉 between Delphi and LuaJIT, providing a powerful scripting solution to extend the capabilities of your Delphi projects. With Callisto, Delphi developers can enjoy all the benefits of embedding a dynamic, fast ⚡, and easy-to-use scripting language like Lua, while leveraging LuaJIT for high performance 🏎️.

This library is designed to make integrating Lua into Delphi applications as seamless as possible, focusing on usability, efficiency, and a minimal learning curve 📈. All dependencies are compiled directly into the executable, eliminating the need for external DLLs and making deployment simpler and more reliable ✅.

Key Features

• Blazing Fast Performance ⚡: Built on LuaJIT, Callisto provides exceptional speed, making it suitable for performance-critical applications.
• Simple APIs 📜: Easy-to-use API for registering Delphi routines and executing Lua scripts.
• Seamless Interoperability 🔄: Effortlessly pass data between Delphi and Lua environments.
• Interactive Debugging 🐞: Use dbg() in your Lua scripts to start interactive debugging.
• Custom Routine Registration ➕: Easily add custom routines in Delphi that Lua scripts can call.
• Minimal Setup 🛠️: Requires only a few lines of code to get started.
• Script Importing and Bundling 📦: Use a custom import command to combine scripts, compile them into a single file, and optionally store them as an EXE resource for a fully self-contained application.
• No External Dependencies 🚫📦: All dependencies are compiled directly into the EXE, so there are no external DLLs to maintain.
• FFI Support 🔗: In addition to the custom routine registration provided by the TCallisto class, you can leverage LuaJIT's powerful Foreign Function Interface (FFI). This allows scripts to call exported routines directly from the current EXE or any loaded DLL, enabling seamless integration with existing Delphi libraries and external modules.

Potential Uses

• Add Modding Support 🛠️: Enhance your applications by allowing users to create mods.
• Dynamic Workflows 🔄: Create flexible workflows with scriptable business logic.
• Runtime Flexibility ⏱️: Offload logic to Lua scripts to modify behavior at runtime.
• Game Development 🎮: Build games or simulation engines with a powerful scripting layer.

Getting Started

This section will help you get Callisto up and running in your Delphi environment.

Prerequisites

• Delphi 12 CE or higher 🖥️
• Windows 10 or higher 🪟
• Tested on Windows 11 64-bit (24H2), Delphi 12.2 ✅

Installation

1. Clone or download the Callisto repository 📂.

2. Add the Callisto source files to your Delphi project.

3. 📥 Download the latest version of Callisto.

4. 📂 Extract the contents to your project directory.

5. ➕ Add the Callisto src folder to your Library Path in Delphi.

6. 📝 In your project, include Callisto in the uses clause.

7. 📁 Refer to the examples folder for detailed usage instructions and demonstrations of the PSFML library in action.

That's it! You should now be able to start scripting with Lua in your Delphi projects 🚀.

Usage Examples

Here are some simple examples to demonstrate how to integrate Callisto into your Delphi project:

Loading and Running Lua Scripts 🐍

var
  LCallisto: TCallisto;
begin
  LCallisto := TCallisto.Create();
  LCallisto.LoadString('print("Hello from Lua!")');
  LCallisto.Free();
end;

Registering a Delphi Routine to be Used in Lua 🔗

class procedure TMyClass.DelphiRoutine(const ALua: ICallistoContext);
begin
  // Example routine that pushes a string result onto Lua stack
  ACallisto.PushValue('Hello from Delphi!');
end;

var
  LCallisto: TCallisto;
begin
  LCallisto := Callisto.Create();
  LCallisto.RegisterRoutine('DelphiRoutine', TMyClass.MyDelphiRoutine);
  LCallisto.LoadString('DelphiRoutine()');
  LCallisto.Free();
end;

Calling Lua Functions from Delphi 🔁

var
  LCallisto: TCallisto;
  LResult: TCallistoValue;
begin
  LCallisto := TCallisto.Create();
  LCallisto.LoadString('function greet() return "Hello from Lua!" end');
  LResult := LCallisto.Call('greet', []);
  ShowMessage(LResult.AsString);  
  LCallisto.Free();
end;

Advanced Features

Callisto also supports advanced features like:

• Interactive Debugging 🐞: Add dbg() in Lua code to begin debugging, useful for identifying issues during runtime.
• Script Importing 📂: Use import to bundle various script files into a single compilation unit, which is useful for saving and loading compiled scripts as resources.
• Bytecode Compilation 📄: Compile Lua scripts to bytecode using CompileToStream(), allowing efficient packaging and distribution.

API Overview

The Callisto API has been designed to be both powerful and easy to use. Below is a quick reference to key classes and methods:

TCallisto 🐍

• Create/Destroy ✨: Manage the lifecycle of the Lua instance.
• LoadStream/LoadString/LoadFile 📥: Load Lua scripts from various sources.
• Run ▶️: Execute the loaded script.
• Call 📞: Call a Lua function from Delphi.
• RegisterRoutine ➕: Register Delphi routines to be callable from Lua.

ICallistoContext 🌐

• PushValue/GetValue 🔄: Push values to or get values from the Lua stack.
• ClearStack/PopStack 🗑️: Manage stack states effectively.
• SetTableFieldValue/GetTableFieldValue 🧩: Access and manipulate Lua tables.

Media

Podcast Deep Dive

Explore the in-depth discussion about Callisto, its features, and its use cases.

Callisto-Lua-Scripting-for-Delph.mp4

Contributing

Contributions to Callisto are highly encouraged. Please feel free to submit issues, suggest new features, or create pull requests to expand the capabilities and robustness of the scripting engine.

License

Callisto is distributed under the 🆓 BSD-3-Clause License, allowing for redistribution and use in both source and binary forms, with or without modification, under specific conditions. See the LICENSE file for more details.

Support

• Issues
• Discussions
• LuaJIT
• Learn Delphi

---

We hope Callisto helps make your Delphi projects more dynamic and flexible. Happy coding! 💻🎉

Made with ❤️ in Delphi