Allium

Appearance

Scripts ​

Scripts are a collection of one or more Lua files and a manifest JSON file, stored in a directory, a zip archive, or within a Java mod.

Manifest ​

The manifest file describes information relevant to the execution of the script, and metadata that might be useful for other scripts.

The following values are required:

  • id: The script ID. Must match the regex pattern [0-9a-z_]+ (lowercase alphanumeric & underscore.)
  • version: A version string. Does not have to be "semver", but consider making it make sense.
  • name: A proper, descriptive name of the script. May be capitalized.
  • entrypoints: The entrypoints from which this script launches from. See below.

Entrypoints ​

Scripts are provided 2 entrypoints to launch from: mixin, and main. Scripts MUST provide a main entrypoint in order to be valid.

mixin ​

The mixin entrypoint is where mixin classes and interfaces are built and registered. This entrypoint is executed during the preLaunch phase, and should avoid doing anything other than mixin building.

For more information see Mixin Library.

main ​

The main entrypoint is where everything else should reside.

The first value returned by this entrypoint becomes the script's module. This module is provided to other scripts that provide this script's ID to require().

Example ​

manifest.json
JSON5
{
  "id": "example",
  "version": "1.0.0",
  "name": "Example Script",
  "entrypoints": {
    "mixin": "mixin.lua",
    "main": "main.lua",
  }
}

Functions ​

The script global is a userdata [instance] that represents the currently executing script. The following functions are provided.

script:getId() ​

Gets the ID provided by the script manifest.

Returns ​

  • string: The script ID.

script:getModule() ​

Gets the module provided by the main entrypoint.

Returns ​

  • any?: The script module.

script:getName() ​

Gets the name provided by the script manifest.

Returns ​

  • string: The script name.

script:getVersion() ​

Gets the version provided by the script manifest.

Returns ​

  • string: The script version.

script:regsiterReloadable(location) ​

Register a path to a file relative to the script root that gets executed when added, and when the script gets reloaded. This method is useful for registering script resources, hooking into events, or hooking into certain mixins.

INFO

Not all code can or should be reloaded. For example, anything that touches Minecraft's registries (blocks, items, etc.) are unlikely to be reloadable and may even cause a crash.

INFO

The default behavior for events and mixins changes whether the hook or event (anything that has an optional destroyOnUnload parameter,) is being registered inside or outside of the file given to this method. Outside of the reloadable file, hooks/events do not get destroyed on reload. However, when used inside the given file, they will be destroyed on reload. Use the optional parameter provided if a more deterministic behavior is desired.

Parameters ​

  1. location - string: A require-like path to the file to execute.

script:registerResource(resource) ​

Register a temporary resource to this script that will close when the script unloads (or reloads). Particularly useful in tandem with script:registerReloadable().

Parameters ​

  1. resource - userdata [instance]: An instance of type ScriptResource.

Returns ​

  • userdata [instance]: A refernece to the resource that will clear the resource from within the script when close() is called.