This project is a simple mud that runs entirely within an ESP8266 and can be accessed via the wifi portal it connects to.

How to Buy / Build the Mud

Where to buy your ESP8266


I like the NodeMcu devices. They have 4mb flash and work well and are fairly robust and compact.

How to Load on a New ESP8266

Vagrant setup


Setup Vagrant SCP

vagrant plugin install vagrant-scp

Use python 3.6+

Create a virtual environment to save your brainspace.

virtualenv venv

Use your virtual env:

Mac / Linux:

source venv/bin/activate



Install esptool and the other required pip modules which will let you install the micropython firmware.

pip install -r requirements.txt

NEW Custom Vagrant image:

python release_image.py

This will write the binary micropython os to the device. After this you will want to validate the write was successful.

We will use the miniterm included with pyserial to connect to the device.

python -m serial.tools.miniterm COM1 115200

After you get in you will have access to the micropython terminal which will let you run python.

Enter the following to check the firmware to be sure everything went well.

import esp

This should return a "True" at the end along with the checksum if things went well.

Next the WebREPL server needs to be setup to ease file transfer.

import webrepl_setup

This script will ask you for a password and a few other odds and ends.

After a reboot you will need to configure your wifi.

import network
sta_if = network.WLAN(network.STA_IF)
ap_if = network.WLAN(network.AP_IF)

# activate the station interface

sta_if.connect('<your ESSID>', '<your password>')

# Run this again and again until you get an IP Address. If this fails your connect is likely wrong.

Note your IP Address from the sta_if.ifconfig()

Disconnect from the serial miniterm with a ctrl+]

After exiting the miniterm edit the release.py and change the IP Address and port:


Create a file called releasepw.conf with the password you used in the webrepl setup.

Run the release script:

python release.py

Reboot your device and the mud will be running at the IP Address on port 1234. To connect:

telnet 1234

Planning and Formats

Next Steps

  1. every tick loop through the players
  2. for each player load the roomname_monsters.txt
  3. execute any current action [flee (maybe later), attack, continue combat, special attack (if enough mp or stamina)]
  4. Write results of action to the roomname_monsters.txt if the monster is killed or mp / stamina has changed. - Sidenote.. don't store inventory, get a list of possible inventory and randomize on death and drop on the ground (no corpses)
  5. Process any special commands from the player [spells, special attacks based on stamina]
  6. Write results of action to the player file [damage, mp use, stamina use]
  7. Write any new inventory to the room file. Expire any inventory that is old TBD....
  8. Every minute respawn mobs for any room the players are in.

Mob Format

Mobs folder:



    "name": "cricket",
    "desc": "A small green chirping insect with large legs suited for jumping.",
    "aa": "1d2",
    "spawn": {
        "hp": "2d2",
        "mp": "0",
        "sta": "10",
    "say": [
        "A cricket quietly chirps",
        "A cricket moves quietly"
    "sp": [],
    "at": [
        {"name": "kick", "cost":5, "dmg": "2d4", "desc": "The cricket kicks with powerful legs"},
        {"name": "antenna tickle", "cost":2, "dmg": "1d3" "desc": "The cricket brushes you with antenna"},


All damage rolls are described in the number of times to roll and the random amount in dice format: 1d20 = 1 to 20, 2d6 = 2 to 12

  • name - The name that will be displayed to the user when the monster is described
  • desc - The description that will be displayed to the user when the monster is looked at
  • aa - Auto-Attack amount that will be applied for every tick
  • spawn - The values used when the spawner creates the monster to seed the values. A direct integer means the value will be set to that value always.
    • hp - the starting hp range
    • mp - the starting mp range
    • sta - the stamina used to perform special attacks or actions
  • say - Things when not in combat the monster will express to anyone in the room.
  • sp - A list of spells that appear in the spells/ folder
  • at - Special attacks
    • name - The special attack name
    • cost - The cost in stamina of the attack
    • dmg - the amount of damage caused by this attack
    • desc - the description to display when the attack is performed