Skip to content

Saving progress so far: PARTY object - script updates - ephemeral roo… #448

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Volte6 wants to merge 3 commits into
base: master
Choose a base branch
from
Draft

Saving progress so far: PARTY object - script updates - ephemeral roo… #448

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
eaf7810
Saving progress so far: PARTY object - script updates - ephemeral roo…
Volte6 Nov 26, 2025
4565d95
Updating docs
Volte6 Nov 26, 2025
fbd5734
Fixing scripts
Volte6 Nov 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 44 additions & 8 deletions _datafiles/guides/building/scripting/FUNCTIONS_ACTORS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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._

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down
8 changes: 6 additions & 2 deletions _datafiles/guides/building/scripting/FUNCTIONS_ITEMS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ ActorObjects are the basic object that represents Users and NPCs
- [ItemObject.SetTempData(key string, value any)](#itemobjectsettempdatakey-string-value-any)
- [ItemObject.GetTempData(key string) any](#itemobjectgettempdatakey-string-any)
- [ItemObject.Rename(newName string \[, displayNameOrStyle string\])](#itemobjectrenamenewname-string--displaynameorstyle-string)
- [ItemObject.ShorthandId() string](#itemobjectshorthandid-string)
- [ItemObject.Redescribe(newDescription string)](#itemobjectredescribenewdescription-string)

## [CreateItem(itemId int) ItemObject ](/internal/scripting/item_func.go)
Expand Down Expand Up @@ -74,10 +75,10 @@ Sets temporary data of any sort on the item. This data is not saved/loaded when
| Argument | Explanation |
| --- | --- |
| key | The name to store the data under. Also used to retrieve the data later. |
| vaue | The data to store. |
| value | The data to store. |

## [ItemObject.GetTempData(key string) any](/internal/scripting/item_func.go)
Sets temporary data of any sort on the item. This data is not saved/loaded when despawning.
Gets temporary data of any sort on the item. This data is not saved/loaded when despawning.

| Argument | Explanation |
| --- | --- |
Expand All @@ -92,6 +93,9 @@ Renames the item, also optionally provide a fancy name or colorpattern
| newName | The plaintext name. |
| displayNameOrStyle | A fancy name in ansi tags, color short tags, or a pattern like :flame |

## [ItemObject.ShorthandId() string](/internal/scripting/item_func.go)
Returns the shorthand identifier for the item.

## [ItemObject.Redescribe(newDescription string)](/internal/scripting/item_func.go)
Change the description for an item

Expand Down
198 changes: 198 additions & 0 deletions _datafiles/guides/building/scripting/FUNCTIONS_PARTY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 |
Loading
Loading