Miscellaneous content changes (#381)

# Description

This adds scripting improvements, documentation, and additional functionality in general.

It also adds a `jail` in Frostfang, an ephemeral room that locks players in for 1 hour (in game time) before letting them out. Later the jail will be used by guards to throw outlaw characters into jail (if caught).

## Changes

- `teleport` admin command can target other players now.
- Frostfang jail added, locks players in for 1 hour in game time if they get sent there.
- Added scripting documentation and more scripting commands:
  - `ActorObject.TimerSet` / `ActorObject. TimerExpired ` / `ActorObject. TimerExists`
  -  `RoomObject.IsEphemeral` / `RoomObject.RoomIdSource()` / `RoomObject.isLocked()`
- Documented `onIdle()` room event.
- `onEnter()` room event can return false to abort showing the Room description.
- Updated some scripts to use new changes.
- Characters can have timers added, useful for scripting some stuff.
- Improved admin build command, adjusted optional formats for exits, added unit tests.

Author: Volte6

_datafiles/guides/building/scripting/FUNCTIONS_ACTORS.md

@@ -84,6 +84,9 @@ ActorObjects are the basic object that represents Users and NPCs
   - [ActorObject.IsHome() bool](#actorobjectishome-bool)
   - [ActorObject.Pathing() bool](#actorobjectpathing-bool)
   - [ActorObject.PathingAtWaypoint() bool](#actorobjectpathingatwaypoint-bool)
+  - [ActorObject.TimerSet(name string, period string)](#actorobjecttimersetname-string-period-string)
+  - [ActorObject.TimerExpired(name string) bool](#actorobjecttimerexpiredname-string-bool)
+  - [ActorObject.TimerExists(name string) bool](#actorobjecttimerexistsname-string-bool)
 
 
 
@@ -566,3 +569,20 @@ returns the total specific statmod from worn items and buffs
 
 ## [ActorObject.PathingAtWaypoint() bool](/internal/scripting/actor_func.go)
 (mobs only) Returns true if actor is pathing and at a waypoint.
+
+
+## [ActorObject.TimerSet(name string, period string)](/internal/scripting/actor_func.go)
+Starts a new Round timer
+
+|  Argument | Explanation |
+| --- | --- |
+| name | A string identifier. Reusing names will overwrite previously assigned names. |
+| period | How long until the timer expires. `1 real hour`, `1 hour`, etc. |
+
+## [ActorObject.TimerExpired(name string) bool](/internal/scripting/actor_func.go)
+Returns true if the specified timer has expired or doesn't exist.
+
+## [ActorObject.TimerExists(name string) bool](/internal/scripting/actor_func.go)
+Returns true if the specified timer exists. 
+Set timers always exist until they are checked for expiration with `TimerExpired(name string)`
+

_datafiles/guides/building/scripting/FUNCTIONS_ROOMS.md

@@ -28,8 +28,11 @@
   - [RoomObject.HasMutator(mutName string) bool](#roomobjecthasmutatormutname-string-bool)
   - [RoomObject.AddMutator(mutName string)](#roomobjectaddmutatormutname-string)
   - [RoomObject.RemoveMutator(mutName string)](#roomobjectremovemutatormutname-string)
+  - [RoomObject.IsEphemeral() bool](#roomobjectisephemeral-bool)
+  - [RoomObject.RoomIdSource() int](#roomobjectroomidsource-int)
   - [RoomObject.RepeatSpawnItem(itemId int, roundInterval int \[, containerName\]](#roomobjectrepeatspawnitemitemid-int-roundinterval-int--containername)
   - [RoomObject.SetLocked(exitName string, lockIt bool)](#roomobjectsetlockedexitname-string-lockit-bool)
+  - [RoomObject.IsLocked(exitName string) bool](#roomobjectislockedexitname-string-bool)
 
 ## [CreateInstancesFromRoomIds(RoomIds [int, int...]) Object ](/internal/scripting/room_func.go)
 Returns an Object with key/value pairs of `ProvidedRoomId`=>`NewRoomId`
@@ -244,6 +247,18 @@ _Note: This only expires it. It may be a mutator that respawns, in which case th
 | --- | --- |
 | mutName | the MutatorId of the mutator. |
 
+## [RoomObject.IsEphemeral() bool](/internal/scripting/room_func.go)
+Returns true if the room is an Ephemeral Copy of a room.
+
+_Note: This only expires it. It may be a mutator that respawns, in which case this doens't really completely remove it._
+
+|  Argument | Explanation |
+| --- | --- |
+| mutName | the MutatorId of the mutator. |
+
+## [RoomObject.RoomIdSource() int](/internal/scripting/room_func.go)
+Returns the source RoomId if this room is an ephemeral copy, otherwise just the normal RoomId
+
 
 ## [RoomObject.RepeatSpawnItem(itemId int, roundInterval int [, containerName]](/internal/scripting/room_func.go)
 Removes a temporary exit
@@ -264,3 +279,5 @@ Sets an exit to locked or not (If it has a lock)
 | exitName | The exitname to lock/unlock |
 | lockIt | if true, sets it to locked. Otherwise, unlocks it. |
 
+## [RoomObject.IsLocked(exitName string) bool](/internal/scripting/room_func.go)
+Returns true if exit is locked, false if unlocked or has no lock.

_datafiles/guides/building/scripting/README.md

@@ -29,6 +29,15 @@ See [Spell Scripting](SCRIPTING_SPELLS.md)
 
 [Messaging Functions](FUNCTIONS_MESSAGING.md) - Helper and info functions.
 
+# Time Periods
+
+Whenever you need to specific a "period" of time, it takes the following string format:
+
+- Should be in the format of: `{num} {unit}` or `{num} real {unit}`
+- Unit can be: `rounds`, `hours`, `days`, `weeks`, `months`, `years`
+- Default is in-game time, not real time. 
+- **To use real time, use the following format:** `{num} real {unit}` - Example: `1 real day`
+
 # Special symbols in user or mob commands:
 
 There are some special prefixes that can help target more specifically than just a name.

_datafiles/guides/building/scripting/SCRIPTING_ROOMS.md

@@ -38,6 +38,8 @@ function onEnter(user ActorObject, room RoomObject) {
 ```
 
 `onEnter()` is called when a player enters the room.
+Return `false` to suppress showing the room description on arrival.
+
 
 |  Argument | Explanation |
 | --- | --- |
@@ -60,6 +62,20 @@ function onExit(user ActorObject, room RoomObject) {
 
 ---
 
+```
+function onIdle(room RoomObject) {
+}
+```
+
+`onIdle()` is called when a round passes in a room that has players in it. 
+Returning true prevents generic idle actions from taking place.
+
+|  Argument | Explanation |
+| --- | --- |
+| room | [RoomObject](FUNCTIONS_ROOMS.md) |
+
+---
+
 ```
 function onCommand(cmd string, rest string, user ActorObject, room RoomObject) {
 }

_datafiles/world/default/rooms/frost_lake/828.js

@@ -11,7 +11,7 @@ function onEnter(user, room) {
 
     nextSpawnRound = lastSpawnRound + UtilGetSecondsToRounds(30);
     if ( lastSpawnRound > 0 && roundNow < nextSpawnRound ) {
-        return;
+        return true;
     }
 
     allItems = room.GetItems();
@@ -20,14 +20,16 @@ function onEnter(user, room) {
     for ( i=0; i<allItems.length; i++ ) {
         if ( allItems[i].ItemId() == 10016 ) {
             oarExists = true;
-            return;
+            return true;
         }
     }
 
     if ( !oarExists ) {
         room.SpawnItem(10016, false);
         lastSpawnRound = roundNow;
     }
+
+    return true;
 }
 
 

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

@@ -1,6 +1,18 @@
 
 mapSignData = "";
 
+function onEnter(user, room) {
+
+    // Special case for if the player left the game while in jail.
+    // The ephemeral room gets destroyed and the player gets sent back to TS
+    // From here we can put them back in jail.
+    if ( user.TimerExists("jail") ) {
+        user.MoveRoom(1003);
+        return false;
+    }
+    return true;
+}
+
 // Generic Command Handler
 function onCommand(cmd, rest, user, room) {
 

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

@@ -0,0 +1,17 @@
+roomid: 1002
+zone: Frostfang
+title: Jail
+description: The jail adjoins the Soldiers Barracks like a grim shadow, its cold stone
+  walls damp with the weight of confinement. Dim torchlight flickers along the corridor,
+  casting long, uneasy shadows across iron-barred windows and heavy oak doors reinforced
+  with blackened steel. At the far end of the room, a thick iron door marked CELLS
+  stands locked and unmoving, its rusted bolts and sturdy latch making it clearbno
+  one passes through without command.
+biome: city
+exits:
+  west:
+    roomid: 270
+nouns:
+  CELLS: :cells
+  cell: :cells
+  cells: The cells are inpenetrable. Only a guard can gain access.

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

@@ -0,0 +1,45 @@
+
+const JAIL_TIME = "1 hour";
+
+function onEnter(user, room) {
+
+    if ( !room.IsEphemeral() ) {
+
+        var newRoomIds = CreateInstancesFromRoomIds( [room.RoomId()] );
+
+        if ( newRoomIds[room.RoomId()] ) {
+            user.MoveRoom(newRoomIds[room.RoomId()]);
+            return false;
+        } 
+
+    }
+    
+    user.TimerSet("jail", JAIL_TIME);
+
+    room.SendText("");
+    room.SendText("<ansi fg=\"red-bold\">********************************************************************************</ansi>");
+    room.SendText("You hear a loud <ansi fg=\"red-bold\">!!!CLANK!!!</ansi>, and can immediately tell...");
+    room.SendText("The cell door is LOCKED from the other side!");
+    room.SendText('You hear someone shout, <ansi fg="saytext-mob">"Maybe an hour in a cell will cool you off!"</ansi>');
+    room.SendText("<ansi fg=\"red-bold\">********************************************************************************</ansi>");
+    room.SendText("");
+
+    user.Command("look", 1);
+
+    return false;
+}
+
+function onIdle(room) {
+
+    if ( room.IsLocked("cell door") ) {
+        var playersInRoom = room.GetPlayers();
+        for( var i in playersInRoom ) {
+            if ( playersInRoom[i].TimerExpired("jail") ) {
+                room.SendText("You hear a loud CLANK, and the cell door is UNLOCKED from the other side.");
+                room.SetLocked("cell door", false);
+            }
+        }
+    }
+
+    return true;
+}

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

@@ -0,0 +1,16 @@
+roomid: 1003
+zone: Frostfang
+title: Inside a Jail Cell
+description: The cell is narrow and barren, carved from the same unforgiving stone
+  as the rest of the jail. A single slit in the wall lets in a pale shaft of light,
+  barely enough to see the rust-streaked walls and the straw-stuffed pallet shoved
+  into the corner. The air is thick with mildew and the lingering stench of past occupants.
+  Iron shackles hang limply from the wall, their presence more threatening than their
+  current use. Every sound echoes with eerie claritybdrips of water, distant footsteps,
+  or worse, silence.
+biome: city
+exits:
+  cell door:
+    roomid: 1002
+    lock:
+      difficulty: 32

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

@@ -8,6 +8,9 @@ description: The Soldiers Barracks in Frostfang is a bastion of military discipl
   area.
 biome: city
 exits:
+  jail:
+    roomid: 1002
+    mapdirection: east
   north:
     roomid: 829
   northeast: