From 5e5440b6972a3cec113a76b8c615541a9ddbd14d Mon Sep 17 00:00:00 2001 From: David Cernat Date: Sun, 23 Jul 2017 21:59:33 +0300 Subject: [PATCH] [Server] Document script functions, part 2 --- apps/openmw-mp/Script/Functions/Factions.hpp | 3 + .../Script/Functions/Miscellaneous.hpp | 4 +- apps/openmw-mp/Script/Functions/Positions.hpp | 90 ++++ apps/openmw-mp/Script/Functions/World.hpp | 468 ++++++++++++++++++ 4 files changed, 563 insertions(+), 2 deletions(-) diff --git a/apps/openmw-mp/Script/Functions/Factions.hpp b/apps/openmw-mp/Script/Functions/Factions.hpp index a668f1f07..d29b9cea8 100644 --- a/apps/openmw-mp/Script/Functions/Factions.hpp +++ b/apps/openmw-mp/Script/Functions/Factions.hpp @@ -132,6 +132,9 @@ public: /** * \brief Add the server's temporary faction to the faction changes for a player. * + * In the process, the server's temporary faction will automatically be cleared so a new one + * can be set up. + * * \param pid The player ID whose faction changes should be used. * \return void */ diff --git a/apps/openmw-mp/Script/Functions/Miscellaneous.hpp b/apps/openmw-mp/Script/Functions/Miscellaneous.hpp index 5e5b5aa6b..158921bbe 100644 --- a/apps/openmw-mp/Script/Functions/Miscellaneous.hpp +++ b/apps/openmw-mp/Script/Functions/Miscellaneous.hpp @@ -28,8 +28,8 @@ public: /** * \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. + * Every object that did not exist in an .ESM or .ESP 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 diff --git a/apps/openmw-mp/Script/Functions/Positions.hpp b/apps/openmw-mp/Script/Functions/Positions.hpp index 570a689ad..8f28b5bb1 100644 --- a/apps/openmw-mp/Script/Functions/Positions.hpp +++ b/apps/openmw-mp/Script/Functions/Positions.hpp @@ -22,18 +22,108 @@ class PositionFunctions { public: + + /** + * \brief Assign the player's positional coordinate values to the variables passed as + * parameters. + * + * \param pid The player id. + * \param x The variable for the X position. + * \param y The variable for the Y position. + * \param z The variable for the Z position. + * \return void + */ static void GetPos(unsigned short pid, float *x, float *y, float *z) noexcept; + + /** + * \brief Get the X position of a player. + * + * \param pid The player id. + * \return The X position. + */ static double GetPosX(unsigned short pid) noexcept; + + /** + * \brief Get the Y position of a player. + * + * \param pid The player id. + * \return The Y position. + */ static double GetPosY(unsigned short pid) noexcept; + + /** + * \brief Get the Z position of a player. + * + * \param pid The player id. + * \return The Z position. + */ static double GetPosZ(unsigned short pid) noexcept; + /** + * \brief Assign the player's rotational coordinate values to the variables passed as + * parameters. + * + * \param pid The player id. + * \param x The variable for the X rotation. + * \param y The variable for the Y rotation. + * \param z The variable for the Z rotation. + * \return void + */ static void GetRot(unsigned short pid, float *x, float *y, float *z) noexcept; + + /** + * \brief Get the X rotation of a player. + * + * \param pid The player id. + * \return The X rotation. + */ static double GetRotX(unsigned short pid) noexcept; + + /** + * \brief Get the Z rotation of a player. + * + * \param pid The player id. + * \return The Z rotation. + */ static double GetRotZ(unsigned short pid) noexcept; + /** + * \brief Set the position of a player. + * + * This changes the positional coordinates recorded for that player in the server memory, but + * does not by itself send a packet. + * + * \param pid The player id. + * \param x The X position. + * \param y The Y position. + * \param z The Z position. + * \return void + */ static void SetPos(unsigned short pid, double x, double y, double z) noexcept; + + /** + * \brief Set the rotation of a player. + * + * This changes the rotational coordinates recorded for that player in the server memory, but + * does not by itself send a packet. + * + * A player's Y rotation is always 0, which is why there is no Y rotation parameter. + * + * \param pid The player id. + * \param x The X position. + * \param z The Z position. + * \return void + */ static void SetRot(unsigned short pid, double x, double z) noexcept; + /** + * \brief Send a PlayerPosition packet about a player. + * + * It is only sent to the affected player. + * + * \param pid The player id. + * \return void + */ static void SendPos(unsigned short pid) noexcept; }; diff --git a/apps/openmw-mp/Script/Functions/World.hpp b/apps/openmw-mp/Script/Functions/World.hpp index e278494b2..8ace72cc4 100644 --- a/apps/openmw-mp/Script/Functions/World.hpp +++ b/apps/openmw-mp/Script/Functions/World.hpp @@ -74,72 +74,540 @@ class WorldFunctions { public: + /** + * \brief Use the last event received by the server as the one being read. + * + * \return void + */ static void ReadLastEvent() noexcept; + + /** + * \brief Clear the data from the last event sent by the server. + * + * This is used to initialize the sending of new Object packets. + * + * \param pid The player ID to whom the event should later be sent. + * \return void + */ static void InitializeEvent(unsigned short pid) noexcept; + /** + * \brief Get the number of indexes in the read event's object changes. + * + * \return The number of indexes. + */ static unsigned int GetObjectChangesSize() noexcept; + + /** + * \brief Get the action type used in the read event. + * + * \return The action type (0 for SET, 1 for ADD, 2 for REMOVE, 3 for REQUEST). + */ static unsigned char GetEventAction() noexcept; + /** + * \brief Get the refId of the object at a certain index in the read event's object changes. + * + * \return The refId. + */ static const char *GetObjectRefId(unsigned int i) noexcept; + + /** + * \brief Get the refNumIndex of the object at a certain index in the read event's object + * changes. + * + * \param i The index of the object. + * \return The refNumIndex. + */ static int GetObjectRefNumIndex(unsigned int i) noexcept; + + /** + * \brief Get the mpNum of the object at a certain index in the read event's object changes. + * + * \param i The index of the object. + * \return The mpNum. + */ static int GetObjectMpNum(unsigned int i) noexcept; + + /** + * \brief Get the count of the object at a certain index in the read event's object changes. + * + * \param i The index of the object. + * \return The object count. + */ static int GetObjectCount(unsigned int i) noexcept; + + /** + * \brief Get the charge of the object at a certain index in the read event's object changes. + * + * \param i The index of the object. + * \return The charge. + */ static int GetObjectCharge(unsigned int i) noexcept; + + /** + * \brief Get the gold value of the object at a certain index in the read event's object + * changes. + * + * This is used solely to get the gold value of gold. It is not used for other objects. + * + * \param i The index of the object. + * \return The gold value. + */ static int GetObjectGoldValue(unsigned int i) noexcept; + + /** + * \brief Get the object scale of the object at a certain index in the read event's object + * changes. + * + * \param i The index of the object. + * \return The object scale. + */ static double GetObjectScale(unsigned int i) noexcept; + + /** + * \brief Get the object state of the object at a certain index in the read event's object + * changes. + * + * \param i The index of the object. + * \return The object state. + */ static bool GetObjectState(unsigned int i) noexcept; + + /** + * \brief Get the door state of the object at a certain index in the read event's object + * changes. + * + * \param i The index of the object. + * \return The door state. + */ static int GetObjectDoorState(unsigned int i) noexcept; + + /** + * \brief Get the lock level of the object at a certain index in the read event's object + * changes. + * + * \param i The index of the object. + * \return The lock level. + */ static int GetObjectLockLevel(unsigned int i) noexcept; + + /** + * \brief Get the X position of the object at a certain index in the read event's object + * changes. + * + * \param i The index of the object. + * \return The X position. + */ static double GetObjectPosX(unsigned int i) noexcept; + + /** + * \brief Get the Y position of the object at a certain index in the read event's object + * changes. + * + * \param i The index of the object. + * \return The Y position. + */ static double GetObjectPosY(unsigned int i) noexcept; + + /** + * \brief Get the Z position at a certain index in the read event's object changes. + * + * \param i The index of the object. + * \return The Z position. + */ static double GetObjectPosZ(unsigned int i) noexcept; + + /** + * \brief Get the X rotation of the object at a certain index in the read event's object + * changes. + * + * \param i The index of the object. + * \return The X rotation. + */ static double GetObjectRotX(unsigned int i) noexcept; + + /** + * \brief Get the Y rotation of the object at a certain index in the read event's object + * changes. + * + * \param i The index of the object. + * \return The Y rotation. + */ static double GetObjectRotY(unsigned int i) noexcept; + + /** + * \brief Get the Z rotation of the object at a certain index in the read event's object + * changes. + * + * \param i The index of the object. + * \return The Z rotation. + */ static double GetObjectRotZ(unsigned int i) noexcept; + /** + * \brief Get the number of container item indexes of the object at a certain index in the + * read event's object changes. + * + * \param i The index of the object. + * \return The number of container item indexes. + */ static unsigned int GetContainerChangesSize(unsigned int objectIndex) noexcept; + + /** + * \brief Get the refId of the container item at a certain itemIndex in the container changes + * of the object at a certain objectIndex in the read event's object changes. + * + * \param objectIndex The index of the object. + * \param itemIndex The index of the container item. + * \return The refId. + */ static const char *GetContainerItemRefId(unsigned int objectIndex, unsigned int itemIndex) noexcept; + + /** + * \brief Get the item count of the container item at a certain itemIndex in the container + * changes of the object at a certain objectIndex in the read event's object changes. + * + * \param objectIndex The index of the object. + * \param itemIndex The index of the container item. + * \return The item count. + */ static int GetContainerItemCount(unsigned int objectIndex, unsigned int itemIndex) noexcept; + + /** + * \brief Get the charge of the container item at a certain itemIndex in the container changes + * of the object at a certain objectIndex in the read event's object changes. + * + * \param objectIndex The index of the object. + * \param itemIndex The index of the container item. + * \return The charge. + */ static int GetContainerItemCharge(unsigned int objectIndex, unsigned int itemIndex) noexcept; + + /** + * \brief Get the action count of the container item at a certain itemIndex in the container + * changes of the object at a certain objectIndex in the read event's object changes. + * + * \param objectIndex The index of the object. + * \param itemIndex The index of the container item. + * \return The action count. + */ static int GetContainerItemActionCount(unsigned int objectIndex, unsigned int itemIndex) noexcept; + /** + * \brief Set the cell of the temporary event stored on the server. + * + * The cell is determined to be an exterior cell if it fits the pattern of a number followed + * by a comma followed by another number. + * + * \param cellDescription The cellDescription. + * \return void + */ static void SetEventCell(const char* cellDescription) noexcept; + + /** + * \brief Set the action type of the temporary event stored on the server. + * + * \param action The action type (0 for SET, 1 for ADD, 2 for REMOVE, 3 for REQUEST). + * \return void + */ static void SetEventAction(unsigned char action) noexcept; + /** + * \brief Set the refId of the temporary world object stored on the server. + * + * \param refId The refId. + * \return void + */ static void SetObjectRefId(const char* refId) noexcept; + + /** + * \brief Set the refNumIndex of the temporary world object stored on the server. + * + * Every object loaded from .ESM and .ESP data files has a unique refNumIndex which needs to be + * retained to refer to it in packets. + * + * On the other hand, objects placed or spawned via the server should always have a refNumIndex + * of 0. + * + * \param refNumIndex The refNumIndex. + * \return void + */ static void SetObjectRefNumIndex(int refNumIndex) noexcept; + + /** + * \brief Set the mpNum of the temporary world object stored on the server. + * + * Every object placed or spawned via the server is assigned an mpNum by incrementing the last + * mpNum stored on the server. Scripts should take care to ensure that mpNums are kept unique + * for these objects. + * + * Objects loaded from .ESM and .ESP data files should always have an mpNum of 0, because they + * have unique refNumIndexes instead. + * + * \param mpNum The mpNum. + * \return void + */ static void SetObjectMpNum(int mpNum) noexcept; + + /** + * \brief Set the object count of the temporary world object stored on the server. + * + * This determines the quantity of an object, with the exception of gold. + * + * \param count The object count. + * \return void + */ static void SetObjectCount(int count) noexcept; + + /** + * \brief Set the charge of the temporary world object stored on the server. + * + * Object durabilities are set through this value. + * + * \param charge The charge. + * \return void + */ static void SetObjectCharge(int charge) noexcept; + + /** + * \brief Set the gold value of the temporary world object stored on the server. + * + * This is used solely to set the gold value for gold. It has no effect on other objects. + * + * \param goldValue The gold value. + * \return void + */ static void SetObjectGoldValue(int goldValue) noexcept; + + /** + * \brief Set the scale of the temporary world object stored on the server. + * + * Objects are smaller or larger than their default size based on their scale. + * + * \param scale The scale. + * \return void + */ static void SetObjectScale(double scale) noexcept; + + /** + * \brief Set the object state of the temporary world object stored on the server. + * + * Objects are enabled or disabled based on their object state. + * + * \param objectState The object state. + * \return void + */ static void SetObjectState(bool objectState) noexcept; + + /** + * \brief Set the door state of the temporary world object stored on the server. + * + * Doors are open or closed based on their door state. + * + * \param doorState The door state. + * \return void + */ static void SetObjectDoorState(int doorState) noexcept; + + /** + * \brief Set the lock level of the temporary world object stored on the server. + * + * \param lockLevel The lock level. + * \return void + */ static void SetObjectLockLevel(int lockLevel) noexcept; + + /** + * \brief Set the disarm state of the temporary world object stored on the server. + * + * \param disarmState The disarmState. + * \return void + */ static void SetObjectDisarmState(bool disarmState) noexcept; + + /** + * \brief Set the master state of the temporary world object stored on the server. + * + * This only affects living actors and determines whether they are followers of another + * living actor. + * + * \param masterState The master state. + * \return void + */ static void SetObjectMasterState(bool masterState) noexcept; + + /** + * \brief Set the position of the temporary world object stored on the server. + * + * \param x The X position. + * \param y The Y position. + * \param z The Z position. + * \return void + */ static void SetObjectPosition(double x, double y, double z) noexcept; + + /** + * \brief Set the rotation of the temporary world object stored on the server. + * + * \param x The X rotation. + * \param y The Y rotation. + * \param z The Z rotation. + * \return void + */ static void SetObjectRotation(double x, double y, double z) noexcept; + /** + * \brief Set the refId of the temporary container item stored on the server. + * + * \param refId The refId. + * \return void + */ static void SetContainerItemRefId(const char* refId) noexcept; + + /** + * \brief Set the item count of the temporary container item stored on the server. + * + * \param count The item count. + * \return void + */ static void SetContainerItemCount(int count) noexcept; + + /** + * \brief Set the charge of the temporary container item stored on the server. + * + * \param charge The charge. + * \return void + */ static void SetContainerItemCharge(int charge) noexcept; + /** + * \brief Add a copy of the server's temporary world object to the server's temporary event. + * + * In the process, the server's temporary world object will automatically be cleared so a new + * one can be set up. + * + * \return void + */ static void AddWorldObject() noexcept; + + /** + * \brief Add a copy of the server's temporary container item to the container changes of the + * server's temporary world object. + * + * In the process, the server's temporary container item will automatically be cleared so a new + * one can be set up. + * + * \return void + */ static void AddContainerItem() noexcept; + /** + * \brief Send an ObjectPlace packet. + * + * It is sent only to the player for whom the current event was initialized. + * + * \return void + */ static void SendObjectPlace() noexcept; + + /** + * \brief Send an ObjectSpawn packet. + * + * It is sent only to the player for whom the current event was initialized. + * + * \return void + */ static void SendObjectSpawn() noexcept; + + /** + * \brief Send an ObjectDelete packet. + * + * It is sent only to the player for whom the current event was initialized. + * + * \return void + */ static void SendObjectDelete() noexcept; + + /** + * \brief Send an ObjectLock packet. + * + * It is sent only to the player for whom the current event was initialized. + * + * \return void + */ static void SendObjectLock() noexcept; + + /** + * \brief Send an ObjectTrap packet. + * + * It is sent only to the player for whom the current event was initialized. + * + * \return void + */ static void SendObjectTrap() noexcept; + + /** + * \brief Send an ObjectScale packet. + * + * It is sent only to the player for whom the current event was initialized. + * + * \return void + */ static void SendObjectScale() noexcept; + + /** + * \brief Send an ObjectState packet. + * + * It is sent only to the player for whom the current event was initialized. + * + * \return void + */ static void SendObjectState() noexcept; + + /** + * \brief Send a DoorState packet. + * + * It is sent only to the player for whom the current event was initialized. + * + * \return void + */ static void SendDoorState() noexcept; + + /** + * \brief Send a Container packet. + * + * It is sent only to the player for whom the current event was initialized. + * + * \return void + */ static void SendContainer() noexcept; + /** + * \brief Set the game hour for a player and send a GameTime packet to that player. + * + * \param pid The player id. + * \param hour The hour. + * \return void + */ static void SetHour(unsigned short pid, double hour) noexcept; + + /** + * \brief Set the game month for a player and send a GameTime packet to that player. + * + * \param pid The player id. + * \param month The month. + * \return void + */ static void SetMonth(unsigned short pid, int month) noexcept; + + /** + * \brief Set the game day for a player and send a GameTime packet to that player. + * + * \param pid The player id. + * \param day The day. + * \return void + */ static void SetDay(unsigned short pid, int day) noexcept; };