Server plugins

Status: Partly implemented. A server-side mod runs on Celestial’s dedicated server (seecraft_server, from <server dir>/mods/) and on the integrated server, and vanilla clients can join. Commands, chat and command events, player messages and titles, inventories, container menus, scheduled tasks, broadcasts, running console commands and sounds work. Server control (MOTD, TPS, stop, save), access lists, scoreboards, teams, boss bars, the tab list, chat formatting, per-player visibility and runtime worlds are Planned.

There is no separate plugin API: a “plugin” is a CLight mod with "side": "server" and "sync": "server_only", using the same API as every other mod. This page collects what plugin-style mods use most. Guide: A server plugin (vanilla clients welcome).

Manifest

{
  "schema": 1,
  "id": "arena_games",
  "version": "3.0.1",
  "name": "Arena Games",
  "license": "MIT",
  "api": 1,
  "side": "server",
  "sync": "server_only",
  "runtime": { "type": "lua", "entry": "scripts/main.lua" }
}

A dedicated server skips "side": "client" mods. Start it with --clight-dev for hot reload while you work.

What plugins use

Task	API	Page
Commands with arguments, selectors and permissions	cl_cmd_literal … cl_cmd_register_tree, Lua cl.cmd.*	Commands
Run a vanilla command as the console	cl_cmd_run("weather clear", &result)	Commands
Join, leave, chat, command, interaction, block and damage events	player.*, block.*, entity.*	Complete event list
Messages, action bar, titles, broadcasts	cl_player_send_message, cl_player_send_title, cl_server_broadcast	Players, Text components and chat
Online players	cl_server_players	Players
Give, take and count items	cl_player_give, cl_player_take, cl_player_count_item	Players
Chest GUIs (shops, kits, menus)	cl_menu_open with locked = true	Inventories and menus
Timers and countdowns	cl_sched_run_server, cl_sched_repeat_server, Lua cl.spawn	Scheduler and jobs
Sounds for one player or everyone nearby	cl_sound_play_to_player, cl_sound_play	Sound and music
Settings files	cl_config_open(CL_CONFIG_SERVER, ...)	Configuration
Data that survives restarts	config; C/C++: files in /data	Persistence and data attachments

Example: a welcome kit (Lua)

local given = {}   -- by UUID; save it with the config API if it must survive restarts

cl.on("player.join", function(event)
  local p = event.player
  if given[p.uuid] then return end
  given[p.uuid] = true
  p:give("minecraft:stone_sword")
  p:give("minecraft:bread", 8)
  p:send_title("Welcome!", "Have a kit")
  cl.entity.server_broadcast(p.name .. " joined for the first time")
end)

Threading

Every server callback runs on the server tick, one at a time per mod (Threading model). Long work belongs in scheduled steps.

Not supported

Bukkit, Spigot, Paper and Folia plugin jars don’t load, and there is no translation layer. Port the logic by hand (Porting a Bukkit, Spigot, Paper or Folia plugin by hand).

Planned

Server control (info, MOTD, max players, TPS and MSPT, stop, save), whitelist, bans and ops lists, scoreboards, teams and boss bars, the tab list header and footer, chat formatting and per-recipient filtering, per-viewer entity visibility, kicking and transfers, runtime worlds for minigames, and a plugins/ folder alias.