Skip to content
Download

Commands (function list)

Status: Implemented (API 1.24). Generated from client/clight/idl/clight_api.json by tools/docs/gen_api_reference.py; do not edit by hand. 21 functions, the newest from API 1.4.

Explanations and examples: Commands. Every function of the cmd module is listed here in table order. The details of each function follow the table, in the same order. Side: where the function works (server, client, both). Context: the thread it may be called on (Conventions). Since: the API version that added it.

C function Lua Side Context Since
cl_cmd_register cl.cmd.register server MAIN 1.0
cl_cmd_ctx_args cl.cmd.ctx_args both TICK 1.0
cl_cmd_ctx_player cl.cmd.ctx_player both TICK 1.0
cl_cmd_ctx_level cl.cmd.ctx_level both TICK 1.0
cl_cmd_send_success cl.cmd.send_success both TICK 1.0
cl_cmd_send_failure cl.cmd.send_failure both TICK 1.0
cl_cmd_run cl.cmd.run server TICK 1.0
cl_cmd_ctx_permission_level ctx:permission_level() both TICK 1.4
cl_cmd_ctx_entities ctx:entities(name) server TICK 1.4
cl_cmd_literal cl.cmd.literal(name) server ANY 1.4
cl_cmd_argument cl.cmd.argument(name, type) server ANY 1.4
cl_cmd_then node:then_(child) server ANY 1.4
cl_cmd_executes node:executes(fn) server ANY 1.4
cl_cmd_requires_level node:requires_permission(level) server ANY 1.4
cl_cmd_requires_permission node:requires_permission(name) server ANY 1.4
cl_cmd_register_tree cl.cmd.register(root) server MAIN 1.4
cl_cmd_arg_str ctx:arg(name) both TICK 1.4
cl_cmd_arg_i32 ctx:arg(name) both TICK 1.4
cl_cmd_arg_f64 ctx:arg(name) both TICK 1.4
cl_cmd_arg_bool ctx:arg(name) both TICK 1.4
cl_cmd_arg_entities ctx:arg(name) (an entity or a list) server TICK 1.4

cl_cmd_register

cl_result cl_cmd_register(const cl_cmd_desc* desc);

Inside server.command_register (or any time before the server starts; re-registered on /reload).

  • Side: server. Context: MAIN (startup (main thread)). Since: API 1.0.
  • Lua: cl.cmd.register
  • C++: (C only)
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_cmd_ctx_args

cl_result cl_cmd_ctx_args(cl_cmd_ctx ctx, char* buf, size_t cap, size_t* out_len);
  • Side: both. Context: TICK (tick thread). Since: API 1.0.
  • Lua: cl.cmd.ctx_args, cmd_ctx:args(...)
  • C++: CmdCtx::args() → Expected<std::string>; clight::cmd::ctx_args(CmdCtx ctx) → Expected<std::string>
  • Writes a string: buf / cap / out_len (a too small buffer returns CL_E_BUFFER_TOO_SMALL with the needed length in *out_len). Lua and C++ return the string.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_cmd_ctx_player

cl_entity cl_cmd_ctx_player(cl_cmd_ctx ctx);
  • Side: both. Context: TICK (tick thread). Since: API 1.0.
  • Lua: cl.cmd.ctx_player, cmd_ctx:player(...)
  • C++: CmdCtx::player() → Entity; clight::cmd::ctx_player(CmdCtx ctx) → Entity

cl_cmd_ctx_level

cl_level cl_cmd_ctx_level(cl_cmd_ctx ctx);
  • Side: both. Context: TICK (tick thread). Since: API 1.0.
  • Lua: cl.cmd.ctx_level, cmd_ctx:level(...)
  • C++: CmdCtx::level() → Level; clight::cmd::ctx_level(CmdCtx ctx) → Level

cl_cmd_send_success

cl_result cl_cmd_send_success(cl_cmd_ctx ctx, cl_text message, bool broadcast_to_admins);
  • Side: both. Context: TICK (tick thread). Since: API 1.0.
  • Lua: cl.cmd.send_success, cmd_ctx:send_success(...)
  • C++: CmdCtx::send_success(cl_text message, bool broadcast_to_admins) → Expected<void>; clight::cmd::send_success(CmdCtx ctx, cl_text message, bool broadcast_to_admins) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_cmd_send_failure

