Introduction

Luanti is a robust platform designed for hosting multiplayer games, allowing you to create engaging gaming environments for players. Managing multiple Luanti servers can be complex, requiring careful attention to configuration and dependency management.

Enter Nix-Luanti, a module and package collection specifically developed for NixOS and Home-Manager users. It streamlines the process of managing Luanti servers by offering:

Declarative Configuration: Simplify the setup of multiple server instances.
Extensive Content Library: Access a wide range of packaged games, mods, and texture packs sourced from the official ContentDB. As well as a few client side mods.
Automatic Dependency Resolution: Ensure your configurations are always correct and functional.
Client Configuration: Easily install mods and packages through luanti.withPackages.

This documentation guide will walk you through everything you need to know about setting up and configuring Luanti servers using Nix-Luanti.

Try out a Luanti game

nix run gitlab:leonard/nix-luanti\?host=git.menzel.lol\#games.x86_64-linux.mineclonia

run an example client Configuration

nix run gitlab:leonard/nix-luanti\?host=git.menzel.lol\#example

Installation

Add the nix-luanti input to your flake:

{ inputs = {
    # other inputs
    nix-luanti = {
      type = "gitlab";
      owner = "leonard";
      repo = "nix-luanti";
      host = "git.menzel.lol";
      ref = "main";
    };
  };
  # the rest of your flake
}

Module

Install the Module

import the nixos module:

# configuration.nix
{inputs, pkgs, config, ...}:
{

  imports = [
      inputs.nix-luanti.nixosModules.default

      # your other imports
  ];

  # your other configuration
}

if you are using home-manager, use the home-manager module instead:

# home.nix
{inputs, pkgs, config, ...}:
{

  imports = [
      inputs.nix-luanti.homeManagerModules.default

      # your other imports
  ];

  # your other configuration
}

Overlay

Install the Overlay

If you already imported the nixos or home-manager module, the overlay is allready installed.

The Overlay gives you access to pkgs.luantiPackages, pkgs.luanti.withPackages, pkgs.fetchFromLuantiContentDB and other helper functions.

# configuration.nix or home.nix
{inputs, pkgs, config, ...}: {
  nixpkgs.overlays = [
    inputs.nix-luanti.overlays.default

    # your other overlays
  ];

  # your other configuration
}

you can also instantiate a pkgs instance with this overlay installed.

pkgs = import inputs.nixpkgs {
  inherit system; # assumes you have system defined in that scope
  overlays = [ inputs.nix-luanti.overlays.default ];
};

Server Configuration

Configure servers

To configure multiple Luanti servers using Nix-Luanti, you can define server instances in your Nix configuration file (configuration.nix or home.nix). Below are example configurations for different scenarios

Example Configuration

Single Server with Default Settings

{ config, pkgs, ... }:
{
  services.luanti.servers.my_very_cool_server_name = {
      # Uses default game: VoxeLibre
      port = 30000;                                # Specifies the server port
    };
  };
}

Multi-Server with Custom Settings

{ config, pkgs, ... }:
{
services.luanti.servers = with pkgs.luantiPackages; {
    my_very_cool_peacefull_server ={
      port = 30001;
      mods = with pkgs-unstable.luantiPackages.mods; [
        waypoints
      ];
      config = {
        only_peaceful_mobs = true;
      };
      whitelist = [
        "alice"
        "bob"
      ];
    };

    another_server = {
      game = games.mineclonia;
      port = 30002;

      # this server uses only default configurations. no configuration is inherited from other servers.
    };
  };
};

Server Accessible trough the Browser

Only works with NixOS and not in the Home-Manager module

{ config, pkgs, ...}: {

  services.luanti.servers = {
    my_very_cool_local_web_server = {
      host = "localhost";
      openFirewall = false;
      port = 30000;
    };
    my_very_cool_public_web_server = {
      host = "game.example.com";
      ssl = true;
      port = 30001;
    };
  };
}

This sets up nginx for web access as well as a Proxy server for the wasm builds to be able to connect to the Servers.

Troubleshooting

The systemd service is named luanti-<your-server-name>.service so if you set up services.luanti.servers.adventure you can see the status of the server by running systemctl status luanti-adventure.service and all its files like the world file the .minetest directory and everything else will be placed in /var/lib/luanti-adventure

Service Configuration Options

These are the options for the NixOS module. the Home-Manger options are almost the same, but the host, and proxy options are not functioning there right now

Top-Level Options

`services.luanti.enable`

Globally disables all Luanti services if set to false, regardless of individual server configurations.

Type: Boolean
Default: true

`services.luanti.addOverlay`

Adds pkgs.luantiPackages and pkgs.fetchFromLuantiContentDB etc.

