nanomud 0.1.0__tar.gz

nanomud-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: nanomud
+Version: 0.1.0
+Summary: A super simple, no-coding builder-focused MUD engine in Python.
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Nanomud
+
+Nanomud is a super simple, **no-coding**, builder-focused MUD (Multi-User Dungeon) engine written in Python. 
+
+Unlike other MUD engines that require you to write Python scripts to expand the world or add objects, Nanomud lets you do **everything entirely in-game through commands** (Online Creation / OLC). The world, items, players, and NPCs are persisted automatically as human-readable JSON files.
+
+## Features
+
+- **No Code Required**: Start a server and construct your entire game world, items, npcs, behaviors, and stats interactively while connected.
+- **Modern CLI & Packaging**: Install via `pip` and run immediately.
+- **Auto-Persistence**: Any modification you make (digging a room, changing descriptions, spawning items, editing stats) is autosaved in real-time to `./data/world.json`.
+- **Property-Based RPG Engine**: Built-in combat, movement, vendor shops, and NPC behaviors (wandering, conversation, aggression) driven by simple object properties (e.g. `hp`, `damage`, `gold`) editable via builder commands.
+- **Standard Telnet Protocol**: Connect with any client (standard telnet, PuTTY, Mudlet, etc.).
+- **Zero Dependencies**: Built entirely using the Python standard library (`asyncio`).
+
+---
+
+## Quick Start
+
+### 1. Installation
+Install Nanomud as a package:
+```bash
+pip install .
+```
+
+### 2. Start the Server
+Run the command in the directory where you want your database to reside:
+```bash
+nanomud --port 4000
+```
+This will automatically create a `./data/` directory containing your world configuration and player profiles.
+
+### 3. Connect to the MUD
+Open a telnet client and connect to your server:
+```bash
+telnet localhost 4000
+```
+*(If you are on Windows, you can use PuTTY set to Connection Type: Telnet, Host: localhost, Port: 4000)*
+
+The **first player to register** is automatically granted **builder admin status** and can run `@` builder commands.
+
+---
+
+## How to Build the World (OLC)
+
+All builder commands start with `@`. Here is a step-by-step example of how to build a basic zone.
+
+### 1. Digging Rooms
+When you log in, you start in `The Grand Lobby` (room ID `lobby`). Let's dig a dark dungeon to the north:
+```
+@dig north A Dark Dungeon
+```
+This creates a new room called `A Dark Dungeon` (with ID `a_dark_dungeon`), links it to your north exit, and automatically creates a return exit `south` from the dungeon to the lobby.
+
+Let's go north to inspect it:
+```
+north
+```
+
+### 2. Customizing Descriptions
+Let's make the dungeon sound more atmospheric:
+```
+@desc The stone walls are covered in damp moss, and you hear water dripping in the distance.
+```
+
+### 3. Creating Items
+Let's summon a weapon:
+```
+@create steel sword
+```
+Let's describe it:
+```
+@itemdesc steel sword A heavy sword forged from polished steel. It feels powerful in your hands.
+```
+By default, items can be picked up. Let's make this sword a weapon by giving it a `damage` property:
+```
+@setprop steel sword damage 15
+```
+*(When a player attacks an NPC, the engine automatically checks their inventory for items with a `damage` property and uses the highest value as their weapon damage).*
+
+### 4. Spawning NPCs and Customizing Behaviors
+Let's spawn a goblin to guard the dungeon:
+```
+@spawn goblin
+@npcdesc goblin A small, green, sneaky goblin looking for gold.
+```
+Let's give the goblin some stats:
+```
+@setprop goblin hp 35
+@setprop goblin max_hp 35
+@setprop goblin damage 6
+@setprop goblin gold 12
+```
+Now, let's configure the goblin's behavior:
+- Make it wander between rooms: `@npcbehavior goblin wander true`
+- Set a custom line of dialogue: `@npcbehavior goblin talk Hehehe, you won't get my gold, human!`
+- Make it aggressive (attack players on sight): `@npcbehavior goblin aggressive true`
+
+### 5. Creating Shops
+You can turn any NPC into a shopkeeper. Let's create a shopkeeper back in the lobby:
+```
+south
+@spawn merchant
+@npcbehavior merchant talk Hello, traveler! Would you like to buy a potion?
+@npcbehavior merchant shop potion:10,shield:50
+```
+This configures the merchant to sell a `potion` for 10 gold and a `shield` for 50 gold. Players can buy items from them using the `buy` command.
+
+---
+
+## Standard Commands Reference
+
+### Player / Gameplay Commands
+- `look` / `l` - Look around the current room.
+- `look <target>` - Examine an item, NPC, or player.
+- `north`, `south`, `east`, `west`, `up`, `down` (aliases: `n`, `s`, `e`, `w`, `u`, `d`) - Move in a direction.
+- `say <message>` (or `"`) - Say something to everyone in the room.
+- `tell <player> <message>` - Whisper a private message.
+- `get <item>` / `drop <item>` - Interact with items.
+- `inventory` / `i` - View your items, gold, base damage, and HP.
+- `who` - See who is currently online.
+- `kill <npc>` - Start round-based combat. Combats tick every 2 seconds.
+- `buy <item>` - Purchase an item from a shop vendor.
+- `quit` - Disconnect and save character state.
+- `help` - Show command help.
+
+### Builder Commands
+- `@dig <direction> <room_name>` - Dig a new room in that direction.
+- `@link <direction> <existing_room_id>` - Link exit to an existing room ID.
+- `@unlink <direction>` - Remove exit in that direction.
+- `@roomname <name>` - Rename the current room.
+- `@desc <description>` - Set room description.
+- `@create <item_name>` - Spawn an item in the room.
+- `@itemdesc <item> <desc>` - Set description of an item.
+- `@itemgettable <item> <t/f>` - Set if an item can be picked up.
+- `@spawn <npc_name>` - Spawn a new NPC in the room.
+- `@npcdesc <npc> <desc>` - Set description of an NPC.
+- `@npcbehavior <npc> <behavior> <value>` - Set behaviors: `wander` (t/f), `aggressive` (t/f), `talk` (msg), `shop` (item:cost,item:cost).
+- `@setprop <target> <property> <value>` - Set arbitrary properties on rooms, items, NPCs, or players (e.g. stats like `hp`, `damage`, `gold`, `admin`).
+- `@rooms` - List all room IDs in the world.
+- `@teleport <room_id>` - Teleport to any room by its ID.
+
+---
+
+## JSON Persistence Files
+
+Nanomud stores your world in a clean, human-readable format. This makes it trivial to version control your world map using git, or manually edit stats in an editor.
+
+- **World Map**: Saved in `data/world.json`.
+- **Player Accounts**: Saved in `data/players/<username>.json`.