cl_result cl_cmd_send_failure(cl_cmd_ctx ctx, cl_text message);
  • Side: both. Context: TICK (tick thread). Since: API 1.0.
  • Lua: cl.cmd.send_failure, cmd_ctx:send_failure(...)
  • C++: CmdCtx::send_failure(cl_text message) → Expected<void>; clight::cmd::send_failure(CmdCtx ctx, cl_text message) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_cmd_run

cl_result cl_cmd_run(cl_str command, int32_t* out);
  • Side: server. Context: TICK (tick thread). Since: API 1.0.
  • Lua: cl.cmd.run
  • C++: clight::cmd::run(std::string_view command) → Expected<int32_t>
  • The last parameter receives the result. Lua returns it; C++ returns it in Expected<T>.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_cmd_ctx_permission_level

int32_t cl_cmd_ctx_permission_level(cl_cmd_ctx ctx);

The source’s permission level (0 a player without op, 2-4 operators, 4 the console).

  • Side: both. Context: TICK (tick thread). Since: API 1.4.
  • Lua: ctx:permission_level()
  • C++: CmdCtx::permission_level() → int32_t; clight::cmd::ctx_permission_level(CmdCtx ctx) → int32_t

cl_cmd_ctx_entities

cl_result cl_cmd_ctx_entities(cl_cmd_ctx ctx, cl_str selector, cl_entity* out, size_t cap, size_t* out_count);

Resolves an entity argument: a selector (@p, @a[distance=…5], @e[type=zombie]), a player name or a UUID, as seen from the command source. CL_E_NOT_FOUND when nothing matches.

  • Side: server. Context: TICK (tick thread). Since: API 1.4.
  • Lua: ctx:entities(name)
  • C++: CmdCtx::entities(std::string_view selector) → Expected<std::vector<Entity>>; clight::cmd::ctx_entities(CmdCtx ctx, std::string_view selector) → Expected<std::vector<Entity>>
  • Fills an array: pointer / cap / out_count. Lua returns a list, C++ a std::vector.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_cmd_literal

cl_cmd_node cl_cmd_literal(cl_str name);

Command trees (Brigadier style). A node lives until cl_cmd_register_tree takes the root (or the mod unloads).

  • Side: server. Context: ANY (any thread). Since: API 1.4.
  • Lua: cl.cmd.literal(name)
  • C++: clight::cmd::literal(std::string_view name) → CmdNode

cl_cmd_argument

cl_cmd_node cl_cmd_argument(cl_str name, cl_str type);

type: “word”, “string” (one word or “quoted”), “greedy” (the rest), “integer”, “double”, “bool”, “player”, “players”, “entity”, “entities” (or the brigadier: / minecraft: names).

  • Side: server. Context: ANY (any thread). Since: API 1.4.
  • Lua: cl.cmd.argument(name, type)
  • C++: clight::cmd::argument(std::string_view name, std::string_view type) → CmdNode

cl_cmd_then

cl_result cl_cmd_then(cl_cmd_node parent, cl_cmd_node child);
  • Side: server. Context: ANY (any thread). Since: API 1.4.
  • Lua: node:then_(child)
  • C++: CmdNode::cmd_then(CmdNode child) → Expected<void>; clight::cmd::then(CmdNode parent, CmdNode child) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_cmd_executes

cl_result cl_cmd_executes(cl_cmd_node node, cl_cmd_fn fn, void* user);
  • Side: server. Context: ANY (any thread). Since: API 1.4.
  • Lua: node:executes(fn)
  • C++: CmdNode::cmd_executes(cl_cmd_fn fn, void* user) → Expected<void>; clight::cmd::executes(CmdNode node, cl_cmd_fn fn, void* user) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_cmd_requires_level

cl_result cl_cmd_requires_level(cl_cmd_node node, int32_t level);

