Repository files navigation

Hullrot is a minimalistMumble server withimmersive integration with the online role-playing gameSpace Station 13.

Features include:

• Local talk by default, so only others in vision range can hear you.
• Push-to-talk over any of the character's available radio channels.
• Handling of intercoms, holopad calls, and hot-miked radios.
• Headsets going inactive if station telecomms is disabled.

Hullrot requires integration with the game server to pass information back andforth. For an example integration, grep forhullrot inour tgstation branch.

Hullrot is still evolving. If you are interested in using it and thedocumentation is insufficient, feel free to contact the author directly.

TheRust compiler:

1. Install the Rust compiler's dependencies (primarily the system linker):

   • Ubuntu:sudo apt-get install gcc-multilib
   • Windows (MSVC):Build Tools for Visual Studio 2017
   • Windows (GNU): No action required

2. Usethe Rust installer, or another Rust installationmethod, or run the following:

   curl https://sh.rustup.rs -sSfo rustup-init.shchmod +x rustup-init.sh./rustup-init.sh

3. Set the default compiler to32-bit:

   # in the `hullrot` directory...cd hullrot# Linuxrustup override add stable-i686-unknown-linux-gnu# Windowsrustup override add stable-i686-pc-windows-msvc

System packages (OpenSSL, Opus, Protobuf):

• Ubuntu and Debian users run:

  sudo apt-get install libssl-dev:i386 libopus-dev:i386 protobuf-compiler pkg-config:i386

• Windows (GNU/MSYS2) users run:

  pacman -S mingw-w64-i686-{openssl,opus,protobuf}

• Windows (MSVC) users:

  • Select fromOpenSSL binaries.
  • Select latestprotoc-win32.zip.
  • Rust Opus package will automatically build from bundled sources.

• Other distributions install the appropriate32-bit development and32-bit runtime packages for OpenSSL, Opus, and the Protobuf compiler.

Note: only the BYOND integrationrequires building in 32-bit mode, but therest of this README will assume 32-bit for simplicity.

Thecargo tool handles compilation, as well as automatically downloading andcompiling all Rust dependencies. To compile in release mode (recommended):

cargo build --release

Abinary (hullrot.exe orhullrot) and alibrary (hullrot.dll orlibhullrot.so) will be produced intarget/release. The binary is the Mumbleserver, and the library is a small RPC client for controlling the serversuitable for BYOND integration.

The Hullrot binary is a standalone Mumble server. It expects to be reachable byplayers on both TCP and UDP. It also exposes a control channel using a simpleJSON-based RPC. By default, the control channel is only accessible by clientson the same host.

Running Hullrot for the first time will create a config filehullrot.toml aswell as a self-signed certificate. Usehullrot.toml to configure the servers,and use a CA such asLet's Encrypt if self-signedcertificates are insufficient.

Passing the name of a config file as a command-line argument will cause Hullrotto use that config file instead.

Hullrot's DM code will need to be integrated into your codebase. The primaryimplementation should be straightforward to port to any/tg/station fork:

• controller
• user interface

The exact behavior - who can speak to who when, what radio channels areavailable, which mobs are restricted from using the radio - can be understoodby reading and adjusted by modifying the DM code.

The Hullrot library (the.dll or.so produced earlier) will need to be madevisible to BYOND, either by being placed in the world directory or in BYOND'sbin directory. If hosting on Linux, the references to"hullrot.dll" in theDM code will need to be changed to"libhullrot.so".

Games with a similar foreign function interface to BYOND may choose to re-usethe Hullrot library. All functions in the library follow the signatureextern "C" const char* hullrot_foo(int argc, const char** argv) and returnresponses as a JSON blob. On failure, the blob will be an object with one key,"error".

• hullrot_dll_version - returns the version of the control client library.
  • {"version": "0.1.0", "major": 0, "minor": 1, "patch": 0}
  • Clients should check thatmajor is exactly the value they expect, andthatminor is at least the value they expect.
  • Ignores its arguments.
• hullrot_init - initializes the control connection and returns the firstcontrol message received from the server.
  • Errors if the control connection could not be made.
    • {"error": "The connection was refused."}
  • On success, the first control message should be aVersion:
    • {"Version": {"version": "0.1.0", "major": 0, "minor": 1, "patch": 0}}
  • Clients may check thatmajor is exactly the value they expect, and thatminor is at least the value they expect.
  • Ignores its arguments.
• hullrot_control - sends each of its arguments (which should be JSON blobs)as control messages to the server.
  • Returns a JSON list of control messages received from the server.
  • May be called with no arguments to poll for incoming control messages.
• hullrot_stop - disconnect from the server, blocking until completion.
  • Ignores its arguments and returns the empty object{}.

Games may also use their own socket facilities. The control channel is a simpleTCP connection. Messages are framed by unsigned big-endian 32-bit integerlength prefixes, and are encoded as JSON blobs.

See the definitions ofenum ControlIn andenum ControlOut insrc/main.rsfor details on the control messages, and theintegrations/ directory forexample clients.

Hullrot is free software: you can redistribute it and/or modifyit under the terms of the GNU Affero General Public License as published bythe Free Software Foundation, either version 3 of the License, or(at your option) any later version.

Hullrot is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See theGNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public Licensealong with Hullrot. If not, seehttp://www.gnu.org/licenses/.