nanomud-0.1.0/README.md

@@ -0,0 +1,150 @@
+# Nanomud
+
+Nanomud is a super simple, **no-coding**, builder-focused MUD (Multi-User Dungeon) engine written in Python. 
+
+Unlike other MUD engines that require you to write Python scripts to expand the world or add objects, Nanomud lets you do **everything entirely in-game through commands** (Online Creation / OLC). The world, items, players, and NPCs are persisted automatically as human-readable JSON files.
+
+## Features
+
+- **No Code Required**: Start a server and construct your entire game world, items, npcs, behaviors, and stats interactively while connected.
+- **Modern CLI & Packaging**: Install via `pip` and run immediately.
+- **Auto-Persistence**: Any modification you make (digging a room, changing descriptions, spawning items, editing stats) is autosaved in real-time to `./data/world.json`.
+- **Property-Based RPG Engine**: Built-in combat, movement, vendor shops, and NPC behaviors (wandering, conversation, aggression) driven by simple object properties (e.g. `hp`, `damage`, `gold`) editable via builder commands.
+- **Standard Telnet Protocol**: Connect with any client (standard telnet, PuTTY, Mudlet, etc.).
+- **Zero Dependencies**: Built entirely using the Python standard library (`asyncio`).
+
+---
+
+## Quick Start
+
+### 1. Installation
+Install Nanomud as a package:
+```bash
+pip install .
+```
+
+### 2. Start the Server
+Run the command in the directory where you want your database to reside:
+```bash
+nanomud --port 4000
+```
+This will automatically create a `./data/` directory containing your world configuration and player profiles.
+
+### 3. Connect to the MUD
+Open a telnet client and connect to your server:
+```bash
+telnet localhost 4000
+```
+*(If you are on Windows, you can use PuTTY set to Connection Type: Telnet, Host: localhost, Port: 4000)*
+
+The **first player to register** is automatically granted **builder admin status** and can run `@` builder commands.
+
+---
+
+## How to Build the World (OLC)
+
+All builder commands start with `@`. Here is a step-by-step example of how to build a basic zone.
+
+### 1. Digging Rooms
+When you log in, you start in `The Grand Lobby` (room ID `lobby`). Let's dig a dark dungeon to the north:
+```
+@dig north A Dark Dungeon
+```
+This creates a new room called `A Dark Dungeon` (with ID `a_dark_dungeon`), links it to your north exit, and automatically creates a return exit `south` from the dungeon to the lobby.
+
+Let's go north to inspect it:
+```
+north
+```
+
+### 2. Customizing Descriptions
+Let's make the dungeon sound more atmospheric:
+```
+@desc The stone walls are covered in damp moss, and you hear water dripping in the distance.
+```
+
+### 3. Creating Items
+Let's summon a weapon:
+```
+@create steel sword
+```
+Let's describe it:
+```
+@itemdesc steel sword A heavy sword forged from polished steel. It feels powerful in your hands.
+```
+By default, items can be picked up. Let's make this sword a weapon by giving it a `damage` property:
+```
+@setprop steel sword damage 15
+```
+*(When a player attacks an NPC, the engine automatically checks their inventory for items with a `damage` property and uses the highest value as their weapon damage).*
+
+### 4. Spawning NPCs and Customizing Behaviors
+Let's spawn a goblin to guard the dungeon:
+```
+@spawn goblin
+@npcdesc goblin A small, green, sneaky goblin looking for gold.
+```
+Let's give the goblin some stats:
+```
+@setprop goblin hp 35
+@setprop goblin max_hp 35
+@setprop goblin damage 6
+@setprop goblin gold 12
+```
+Now, let's configure the goblin's behavior:
+- Make it wander between rooms: `@npcbehavior goblin wander true`
+- Set a custom line of dialogue: `@npcbehavior goblin talk Hehehe, you won't get my gold, human!`
+- Make it aggressive (attack players on sight): `@npcbehavior goblin aggressive true`
+
+### 5. Creating Shops
+You can turn any NPC into a shopkeeper. Let's create a shopkeeper back in the lobby:
+```
+south
+@spawn merchant
+@npcbehavior merchant talk Hello, traveler! Would you like to buy a potion?
+@npcbehavior merchant shop potion:10,shield:50
+```
+This configures the merchant to sell a `potion` for 10 gold and a `shield` for 50 gold. Players can buy items from them using the `buy` command.
+
+---
+
+## Standard Commands Reference
+
+### Player / Gameplay Commands
+- `look` / `l` - Look around the current room.
+- `look <target>` - Examine an item, NPC, or player.
+- `north`, `south`, `east`, `west`, `up`, `down` (aliases: `n`, `s`, `e`, `w`, `u`, `d`) - Move in a direction.
+- `say <message>` (or `"`) - Say something to everyone in the room.
+- `tell <player> <message>` - Whisper a private message.
+- `get <item>` / `drop <item>` - Interact with items.
+- `inventory` / `i` - View your items, gold, base damage, and HP.
+- `who` - See who is currently online.
+- `kill <npc>` - Start round-based combat. Combats tick every 2 seconds.
+- `buy <item>` - Purchase an item from a shop vendor.
+- `quit` - Disconnect and save character state.
+- `help` - Show command help.
+
+### Builder Commands
+- `@dig <direction> <room_name>` - Dig a new room in that direction.
+- `@link <direction> <existing_room_id>` - Link exit to an existing room ID.
+- `@unlink <direction>` - Remove exit in that direction.
+- `@roomname <name>` - Rename the current room.
+- `@desc <description>` - Set room description.
+- `@create <item_name>` - Spawn an item in the room.
+- `@itemdesc <item> <desc>` - Set description of an item.
+- `@itemgettable <item> <t/f>` - Set if an item can be picked up.
+- `@spawn <npc_name>` - Spawn a new NPC in the room.
+- `@npcdesc <npc> <desc>` - Set description of an NPC.
+- `@npcbehavior <npc> <behavior> <value>` - Set behaviors: `wander` (t/f), `aggressive` (t/f), `talk` (msg), `shop` (item:cost,item:cost).
+- `@setprop <target> <property> <value>` - Set arbitrary properties on rooms, items, NPCs, or players (e.g. stats like `hp`, `damage`, `gold`, `admin`).
+- `@rooms` - List all room IDs in the world.
+- `@teleport <room_id>` - Teleport to any room by its ID.
+
+---
+
+## JSON Persistence Files
+
+Nanomud stores your world in a clean, human-readable format. This makes it trivial to version control your world map using git, or manually edit stats in an editor.
+
+- **World Map**: Saved in `data/world.json`.
+- **Player Accounts**: Saved in `data/players/<username>.json`.

nanomud-0.1.0/nanomud/__init__.py

@@ -0,0 +1,3 @@
+from .server import TelnetServer as NanoMUD
+
+__all__ = ["NanoMUD"]

nanomud-0.1.0/nanomud/__main__.py

@@ -0,0 +1,16 @@
+import argparse
+from .server import TelnetServer
+
+def main():
+    parser = argparse.ArgumentParser(description="Nanomud: A super simple no-coding builder MUD engine.")
+    parser.add_argument("--host", default="0.0.0.0", help="Host address to bind to (default: 0.0.0.0)")
+    parser.add_argument("--port", type=int, default=4000, help="Port to listen on (default: 4000)")
+    parser.add_argument("--data", default="./data", help="Directory for world and player JSON files (default: ./data)")
+    
+    args = parser.parse_args()
+    
+    server = TelnetServer(host=args.host, port=args.port, data_dir=args.data)
+    server.run()
+
+if __name__ == "__main__":
+    main()