Quickstart

• PyPI

• Luanti ContentDB

Welcome in the sandbox!

Blockgames like Luanti or Minecraft give you the ideal playground for creative playing and building just like a real sandbox. But other than real sandboxes, you can work on very large worlds together with your friends over the internet. And you can use (very simplified) physics, save the progress and more.

But what about learning programming while expressing your creativity? Why not automate things? Or build even greater things?

Installation

Miney consists of two parts: the Luanti mod and the Python library. The Luanti mod is required to connect to the game, while the Python library provides the API for interacting with the game.

• Miney in the Luanti ContentDB

• Miney im Python Package Index (PyPI)

Windows

• Download the latest Luanti distribution from https://www.luanti.org/downloads/ and extract it to a folder.

• Start Luanti by running the “luanti.exe” in the “bin” folder.

• Download the latest Python Version from https://www.python.org/downloads/ and install it.

• Install miney by opening a command prompt (cmd) and typing:

>>> pip install miney

Linux

• Download the latest Luanti by following instruction on https://www.luanti.org/downloads/

• You should have Python 3 installed, if not, install it with your package manager.

• Install miney by opening a terminal and typing:

>>> pip3 install miney

MacOS

• Download the latest Luanti by following instruction on https://www.luanti.org/downloads/

• You should have Python 3 installed, if not, install it with Homebrew or download it from https://www.python.org/downloads/.

• Install miney by opening a terminal and typing:

>>> pip install miney

For all Plattforms

• Luanti:

  • Install the Miney mod by starting Luanti and clicking to “Content”, “Browse online content” and searching for miney.

• Python:

  • You can install Miney systemwide by typing this in a command prompt: “pip install miney”

  • Suggestion: Make yourself familiar with venv’s, so you can isolate different development environments. A good starting point is https://docs.python.org/3/tutorial/venv.html

How to start a game

• Start Luanti and create a new world.

• Press the “Select Mods” Button, then select “miney” and enable it. Close this screen by pressing “Save”.

• Activate the “Host Server” option, so that the miney client (and others) can connect to your game.

• Press “Host Game” to start.

• Run your favorite Python IDE or editor and start coding!

Verify your setup

After installing Miney and the Luanti mod, it’s a good idea to verify that everything is working together. The check_setup.py script is designed for this purpose. It connects to your Luanti server, performs a few basic actions, and reports whether the connection was successful.

View Code (check_setup.py)

"""
Miney Setup Checker
===================

This script connects to a Luanti server to verify that both the server and
the Miney library are correctly configured. It gathers and displays key
information, such as the server version, online players, and the number of
registered nodes and tools.

This is the recommended first script to run after installing Miney to ensure
your environment is ready.

How to Run:
1. Make sure the `miney` mod is installed and enabled on your Luanti server.
2. Run this script from your terminal, providing connection details if needed:
   python examples/check_setup.py [server] [port] [playername] [password]
"""
import logging
import sys

from miney import Luanti, LuantiConnectionError

# --- Logger Setup ---
# Configure a simple logger for clean and informative output
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s | %(levelname)-8s | %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S",
)
logger = logging.getLogger(__name__)


