Saving progress so far: PARTY object - script updates - ephemeral rooms - procedural mazes

Author: Volte6

_datafiles/guides/building/scripting/FUNCTIONS_ACTORS.md

@@ -16,6 +16,7 @@ ActorObjects are the basic object that represents Users and NPCs
   - [ActorObject.GetLevel() int](#actorobjectgetlevel-int)
   - [ActorObject.GetStat(statName string) int](#actorobjectgetstatstatname-string-int)
   - [ActorObject.SetTempData(key string, value any)](#actorobjectsettempdatakey-string-value-any)
+  - [ActorObject.SetResetRoomId(roomId int)](#actorobjectsetresetroomidroomid-int)
   - [ActorObject.GetTempData(key string) any](#actorobjectgettempdatakey-string-any)
   - [ActorObject.SetMiscCharacterData(key string, value any)](#actorobjectsetmisccharacterdatakey-string-value-any)
   - [ActorObject.GetMiscCharacterData(key string) any](#actorobjectgetmisccharacterdatakey-string-any)
@@ -25,16 +26,19 @@ ActorObjects are the basic object that represents Users and NPCs
   - [ActorObject.GetRoomId() int](#actorobjectgetroomid-int)
   - [ActorObject.HasQuest(questId string) bool](#actorobjecthasquestquestid-string-bool)
   - [ActorObject.GiveQuest(questId string)](#actorobjectgivequestquestid-string)
-  - [ActorObject.GetPartyMembers() \[\]Actor](#actorobjectgetpartymembers-actor)
+  - [ActorObject.GetParty(\[excludeSelf bool\])](#actorobjectgetpartyexcludeself-bool)
+  - [ActorObject.GetPartyPresent(\[excludeSelf bool\])](#actorobjectgetpartypresentexcludeself-bool)
+  - [ActorObject.GetPartyMissing()](#actorobjectgetpartymissing)
   - [ActorObject.AddGold(amt int \[, bankAmt int\])](#actorobjectaddgoldamt-int--bankamt-int)
   - [ActorObject.AddHealth(amt int) int](#actorobjectaddhealthamt-int-int)
+  - [ActorObject.AddMana(amt int) int](#actorobjectaddmanaamt-int-int)
   - [ActorObject.Sleep(seconds int)](#actorobjectsleepseconds-int)
   - [ActorObject.Command(cmd string \[, waitTurns int\])](#actorobjectcommandcmd-string--waitturns-int)
   - [ActorObject.CommandFlagged(cmd string, flag int \[, waitTurns int\])](#actorobjectcommandflaggedcmd-string-flag-int--waitturns-int)
   - [ActorObject.IsTameable() bool](#actorobjectistameable-bool)
   - [ActorObject.TrainSkill(skillName string, skillLevel int)](#actorobjecttrainskillskillname-string-skilllevel-int)
   - [ActorObject.GetSkillLevel(skillName string)](#actorobjectgetskilllevelskillname-string)
-  - [ActorObject.MoveRoom(destRoomId int \[, leaveCharmedMobsBehind bool\] )](#actorobjectmoveroomdestroomid-int--leavecharmedmobsbehind-bool-)
+  - [ActorObject.MoveRoom(destRoomId int )](#actorobjectmoveroomdestroomid-int-)
   - [ActorObject.UpdateItem(itemId ItemObject)](#actorobjectupdateitemitemid-itemobject)
   - [ActorObject.GiveItem(itemId ItemObject)](#actorobjectgiveitemitemid-itemobject)
   - [ActorObject.TakeItem(itemId ItemObject)](#actorobjecttakeitemitemid-itemobject)
@@ -118,7 +122,7 @@ Retrieves a ActorObject for a given mobInstanceId.
 | 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.˚
+Returns the userId of the ActorObject.
 
 _Note: Only useful for User ActorObjects - Returns zero otherwise._
 
@@ -173,6 +177,16 @@ _Note: This is useful for saving/retrieving data that an ActorObject can carry a
 | key | A unique identifier for the data. |
 | value | What you will be saving. If null, frees from memory. |
 
+## [ActorObject.SetResetRoomId(roomId int)](/internal/scripting/actor_func.go)
+Sets the "Reset Room Id" a player will be sent to if they log out.
+
+_Note: This is only useful if the player is being sent to an ephemeral chunk._
+
+|  Argument | Explanation |
+| --- | --- |
+| roomId | The RoomId the player should be sent to. |
+
+
 ## [ActorObject.GetTempData(key string) any](/internal/scripting/actor_func.go)
 Gets temporary data for the ActorObject.
 
@@ -235,14 +249,28 @@ Get whether a ActorObject has a quest/progress.
 | questId | The quest identifier string to check, such as `3-start`. |
 
 ## [ActorObject.GiveQuest(questId string)](/internal/scripting/actor_func.go)
-Grants a quest or progress on a quest to a ActorObject. If they are in a party, grants to the party members as well.
+Grants a quest or progress on a quest to a ActorObject. 
 
 |  Argument | Explanation |
 | --- | --- |
 | questId | The quest identifier string to give, such as `3-start`. |
 
-## [ActorObject.GetPartyMembers() []Actor](/internal/scripting/actor_func.go)
-Returns a list of actors in the party, both players and mobs.
+## [ActorObject.GetParty([excludeSelf bool])](/internal/scripting/actor_func.go)
+Returns a Party object that operates on the entire party and charmed mobs.
+
+|  Argument | Explanation |
+| --- | --- |
+| excludeSelf | If true, excludes the actor from the operating list. |
+
+## [ActorObject.GetPartyPresent([excludeSelf bool])](/internal/scripting/actor_func.go)
+Returns a Party object that operates on the party members and charmed mobs in the same room.
+
+|  Argument | Explanation |
+| --- | --- |
+| excludeSelf | If true, excludes the actor from the operating list. |
+
+## [ActorObject.GetPartyMissing()](/internal/scripting/actor_func.go)
+Returns a Party object that operates on the party members and charmed mobs missing from the room.
 
 ## [ActorObject.AddGold(amt int [, bankAmt int])](/internal/scripting/actor_func.go)
 Update how much gold an ActorObject has
@@ -259,6 +287,13 @@ Update how much health an ActorObject has, and returns the actual amount their h
 | --- | --- |
 | amt | A positive or negative amount of health to alter the actors health by. |
 
+## [ActorObject.AddMana(amt int) int](/internal/scripting/actor_func.go)
+Update how much mana an ActorObject has, and returns the actual amount their mana changed.
+
+|  Argument | Explanation |
+| --- | --- |
+| amt | A positive or negative amount of mana to alter the actors mana by. |
+
 
 ## [ActorObject.Sleep(seconds int)](/internal/scripting/actor_func.go)
 Force a mob to wait this many seconds before executing any additional behaviors
@@ -309,13 +344,14 @@ Returns the current skil level for the skillName, or zero if none.
 | skillName | The name of the skill to train, such as `map` or `backstab`. |
 
 
-## [ActorObject.MoveRoom(destRoomId int [, leaveCharmedMobsBehind bool] )](/internal/scripting/actor_func.go)
+## [ActorObject.MoveRoom(destRoomId int )](/internal/scripting/actor_func.go)
 Quietly moves an ActorObject to a new room
 
 |  Argument | Explanation |
 | --- | --- |
 | destRoomId | The room id to move them to. |
-| leaveCharmedMobsBehind | If true, does not also move charmed mobs with the user. |
+
+
 
 ## [ActorObject.UpdateItem(itemId ItemObject)](/internal/scripting/actor_func.go)
 Accepts an ItemObject to update in the players backpack. If the item does not already exist in the players backpack, it is ignored.

_datafiles/guides/building/scripting/FUNCTIONS_PARTY.md

@@ -0,0 +1,198 @@
+# PartyObject
+
+PartyObjects represent collections of actors (users and NPCs) that are grouped together. They provide convenient methods to perform operations on multiple actors at once.
+
+- [PartyObject](#partyobject)
+  - [PartyObject.GetMembers() \[\]ActorObject](#partyobjectgetmembers-actorobject)
+  - [PartyObject.SendText(msg string)](#partyobjectsendtextmsg-string)
+  - [PartyObject.SetResetRoomId(roomId int)](#partyobjectsetresetroomidroomid-int)
+  - [PartyObject.GiveQuest(questId string)](#partyobjectgivequestquestid-string)
+  - [PartyObject.AddGold(amt int \[, bankAmt int\])](#partyobjectaddgoldamt-int--bankamt-int)
+  - [PartyObject.AddHealth(amt int)](#partyobjectaddhealthamt-int)
+  - [PartyObject.AddMana(amt int)](#partyobjectaddmanaamt-int)
+  - [PartyObject.Command(cmd string \[, waitSeconds float\])](#partyobjectcommandcmd-string--waitseconds-float)
+  - [PartyObject.TrainSkill(skillName string, skillLevel int)](#partyobjecttrainskillskillname-string-skilllevel-int)
+  - [PartyObject.MoveRoom(destRoomId int)](#partyobjectmoveroomdestroomid-int)
+  - [PartyObject.AddEventLog(category string, message string)](#partyobjectaddeventlogcategory-string-message-string)
+  - [PartyObject.GiveBuff(buffId int, source string)](#partyobjectgivebuffbuffid-int-source-string)
+  - [PartyObject.CancelBuffWithFlag(buffFlag string)](#partyobjectcancelbuffwithflagbuffflag-string)
+  - [PartyObject.RemoveBuff(buffId int)](#partyobjectremovebuffbuffid-int)
+  - [PartyObject.ChangeAlignment(alignmentChange int)](#partyobjectchangealignmentalignmentchange-int)
+  - [PartyObject.LearnSpell(spellId string)](#partyobjectlearnspellspellid-string)
+  - [PartyObject.SetHealth(amt int)](#partyobjectsethealthamt-int)
+  - [PartyObject.SetAdjective(adj string, addIt bool)](#partyobjectsetadjectiveadj-string-addit-bool)
+  - [PartyObject.GiveTrainingPoints(ct int)](#partyobjectgivetrainingpointsct-int)
+  - [PartyObject.GiveStatPoints(ct int)](#partyobjectgivestatpointsct-int)
+  - [PartyObject.GiveExtraLife()](#partyobjectgiveextralife)
+  - [PartyObject.GrantXP(xpAmt int, reason string)](#partyobjectgrantxpxpamt-int-reason-string)
+  - [PartyObject.TimerSet(name string, period string)](#partyobjecttimersetname-string-period-string)
+
+
+
+
+## [PartyObject.GetMembers() []ActorObject](/internal/scripting/party_func.go)
+Returns an array of all ActorObjects in the party based on the party configuration.
+
+_Note: This includes both party members and their charmed creatures, filtered by presence/absence based on how the party object was created._
+
+## [PartyObject.SendText(msg string)](/internal/scripting/party_func.go)
+Sends a message to all members of the party.
+
+|  Argument | Explanation |
+| --- | --- |
+| msg | the message to send to all party members |
+
+## [PartyObject.SetResetRoomId(roomId int)](/internal/scripting/party_func.go)
+Sets the "Reset Room Id" for all user party members (where they will be sent if they log out).
+
+_Note: Only affects user party members, not NPCs. This is only useful if players are being sent to ephemeral chunks._
+
+|  Argument | Explanation |
+| --- | --- |
+| roomId | The RoomId all party members should be sent to |
+
+## [PartyObject.GiveQuest(questId string)](/internal/scripting/party_func.go)
+Grants a quest or progress on a quest to all party members.
+
+|  Argument | Explanation |
+| --- | --- |
+| questId | The quest identifier string to give, such as `3-start` |
+
+## [PartyObject.AddGold(amt int [, bankAmt int])](/internal/scripting/party_func.go)
+Updates how much gold all party members have.
+
+|  Argument | Explanation |
+| --- | --- |
+| amt | A positive or negative amount of gold to alter each party member's gold by |
+| bankAmt (optional) | A positive or negative amount of gold to alter each party member's bank gold by |
+
+## [PartyObject.AddHealth(amt int)](/internal/scripting/party_func.go)
+Updates how much health all party members have.
+
+|  Argument | Explanation |
+| --- | --- |
+| amt | A positive or negative amount of health to alter each party member's health by |
+
+## [PartyObject.AddMana(amt int)](/internal/scripting/party_func.go)
+Updates how much mana all party members have.
+
+|  Argument | Explanation |
+| --- | --- |
+| amt | A positive or negative amount of mana to alter each party member's mana by |
+
+## [PartyObject.Command(cmd string [, waitSeconds float])](/internal/scripting/party_func.go)
+Forces all party members to execute a command as if they entered it.
+
+_Note: Don't underestimate the power of this function! Complex and interesting behaviors or interactions can emerge from using it._
+
+|  Argument | Explanation |
+| --- | --- |
+| cmd | The command to execute such as `look west` or `say goodbye` |
+| waitSeconds (optional) | The number of seconds to wait before executing the command |
+
+## [PartyObject.TrainSkill(skillName string, skillLevel int)](/internal/scripting/party_func.go)
+Sets a skill level for all party members, if it's greater than what they already have.
+
+|  Argument | Explanation |
+| --- | --- |
+| skillName | The name of the skill to train, such as `map` or `backstab` |
+| skillLevel | The skill level to train to |
+
+## [PartyObject.MoveRoom(destRoomId int)](/internal/scripting/party_func.go)
+Quietly moves all party members to a new room.
+
+|  Argument | Explanation |
+| --- | --- |
+| destRoomId | The room id to move them all to |
+
+## [PartyObject.AddEventLog(category string, message string)](/internal/scripting/party_func.go)
+Adds a line to all party members' Event Log (`history`).
+
+|  Argument | Explanation |
+| --- | --- |
+| category | A short single word category |
+| message | A single line describing the event |
+
+## [PartyObject.GiveBuff(buffId int, source string)](/internal/scripting/party_func.go)
+Grants all party members a Buff.
+
+|  Argument | Explanation |
+| --- | --- |
+| buffId | The ID of the buff to give them |
+| source | The source of the buff, "item", "spell", "trap", "curse", etc. or empty |
+
+## [PartyObject.CancelBuffWithFlag(buffFlag string)](/internal/scripting/party_func.go)
+Cancels any buffs that have the flag provided for all party members.
+
+|  Argument | Explanation |
+| --- | --- |
+| buffFlag | The buff flag to check [see buffspec.go](../buffs/buffspec.go) |
+
+## [PartyObject.RemoveBuff(buffId int)](/internal/scripting/party_func.go)
+Remove a buff from all party members without triggering onEnd.
+
+|  Argument | Explanation |
+| --- | --- |
+| buffId | The ID of the buff to remove |
+
+## [PartyObject.ChangeAlignment(alignmentChange int)](/internal/scripting/party_func.go)
+Updates the alignment of all party members by a relative amount. Caps result at -100 to 100.
+
+|  Argument | Explanation |
+| --- | --- |
+| alignmentChange | The alignment adjustment, from -200 to 200 |
+
+## [PartyObject.LearnSpell(spellId string)](/internal/scripting/party_func.go)
+Adds the spell to all party members' spellbooks.
+
+|  Argument | Explanation |
+| --- | --- |
+| spellId | The ID of the spell |
+
+## [PartyObject.SetHealth(amt int)](/internal/scripting/party_func.go)
+Sets all party members' health to a specific amount. If this exceeds their maximum health, sets to their maximum health.
+
+|  Argument | Explanation |
+| --- | --- |
+| amt | number of hitpoints to set them to |
+
+## [PartyObject.SetAdjective(adj string, addIt bool)](/internal/scripting/party_func.go)
+Adds or removes a specific text adjective to all party members' names.
+
+|  Argument | Explanation |
+| --- | --- |
+| adj | Adjective such as "sleeping", "crying" or "busy" |
+| addIt | `true` to add it. `false` to remove it |
+
+## [PartyObject.GiveTrainingPoints(ct int)](/internal/scripting/party_func.go)
+Increases training points for all party members.
+
+|  Argument | Explanation |
+| --- | --- |
+| ct | How many training points to give |
+
+## [PartyObject.GiveStatPoints(ct int)](/internal/scripting/party_func.go)
+Increases stat points for all party members.
+
+|  Argument | Explanation |
+| --- | --- |
+| ct | How many stat points to give |
+
+## [PartyObject.GiveExtraLife()](/internal/scripting/party_func.go)
+Increases extra lives by 1 for all party members.
+
+## [PartyObject.GrantXP(xpAmt int, reason string)](/internal/scripting/party_func.go)
+Gives experience points to all party members.
+
+|  Argument | Explanation |
+| --- | --- |
+| xpAmt | How much experience to grant |
+| reason | Short reasons such as "combat", "trash cleanup" |
+
+## [PartyObject.TimerSet(name string, period string)](/internal/scripting/party_func.go)
+Starts a new Round timer for all party members.
+
+|  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 |

_datafiles/guides/building/scripting/README.md

@@ -21,6 +21,8 @@ See [Spell Scripting](SCRIPTING_SPELLS.md)
 
 [ActorObject Functions](FUNCTIONS_ACTORS.md) - Functions that query or alter user/mob data.
 
+[ActorObject Functions](FUNCTIONS_PARTY.md) - Functions that operate on the whole party.
+
 [RoomObject Functions](FUNCTIONS_ROOMS.md) - Functions that query or alter room data.
 
 [ItemObject Functions](FUNCTIONS_ITEMS.md) - Functions that query or alter item data.

_datafiles/sample-scripts/mobs/item-gold-quest.js

@@ -55,7 +55,7 @@ function onAsk(mob, room, eventDetails) {
             //
             // Give them the start quest id
             //
-            user.GiveQuest(QUEST_START_ID);
+            user.GetParty().GiveQuest(QUEST_START_ID);
 
         }
 
@@ -129,7 +129,7 @@ function onGive(mob, room, eventDetails) {
         //
         // Give them the next step of the quest
         //
-        user.GiveQuest(QUEST_NEXT_STEP_ID);
+        user.GetParty().GiveQuest(QUEST_NEXT_STEP_ID);
 
         return true;
     }
@@ -179,7 +179,7 @@ function onGive(mob, room, eventDetails) {
             //
             // They have now completed the entire quest, all steps are complete.
             //
-            user.GiveQuest(QUEST_END_ID);
+            user.GetParty().GiveQuest(QUEST_END_ID);
 
             return true;
         }

_datafiles/world/default/mobs/frostfang/scripts/2-guard-hungry.js

@@ -23,7 +23,7 @@ function onAsk(mob, room, eventDetails) {
             mob.Command("say I forgot my lunch today, and I'm so hungry.");
             mob.Command("say Do you think you could find a cheese sandwich for me?");
 
-            user.GiveQuest("4-start");
+            user.GetParty().GiveQuest("4-start");
 
         } else if ( user.HasQuest("4-end") ) {
             mob.Command("sayto @" + String(user.UserId()) + " Thanks, but you've done enough. Too much, really.");
@@ -70,7 +70,7 @@ function onGive(mob, room, eventDetails) {
 
     if ( user.HasQuest("4-start") ) {
 
-        user.GiveQuest("4-end");
+        user.GetParty().GiveQuest("4-end");
         mob.Command("say Thanks! I can get on with my day now.");
         mob.Command("eat !"+String(eventDetails.item.ItemId) );
 

_datafiles/world/default/mobs/frostfang/scripts/26-frostfang_citizen-locketsadness.js

@@ -30,7 +30,7 @@ function onAsk(mob, room, eventDetails) {
             mob.Command("emote sighs deeply.");
             mob.Command("say I lost my locket. I think it was when I was gardening.");
 
-            user.GiveQuest("1-start");
+            user.GetParty().GiveQuest("1-start");
 
             return true;
         }
@@ -78,7 +78,7 @@ function onGive(mob, room, eventDetails) {
                 mob.Command("give !20033 @" + String(eventDetails.sourceId)); // Give it to the player using shorthand
             }
 
-            user.GiveQuest("1-end");
+            user.GetParty().GiveQuest("1-end");
 
             return true;
 

_datafiles/world/default/mobs/frostfang/scripts/26-frostfang_citizen-rattrap.js

@@ -19,7 +19,7 @@ function onAsk(mob, room, eventDetails) {
 
             mob.Command("say Thanks for picking it up!");
 
-            user.GiveQuest("7-gettrap");
+            user.GetParty().GiveQuest("7-gettrap");
 
             return true;
         }