[Server] Document script functions, part 1

apps/openmw-mp/Script/Functions/Books.hpp

@@ -16,15 +16,52 @@ class BookFunctions
 {
 public:
 
+    /**
+    * \brief Clear the last recorded book changes for a player.
+    *
+    * This is used to initialize the sending of new PlayerBook packets.
+    *
+    * \param pid The player ID whose book changes should be used.
+    * \return void
+    */
     static void InitializeBookChanges(unsigned short pid) noexcept;
 
+    /**
+    * \brief Get the number of indexes in a player's latest book changes.
+    *
+    * \param pid The player ID whose book changes should be used.
+    * \return The number of indexes.
+    */
     static unsigned int GetBookChangesSize(unsigned short pid) noexcept;
 
+    /**
+    * \brief Add a new book to the book changes for a player.
+    *
+    * \param pid The player ID whose book changes should be used.
+    * \param topicId The bookId of the book.
+    * \return void
+    */
     static void AddBook(unsigned short pid, const char* bookId) noexcept;
 
+    /**
+    * \brief Get the bookId at a certain index in a player's latest book changes.
+    *
+    * \param pid The player ID whose book changes should be used.
+    * \param i The index of the book.
+    * \return The bookId.
+    */
     static const char *GetBookId(unsigned short pid, unsigned int i) noexcept;
 
+    /**
+    * \brief Send a PlayerBook packet with a player's recorded book changes.
+    *
+    * \param pid The player ID whose book changes should be used.
+    * \param toOthers Whether this packet should be sent only to other players or
+    *                 only to the player it is about.
+    * \return void
+    */
     static void SendBookChanges(unsigned short pid, bool toOthers = false) noexcept;
+
 private:
 
 };

apps/openmw-mp/Script/Functions/Dialogue.hpp

@@ -16,14 +16,50 @@ class DialogueFunctions
 {
 public:
 
+    /**
+    * \brief Clear the last recorded topic changes for a player.
+    *
+    * This is used to initialize the sending of new PlayerTopic packets.
+    *
+    * \param pid The player ID whose topic changes should be used.
+    * \return void
+    */
     static void InitializeTopicChanges(unsigned short pid) noexcept;
 
+    /**
+    * \brief Get the number of indexes in a player's latest topic changes.
+    *
+    * \param pid The player ID whose topic changes should be used.
+    * \return The number of indexes.
+    */
     static unsigned int GetTopicChangesSize(unsigned short pid) noexcept;
 
+    /**
+    * \brief Add a new topic to the topic changes for a player.
+    *
+    * \param pid The player ID whose topic changes should be used.
+    * \param topicId The topicId of the topic.
+    * \return void
+    */
     static void AddTopic(unsigned short pid, const char* topicId) noexcept;
 
+    /**
+    * \brief Get the topicId at a certain index in a player's latest topic changes.
+    *
+    * \param pid The player ID whose topic changes should be used.
+    * \param i The index of the topic.
+    * \return The topicId.
+    */
     static const char *GetTopicId(unsigned short pid, unsigned int i) noexcept;
 
+    /**
+    * \brief Send a PlayerTopic packet with a player's recorded topic changes.
+    *
+    * \param pid The player ID whose topic changes should be used.
+    * \param toOthers Whether this packet should be sent only to other players or
+    *                 only to the player it is about.
+    * \return void
+    */
     static void SendTopicChanges(unsigned short pid, bool toOthers = false) noexcept;
 private:
 

apps/openmw-mp/Script/Functions/Factions.cpp

@@ -52,7 +52,7 @@ int FactionFunctions::GetFactionRank(unsigned short pid, unsigned int i) noexcep
     return player->factionChanges.factions.at(i).rank;
 }
 
-bool FactionFunctions::GetFactionExpelledState(unsigned short pid, unsigned int i) noexcept
+bool FactionFunctions::GetFactionExpulsionState(unsigned short pid, unsigned int i) noexcept
 {
     Player *player;
     GET_PLAYER(pid, player, false);
@@ -86,9 +86,9 @@ void FactionFunctions::SetFactionRank(unsigned int rank) noexcept
     tempFaction.rank = rank;
 }
 
