Miscellaneous content changes

_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:

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

@@ -7,5 +7,6 @@ function onEnter(user, room) {
     if ( !user.HasQuest("6-return") ) {
         room.RepeatSpawnItem(10, 30);
     }
-
+
+    return true;
 }

_datafiles/world/default/rooms/nowhere/-1.js

@@ -4,5 +4,5 @@ function onEnter(user, room) {
 
     user.SendText('  <ansi fg="red">To get started, type <ansi fg="command">look</ansi> or <ansi fg="command">start</ansi>.</ansi>');
     user.SendText('');
-
+    return true;
 }

_datafiles/world/default/rooms/tutorial/900.js

@@ -103,6 +103,8 @@ function onEnter(user, room) {
     teacherMob.Command('say I\'ll give you some tips to help you get started.', 1.0);
     teacherMob.Command('say In this area you\'ll learn the basics of inspecting your environment with the <ansi fg="command">look</ansi> command.', 1.0);
     teacherMob.Command('say type <ansi fg="command">look</ansi> and hit enter to see a description of the area you are in.', 1.0);
+
+    return true;
 }
 
 function onExit(user , room) {

_datafiles/world/default/rooms/tutorial/901.js

@@ -109,6 +109,7 @@ function onEnter(user, room) {
 
     teacherMob.Command('say Hi! I\'m here to teach you about inspecting your characters information.', 1.0);
     teacherMob.Command('say To get a detailed view of a LOT of information all at once, type <ansi fg="command">status</ansi> and hit enter.', 1.0);
+    return true;
 }
 
 function onExit(user , room) {
@@ -124,8 +125,6 @@ function onLoad(room) {
 }
 
 function getTeacher(room) {
-    var mobActor = null;
-
     var mobActor = room.GetMob(teacherMobId, true);
     mobActor.SetCharacterName(teacherName);
 

_datafiles/world/default/rooms/tutorial/902.js

@@ -106,6 +106,8 @@ function onEnter(user, room) {
     }
 
     teacherMob.Command('say Go ahead and equip that sharp stick you\'ve got. Type <ansi fg="command">equip stick</ansi>.', 1.0);
+
+    return true;
 }
 
 function onExit(user , room) {

_datafiles/world/default/rooms/tutorial/903.js

@@ -94,6 +94,7 @@ function onEnter(user, room) {
     teacherMob.Command('emote gestures to the <ansi fg="item">graduation cap</ansi> on the ground.', 3.0);
     teacherMob.Command('say type <ansi fg="command">get cap</ansi> to pick up the <ansi fg="item">graduation cap</ansi>.', 1.0);
 
+    return true;
 }
 
 function onExit(user , room) {

_datafiles/world/default/templates/admincommands/help/command.build.template

@@ -8,3 +8,23 @@ of it.
 Create a new empty room, and connect this room to it using the exit name 
 supplied. If a second exit name is supplied, the  room will be linked back 
 using that exit name.
+
+<ansi fg="yellow">Possible Exit Name Formats ("<ansi fg="command">east</ansi>" and "<ansi fg="command">cave</ansi>" used as examples):</ansi>
+
+  <ansi fg="command">cave</ansi>                  - An exit to somewhere that doesn't show up on the map.
+
+  <ansi fg="command">east</ansi>                  - Just an exist called east, that exits to the east 
+                          direction.
+  <ansi fg="command">east-x2</ansi> / <ansi fg="command">east-x3</ansi>     - Same as "east", just 2 or 3 spaces away.
+  <ansi fg="command">east-gap</ansi>              - Connects to the east, but does not show a 
+                          connection on the map.
+  <ansi fg="command">east-gap2</ansi> / <ansi fg="command">east-gap3</ansi> - Same as "east-gap" just 2 or 3 spaces away.
+
+  <ansi fg="command">cave:east</ansi>             - The exit will be called "cave", but the direction on 
+                          the map will be to the east.
+  <ansi fg="command">cave:east-x2</ansi>          - The pattern continues from above, just with a 
+                          freeform exit name.
+
+  So <ansi fg="command">build room cave:east-x2 out</ansi> would add a "<ansi fg="command">cave</ansi>" exit <ansi fg="command">2 spaces</ansi> to the <ansi fg="command">east</ansi>, 
+  and create a returning exit called "<ansi fg="command">out</ansi>"
+

_datafiles/world/default/templates/admincommands/help/command.teleport.template

@@ -9,3 +9,6 @@ Move through walls, across gaps, etc. to the first room found to the direction s
 <ansi fg="command">teleport [name]</ansi> - e.g. <ansi fg="command">teleport davey</ansi>
 Move to the room of a player matching the specified name.
 
+You can optionally target an online user instead of yourself by putting their name first.
+
+Example: <ansi fg="command">teleport [name] east</ansi>

_datafiles/world/empty/rooms/shadow_realm/-1.js

@@ -5,4 +5,5 @@ function onEnter(user, room) {
     user.SendText('  <ansi fg="red">To get started, type <ansi fg="command">look</ansi> or <ansi fg="command">start</ansi>.</ansi>');
     user.SendText('');
 
+    return true;
 }

_datafiles/world/empty/rooms/tutorial/900.js

@@ -108,6 +108,8 @@ function onEnter(user, room) {
     teacherMob.Command('say I\'ll give you some tips to help you get started.', 2.0);
     teacherMob.Command('say In this area you\'ll learn the basics of inspecting your environment with the <ansi fg="command">look</ansi> command.', 3.0);
     teacherMob.Command('say type <ansi fg="command">look</ansi> and hit enter to see a description of the area you are in.', 5.0);
+
+    return true;
 }
 
 function onExit(user , room) {

_datafiles/world/empty/rooms/tutorial/901.js

@@ -111,6 +111,8 @@ function onEnter(user, room) {
 
     teacherMob.Command('say Hi! I\'m here to teach you about inspecting your characters information.', 1.0);
     teacherMob.Command('say To get a detailed view of a LOT of information all at once, type <ansi fg="command">status</ansi> and hit enter.', 2.0);
+
+    return true;
 }
 
 

_datafiles/world/empty/rooms/tutorial/902.js

@@ -111,6 +111,8 @@ function onEnter(user, room) {
     }
 
     teacherMob.Command('say Go ahead and equip that sharp stick you\'ve got. Type <ansi fg="command">equip stick</ansi>.', 2.0);
+
+    return true;
 }
 
 function onExit(user , room) {

_datafiles/world/empty/rooms/tutorial/903.js

@@ -98,6 +98,7 @@ function onEnter(user, room) {
     teacherMob.Command('emote gestures to the <ansi fg="item">graduation cap</ansi> on the ground.', 3.0);
     teacherMob.Command('say type <ansi fg="command">get cap</ansi> to pick up the <ansi fg="item">graduation cap</ansi>.', 4.0);
 
+    return true;
 }
 
 function onExit(user , room) {