README.md

   1 # Hydra
   2 <img src="https://cdn8.picryl.com/photo/2016/05/14/hydra-from-bl-royal-12-c-xix-f-13-b31e4a-1024.jpg" width="500" />
   3
   4 Lua bindings for client side minetest protocol - written in Go, using [anon5's mt package](https://github.com/anon55555/mt).
   5 Capable of deserializing ToClt packets and serializing ToSrv packets.
   6
   7 Main use case are bot clients. Multiple clients can easily be spawend and polled from one script - hence the name "Hydra".
   8 Hydra may also be useful for integration testing or network debugging.
   9
  10 Hydra is WIP: there are bugs, API may change any time, some packets are unimplemented and many components are yet to be added.
  11
  12 # Installation
  13 Go 1.18 is required.
  14 `go install github.com/dragonfireclient/hydra-dragonfire@latest`
  15
  16 # Invocation
  17 Due to limitations of Go, hydra can not simply be required from a Lua script. Instead, the hydra binary has to be invoked with a script as argument:
  18 `hydra-dragonfire file.lua <args>`. Any additional arguments `<args>` are provided to the script.
  19
  20 # Architecture
  21 By default, hydra will only take care of connection and packet serialization, no state management takes place.
  22 Hydra is a library, not a framework: it does not organize your code and there is no module system.
  23
  24 Multiple clients can be created independently by calling the `hydra.client` function.
  25 `poll` can be used on one or multiple clients to receive packets and `send` can be used to send packets.
  26 Only selected packets will be returned by `poll`, to avoid unnecessary conversion of packets to Lua.
  27 Poll will return early if the script is interrupted by a signal, one of the selected clients is disconnected or the configured timeout elapses.
  28
  29 Additionally, different native components can be enabled per-client to manage state.
  30 Currently only the `auth` component is available, but components like `map`, `objs`, `inv`, `pos`, `playerlist` etc. will be added in the future.
  31 Components handle packets asynchronously, they will process them even if poll is not called.
  32
  33 # Documentation
  34 For available packets, see `spec/client` and `spec/server`.
  35
  36 For available utilities, see `builtin`.
  37
  38 Documentation for native functions is yet TODO.