Lua Scripting in HELIX

You can add game logic to your HELIX World using Blueprints and Lua scripts. This tutorial walks you through how to get started with Lua scripting. A detailed Blueprint scripting guide will be added soon. HELIX is powered by a modular Lua package system. A Lua package is a self-contained set of Lua scripts and related assets that can be loaded and initialized dynamically based on configuration files. This structure allows for flexible, organized scripting and content loading.

📁 Package Directory Structure

All Lua packages are located under the Workspace/scripts/ directory. Each subfolder inside this directory represents a single Lua package. Every package must include a package.json file to define its structure, including which files to load.

Example

Workspace
└── scripts
    ├── MyPackage
    │   ├── client.lua
    │   ├── server.lua
    │   └── package.json
    ├── MyPackage2
    │   ├── client.lua
    │   └── package.json
    └── config.json

📜 Defining Which Packages to Load

The config.json file located in Workspace/scripts/ acts as the entry point for loading Lua packages. It contains a simple JSON structure with a packages key, which is a list of package folder names you want to load in order.

Example

{
  "packages": [
    "MyPackage",
    "MyPackage2"
  ]
}

When the server starts, it reads this list and loads each specified package, resolving their internal file structure through their respective package.json.

📦 Declaring Package Files

Each Lua package must include a package.json file. This manifest defines which files the system should load and in what order.

Example

{
  "shared": ["config.lua", "shared/main.lua"],
  "server": ["server/*.lua"],
  "client": ["client/main.lua"]
}

Supported Fields

• client: Lua scripts to run on the client side
• server: Lua scripts to run on the server side
• shared: Scripts loaded on both client and server (optional)

Wildcard Support

You can use wildcard patterns such as server/*.lua to include all .lua files in a directory. This makes it easier to manage large packages without listing every file individually.