Defold Penlight

A minimal Defold project template that makes Penlight work out of the box.

Introduction

This project was created from the "empty" project template with the addition of the Penlight Lua libraries.

Penlight libraries are located in the lib/pl directory and distributed under the MIT license.

The settings in "game.project" are all the default, except for the custom_resources setting, which includes the /lib/pl directory.

A bootstrap "main.collection" is included.

Issue

Unfortunately, some Penlight libraries do not work with Defold out of the box.

For example, pl.List requires pl.tablex, and pl.tablex in turn requires pl.List in some of its methods.

This is not an issue in standard Lua environments because Lua resolves circular dependencies at runtime using package.loaded. However, Defold performs static build-time dependency analysis and rejects circular require() chains.

Solution

In order to keep the Penlight libraries working with Defold as-is, without any additional modifications, a custom loader is introduced.

It loads the Penlight libraries at runtime as custom resources, bypassing the circular dependency issue during the build process. The original Penlight source code is not modified. This keeps the library upgrade path simple and maintains full compatibility with upstream Penlight releases.

The loader resolves circular dependencies by pre-populating package.loaded before executing each module, allowing Lua to handle cyclic require() calls safely at runtime.

The /lib/pl directory is included in the bundle using the custom_resources setting in game.project:

[project]
...
custom_resources = /lib/pl

This ensures the Penlight source files are packaged with the build, even though they are not loaded via Defold's normal require() mechanism.

Usage

Example usage of the custom loader for Penlight libraries can be found in main.script.

local pl = require "lib.penlight_loader"
local List = pl.require "pl.List"

Important

Do not use normal require("pl.*") in your project. Always load Penlight modules through the custom loader. Mixing normal require() with the custom loader for pl.* modules may reintroduce circular dependency build errors.

Compatibility

Tested with LuaJIT (Defold's default runtime). This approach should work on all platforms supported by Defold.

The following versions were used:

Component	Version
Defold	1.12.1
Penlight	1.15