From 340fe17f4fd7f891fa6e323c3135cbdb6783c890 Mon Sep 17 00:00:00 2001 From: Patman64 Date: Mon, 22 Dec 2014 00:30:22 -0500 Subject: [PATCH] Add Object method documentation and drop Object:UpdateUInt32. UpdateUInt32 appears to be a deprecated method and isn't used anywhere else in CMaNGOS. SetUInt32 should be used instead. --- LuaFunctions.cpp | 1 - ObjectMethods.h | 220 +++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 212 insertions(+), 9 deletions(-) diff --git a/LuaFunctions.cpp b/LuaFunctions.cpp index dc02d7d..de11338 100644 --- a/LuaFunctions.cpp +++ b/LuaFunctions.cpp @@ -151,7 +151,6 @@ ElunaRegister ObjectMethods[] = // Setters { "SetInt32Value", &LuaObject::SetInt32Value }, // :SetInt32Value(index, value) - Sets an int value for the object { "SetUInt32Value", &LuaObject::SetUInt32Value }, // :SetUInt32Value(index, value) - Sets an uint value for the object - { "UpdateUInt32Value", &LuaObject::UpdateUInt32Value }, // :UpdateUInt32Value(index, value) - Updates an uint value for the object { "SetFloatValue", &LuaObject::SetFloatValue }, // :SetFloatValue(index, value) - Sets a float value for the object { "SetByteValue", &LuaObject::SetByteValue }, // :SetByteValue(index, offset, value) - Sets a byte value for the object { "SetUInt16Value", &LuaObject::SetUInt16Value }, // :SetUInt16Value(index, offset, value) - Sets an uint16 value for the object diff --git a/ObjectMethods.h b/ObjectMethods.h index 3dcb3f6..81f3645 100644 --- a/ObjectMethods.h +++ b/ObjectMethods.h @@ -7,9 +7,29 @@ #ifndef OBJECTMETHODS_H #define OBJECTMETHODS_H +/*** + * A basic game object (either an [Item] or a [WorldObject]). + * + * Objects in MaNGOS/Trinity are stored an a giant block of "values". + * Subclasses of Object, like [WorldObject], extend the block with more data specific to that subclass. + * Further subclasses, like [Player], extend it even further. + * + * A detailed map of all the fields in this data block can be found in the UpdateFields.h file of your emulator + * (it varies depending on the expansion supported). + * + * The GetValue methods in this class (e.g. [Object:GetInt32Value]) provide low-level access to the data block. + * Other methods, like [Object:HasFlag] and [Object:GetScale], merely wrap the GetValue methods and provide a simpler interface. + */ namespace LuaObject { /* BOOLEAN */ + /** + * Returns `true` if the specified flag is set, otherwise `false`. + * + * @param uint16 index : the index of the flags data in the [Object] + * @param uint32 flag : the flag to check for in the flags data + * @return bool hasFlag + */ int HasFlag(Eluna* /*E*/, lua_State* L, Object* obj) { uint16 index = Eluna::CHECKVAL(L, 2); @@ -19,6 +39,11 @@ namespace LuaObject return 1; } + /** + * Returns `true` if the [Object] has been added to its [Map], otherwise `false`. + * + * @return bool inWorld + */ int IsInWorld(Eluna* /*E*/, lua_State* L, Object* obj) { Eluna::Push(L, obj->IsInWorld()); @@ -26,6 +51,12 @@ namespace LuaObject } /* GETTERS */ + /** + * Returns the data at the specified index, casted to a signed 32-bit integer. + * + * @param uint16 index + * @return int32 value + */ int GetInt32Value(Eluna* /*E*/, lua_State* L, Object* obj) { uint16 index = Eluna::CHECKVAL(L, 2); @@ -33,6 +64,12 @@ namespace LuaObject return 1; } + /** + * Returns the data at the specified index, casted to a unsigned 32-bit integer. + * + * @param uint16 index + * @return uint32 value + */ int GetUInt32Value(Eluna* /*E*/, lua_State* L, Object* obj) { uint16 index = Eluna::CHECKVAL(L, 2); @@ -40,6 +77,12 @@ namespace LuaObject return 1; } + /** + * Returns the data at the specified index, casted to a single-precision floating point value. + * + * @param uint16 index + * @return float value + */ int GetFloatValue(Eluna* /*E*/, lua_State* L, Object* obj) { uint16 index = Eluna::CHECKVAL(L, 2); @@ -47,6 +90,15 @@ namespace LuaObject return 1; } + /** + * Returns the data at the specified index and offset, casted to an unsigned 8-bit integer. + * + * E.g. if you want the second byte at index 10, you would pass in 1 as the offset. + * + * @param uint16 index + * @param uint8 offset : should be 0, 1, 2, or 3 + * @return uint8 value + */ int GetByteValue(Eluna* /*E*/, lua_State* L, Object* obj) { uint16 index = Eluna::CHECKVAL(L, 2); @@ -55,6 +107,15 @@ namespace LuaObject return 1; } + /** + * Returns the data at the specified index and offset, casted to a signed 16-bit integer. + * + * E.g. if you want the second half-word at index 10, you would pass in 1 as the offset. + * + * @param uint16 index + * @param uint8 offset : should be 0 or 1 + * @return uint16 value + */ int GetUInt16Value(Eluna* /*E*/, lua_State* L, Object* obj) { uint16 index = Eluna::CHECKVAL(L, 2); @@ -63,36 +124,86 @@ namespace LuaObject return 1; } + /** + * Returns the scale/size of the [Object]. + * + * This affects the size of a [WorldObject] in-game, but [Item]s don't have a "scale". + * + * @return float scale + */ int GetScale(Eluna* /*E*/, lua_State* L, Object* obj) { Eluna::Push(L, obj->GetObjectScale()); return 1; } + /** + * Returns the entry of the [Object]. + * + * [Player]s do not have an "entry". + * + * @return uint32 entry + */ int GetEntry(Eluna* /*E*/, lua_State* L, Object* obj) { Eluna::Push(L, obj->GetEntry()); return 1; } + /** + * Returns the GUID of the [Object]. + * + * @return uint64 guid + */ int GetGUID(Eluna* /*E*/, lua_State* L, Object* obj) { Eluna::Push(L, obj->GET_GUID()); return 1; } + /** + * Returns the low-part of the [Object]'s GUID. + * + * This is the counter that is unique among [Object]s of the same type + * (e.g. no two [Creature]s will have a low-GUID of 5 at the same time). + * + * @return uint32 guidLow + */ int GetGUIDLow(Eluna* /*E*/, lua_State* L, Object* obj) { Eluna::Push(L, obj->GetGUIDLow()); return 1; } + /** + * Returns the TypeId of the [Object]. + * + * enum TypeID + * { + * TYPEID_OBJECT = 0, + * TYPEID_ITEM = 1, + * TYPEID_CONTAINER = 2, + * TYPEID_UNIT = 3, + * TYPEID_PLAYER = 4, + * TYPEID_GAMEOBJECT = 5, + * TYPEID_DYNAMICOBJECT = 6, + * TYPEID_CORPSE = 7 + * }; + * + * @return uint8 typeID + */ int GetTypeId(Eluna* /*E*/, lua_State* L, Object* obj) { Eluna::Push(L, obj->GetTypeId()); return 1; } + /** + * Returns the data at the specified index, casted to an unsigned 64-bit integer. + * + * @param uint16 index + * @return uint64 value + */ int GetUInt64Value(Eluna* /*E*/, lua_State* L, Object* obj) { uint16 index = Eluna::CHECKVAL(L, 2); @@ -101,6 +212,16 @@ namespace LuaObject } /* SETTERS */ + /** + * Sets the specified flag in the data value at the specified index. + * + * If the flag was already set, it remains set. + * + * To remove a flag, use [Object:RemoveFlag]. + * + * @param uint16 index + * @param uint32 value + */ int SetFlag(Eluna* /*E*/, lua_State* L, Object* obj) { uint16 index = Eluna::CHECKVAL(L, 2); @@ -110,6 +231,12 @@ namespace LuaObject return 0; } + /** + * Sets the data at the specified index to the given value, converted to a signed 32-bit integer. + * + * @param uint16 index + * @param int32 value + */ int SetInt32Value(Eluna* /*E*/, lua_State* L, Object* obj) { uint16 index = Eluna::CHECKVAL(L, 2); @@ -118,6 +245,12 @@ namespace LuaObject return 0; } + /** + * Sets the data at the specified index to the given value, converted to an unsigned 32-bit integer. + * + * @param uint16 index + * @param uint32 value + */ int SetUInt32Value(Eluna* /*E*/, lua_State* L, Object* obj) { uint16 index = Eluna::CHECKVAL(L, 2); @@ -126,6 +259,12 @@ namespace LuaObject return 0; } + /** + * Sets the data at the specified index to the given value, converted to a single-precision floating point value. + * + * @param uint16 index + * @param float value + */ int SetFloatValue(Eluna* /*E*/, lua_State* L, Object* obj) { uint16 index = Eluna::CHECKVAL(L, 2); @@ -135,6 +274,13 @@ namespace LuaObject return 0; } + /** + * Sets the data at the specified index and offset to the given value, converted to an unsigned 8-bit integer. + * + * @param uint16 index + * @param uint8 offset : should be 0, 1, 2, or 3 + * @param uint8 value + */ int SetByteValue(Eluna* /*E*/, lua_State* L, Object* obj) { uint16 index = Eluna::CHECKVAL(L, 2); @@ -144,6 +290,13 @@ namespace LuaObject return 0; } + /** + * Sets the data at the specified index to the given value, converted to an unsigned 16-bit integer. + * + * @param uint16 index + * @param uint8 offset : should be 0 or 1 + * @param uint16 value + */ int SetUInt16Value(Eluna* /*E*/, lua_State* L, Object* obj) { uint16 index = Eluna::CHECKVAL(L, 2); @@ -153,6 +306,13 @@ namespace LuaObject return 0; } + /** + * Sets the data at the specified index to the given value, converted to a signed 16-bit integer. + * + * @param uint16 index + * @param uint8 offset : should be 0 or 1 + * @param int16 value + */ int SetInt16Value(Eluna* /*E*/, lua_State* L, Object* obj) { uint16 index = Eluna::CHECKVAL(L, 2); @@ -162,6 +322,11 @@ namespace LuaObject return 0; } + /** + * Sets the [Object]'s scale/size to the given value. + * + * @param float scale + */ int SetScale(Eluna* /*E*/, lua_State* L, Object* obj) { float size = Eluna::CHECKVAL(L, 2); @@ -170,6 +335,12 @@ namespace LuaObject return 0; } + /** + * Sets the data at the specified index to the given value, converted to an unsigned 64-bit integer. + * + * @param uint16 index + * @param uint64 value + */ int SetUInt64Value(Eluna* /*E*/, lua_State* L, Object* obj) { uint16 index = Eluna::CHECKVAL(L, 2); @@ -179,6 +350,12 @@ namespace LuaObject } /* OTHER */ + /** + * Removes a flag from the value at the specified index. + * + * @param uint16 index + * @param uint32 flag + */ int RemoveFlag(Eluna* /*E*/, lua_State* L, Object* obj) { uint16 index = Eluna::CHECKVAL(L, 2); @@ -188,38 +365,65 @@ namespace LuaObject return 0; } - int UpdateUInt32Value(Eluna* /*E*/, lua_State* L, Object* obj) - { - uint16 index = Eluna::CHECKVAL(L, 2); - uint32 value = Eluna::CHECKVAL(L, 3); - obj->UpdateUInt32Value(index, value); - return 0; - } - + /** + * Attempts to convert the [Object] to a [Corpse]. + * + * If the [Object] is not a [Corpse], returns `nil`. + * + * @return [Corpse] corpse : the [Object] as a [Corpse], or `nil` + */ int ToCorpse(Eluna* /*E*/, lua_State* L, Object* obj) { Eluna::Push(L, obj->ToCorpse()); return 1; } + /** + * Attempts to convert the [Object] to a [GameObject]. + * + * If the [Object] is not a [GameObject], returns `nil`. + * + * @return [GameObject] gameObject : the [Object] as a [GameObject], or `nil` + */ int ToGameObject(Eluna* /*E*/, lua_State* L, Object* obj) { Eluna::Push(L, obj->ToGameObject()); return 1; } + /** + * Attempts to convert the [Object] to a [Unit]. + * + * If the [Object] is not a [Unit], returns `nil`. + * + * @return [Unit] unit : the [Object] as a [Unit], or `nil` + */ int ToUnit(Eluna* /*E*/, lua_State* L, Object* obj) { Eluna::Push(L, obj->ToUnit()); return 1; } + /** + * Attempts to convert the [Object] to a [Creature]. + * + * If the [Object] is not a [Creature], returns `nil`. + * + * @return [Creature] creature : the [Object] as a [Creature], or `nil` + */ int ToCreature(Eluna* /*E*/, lua_State* L, Object* obj) { Eluna::Push(L, obj->ToCreature()); return 1; } + /** + * Attempts to convert the [Object] to a [Player]. + * + * If the [Object] is not a [Player], returns `nil`. + * + * @return [Player] player : the [Object] as a [Player], or `nil` + */ int ToPlayer(Eluna* /*E*/, lua_State* L, Object* obj) { Eluna::Push(L, obj->ToPlayer());