Item purchase scripting (#412)

# Description

This PR primarily adds an `onPurchase()` script event for items.

The intention is that an admin can create an item listed in a shop that can be scripted to do creative things that we may not anticipate, allowing them to leverage shops for other purchases.

An initial example has been created/added, which is buying a `room for rent` at the inn.

It also addresses some other small typos and bugs.

## Changes

- Added `onPurchase()` item script event and documentation
- Fixed a typo for a room: `paventment` => `pavement`
- Added an example `onPurchase()` event to the inn shop (`room rental`).
- Fixed `cancel-on-action` buffs to cancel on leaving to an exit
- Renamed "leave" to "downstairs" in Inn room, since "l" (for look) was a little confusingly taking the "leave" exit after sleeping.
- Inn room now uses an ephemeral copy per player, so players don't all end up in one instance of the room.
- roominfo template had an error, referring to old ZoneInfo. This is fixed.
- `buy` was not doing anything when you weren't in a shop. Now provides feedback to the user.
- Some small language updates around the `buy` command feedback.

### Links
#411

Author: Volte6

_datafiles/guides/building/scripting/FUNCTIONS_ROOMS.md

@@ -38,6 +38,8 @@
 Returns an Object with key/value pairs of `ProvidedRoomId`=>`NewRoomId`
 Creates ephemeral instances of the RoomId's provided.
 
+NOTE: Ephemeral rooms clean up (delete from memory) mobs, items, etc. when no players occupy the set of created rooms.
+
 |  Argument | Explanation |
 | --- | --- |
 | RoomIds | an array of integers containing RoomId's you want instanced |

_datafiles/guides/building/scripting/SCRIPTING_ITEMS.md

@@ -87,4 +87,21 @@ In all other ways, this follows the same rules as the normal `onCommand()` funct
 | item | [ItemObject](FUNCTIONS_ITEMS.md) |
 | room | [RoomObject](FUNCTIONS_ROOMS.md) |
 
+---
+
+```
+function onPurchase(user ActorObject, item ItemObject, room RoomObject) {
+}
+```
+
+`onPurchase()` is called when a player successfully purchases an item in a shop, after the item is
+
+|  Argument | Explanation |
+| --- | --- |
+| user | [ActorObject](FUNCTIONS_ACTORS.md) |
+| item | [ItemObject](FUNCTIONS_ITEMS.md) |
+| room | [RoomObject](FUNCTIONS_ROOMS.md) |
+
+Returning `false` will prevent the user from being given the object. This can be useful if you want to initate a script from a purchase, but not actually grant the item to the user, such as purchasing extra lives, a ticket for travel, or renting a room.
+
 ---

_datafiles/world/default/items/other-0/102-room_rental.js

@@ -0,0 +1,18 @@
+
+
+function onPurchase(user, item, room) {
+
+    var newRoomIds = CreateInstancesFromRoomIds( [432] );
+
+    if ( newRoomIds[432] ) {
+
+        SendUserMessage(user.UserId(), "You are directed to a room upstairs with a large bed. How inviting...");
+        SendRoomMessage(room.RoomId(), user.GetCharacterName(true)+" says something to the Inn keeper and is escorted to another room.", user.UserId());
+        
+        user.MoveRoom(newRoomIds[432]);
+        return false;
+    } 
+
+    return false;
+}
+

_datafiles/world/default/items/other-0/102-room_rental.yaml

@@ -0,0 +1,9 @@
+itemid: 102
+value: 5
+hands: 0
+name: room rental
+namesimple: room rental
+description: Rent a room in the Inn and rest up.
+type: service
+subtype: generic
+

_datafiles/world/default/mobs/frostfang/7-wench.yaml

@@ -7,8 +7,7 @@ groups:
 combatcommands:
   - 'callforhelp 7:guard:calls for the guards.'
 idlecommands:
-  - 'say You can <ansi fg="command">sleep</ansi> here for a bit here to refresh.'
-  - 'say If you''re hungry check the <ansi fg="command">list</ansi> of food for sale.'
+  - 'say If you''re hungry check the <ansi fg="command">list</ansi> of food and services for sale.'
 activitylevel: 10
 character:
   name: wench
@@ -19,6 +18,8 @@ character:
   spellbook:
     curepoison: 50
   shop:
+    - itemid: 102
+      quantitymax: 0
     - itemid: 30004
       quantitymax: 2
     - itemid: 30005

_datafiles/world/default/rooms/frostfang/432.js

@@ -4,6 +4,13 @@ crowbarAvailableRound = 0;
 const crowbar = ["crowbar", "rod", "metal", "bar"];
 const verbs = ["get", "take", "grab", "steal", "snatch"];
 
+
+function onEnter(user, room) {
+    user.GiveBuff(15, "sleep");
+    return false; // return false to prevent the "auto look"
+}
+
+
 function onCommand_look(rest, user, room) {
 
     matches = UtilFindMatchIn(rest, crowbar);

_datafiles/world/default/rooms/frostfang/432.yaml

@@ -13,8 +13,10 @@ description: The dim glow of a crackling hearth in one corner bathes the wooden
 mapsymbol: I
 maplegend: Inn
 biome: city
+nouns:
+  metal rod: a crowbar leans against the hearth. It must be used as a fire poker.
 exits:
-  leave:
+  downstairs:
     roomid: 61
     exitmessage: You gather your belongings and head back towards the main room of
       the Inn.

_datafiles/world/default/rooms/frostfang/5.yaml

@@ -1,7 +1,7 @@
 roomid: 5
 zone: Frostfang
 title: Cobblestone Way
-description: Almost at the end of Cobblestone Way, the stones paventment underfoot
+description: Almost at the end of Cobblestone Way, the stones pavement underfoot
   is slick with ice, reflecting the soft glow of lanterns that line the path. The
   trees have receded, replaced by statues of figures posed in moments of triumph,
   each one covered in a layer of frost. The music is now a symphony, with flutes and

_datafiles/world/default/rooms/frostfang/61.js

@@ -1,5 +1,5 @@
 {{ $room := .room }}{{ $zone := .zone }}
-<ansi fg="yellow-bold">RoomId:</ansi>         <ansi fg="red">{{ $room.RoomId }}</ansi>{{ if eq $room.ZoneConfig.RoomId $room.RoomId }} <ansi fg="white">(This is the zone root)</ansi>{{ else }} <ansi fg="white">(Zone root is {{ $zone.RoomId }})</ansi>{{ end }}
+<ansi fg="yellow-bold">RoomId:</ansi>         <ansi fg="red">{{ $room.RoomId }}</ansi>{{ if eq $zone.RoomId $room.RoomId }} <ansi fg="white">(This is the zone root)</ansi>{{ else }} <ansi fg="white">(Zone root is {{ $zone.RoomId }})</ansi>{{ end }}
 <ansi fg="yellow-bold">Filepath:</ansi>       <ansi fg="129">{{ $room.Filepath }}</ansi>
 <ansi fg="yellow-bold">Zone:</ansi>           <ansi fg="room-zone">{{ $room.Zone }}</ansi>
 <ansi fg="yellow-bold">MapSymbol:</ansi>      <ansi fg="map-{{ lowercase $room.MapLegend }}">{{ $room.GetMapSymbol }}</ansi>