Skip to content

Getting Started

Jump to bottom
Matheus Pratta edited this page Oct 20, 2022 · 8 revisions

Hello and welcome to the Lua CLI for Dual Universe!

This small guide is intended to help you getting started with the CLI and create a simple "hello world" project.

Pre-Requisites

As the CLI is built using Node.js and JavaScript, you will need to install it on your system. You can download it on the official Node.js website, the LTS version is good enough.

You might also want to check if your system has Git installed, this is required for things such as importing projects from GitHub. It can be obtained for all major systems (including Windows) on Git's official website.

Installation

To install the compiler, run the command npm i -g @wolfe-labs/du-luac, it will install the CLI into your global NPM environment and the command du-lua will become available everywhere on your operating system.

Experimenting Development Versions

To try out a development version that is not on NPM, you can install directly from Git, just follow the guide on Installing or Building from Git and you should be good to go!

Be wary that you will end up encountering incomplete stuff and bugs when doing this, so this is not very recommended for working with production projects.

Creating Your First Project

To create a new project, you can run du-lua create hello-world, this will do two steps:

  1. Create a new directory "hello-world"
  2. Initialize a new project using du-lua init inside that directory

You can follow the on-screen prompt to set-up your project's name, description, source and output directories, and also pre-configure it with default entry-points and build targets.

After completed, your directory will have a project.json file and a pre-configured .gitignore. If you opted for the default entry-point and build target, you should also have a source directory with the main.lua file connected to the main entry-point.

You can start writing your code into the main.lua file, by default it comes with some code to dump all connected elements.

Building Your Project

To build your project, along with all of its entry-points and build targets, run the command du-lua build.

Optionally, you can copy the resulting JSON automatic configuration into your system's clipboard by adding the --copy=target/build, where target is the build target name and build is the entry-point name. You can also completely omit the build target and only include the build name, in that case, you can do it with just --copy=build.

Adding a new Entry-Point

In the CLI, each entry-point is an individual script that you are going to use for a different Control Unit or Render Script. For example, if you create a project for a new ship, you can have a main flight script that will be used on the flight seat, with another separate script for managing the cargo and a Render Script to display the cargo contents into a screen. Each of those would be a different entry-point in the project's perspective.

To add a new Control Unit script, run du-lua script-add your-script-name where your-script-name is an unique identifier for that entry-point. You can also add a Render Script entry-point by using du-lua script-add-screen your-script-name instead. This will add a new entry into the builds section of your project file, along with the corresponding Lua file inside your source directory. On compilation time, you should also see new output files being generated, corresponding to the new entry-point added.

A quick note about Render Scripts

Render Scripts don't share the same functions and APIs as Control Units, which means that even though your syntax highlighter/auto-complete will show those APIs while editing the Lua files, they won't be available in-game. This happens because the Codex file seems to be used everywhere on the project, with no distinctions between entry-point types.

Also, keep in mind that link detection and event handlers are not included by default on Render Scripts, as those are special cases where we have very strict size limits on how much code can be used per screen.

Adding a new Build Target

You might want to have different versions of your builds for different ends. For example, a development version with non-minified code is very useful for testing and debugging, while a minified version of your code might be useful for production use. For those cases, you might want different build targets in your project. Those are defined under the targets field of the project file, and can be created by running du-lua target-add and following the prompt.

After a new build target is created and the build command is executed, you will have a new directory under the output directory, with the resulting files for that specific build target. You can enable things such as minification for individual targets, too.

Defining Linked Elements

You can pre-define which elements will be linked to each of your entry-points by running du-lua script-link your-script-name where your-script-name is the unique name of that entry-point/script. After you declare a linked element on your project, you will be able to add event handlers to it.

Important Note: Those elements must be declared in the exact same order as they will be used linked in-game, as we need to specify them in that order when generating the JSON/YAML output files for each Control Unit, otherwise event handlers will not work. This is not the case with auto-config (CONF) files, as they allow for automatic linking of elements in the right order.

Handling/Listening to Linked Element Events

After you declared a linked element on your project, you will be able to add event handlers to it by using the CLI's built-in events helper. Let's say you're listening to the onInputText event from the system slot and printing it back to the user:

system:onEvent('onInputText', function (self, text)
  -- Writes what was received
  system.print('You said: ' .. text)
end)

On the example above, we're passing an anonymous function as the event handler. That function takes two arguments:

  • self is a reference back to the original system object. This argument is always present for all events and allows you to have a single function handling all events for all elements while still "knowing" which element emitted that specific event.
  • text is the text that was input by the user, which in-game corresponds to the first argument from onInputText.

Importing and Using External Libraries

To make it easier working with very large projects, the CLI has support for importing external Lua from a few different sources:

  1. Another CLI project, be it local or remote
  2. Another Lua project, without any kind of project, also local and remote
  3. A local file from your LUA_PATH environment variable

For CLI and Lua projects, you can use the command du-lua import followed by a path either to the local directory where those files are located, or a remote Git repository. When using Git, you are required to have it installed on your system, as everything is done via the native Git client. You must also check whether you're using HTTPS or SSH Git paths, as private repositories usually require the latter.

After importing those projects, you should be able to access files within them with the syntax local my_api = require('PackageName:path/to/file'), where PackageName is the library name on your project file, and path/to/file is the desired file from that package.

When using Git you have the benefit of being able to work from muitple computers as not only the code is saved somewhere shared with multiple people, but the Git repository data is also stored into the project file and is automatically downloaded whenever needed.

For LUA_PATH files, as far as they exist and no other file exists with that name, you should be able to use them. So for example, if you have /home/wolfe/lua/?.lua in your path, and a file called something.lua inside that directory, just calling local thing = require('something') will be enough to find it, as far you don't have another file called something.lua on your source directory.

Embedding Files (CSV, HTML templates, etc)

With the library.embedFile(file) function you are able to embed files at compilation time.

A great use case for HTML templates or any other kind of "large" content. You can simply put everything into a file (let's call it "hud.html"), edit it with your favorite editor's full capability of syntax highlighting and, when done, simply embed it into your code automatically with local hud = library.embedFile('hud.html'). All the contents of your file will be output into as a string into the hud variable, as if it was always there!

Please note that:

  • Values passed to that kind of function MUST be literals, so you can't pass any kind of value which requires processing (like 'test' .. 123, it must be pre-set as 'test123' instead).
  • File paths are relative to the Lua file being currently processed
  • File access is restricted only to the current project, due to security concerns
Clone this wiki locally