luanti-mod-network-api/README.md

# Luanti Network API MOD

It's Luanti MOD adding a Network API.

*It is an updated project originally started [here](https://github.com/miney-py/mineysocket)*

---

# mineysocket - A network api mod for minetest

The goal of this mod is to open minetest for other scripting languages.

For that this mod opens a TCP network port where it receives lua snippets to execute these inside the minetest.
That allows you to write a socket client in your favorite language to wrap api functions over network/internet.

**The reference implementation is [Miney](https://github.com/miney-py/miney), a python interface to minetest.**

## Requirements

* luasockets

### Running with docker

Look here: [Documentation](docker/README.md)

### Installation with Windows

It's more complicated, because you can't just put some dlls in the right place. 
You have to recompile minetest together with luasocket. 

Luckily there are some scripts to do that for you or you just download a precompiled binary that includes all you need.

* **Miney windows distribution: https://github.com/miney-py/miney_distribution**

  The miney distribution is an all-in-one bundle of minetest, mineysocket, python, miney and a launcher for quickstart.

* **Precompiled binary: https://github.com/miney-py/minetest_windows/releases**
  
  Just minetest with mineysocket, nothing else

* **Build script: https://github.com/miney-py/minetest_windows**

  Use the build script yourself, to compile binaries.

### Installation with Debian Buster

The latest minetest version is in the backport repository for buster, so it's very easy to install: https://wiki.minetest.net/Setting_up_a_server/Debian
```
apt install lua5.1-socket
cd /var/games/minetest-server/.minetest/mods
git clone git@github.com:miney-py/mineysocket.git
```
* Edit /var/games/minetest-server/.minetest/worlds/\<your_world\>/world.mt and add:
```
load_mod_mineysocket = true
```
* Edit /etc/minetest/minetest.conf
  * name = \<your_playername\>  # This gives you all privileges on your server
  * secure.trusted_mods = mineysocket  # This is needed for luasocket
  * Optional but recommended:
    * enable_rollback_recording = true  # This allows you to clean up your world
* Connect at least once with minetest to your server and login with a username + password, to get you registered.

## Settings

Default is, that mineysocket listens on 127.0.0.1 on port 29999.

You can change this in the minetest menu (Settings -> All Settings -> Mods -> mineysocket) or in the minetest.conf.

```
mineysocket.host_ip = 127.0.0.1
```
The IP mineysocket is listening on. 
With "127.0.0.1" only you can connect, with "*" or "0.0.0.0" anyone in the network or internet can connect. 
 
**WARNING: It could be dangerous to open this to everyone in the internet! Only change if you know what you are doing! If you don't know, let it at "127.0.0.1".**
```
mineysocket.host_port = 29999
```
The TCP port mineysocket is listening. 

## Notes

Clients can only run code after authentication and if the user has "server" privilege (or if connected from 127.0.0.1).

This may change, but currently authenticated users can do anything in the minetest api, also change their own and other users privileges!

**You use this at your own risk!**

## Todo

- [ ] Authentication without sending cleartext password
- [ ] Implement limited user rights with a fixed set of available commands

## Protocol description

mineysocket is a simple JSON-based TCP protocol. Send a valid JSON-String with a tailing linebreak (`\n`) to the port 
and mineysocket responds a JSON string with a tailing linebreak.

### Ping

A simple alive check, and the only command implemented without json.

```
>>> ping\n
<<< pong\n
``` 

### Authentication

```
>>> {"playername": "player", "password": "my_password"}\n
<<< {"result": ["auth_ok", "127.0.0.1:31928"], "id": "auth"}\n
``` 
Send playername and password and you get auth_ok with your clientid.

On error you get a error object:
```
<<< {"error": "authentication error"}\n
```
Btw: All errors look like this, with different error descriptions.

Connections from 127.0.0.1 don't need to authenticate.

### Run lua code

After authentication, you are ready to send a command. An JSON object key is a command, in this example 
"lua" to run lua code.
```
>>> {"lua": "return 12 + 2, \"something\"", id="myrandomstring"}\n
<<< {"result": [14, "something"], id="myrandomstring"}\n
```
Lua code runs inside a function definition, so you need to return a value to get a result send back to you. 
As you see, you can return multiple values. 
Optional you can send a (random) id to identify your result, if you run multiple codes parallel.

More commands will be added later.

### Events

Mineysocket can send JSON objects on global events. 

To receive events, you need to register for this event. This example registers for `chat_message`:
```
>>> {"register_event": "chat_message"}\n
```

To unregister, do this:
```
>>> {"unregister_event": "chat_message"}\n
```

You can register for the following events.

##### The server was gracefully stopped
```
<<< { "event" = "shutdown" }\n
```

#####  A player's health points changed
```
<<< {"event" = "player_hpchanged", params = ["player_hpchanged", "<playername>", "<hp change>", {'type': '<reason>', 'from': '<player or engine>'}]}\n
```

##### A player died
```
<<< {"event" = "player_died", params = ["<playername>", "<reason>"]}\n
```

##### A player respawned
```
<<< {"event" = "player_respawned", params = ["<playername>"]}\n
```

##### A player joined
```
<<< {"event" = "player_joined", params = ["<playername>"]}\n
```

##### A player left
```
<<< {"event"= "player_left", params = ["<playername>"]}\n
```

##### An authentication failed
```
<<< {"event" = "auth_failed", params = ["<name>", "<ip>"]}\n
```

##### A player cheated

With one of the following types

* `moved_too_fast`
* `interacted_too_far`
* `interacted_while_dead`
* `finished_unknown_dig`
* `dug_unbreakable`
* `dug_too_fast`
```
<<< {"event" = "player_cheated", params = ["<playername>", {"type": "<type>"}]}\n
```

##### A new chat message
```
<<< {"event" = "chat_message", params = ["<name>", "<message>"]}\n
```

##### A node was placed
```
<<< {"event" = "node_placed", params = [<pos>, <newnode>, <playername>, <oldnode>, <itemstack>, <pointed_thing>]}\n
```

##### A node was dug
```
<<< {"event" = "node_dug", params = [<pos>, <oldnode>, <playername>]}\n
```

##### A node was punched
```
<<< {"event" = "node_punched", params = [<pos>, <node>, <playername>, <pointed_thing>]}\n
```