Proposals/Client scripting plans

Minetest is planned to get client side scripting. This page summarizes the plans for development, and tries to document the consensus inside the core development team. If your changes don't want to serve this documenting purpose, please don't edit this page (except trivial edits like grammar corrections), but rather edit the talk page, or suggest changes on IRC. This is no Feature request page.

General design

The language will be plaintext lua (no bytecode, as it's insecure and against the open source nature of minetest). There won't be any restrictions on mod licenses though.

The general design should be much like the Web browser-JavaScript relationship. During the connection, the server sends all code that should be executed to the client, which runs it inside a locked down sandbox. Unlike with server mods, there will be no way (without changing C++ source code) to execute code outside of that sandbox.

Unlike with Web browsers, Lua code should run in a separate thread. Also, to be completely separate, it shouldn't share the Lua environment with the mainmenu Lua (to forestall intra-environment exploits).

Base execution setup

Every server mod can have a directory "client" whose content will be sent to the client upon connection. After all files have been recieved, the client executes an "init.lua" file for every of those mods.

To emphase the short-lived-ness of the code, the client shouldn't give any access to the filesystem. This implies that all lua files should be held in memory. There can be caches (even permanent ones, like with the texture cache), but lua code shouldn't be abled to "just access the filesystem", not even subdirectories.

Communication between server and client

Note: this section is waiting for approval by hmmmm, doesn't display consensus (yet).

Client lua and server lua should be abled to communicate with each other. There should be no minetest.client_exec_code(playername, codestring) like call, because it favours a bad setup where code is parsed and re-parsed again, generating lag. Instead, code should be sent.

Server and client communicate in events which they can both raise, and handle. Every event type has a name and an associated mod. The data which get sent over the network will include (int,int) event types, to be faster. Therefore, client and server have to register events they want to raise, and call both registering functions while loading. In later code, calling registering functions for unkown events should yield a warning, but without register.

Server functions

minetest.register_on_event(modname, eventname, function(clientid, evtdata))
-> changes the event handler for the (modname, eventname) typed event
minetest.register_event(modname, eventname)
-> registers an event type. Doesn't have to be the same order that on_event methods get registered on the other side, but has to be the same events.
minetest.raise_event(clientid/-s, modname, eventname, evtdata)
-> raises an event for client with clientid, or if a table is passed, all clientids in that table.
minetest.raise_event_all(modname, eventname, evtdata)
-> raises an event for client all clients

Client functions

minetest.register_on_event(modname, eventname, function(evtdata))
-> changes the event handler for the (modname, eventname) typed event
minetest.register_event(modname)
-> registers an event type. Doesn't have to be the same order that on_event methods get registered on the other side, but has to be the same events.
minetest.raise_event(modname, eventname, evtdata)
-> raises an event

API compartments

SAO/CAO control

There should be ways to modify CAOs from client lua.

Formspec replacement

There is still a debate with what to replace formspecs.

Specific features to be implemented using Client-side scripting interfaces

https://github.com/minetest/minetest/issues/816 -- Add wield light by Zeg9 ---- generally, to be defined per-game through shaders registered via the client-side mod
https://github.com/minetest/minetest/issues/958 -- Add player list, viewable by holding Tab by sfan5 ---- Trivially doable using client scripting to bind the key and the Hud interface