How the API works
The API of LSE is the same in every language: the reference describes it once, and each engine maps it to its language. This page explains its shape: what a script finds in its global scope, what the objects it gets are, and when the engine calls the functions it gives.
What a script starts with
LSE binds the API into the global scope of every plugin before it runs the entry script. You do not import or
require it.
Global functions:
log,colorLogandfastLogwrite to the server console;setTimeout,setIntervalandclearIntervalrun code later (see Script helper API). The Node.js engine uses Node.js's ownsetTimeoutandsetIntervalinstead.
Namespaces, objects with static functions:
| Name | What it is about | Reference |
|---|---|---|
mc |
The game: events (mc.listen), commands, players, entities, blocks, items, forms, the scoreboard |
GameAPI, EventAPI, GuiAPI |
ll |
The loader and the plugins: versions, plugin information, ll.exports / ll.imports, ll.onUnload |
ll |
logger |
A configurable log of the plugin | Logger |
data |
Data helpers: player data, JSON, MD5, SHA-1, Base64 | Other data |
money |
The economy | Economy |
File |
Files and folders | File, File system |
network |
HTTP requests (WebSocket clients and HTTP servers are the objects WSClient and HttpServer) |
Network |
system |
System commands, processes and system information | System call, System info |
NBT |
Parsing NBT, and the NBT tag types | NBT |
i18n |
Translations of the plugin's texts | i18n |
Format |
The formatting codes of Minecraft text | Game utilities |
Enumerations, such as PermType and ParamType for commands, are globals too.
Objects
Most of the API works through objects. You get them in two ways:
- From the game, as values the API returns or passes to your functions: a
Playerfrommc.getPlayeror from anonJoinlistener, anEntity, aBlock, anItem, aContainer, aCommandOriginin a command callback. - By creating them with a constructor:
new JsonConfigFile(path),new KVDatabase(dir),new DBSession(type, params),new WSClient(),new IntPos(x, y, z, dimid),new NbtCompound(...). In Lua, call the class withoutnew:JsonConfigFile(path).
The reference names these types Player, Entity, Block and so on; the classes registered in the engine are named
LLSE_Player, LLSE_Entity, LLSE_Block, …, as the Data Types section of the overview of the reference
lists.
Players and entities are references, not copies
A Player or Entity object refers to the player or entity in the game: its properties are read when you access
them, and its functions act on the game. It holds a weak reference: once the player has left, or the entity is gone,
its properties return Null. So do not keep Player objects for a long time. Keep what identifies the player
(pl.xuid, pl.name) and get the object again with mc.getPlayer when you need it.
Values and types
The reference uses general type names (Integer, Float, String, Boolean, Array, Object, Null, …), which
each engine maps to its own types: an Object is a JavaScript object and a Lua table, Null is null or undefined
in JavaScript and nil in Lua. The overview of the reference has the full table and
the conventions of the pages: name : Type for a parameter, [ ] around optional parameters.
Many functions return Null when they fail (a player that is not online, a form that could not be sent): check the
value before you use it. Some, such as those of the SQL database, throw an error instead.
When your code runs
The engine runs your entry script once, when the plugin is loaded. Everything else your plugin does happens in the functions it gives to the API:
- event listeners (
mc.listen), called each time the event happens; - command callbacks (
mc.newCommand,mc.regPlayerCmd,mc.regConsoleCmd), called when someone runs the command; - form callbacks (
pl.sendForm,pl.sendModalForm), called when the player answers the form or closes it; - timers (
setTimeout,setInterval), called when their time has come; - unload functions (
ll.onUnload), called when the plugin is unloaded.
These functions run on the server's thread, between the game's own work. A function that takes long
holds up the server: keep listeners short, and avoid heavy work in frequent events such as onTick.
If your function throws, LSE catches the error and logs it in the console with the event or callback and the name of your plugin; the plugin keeps running. A call to the API with too few arguments or an argument of the wrong type throws an error that names the API and your plugin.
Events go to every listener
When an event happens, LSE calls the listeners of every plugin for it, in the order they were registered (in general
the order the plugins were loaded). A listener that returns false intercepts the event: the game does not process
it, as if it had not happened, but the other plugins' listeners are still called. See
Event listening.
Next
- Plugins and engines: how a plugin is loaded and unloaded.
- Language support: what differs between the engines.
- The guides: listening to events, registering commands, showing forms, storing data and logging and timers.