if __name__ == "__main__":
    # --- Connection Details ---
    server = sys.argv[1] if len(sys.argv) > 1 else "127.0.0.1"
    port = int(sys.argv[2]) if len(sys.argv) > 2 else 30000
    username = sys.argv[3] if len(sys.argv) > 3 else "miney"
    password = sys.argv[4] if len(sys.argv) > 4 else "ChangeThePassword!"

    logger.info(f"Attempting to connect to {server}:{port} as '{username}'...")

    try:
        # Use a 'with' statement for automatic connection management
        with Luanti(server=server, playername=username, password=password, port=port) as lt:
            logger.info("Connection successful!")
            print("-" * 40)
            logger.info("--- Luanti & Miney Setup Check ---")

            # 1. Get Server Information
            server_version = lt.version
            logger.info(f"Luanti Server Version: {server_version}")

            # 2. Get Player Information
            players = list(lt.players)
            player_count = len(players)
            player_names = ", ".join([p.name for p in players]) if players else "None"
            logger.info(f"Players Online ({player_count}): {player_names}")

            # 3. Get World Content Information
            # This confirms that Miney can access the game's content database
            node_count = len(list(lt.nodes.names))
            tool_count = len(list(lt.tool))
            logger.info(f"Registered Node Types: {node_count}")
            logger.info(f"Registered Tool Types: {tool_count}")

            print("-" * 40)

            # 4. Final Verification
            if node_count > 10 and tool_count > 0:
                logger.info("✅ Verification successful. Miney appears to be correctly set up!")
            else:
                logger.warning("⚠️ Verification complete, but with warnings.")
                logger.warning("Low node/tool count may indicate an issue with the server or mod.")

    except LuantiConnectionError as e:
        logger.critical(f"❌ Connection Failed: {e}")
        logger.critical("Please check the following:")
        logger.critical("  - Is the Luanti server running?")
        logger.critical("  - Are the server address and port correct?")
        logger.critical("  - Is the 'miney' mod installed and enabled on the server?")
        logger.critical("  - Is the password correct?")
    except KeyboardInterrupt:
        logger.info("\nScript interrupted by user.")
    except Exception as e:
        logger.critical(f"An unexpected error occurred: {e}", exc_info=True)
    finally:
        logger.info("Script finished.")

Just copy the code in a file named check_setup.py and open a terminal in the same folder and type this into it:

>>> python check_setup.py
...
2025-08-11 01:03:43 | INFO     | ✅ Verification successful. Miney appears to be correctly set up!
2025-08-11 01:03:44 | INFO     | Disconnecting from server
2025-08-11 01:03:44 | INFO     | Script finished.

This is the best way to confirm your setup before diving into more complex projects. You can find this and other examples in the Code Examples section.

First lines of code

The first lines of code with Miney should be the import statement and the creation of the Miney object “lt” (short for Luanti). This will connect Miney to your already running Luanti.

import miney

lt = miney.Luanti()

Important

Whenever you see a object “lt” in the documentation, it was created with this line!

Interactive Exploration with the Python Shell

Miney is designed to be highly interactive, making it perfect for use in a Python REPL (Read-Eval-Print Loop) or an IDE like IDLE. This allows you to explore the game world and the Miney API without needing to write and run a full script—an excellent way for beginners to learn and experiment.

Note

IDLE is Python’s Integrated Development and Learning Environment and is included with every Python installation. You can start it from your command line by typing python -m idlelib.idle.

A key feature is dynamic auto-completion. Miney fetches information like node types and online player names from the server and makes them available for tab-completion in modern Python shells.

Example: Interacting with Players

You can easily see and interact with online players. Type lt.players. in your Python shell and press the Tab key. You will see a list of all online players. You can then access a player object directly by their name to get their properties.

Example of player completion in a Python REPL

>>> lt.players.  # Press Tab
lt.players.miney          lt.players.HumanPlayer          lt.players.Player3
>>>
>>> lt.players.HumanPlayer
<miney.player.PlayerIterable object at 0x000001AD4F56F4D0>
>>> lt.players.HumanPlayer.position
<Luanti Point(x=-145.0, y=6.0, z=-243.0)>

Example: Discovering Node Types

Similarly, you can discover all available node types. Type lt.nodes.names. and press Tab. You’ll see a list of all registered node names (e.g., default:stone, flowers:rose). You can then use these names as strings in functions that manipulate the world.

Discovering and using a node name

>>> from miney import Point
>>> lt.nodes.names.  # Press Tab
>>> lt.nodes.names.default.  # Press Tab
>>> lt.nodes.names.default.apple  # Press Enter
'default:apple'
>>> lt.nodes.set(Point(10, 20, 30), lt.nodes.names.default.apple)

This powerful interactive discovery feature significantly lowers the barrier to entry, especially in educational settings, as you can learn and explore what’s possible directly within the Python shell.