Only sources with at least this permission level see and use this node (and everything below it).

  • Side: server. Context: ANY (any thread). Since: API 1.4.
  • Lua: node:requires_permission(level)
  • C++: CmdNode::cmd_requires_level(int32_t level) → Expected<void>; clight::cmd::requires_level(CmdNode node, int32_t level) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_cmd_requires_permission

cl_result cl_cmd_requires_permission(cl_cmd_node node, cl_str permission);

A named permission (“my_mod.admin”). Without a permissions plugin it means operators (level 2).

  • Side: server. Context: ANY (any thread). Since: API 1.4.
  • Lua: node:requires_permission(name)
  • C++: CmdNode::cmd_requires_permission(std::string_view permission) → Expected<void>; clight::cmd::requires_permission(CmdNode node, std::string_view permission) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_cmd_register_tree

cl_result cl_cmd_register_tree(cl_cmd_node root);

Registers the tree under its root literal (inside server.command_register, like cl_cmd_register).

  • Side: server. Context: MAIN (startup (main thread)). Since: API 1.4.
  • Lua: cl.cmd.register(root)
  • C++: CmdNode::cmd_register_tree() → Expected<void>; clight::cmd::register_tree(CmdNode root) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_cmd_arg_str

cl_result cl_cmd_arg_str(cl_cmd_ctx ctx, cl_str name, char* buf, size_t cap, size_t* out_len);
  • Side: both. Context: TICK (tick thread). Since: API 1.4.
  • Lua: ctx:arg(name)
  • C++: CmdCtx::arg_str(std::string_view name) → Expected<std::string>; clight::cmd::arg_str(CmdCtx ctx, std::string_view name) → Expected<std::string>
  • Writes a string: buf / cap / out_len (a too small buffer returns CL_E_BUFFER_TOO_SMALL with the needed length in *out_len). Lua and C++ return the string.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_cmd_arg_i32

cl_result cl_cmd_arg_i32(cl_cmd_ctx ctx, cl_str name, int32_t* out);
  • Side: both. Context: TICK (tick thread). Since: API 1.4.
  • Lua: ctx:arg(name)
  • C++: CmdCtx::arg_i32(std::string_view name) → Expected<int32_t>; clight::cmd::arg_i32(CmdCtx ctx, std::string_view name) → Expected<int32_t>
  • The last parameter receives the result. Lua returns it; C++ returns it in Expected<T>.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_cmd_arg_f64

cl_result cl_cmd_arg_f64(cl_cmd_ctx ctx, cl_str name, double* out);
  • Side: both. Context: TICK (tick thread). Since: API 1.4.
  • Lua: ctx:arg(name)
  • C++: CmdCtx::arg_f64(std::string_view name) → Expected<double>; clight::cmd::arg_f64(CmdCtx ctx, std::string_view name) → Expected<double>
  • The last parameter receives the result. Lua returns it; C++ returns it in Expected<T>.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_cmd_arg_bool

cl_result cl_cmd_arg_bool(cl_cmd_ctx ctx, cl_str name, bool* out);
  • Side: both. Context: TICK (tick thread). Since: API 1.4.
  • Lua: ctx:arg(name)
  • C++: CmdCtx::arg_bool(std::string_view name) → Expected<bool>; clight::cmd::arg_bool(CmdCtx ctx, std::string_view name) → Expected<bool>
  • The last parameter receives the result. Lua returns it; C++ returns it in Expected<T>.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_cmd_arg_entities

cl_result cl_cmd_arg_entities(cl_cmd_ctx ctx, cl_str name, cl_entity* out, size_t cap, size_t* out_count);

The entities of a player / players / entity / entities argument.

  • Side: server. Context: TICK (tick thread). Since: API 1.4.
  • Lua: ctx:arg(name) (an entity or a list)
  • C++: CmdCtx::arg_entities(std::string_view name) → Expected<std::vector<Entity>>; clight::cmd::arg_entities(CmdCtx ctx, std::string_view name) → Expected<std::vector<Entity>>
  • Fills an array: pointer / cap / out_count. Lua returns a list, C++ a std::vector.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.