Type: Boolean
Default: true

`services.luanti.proxy`

The proxy is used for the minetest-wasm package. If a server defines the host option these options are set automatically

services.luanti.proxy.port

TCP port used by the proxy service.
- Type: Integer
- Default: 30261
services.luanti.proxy.directProxies
- Type: List of configurations
- Structure:
  - address: String (IP or hostname)
  - realAddress: String (Default: "127.0.0.1")
  - port: Integer

`services.luanti.package`

Specifies the default Luanti server package to use. Can be overwritten by each server specifically.

Type: Package reference
Default: pkgs.luanti-server

`services.luanti.whitelist`

Global default whitelist for all servers. Example: ["alice", "bob"].

Type: List of Strings or Null
Default: null

Server-Specific Options

Each server instance is configured under services.luanti.servers.<name>, where <name> is a unique identifier for the server.

`services.luanti.servers.<name>.enable`

Enables or disables a specific server instance.

Type: Boolean
Default: true

`services.luanti.servers.<name>.openFirewall`

Opens UDP port for the server and if host is set, the TCP ports for nginx in the firewall.

Type: Boolean
Default: true

`services.luanti.servers.<name>.port`

Port number to bind to.

Type: Integer
Default: Determined by server index

`services.luanti.servers.<name>.game`

Specifies the game package for the server.

Type: Package reference
Default: pkgs.luantiPackages.games.mineclone2

`services.luanti.servers.<name>.package`

Allows overriding the luanti-server package per server instance.

Type: Package reference
Default: Uses value of top-level package option.

`services.luanti.servers.<name>.whitelist`

Whitelist specific to this server, overriding global whitelist if set.

Type: List of Strings or Null
Default: null

`services.luanti.servers.<name>.host`

FQDN for experimental Luanti-WASM builds. Only functional in the NixOS module.

Type: String or Null
Default: null

`services.luanti.servers.<name>.ssl`

Enables HTTPS for the WASM build. Only functional in the NixOS module.

Type: Boolean
Default: false

`services.luanti.servers.<name>.webTexturePack`

The Texture Pack used by the web client (only used if host is defined)

Type: Package or null
Default null

`services.luanti.servers.<name>.mods`

List of Luanti mods to include.

Type: List of Packages
Default: []

`services.luanti.servers.<name>.config`

Additional settings for the Luanti config file.

Type: Configuration block (attrsOf)
Default: Sets the port for Prometheus to the same port as the luanti server

`services.luanti.servers.<name>.mapserver.enable`

Start a dedicated mapserver instance for this Luanti server (only functional in the NixOS module right now).

Type: Boolean
Default: false

`services.luanti.servers.<name>.mapserver.config`

Configuration written verbatim to mapserver.json. The port key is required when the mapserver is enabled; other keys follow the upstream mapserver schema.

Type: Configuration block (attrsOf)
Default: {}
Notes:
- Set webapi.secretkey when the companion mod is enabled so the mod can authenticate.
- When host is configured, the NixOS module proxies /map to this port.

`services.luanti.servers.<name>.mapserver.companionMod`

Installs the mapserver companion mod into the server and wires it to the configured mapserver URL and secret key.

Type: Boolean
Default: false

Client Configuration

Configure client

All official clients can connect to servers set up with nix-luanti. No additional client configuration needed.

Example configuration:

{inputs, pkgs, config, ...}:
{
  # for home-manager
  home.packages = with pkgs; [
    (with luantiPackages; luanti.withPackages {
      games = with games; [
        mineclone2 # VoxeLibre
        (minetest_game.withMods (m: [
          # m contains all mods that state compatibility with that game on contentDB
          m."3d_armor"

          # but you can still add other mods
          mods.i3

          # mods installed using withMods on a game do not appear in the content browser and are installed and active on every world using that game

          # if installed using withMods dependencies are automatically added if possible
        ]))
        nodecore
      ];
      mods = with mods; [
        # mods that can be enabled/disabled per world
        # you are responsible to install dependencies
        animalia
        draconis
      ];
      texturePacks = with texturePacks; [
        # you still need to enable them in settings
        soothing32
        vilja_pix_2
      ];
      clientMods = with clientMods; [
        # client mods are enabled on every world you join even on servers
        alarm_watch
        toomuchinfo
      ];
    })

    # your other packages
  ];

  # your other home configuration
}

Advanced

Need a different package?

Nix-luanti provides a set of functions to help you package additional content:

pkgs.buildLuantiMod
pkgs.buildLuantiModPack
pkgs.buildLuantiGame
pkgs.buildLuantiTexturePack
pkgs.fetchFromLuantiContentDB

you can look at src/packages.nix to see how they work

Keyboard shortcuts