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.

Event Driven Architecture

Client-side mods operate on asynchronous events. This is necessary to prevent mods from preventing or otherwise delaying scene rendering. Events are posted to a separate thread which then dispatches them via Lua (that is, the client-side equivalent to Script API):

On keypress input
On mouse input (move, mousebutton)
Digging/punching/dig complete
Item events
Inventory changes
Local player events (move, jump, crouch, etc.)
Player events (Server HP change/breath change, eventually to be a network event)
Network events
This is deserialized from within Lua
Lua side abstracts as an RPC call
GUI events

Longer term stretch goals:

Client-side biome change events

To prevent excessive event generation, a mask of wanted events will be maintained. Nothing will be queued unless a mod subscribes to the event type.

Functions available to client side mods (aka the Lua API):

HUD manipulation
GUI manipulation
Register ParticleSpawners
Register sounds and play them
Register shaders and trigger them on events ??? uh oh how are we going to do this
Send network events - abstracted to RPC call to the server
this will serve as the basis to many of the currently built-in mechanisms
Emulate local player events or keypresses?
Set sky/bg/general video effects
Set player pos/crouch/jump state
Set player camera pitch/yaw

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.

HUD and Formspec replacement

There is still a debate with what to replace huds and 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