Improving scripting, scripts, documentation, follow command, adding a special item (#379)

# Description

This adds/changes some scripting functions, improves some scripts, and adds a magic flute, used to charm rats at night to follow the player.

## Changes

- `follow` command now has a default time it lasts. Longer periods can be specified.
- Implemented a magic flute which when played at night, causes rats to follow the player.
- Added some new scripting functions and modified existing ones
  - Return Actor objects instead of userId/mob instance id
- Updated/improved some scripts to use changes.

Author: Volte6

_datafiles/guides/building/scripting/FUNCTIONS_ACTORS.md

@@ -5,7 +5,7 @@ ActorObjects are the basic object that represents Users and NPCs
 - [ActorObject](#actorobject)
   - [ActorNames(actors \[\]ActorObject) string ](#actornamesactors-actorobject-string-)
   - [GetUser(userId int) ActorObject ](#getuseruserid-int-actorobject-)
-  - [GetMob(mobInstanceId int) ActorObject ](#getmobmobinstanceid-int-actorobject-)
+  - [GetMob(mobInstanceId int \[,createIfMissing bool\]) ActorObject ](#getmobmobinstanceid-int-createifmissing-bool-actorobject-)
   - [ActorObject.UserId() int](#actorobjectuserid-int)
   - [ActorObject.InstanceId() int](#actorobjectinstanceid-int)
   - [ActorObject.MobTypeId() int](#actorobjectmobtypeid-int)
@@ -104,12 +104,13 @@ Retrieves a ActorObject for a given userId.
 | --- | --- |
 | userId | The target user id to get. |
 
-## [GetMob(mobInstanceId int) ActorObject ](/internal/scripting/actor_func.go)
+## [GetMob(mobInstanceId int [,createIfMissing bool]) ActorObject ](/internal/scripting/actor_func.go)
 Retrieves a ActorObject for a given mobInstanceId.
 
 |  Argument | Explanation |
 | --- | --- |
 | mobInstanceId | The target mobInstanceId to get. |
+| createIfMissing | If true and mob isn't found, the mob will be created and returned. |
 
 ## [ActorObject.UserId() int](/internal/scripting/actor_func.go)
 Returns the userId of the ActorObject.˚

_datafiles/guides/building/scripting/FUNCTIONS_ROOMS.md

@@ -13,8 +13,10 @@
   - [RoomObject.GetItems() \[\]ItemObject](#roomobjectgetitems-itemobject)
   - [RoomObject.DestroyItem(itm ScriptItem) ](#roomobjectdestroyitemitm-scriptitem-)
   - [RoomObject.SpawnItem(itemId int, inStash bool) \[\]ItemObject](#roomobjectspawnitemitemid-int-instash-bool-itemobject)
-  - [RoomObject.GetMobs() \[\]int](#roomobjectgetmobs-int)
-  - [RoomObject.GetPlayers() \[\]int](#roomobjectgetplayers-int)
+  - [RoomObject.GetMob(mobId int) Actor](#roomobjectgetmobmobid-int-actor)
+  - [RoomObject.GetMobs(\[mobId int\]) \[\]Actor](#roomobjectgetmobsmobid-int-actor)
+  - [RoomObject.GetPlayers() \[\]Actor](#roomobjectgetplayers-actor)
+  - [RoomObject.GetAllActors() \[\]Actor](#roomobjectgetallactors-actor)
   - [RoomObject.GetContainers() \[\]string](#roomobjectgetcontainers-string)
   - [RoomObject.GetExits() \[\]object](#roomobjectgetexits-object)
   - [GetMap(mapRoomId int, mapZoom, mapHeight int, mapWidth int, mapName string, showSecrets bool \[,mapMarker string, mapMarker string\]) string](#getmapmaproomid-int-mapzoom-mapheight-int-mapwidth-int-mapname-string-showsecrets-bool-mapmarker-string-mapmarker-string-string)
@@ -113,11 +115,26 @@ Spawns an item in the room.
 | itemId | ItemId to spawn. |
 | inStash | If true, spawns stashed instead of visible. |
 
-## [RoomObject.GetMobs() []int](/internal/scripting/room_func.go)
-Returns an array of `mobInstanceIds` in the room.
 
-## [RoomObject.GetPlayers() []int](/internal/scripting/room_func.go)
-Returns an array of `userIds` in the room.
+## [RoomObject.GetMob(mobId int) Actor](/internal/scripting/room_func.go)
+Returns the first mob that matches the provided MobId type (Note: NOT MOB INSTANCE ID!)
+
+|  Argument | Explanation |
+| --- | --- |
+| mobId | MobId to match. |
+
+## [RoomObject.GetMobs([mobId int]) []Actor](/internal/scripting/room_func.go)
+Returns an array of mob `Actor`s in the room.
+
+|  Argument | Explanation |
+| --- | --- |
+| mobId (optional) | Only get mobs of the provided MobId type. (Note: NOT MOB INSTANCE ID!) |
+
+## [RoomObject.GetPlayers() []Actor](/internal/scripting/room_func.go)
+Returns an array of player `Actor`s in the room.
+
+## [RoomObject.GetAllActors() []Actor](/internal/scripting/room_func.go)
+Returns an array of all `Actor`s in the room.
 
 ## [RoomObject.GetContainers() []string](/internal/scripting/room_func.go)
 Gets a list of container names in the room.

_datafiles/world/default/items/other-0/101-arcane_flute.js

@@ -0,0 +1,38 @@
+
+const MUSIC_DESCRIPTIONS = [
+    "a silvery trill dances on the breeze. ♪♪ ♫",
+    "a cascade of notes unravels into open air. ♫ ♪♪",
+    "a soft melody fills the air. ♪♫ ♪",
+];
+
+const RAT_MOB_IDS = [1, 12];
+
+function onCommand_play(user, item, room) {
+
+    var randomPhrase = MUSIC_DESCRIPTIONS[UtilDiceRoll(1, MUSIC_DESCRIPTIONS.length)-1];
+
+    if ( UtilIsDay() ) {
+        SendUserMessage(user.UserId(), "You attempt to play the flute, but only succeed in producing a shrill noise");
+        SendRoomMessage(room.RoomId(), user.GetCharacterName(true)+" attempts to play their <ansi fg=\"item\">"+item.Name(true)+"</ansi> and a horrible, shrill sound fills the air.", user.UserId());   
+        
+        return true;
+    } 
+
+    SendUserMessage(user.UserId(), "You surprisingly find yourself able to play the flute effortlessly, and "+randomPhrase);
+    SendRoomMessage(room.RoomId(), user.GetCharacterName(true)+" plays their <ansi fg=\"item\">"+item.Name(true)+"</ansi> and "+randomPhrase, user.UserId());   
+
+    // NOTE: This is not charming the mob. This is a special pacify and force follow.
+    //       The rats will not follow the behavior of charmed mobs.
+    for( var i in RAT_MOB_IDS ) {
+        var ratMobs = room.GetMobs(RAT_MOB_IDS[i]);
+        for ( var j in ratMobs ) {
+            ratMobs[j].Command(`break`); // Break off any combat
+            ratMobs[j].Command(`follow ` + user.ShorthandId() + ` sunrise`); // follow whoever played the flute until sunrise
+            ratMobs[j].ChangeAlignment(user.GetAlignment()); // Set alignment to the flute player
+        }
+    }
+
+
+    return true;
+}
+

_datafiles/world/default/items/other-0/101-arcane_flute.yaml

@@ -0,0 +1,8 @@
+itemid: 101
+value: 10000
+hands: 0
+name: arcane flute
+namesimple: arcane flute
+description: A flute with faintly glowing markings all along it. Maybe you can <ansi fg="command">play</ansi> it.
+type: object
+subtype: generic

_datafiles/world/default/mobs/frostfang/10-ivar_froststeel.yaml

@@ -5,7 +5,7 @@ hostile: false
 groups: 
   - frostfang-npc
 idlecommands:
-  - 'say type `list` to see my wares'
+  - 'say type <ansi fg="command">list</ansi> to see my wares'
   - 'say If you''re looking to sell something, I may be interested... as long as it''s not too special or unique'
   - emote is counting his coins
   - emote watches you carefully

_datafiles/world/default/mobs/frostfang/11-brynja_snowdeal.yaml

@@ -5,7 +5,7 @@ hostile: false
 groups: 
   - frostfang-npc
 idlecommands:
-  - 'say type `list` to see my wares'
+  - 'say type <ansi fg="command">list</ansi> to see my wares'
   - 'say If you''re looking to sell something, I may be interested... as long as it''s not too special or unique'
   - emote shuffles some papers
   - emote is counting her coins

_datafiles/world/default/mobs/frostfang/5-armorer.yaml

@@ -5,7 +5,7 @@ hostile: false
 groups: 
   - frostfang-npc
 idlecommands:
-  - 'say type `list` to see my wares'
+  - 'say type <ansi fg="command">list</ansi> to see my wares'
   - 'say If you''re looking to sell something, I may be interested... as long as it''s not too special or unique'
   - emote shuffles some papers
   - emote is counting his coins

_datafiles/world/default/mobs/frostfang/50-moilyn_the_wizard.yaml

@@ -5,7 +5,7 @@ hostile: false
 groups: 
   - frostfang-npc
 idlecommands:
-  - 'say type `list` to see what magical objects I have for sale'
+  - 'say type <ansi fg="command">list</ansi> to see what magical objects I have for sale'
 activitylevel: 10
 character:
   name: moilyn the wizard

_datafiles/world/default/mobs/mystarion/46-herbalist.yaml

@@ -7,9 +7,8 @@ groups:
   - mystarion-npc
 activitylevel: 40
 idlecommands:
-  - say type `list` to see my wares
-  - say If you're looking to sell something, I may be interested... as long as it's
-    not too special or unique
+  - say type <ansi fg="command">list</ansi> to see my wares
+  - say If you're looking to sell something, I may be interested... as long as it's not too special or unique
   - emote is watching you
 combatcommands:
   - 'say How dare you attack the citizens of Mystarion! We do not forget!'

_datafiles/world/default/mobs/mystarion/47-brewer.yaml

@@ -7,9 +7,8 @@ groups:
   - mystarion-npc
 activitylevel: 40
 idlecommands:
-  - say type `list` to see my wares
-  - say If you're looking to sell something, I may be interested... as long as it's
-    not too special or unique
+  - say type <ansi fg="command">list</ansi> to see my wares
+  - say If you're looking to sell something, I may be interested... as long as it's not too special or unique
   - emote is watching you
 combatcommands:
   - 'say How dare you attack the citizens of Mystarion! We do not forget!'