tbamud/lib/scripts/README.md

Scripts In lib/scripts
======================

This directory contains Python and DSL-style scripts used by the game. Scripts
are attached to rooms, npc's, and objects via builder commands (e.g. `rset add script`,
`mset add script`, `oset add script`). The script file itself is the data format.

Two Script Styles
-----------------

1) DSL (no function definitions)
   - If the file does NOT contain `def on_trigger`, it is treated as the DSL.
   - The DSL supports Python-style `if/elif/else`, `for`, and `while` blocks.
   - Actions are written as simple verbs or function-style calls:
     - `move("n")` or `move("north")`
     - `move(1200)` (room vnum path step, no closed doors)
     - `emote("looks around warily")`
     - `sleep(3)`
     - `log("text with {npc.vnum}")`
     - `do("say hello")`
   - Command-style is also supported:
     - `move "n"`
     - `sleep 3`
     - `log "hello {npc.vnum}"`
   - NOTE: The DSL does not support custom variable assignments yet. Use the
     full Python style if you need variables.

2) Full Python (with `def on_trigger(event):`)
   - If the file contains `def on_trigger`, it runs as normal Python.
   - Use `mud.sleep(seconds)` to pause and resume later.
   - You can use local variables, helpers, and full Python expressions.

Event Context (Full Python)
---------------------------

`on_trigger(event)` receives a dict with:
- `event["self"]`: the entity this trigger is attached to (mob/object/room)
- `event["trigger"]`: info about the trigger (vnum, name, type, narg, etc.)
- `event["vars"]`: trigger variables (if any)

Entity Data Model (DSL and Python)
----------------------------------

Every entity has these common properties:
- `entity.kind`    -> kind id (mob/obj/room)
- `entity.uid`     -> unique runtime id
- `entity.vnum`    -> vnum (mob/obj/room)
- `entity.name`    -> name/short for display

Mob (NPC or PC) properties:
- `npc.health` / `npc.max_health`
- `npc.mana` / `npc.max_mana`
- `npc.stamina` / `npc.max_stamina`
- `npc.move` / `npc.max_move` (alias for stamina)
- `npc.class` / `npc.class_id`
- `npc.species` / `npc.species_id`
- `npc.is_pc` / `npc.is_npc`
- `npc.keyword` (NPC keywords; for PCs, name)
- `npc.room` -> room entity where the mob is located
  - `npc.room.vnum` -> room vnum
  - `npc.room.name` -> room name/short

Object properties:
- `object.keyword` -> object keywords
- `object.oval`    -> list of object values (oval[0] .. oval[NUM_OBJ_VAL_POSITIONS-1])
- `object.room`    -> room entity where the object is located
  - `object.room.vnum` -> room vnum
  - `object.room.name` -> room name/short

Room properties:
- `room.contents`  -> list of objects in the room
- `room.people`    -> list of characters in the room
- `room.vnum`      -> room vnum
- `room.name`      -> room name/short

Entity comparisons:
- `entity == "rat"` checks keyword match for mobs/objects.
- `entity == 123456` checks entity uid.
- `entity_a == entity_b` matches if kind+uid are equal.

Available Methods
-----------------

These are available in both DSL and Python (via the `mud` module).

Core methods:
- `mud.do(command, actor=None)`
  Execute a game command. If `actor` is a mob, it runs as that mob. If `actor`
  is a room, it runs in that room context.
- `mud.emote(message, actor=None)`
  Emote as a mob (actor is optional if the trigger is on a mob).
- `mud.move(direction, actor=None)`
  Move a mob in a direction (e.g. "n", "south", "ne").
  You can also pass a room vnum to step toward a destination, but if it is blocked (eg. with a door), this will not work.
- `mud.sleep(seconds)`
  Pause the script and resume later.
- `mud.roll("1d6")`
  Roll dice. Supported: d4/d6/d8/d10/d12/d20/d100.
- `mud.log(message)`
  Write to `log/script.log`.
- `mud.echo_room(room, message)`
  Echo a message to a specific room.
- `mud.send_char(character, message)`
  Send a message to a character.
- `mud.call_later(seconds, func, *args, **kwargs)`
  Call a function later (Python scripts only).

Convenience names in full Python scripts:
- `log("...")` is available as a shortcut for `mud.log(...)`.
- Direction strings are available as `mud.n`, `mud.s`, `mud.e`, `mud.w`, etc.

Formatting / Expressions
------------------------

DSL supports Python-style blocks:
```
while True:
    if npc.stamina < 20:
        rest
    else:
        stand
```

DSL logging supports f-string style with braces:
```
log "rat {npc.vnum} in room {npc.room.vnum}"
```

In full Python scripts, use normal f-strings:
```
log(f"rat {event['self'].vnum} in room {event['self'].room.vnum}")
```

Variables (Full Python)
-----------------------

Use normal Python variables:
```
def on_trigger(event):
    room = event["self"]
    count = 0
    while True:
        count += 1
        mud.echo_room(room, f"tick {count}")
        mud.sleep(30)
```

The DSL currently does not support custom variable assignment. If you need
variables, use full Python with `def on_trigger(event):`.

Best Practices
--------------
- Keep scripts small and focused.
- Use `log(...)` during development and remove or reduce noise later.
- Avoid infinite tight loops without `sleep`.
- Use comments generously (`# ...`).
- Prefer readable direction strings: `"north"`, `"west"`, etc.

Sample: Room Echo Script
------------------------

See `sample_echo.py` in this directory for a ready-to-attach room script.