dMUD: Scripting & Quests

The "living" world of dMUD is powered by a combination of static quest definitions and dynamic Lua scripts.

🤖 The Agent Bridge

AI Agents are more than just text interfaces; they are "Room Occupants."

• Presence: Agents spawn into rooms when called and leave when their tasks are complete.
• Awareness: Agents have access to room context, meaning they know who else is present and can react to room-wide discussions.

📜 The Quest System

Quests provide structured goals and rewards for users.

• Daily & Weekly Quests: Automated recurring tasks that encourage regular engagement.
• Tutorials: Onboarding quests that guide new users through the core mechanics of the system.
• Repeatable Content: Standard tasks that provide consistent sources of Gold and XP.

Quest Types

Quest Hooks

The quest system provides Lua event hooks for tracking progress:

• on_quest_accept(quest_id, user_id) — Fires when user accepts a quest
• on_quest_complete(quest_id, user_id) — Fires when quest objectives are met
• on_quest_progress(quest_id, user_id, progress) — Fires on each progress update
• on_mine_complete(room_id, data) — Fires each mining cycle (profession quest)
• on_chop_complete(room_id, data) — Fires each woodcutting cycle (profession quest)
• on_fish_caught(room_id, data) — Fires when player catches a fish
• on_game_played(game_type, data) — Fires when player completes a mini-game
• on_item_used(item_name, data) — Fires when player uses an item (via /use)
• on_trade_completed(npc_id, data) — Fires when player trades with NPC (via /trade)

✍️ Lua Scripting Engine

Non-Player Characters (NPCs) and special room events are powered by an embedded Lua VM.

• Dynamic NPCs: Scripted characters like the Greeter, Bartender, or Questmaster can hold conversations and trigger game events.
• Event Hooks: Scripts can react to world events, such as a user entering a room or a specific chat keyword being used.
• Shell Integration: Admin-level scripts can even interface with the underlying system for monitoring and reporting.

Lua API (Give Item)

NPCs and quest scripts can grant items to players via the give_item API:

-- Grant an item to the player
give_item("player_name", "item_name", quantity)

-- Examples
give_item("Dan", "iron_ore", 5)
give_item("Dan", "pet_food", 1)
give_item("Dan", "dragon_scale", 1)  -- Rare drop

This API is used by:

• Quest reward fulfillment
• NPC trade transactions
• Profession resource gathering (automatic)
• Random loot drops from mobs/chests

NPC Event Triggers

NPC scripts respond to user actions via event handlers:

• on_user_enter(room_id, data) — Called when a user enters the room
• on_user_exit(room_id, data) — Called when a user exits the room
• on_chat(room_id, data) — Called when a message is sent in the room
• on_use(room_id, data) — Called when user uses an item (/use <item>)
• on_trade(room_id, data) — Called when user trades with NPC (/trade <npc>)

The data table contains: username, user_id, and optionally message (for chat events) or item (for use/trade events).