FarAway Lua Plugin API

Farkit is the Lua plugin system included with the FarAway server. Plugins run inside the server process and can add commands, react to game events, schedule work, inspect players, and modify the primary world.

How plugins are loaded

Place plugins in the server's plugins/ directory. A plugin may be a single .lua file or a directory containing main.lua. The filename or directory name becomes its plugin name.

plugins/
  Welcome.lua
  Clock/
    main.lua
  lib/
    shared.lua

What you can do

• Register commands with command().
• Listen to built-in events and dispatch custom events with on() and emit().
• Use server and player wrappers to interact with online players.
• Play, stop, or resume background music for a player with the player music API.
• Send outbound HTTPS requests or one-shot TCP/UDP messages with the network API.
• Format plugin messages and player chat with color.* and color.translate().
• Read or change blocks with the world API and use region() for area helpers.
• Schedule callbacks in ticks with after() and every().
• Store settings and persistent data with config(), playerData(), and save().

Runtime model

Callbacks execute synchronously on the server thread. Keep them short: blocking work and large loops can delay game ticks. Scheduled delays and periods are measured in ticks; at the normal 20 ticks per second, 20 ticks are approximately one second.

Security

Plugins have broad access to the server process, including LuaJ Java interop and file access. This is not a sandbox. Only install plugins you trust, and check permissions before performing privileged actions at a player's request.

Compatibility

The bundled API identifies itself as Farkit 1.6. Lua execution is provided by LuaJ with Lua 5.2 syntax. Music controls require the paired updated Faraway client and server JARs; see Player music API.