MudLang Concept Document - wwestlake/Labyrinth GitHub Wiki

MudLang Concept Document

MudLang is a domain-specific language (DSL) designed to enable users and administrators to interact with the game environment in a flexible, powerful, and secure manner. This document outlines the syntax, structure, and key features of MudLang, including the recent addition of function definitions.

1. Basic Syntax and Structure

Commands in MudLang follow a specific structure:

  • command [target] [arguments] [options]

Example

  • attack @target with @weapon

This command initiates an attack on the specified target using the specified weapon.

2. Accessing User Properties

You can access various properties of the user or other entities using special tokens:

  • @user.health – The user's current health.
  • @target.name – The target's name.
  • @user.inventory – The user's inventory list.

Example

  • give @target @item if @user.health > 50

This command gives an item to the target if the user's health is above 50.

3. Expressions and Conditional Logic

You can evaluate expressions and use conditional logic in your commands:

  • if (@user.health < 20) { say "You are low on health!" }

This command will make the user say "You are low on health!" if their health drops below 20.

4. Variables and Assignments

Variables can be created to store values that result from expressions or are required for later use in commands:

  • let currentHealth = @user.health
  • let weapon = @user.weapon
  • attack @target with @weapon if currentHealth > 50

This example stores the user's current health and weapon in variables and then attacks the target if the user's health is above 50.

5. Function Definitions

MudLang supports the definition of functions using the let syntax. Functions in MudLang are defined as expressions that take arguments and return a result.

Syntax

  • let functionName arg1 arg2 = expression

Example

  • let add a b = a + b
  • let calculateDamage base damageMultiplier = base * damageMultiplier
  • let heal amount = if (@user.health + amount > 100) { 100 } else { @user.health + amount }

These examples define:

  1. add: A function that takes two arguments, a and b, and returns their sum.
  2. calculateDamage: A function that multiplies a base value by a damage multiplier.
  3. heal: A function that heals the user by a given amount, but not exceeding 100 health.

Usage

Once defined, functions can be used in expressions or as part of commands:

  • let result = add 5 10
  • attack @enemy with @user.weapon if calculateDamage(10, 2) > @enemy.health
  • let newHealth = heal 20

This demonstrates how functions can be invoked with arguments and their results stored or used in commands.

6. Looping and Iteration

Looping constructs allow repeated actions:

  • for each @enemy in @room.enemies { attack @enemy with @user.weapon }

This command attacks each enemy in the room using the user's weapon.

7. Built-in Functions

MudLang includes built-in functions for common tasks, which can be used within commands:

  • @user.getClosestEnemy()
  • @room.getItems()
  • @user.heal(amount)

Example

  • heal @user by @user.getItem("healingPotion").power

This heals the user by the power of the healing potion in their inventory.

8. Command Examples

Attack Command

  • attack @enemy with @user.weapon if @enemy.distance < 10

This command attacks the enemy if they are within a distance of 10 units.

Item Transfer

  • give @target @item if @user.inventory.has(@item)

This command gives an item to the target if the item is present in the user's inventory.

Broadcast Message

  • broadcast "Server is restarting in 10 minutes!" if @server.time == "10:00 PM"

This command broadcasts a server-wide message if the server time is 10:00 PM.

Check and Act

  • let health = @user.health
  • if (health < 20) { say "You are low on health!" }

This command checks the user's health and makes them say a warning if their health is below 20.

Using Functions

  • let damage = calculateDamage(15, 1.5)
  • attack @enemy with @user.weapon if damage > @enemy.health

This example demonstrates the use of a defined function to calculate damage and use it in a command.

9. Conclusion

MudLang is a versatile language designed to simplify and enhance interaction within the game environment. The introduction of function definitions further extends its capabilities, allowing for more complex and reusable logic to be encapsulated within the language. This document provides a foundation for using MudLang effectively in various scenarios within the game.