-void FactionFunctions::SetFactionExpulsionState(bool isExpelled) noexcept
+void FactionFunctions::SetFactionExpulsionState(bool expulsionState) noexcept
 {
-    tempFaction.isExpelled = isExpelled;
+    tempFaction.isExpelled = expulsionState;
 }
 
 void FactionFunctions::SetFactionReputation(int reputation) noexcept

apps/openmw-mp/Script/Functions/Factions.hpp

@@ -9,7 +9,7 @@
     \
     {"GetFactionId",             FactionFunctions::GetFactionId},\
     {"GetFactionRank",           FactionFunctions::GetFactionRank},\
-    {"GetFactionExpelledState",  FactionFunctions::GetFactionExpelledState},\
+    {"GetFactionExpulsionState", FactionFunctions::GetFactionExpulsionState},\
     {"GetFactionReputation",     FactionFunctions::GetFactionReputation},\
     \
     {"SetFactionChangesAction",  FactionFunctions::SetFactionChangesAction},\
@@ -26,24 +26,125 @@ class FactionFunctions
 {
 public:
 
+    /**
+    * \brief Clear the last recorded faction changes for a player.
+    *
+    * This is used to initialize the sending of new PlayerFaction packets.
+    *
+    * \param pid The player ID whose faction changes should be used.
+    * \return void
+    */
     static void InitializeFactionChanges(unsigned short pid) noexcept;
 
+    /**
+    * \brief Get the number of indexes in a player's latest faction changes.
+    *
+    * \param pid The player ID whose faction changes should be used.
+    * \return The number of indexes.
+    */
     static unsigned int GetFactionChangesSize(unsigned short pid) noexcept;
+
+    /**
+    * \brief Get the action type used in a player's latest faction changes.
+    *
+    * \param pid The player ID whose faction changes should be used.
+    * \return The action type (0 for RANK, 1 for EXPULSION, 2 for REPUTATION).
+    */
     static unsigned char GetFactionChangesAction(unsigned short pid) noexcept;
 
+    /**
+    * \brief Get the factionId at a certain index in a player's latest faction changes.
+    *
+    * \param pid The player ID whose faction changes should be used.
+    * \param i The index of the faction.
+    * \return The factionId.
+    */
     static const char *GetFactionId(unsigned short pid, unsigned int i) noexcept;
+
+    /**
+    * \brief Get the rank at a certain index in a player's latest faction changes.
+    *
+    * \param pid The player ID whose faction changes should be used.
+    * \param i The index of the faction.
+    * \return The rank.
+    */
     static int GetFactionRank(unsigned short pid, unsigned int i) noexcept;
-    static bool GetFactionExpelledState(unsigned short pid, unsigned int i) noexcept;
+
+    /**
+    * \brief Get the expulsion state at a certain index in a player's latest faction changes.
+    *
+    * \param pid The player ID whose faction changes should be used.
+    * \param i The index of the faction.
+    * \return The expulsion state.
+    */
+    static bool GetFactionExpulsionState(unsigned short pid, unsigned int i) noexcept;
+
+    /**
+    * \brief Get the reputation at a certain index in a player's latest faction changes.
+    *
+    * \param pid The player ID whose faction changes should be used.
+    * \param i The index of the faction.
+    * \return The reputation.
+    */
     static int GetFactionReputation(unsigned short pid, unsigned int i) noexcept;
 
+    /**
+    * \brief Set the action type in a player's faction changes.
+    *
+    * \param pid The player ID whose faction changes should be used.
+    * \param action The action (0 for RANK, 1 for EXPULSION, 2 for REPUTATION).
+    * \return void
+    */
     static void SetFactionChangesAction(unsigned short pid, unsigned char action) noexcept;
+
+    /**
+    * \brief Set the factionId of the temporary faction stored on the server.
+    *
+    * \param factionId The factionId.
+    * \return void
+    */
     static void SetFactionId(const char* factionId) noexcept;
+
+    /**
+    * \brief Set the rank of the temporary faction stored on the server.
+    *
+    * \param rank The rank.
+    * \return void
+    */
     static void SetFactionRank(unsigned int rank) noexcept;
-    static void SetFactionExpulsionState(bool isExpelled) noexcept;
+
+    /**
+    * \brief Set the expulsion state of the temporary faction stored on the server.
+    *
+    * \param expulsionState The expulsion state.
+    * \return void
+    */
+    static void SetFactionExpulsionState(bool expulsionState) noexcept;
+
+    /**
+    * \brief Set the reputation of the temporary faction stored on the server.
+    *
+    * \param reputation The reputation.
+    * \return void
+    */
     static void SetFactionReputation(int reputation) noexcept;
 
+    /**
+    * \brief Add the server's temporary faction to the faction changes for a player.
+    *
+    * \param pid The player ID whose faction changes should be used.
+    * \return void
+    */
     static void AddFaction(unsigned short pid) noexcept;
 
+    /**
+    * \brief Send a PlayerFaction packet with a player's recorded faction changes.
+    *
+    * \param pid The player ID whose faction changes should be used.
+    * \param toOthers Whether this packet should be sent only to other players or
+    *                 only to the player it is about.
+    * \return void
+    */
     static void SendFactionChanges(unsigned short pid, bool toOthers = false) noexcept;
 private:
 

apps/openmw-mp/Script/Functions/Mechanics.hpp

@@ -17,15 +17,72 @@ class MechanicsFunctions
 {
 public:
 
+    /**
+    * \brief Check whether a player is a werewolf.
+    *
+    * This is based on the last PlayerShapeshift packet received or sent for that player.
+    *
+    * \param pid The player id.
+    * \return The werewolf state.
+    */
     static bool IsWerewolf(unsigned short pid) noexcept;
 
+    /**
+    * \brief Set the werewolf state of a player.
+    *
+    * This changes the werewolf state recorded for that player in the server memory, but
+    * does not by itself send a packet.
+    *
+    * \param pid The player id.
+    * \param bool The new werewolf state.
+    * \return void
+    */
     static void SetWerewolfState(unsigned short pid, bool isWerewolf);
 
+    /**
+    * \brief Send a PlayerShapeshift packet about a player.
+    *
+    * This sends the packet to all players connected to the server. It is currently used
+    * only to communicate werewolf states.
+    *
+    * \param pid The player id.
+    * \return void
+    */
     static void SendShapeshift(unsigned short pid);
 
+    /**
+    * \brief Send a PlayerJail packet about a player.
+    *
+    * This is similar to the player being jailed by a guard, but provides extra parameters for
+    * increased flexibility.
+    *
+    * It is only sent to the player being jailed, as the other players will be informed of the
+    * jailing's actual consequences via other packets sent by the affected client.
+    *
+    * \param pid The player id.
+    * \param jailDays The number of days to spend jailed, where each day affects one skill point.
+    * \param ignoreJailTeleportation Whether the player being teleported to the nearest jail
+    *                                marker should be overridden.
+    * \param ignoreJailSkillIncrease Whether the player's Sneak and Security skills should be
+    *                                prevented from increasing as a result of the jailing,
+    *                                overriding default behavior.
+    * \param jailProgressText The text that should be displayed while jailed.
+    * \param jailEndText The text that should be displayed once the jailing period is over.
+    * \return void
+    */
     static void Jail(unsigned short pid, int jailDays, bool ignoreJailTeleportation = false, bool ignoreJailSkillIncreases = false,
                      const char* jailProgressText = "", const char* jailEndText = "") noexcept;
 
+    /**
+    * \brief Send a PlayerResurrect packet about a player.
+    *
+    * This sends the packet to all players connected to the server.
+    *
+    * \param pid The player id.
+    * \param type The type of resurrection (0 for REGULAR, 1 for IMPERIAL_SHRINE,
+    *             2 for TRIBUNAL_TEMPLE).
+    * \return void
+    */
     static void Resurrect(unsigned short pid, unsigned int type) noexcept;
 };
 

apps/openmw-mp/Script/Functions/Miscellaneous.hpp

@@ -15,12 +15,64 @@
 class MiscellaneousFunctions
 {
 public:
+    /**
+    * \brief Get the last player ID currently connected to the server.
+    *
+    * Every player receives a unique numerical index known as their player ID upon joining the
+    * server.
+    *
+    * \return The player ID.
+    */
     static unsigned int GetLastPlayerId() noexcept;
 
+    /**
+    * \brief Get the current (latest) mpNum generated by the server.
+    *
+    * Every object that did not exist in a data file and has instead been placed or spawned through
+    * a server-sent packet has a numerical index known as its mpNum.
+    *
+    * When ObjectPlace and ObjectSpawn packets are received from players, their objects lack mpNums,
+    * so the server assigns them some based on incrementing the server's current mpNum, with the
+    * operation's final mpNum becoming the server's new current mpNum.
+    *
+    * \return The mpNum.
+    */
     static int GetCurrentMpNum() noexcept;
+
+    /**
+    * \brief Set the current (latest) mpNum generated by the server.
+    *
+    * When restarting a server, it is important to revert to the previous current (latest) mpNum
+    * as stored in the server's data, so as to avoid starting over from 0 and ending up assigning
+    * duplicate mpNums to objects.
+    *
+    * \param mpNum The number that should be used as the new current mpNum.
+    * \return void
+    */
     static void SetCurrentMpNum(int mpNum) noexcept;
 
+    /**
+    * \brief Write a log message with its own timestamp.
+    *
+    * It will have "[Script]:" prepended to it so as to mark it as a script-generated log message.
+    *
+    * \param level The logging level used (0 for LOG_VERBOSE, 1 for LOG_INFO, 2 for LOG_WARN,
+    *              3 for LOG_ERROR, 4 for LOG_FATAL).
+    * \param message The message logged.
+    * \return void
+    */
     static void LogMessage(unsigned short level, const char *message) noexcept;
+
+    /**
+    * \brief Write a log message without its own timestamp.
+    *
+    * It will have "[Script]:" prepended to it so as to mark it as a script-generated log message.
+    *
+    * \param level The logging level used (0 for LOG_VERBOSE, 1 for LOG_INFO, 2 for LOG_WARN,
+    *              3 for LOG_ERROR, 4 for LOG_FATAL).
+    * \param message The message logged.
+    * \return void
+    */
     static void LogAppend(unsigned short level, const char *message) noexcept;
 };
 

apps/openmw-mp/Script/Functions/Quests.hpp

@@ -25,25 +25,150 @@
 class QuestFunctions
 {
 public:
+
+    /**
+    * \brief Clear the last recorded journal changes for a player.
+    *
+    * This is used to initialize the sending of new PlayerJournal packets.
+    *
+    * \param pid The player ID whose journal changes should be used.
+    * \return void
+    */
     static void InitializeJournalChanges(unsigned short pid) noexcept;
+
+    /**
+    * \brief Clear the last recorded kill count changes for a player.
+    *
+    * This is used to initialize the sending of new PlayerKillCount packets.
+    *
+    * \param pid The player ID whose kill count changes should be used.
+    * \return void
+    */
     static void InitializeKillChanges(unsigned short pid) noexcept;
 
+    /**
+    * \brief Get the number of indexes in a player's latest journal changes.
+    *
+    * \param pid The player ID whose journal changes should be used.
+    * \return The number of indexes.
+    */
     static unsigned int GetJournalChangesSize(unsigned short pid) noexcept;
+
+    /**
+    * \brief Get the number of indexes in a player's latest kill count changes.
+    *
+    * \param pid The player ID whose kill count changes should be used.
+    * \return The number of indexes.
+    */
     static unsigned int GetKillChangesSize(unsigned short pid) noexcept;
 
+    /**
+    * \brief Add a new journal item of type ENTRY to the journal changes for a player.
+    *
+    * \param pid The player ID whose journal changes should be used.
+    * \param quest The quest of the journal item.
+    * \param index The quest index of the journal item.
+    * \param actorRefId The actor refId of the journal item.
+    * \return void
+    */
     static void AddJournalEntry(unsigned short pid, const char* quest, unsigned int index, const char* actorRefId) noexcept;
+
+    /**
+    * \brief Add a new journal item of type INDEX to the journal changes for a player.
+    *
+    * \param pid The player ID whose journal changes should be used.
+    * \param quest The quest of the journal item.
+    * \param index The quest index of the journal item.
+    * \return void
+    */
     static void AddJournalIndex(unsigned short pid, const char* quest, unsigned int index) noexcept;
+
+    /**
+    * \brief Add a new kill count to the kill count changes for a player.
+    *
+    * \param pid The player ID whose kill count changes should be used.
+    * \param refId The refId of the kill count.
+    * \param number The number of kills in the kill count.
+    * \return void
+    */
     static void AddKill(unsigned short pid, const char* refId, int number) noexcept;
 
+    /**
+    * \brief Get the quest at a certain index in a player's latest journal changes.
+    *
+    * \param pid The player ID whose journal changes should be used.
+    * \param i The index of the journalItem.
+    * \return The quest.
+    */
     static const char *GetJournalItemQuest(unsigned short pid, unsigned int i) noexcept;
+
+    /**
+    * \brief Get the quest index at a certain index in a player's latest journal changes.
+    *
+    * \param pid The player ID whose journal changes should be used.
+    * \param i The index of the journalItem.
+    * \return The quest index.
+    */
     static int GetJournalItemIndex(unsigned short pid, unsigned int i) noexcept;
+
+    /**
+    * \brief Get the journal item type at a certain index in a player's latest journal changes.
+    *
+    * \param pid The player ID whose journal changes should be used.
+    * \param i The index of the journalItem.
+    * \return The type (0 for ENTRY, 1 for INDEX).
+    */
     static int GetJournalItemType(unsigned short pid, unsigned int i) noexcept;
+
+    /**
+    * \brief Get the actor refId at a certain index in a player's latest journal changes.
+    *
+    * Every journal change has an associated actor, which is usually the quest giver.
+    *
+    * \param pid The player ID whose journal changes should be used.
+    * \param i The index of the journalItem.
+    * \return The actor refId.
+    */
     static const char *GetJournalItemActorRefId(unsigned short pid, unsigned int i) noexcept;
+
+    /**
+    * \brief Get the refId at a certain index in a player's latest kill count changes.
+    *
+    * \param pid The player ID whose kill count changes should be used.
+    * \param i The index of the kill count.
+    * \return The refId.
+    */
     static const char *GetKillRefId(unsigned short pid, unsigned int i) noexcept;
+
+    /**
+    * \brief Get the number of kills at a certain index in a player's latest kill count changes.
+    *
+    * \param pid The player ID whose kill count changes should be used.
+    * \param i The index of the kill count.
+    * \return The number of kills.
+    */
     static int GetKillNumber(unsigned short pid, unsigned int i) noexcept;
 
+    /**
+    * \brief Send a PlayerJournal packet with a player's recorded journal changes.
+    *
+    * \param pid The player ID whose journal changes should be used.
+    * \param toOthers Whether this packet should be sent only to other players or
+    *                 only to the player it is about.
+    * \return void
+    */
     static void SendJournalChanges(unsigned short pid, bool toOthers = false) noexcept;
+
+    /**
+    * \brief Send a PlayerKillCount packet with a player's recorded kill count changes.
+    *
+    * \param pid The player ID whose kill count changes should be used.
+    * \param toOthers Whether this packet should be sent only to other players or
+    *                 only to the player it is about.
+    * \return void
+    */
     static void SendKillChanges(unsigned short pid, bool toOthers = false) noexcept;
+
 private:
 
 };

apps/openmw-mp/Script/Functions/Settings.hpp

@@ -12,9 +12,37 @@
 class SettingFunctions
 {
 public:
+
+    /**
+    * \brief Set whether the console is allowed for a player.
+    *
+    * This changes the console permission for that player in the server memory, but does not
+    * by itself send a packet.
+    *
+    * \param pid The player id.
+    * \param bool The console permission state.
+    * \return void
+    */
     static void SetConsoleAllow(unsigned short pid, bool state);
+
+    /**
+    * \brief Set the difficulty for a player.
+    *
+    * This changes the difficulty for that player in the server memory, but does not by itself
+    * send a packet.
+    *
+    * \param pid The player id.
+    * \param bool The difficulty.
+    * \return void
+    */
     static void SetDifficulty(unsigned short pid, int difficulty);
 
+    /**
+    * \brief Send a PlayerSettings packet to the player affected by it.
+    *
+    * \param pid The player ID to send it to.
+    * \return void
+    */
     static void SendSettings(unsigned short pid) noexcept;
 };
 

apps/openmw-mp/Script/Functions/Spells.hpp

@@ -18,17 +18,75 @@ class SpellFunctions
 {
 public:
 
+    /**
+    * \brief Clear the last recorded spellbook changes for a player.
+    *
+    * This is used to initialize the sending of new PlayerSpellbook packets.
+    *
+    * \param pid The player ID whose spellbook changes should be used.
+    * \return void
+    */
     static void InitializeSpellbookChanges(unsigned short pid) noexcept;
 
+    /**
+    * \brief Get the number of indexes in a player's latest spellbook changes.
+    *
+    * \param pid The player ID whose spellbook changes should be used.
+    * \return The number of indexes.
+    */
     static unsigned int GetSpellbookChangesSize(unsigned short pid) noexcept;
+
+    /**
+    * \brief Get the action type used in a player's latest spellbook changes.
+    *
+    * \param pid The player ID whose faction changes should be used.
+    * \return The action type (0 for SET, 1 for ADD, 2 for REMOVE).
+    */
     static unsigned int GetSpellbookAction(unsigned short pid) noexcept;
 
+    /**
+    * \brief Prepare the addition of a spell to a player.
+    *
+    * In practice, this changes the action type of the PlayerSpellbook packet to
+    * ADD and adds this spell to it.
+    *
+    * \param pid The player ID whose spellbook changes should be used.
+    * \param topicId The spellId of the spell.
+    * \return void
+    */
     static void AddSpell(unsigned short pid, const char* spellId) noexcept;
+
+    /**
+    * \brief Prepare the removal of a spell from a player.
+    *
+    * In practice, this changes the action type of the PlayerSpellbook packet to
+    * REMOVE and adds this spell to it.
+    *
+    * \param pid The player ID whose spellbook changes should be used.
+    * \param topicId The spellId of the spell.
+    * \return void
+    */
     static void RemoveSpell(unsigned short pid, const char* spellId) noexcept;
 
+    /**
+    * \brief Get the spellId at a certain index in a player's latest spellbook changes.
+    *
+    * \param pid The player ID whose spellbook changes should be used.
+    * \param i The index of the spell.
+    * \return The spellId.
+    */
     static const char *GetSpellId(unsigned short pid, unsigned int i) noexcept;
 
+    /**
+    * \brief Send a PlayerSpellbook packet with a player's recorded spellbook changes.
+    *
+    * \param pid The player ID whose spellbook changes should be used.
+    * \param toOthers Whether this packet should be sent only to other players or
+    *                 only to the player it is about.
+    * \return void
+    */
     static void SendSpellbookChanges(unsigned short pid, bool toOthers = false) noexcept;
+
 private:
 
 };