Script packages

Bundle scripts and shared code, then install them from GitHub.

A script package is a folder directly inside Documents/Lucent/packages with a package.json. It can hold several runnable scripts, some shared code, or both.

A standalone .js file in Documents/Lucent/scripts is called a loose script. Script packages resemble npm packages.

Make a package

Here is a small package with one script and one shared module:

Lucent lists every .js file under scripts/ as a runnable script. The main file is what another script gets when it requires the package by name. Other files are just internal modules.

Start with this package.json:

{
  "name": "@your-name/farming-tools",
  "version": "1.0.0",
  "description": "A few farming scripts and shared helpers.",
  "main": "index.js",
  "lucent": {
    "version": ">=0.0.1 <0.1.0"
  }
}

name should be unique. If present, version must be an exact semantic version. Use lucent.version to say which Lucent versions the package supports. Without it, Lucent cannot check compatibility.

• description, version, and lucent are optional.
• main defaults to index.js.

The folder name and package name are separate. The example above can live at Documents/Lucent/packages/farming-tools, while scripts still import it as @your-name/farming-tools. Each package must have a unique name.

Lucent picks an unused folder name when it installs a package from GitHub and remembers that folder for updates and removal.

Share code

Packages use CommonJS modules. For example, lib/travel.js can export a helper:

const api = require("lucent/api");

function* visitBattleon() {
  yield* api.player.joinMap("battleon");
}

module.exports = { visitBattleon };

Then index.js can expose it as the package’s public API:

module.exports = require("./lib/travel");

A runnable script inside the package can require its own public API:

const farmingTools = require("@your-name/farming-tools");

module.exports = function* run() {
  yield* farmingTools.visitBattleon();
};

Loose scripts can use the same require("@your-name/farming-tools") call once the package is installed.

Always write require paths as string literals. Lucent finds dependencies before a script runs, so computed paths do not work. A path can point to a built-in module, a relative .js file, or an installed script package.

Depend on another package

Use lucent.dependencies when your package requires other script packages:

{
  "name": "@your-name/farming-tools",
  "version": "1.0.0",
  "lucent": {
    "version": ">=0.0.1 <0.1.0",
    "dependencies": {
      "@someone/quest-tools": "^2.1.0"
    }
  }
}

List each script package your code requires and its version range. Do not list the package itself or built-in modules such as lucent/api and effect.

Lucent checks dependency versions before a script runs, but it does not install them for you. Install each dependency separately. A dependency also needs an exact version in its own package.json, otherwise Lucent cannot check the range.

Vendored script packages

Each Lucent release includes snapshots of its vendored script packages. Browse the package reference for the included packages, their documented versions, and their public APIs.

On first launch, Lucent installs the package snapshot included with that release if no matching package or folder exists.

Script packages can be updated independently of Lucent.

Install from GitHub

Open Scripts > Packages in a game window and select Install package. Paste the GitHub repository URL, then confirm. The package’s scripts will appear in the Scripts tab.

Only install repositories you trust. Package code has the same access as other Lucent scripts.

Notes

• package.json should be at the repository root. If the package lives in a subfolder, set Package directory under Advanced options, for example packages/farming-tools.
• Git ref can select a branch, tag, or commit. Leave it blank to use the default branch. Add a GitHub credential for private repositories or a higher request limit.
• Use Check for updates to compare the installed package with its Git ref. Updating or restoring replaces local edits. Packages added by hand cannot be updated by Lucent.