WebSVN – vanilla-wow-addons – Blame – Rev 1 – /m/MobInfo2/ReadMe_MobInfo

1

office

1

2

--

3

-- This file explains in great detail all information and functions of

4

-- the MobInfo2 external API and the built-in MobHealth external API.

5

-- (API = Application Programmers Interface)

6

--

7

-- It tells you how to best check for the presence of the AddOn(s) and

8

-- provides functions for easy access to the MobInfo database and the

9

-- MobHealth database.

10

--

11

-- There are 3 sections:

12

--

13

-- Section 1 : How to best check if (any) MobHealth AddOn is available ?

14

-- Section 2 : Functions for accessing ALL MobHealth data

15

-- Section 3 : Functions for accessing ALL MobInfo data

16

-- Section 4 : Free Source Code for Accessing MobHealth in a Compatible Way

17

18

19

-- ==========================================================================

20

-- Section 1 : How to best check if (any) MobHealth AddOn is available ?

21

-- ==========================================================================

22

--

23

-- Info: there are at present three known AddOns that provide MobHealth

24

-- functionality and MobHealth data : "MobHealth by Telo", "MobHealth2

25

-- by Wyv" and MobInfo2. All three AddOns provide their service in

26

-- extremely similar, almost identical fashion.

27

--

28

-- The best way to check whether any one MobHealth service is available

29

-- is to add this simple "if" to your "VARIABLES_LOADED" event handler:

30

--

31

-- if MobHealthFrame then

-- ......

-- end

--

-- Its all that is required. If the condition is true you can rest

36

-- assured that one of the MobHealth AddOns is present. Please do NOT

37

-- place the check into the "OnLoad" event handler. That is potentially

38

-- unsave and error prone. "OnLoad" is called at a time where NOT all

39

-- AddOns have been loaded. On the other hand "VARIABLES_LOADED" is

40

-- invoked at a time when you can be sure that ALL AddOns have been

41

-- loaded and can thus be checked for and accessed.

42

-- ==========================================================================

43

44

45

-- ==========================================================================

46

-- Section 2 : Functions for accessing ALL MobHealth data

47

-- ==========================================================================

48

--

49

-- Note that Telos MobHealth (sadly!) does not offer such interface

50

-- functions. They got invented by MobHealth2. They get officially supported

51

-- by MobInfo. I will suggest to Telo to add them to his MobHealth

52

-- AddOn as well for the sake of compatibility.

53

--

54

-- This is the RECOMMENDED way to access the MobHealth data. Using the

55

-- functions make you independant of how the data is stored internally

56

-- within the AddOns database. Please do NOT access the AddOns database

57

-- variable directly. Instead ALWAYS use one of the three functions

58

-- listed below.

59

--

60

-- In the future I plan to make considerable changes to the way that

61

-- MobHealth stores its data. This will have great advantages for the

62

-- AddOn, but will result in problems for AddOns that access the database

63

-- variable directly. The source code for these functions is in

64

-- "MI2_Health.lua".

65

--

66

-- Additional compatibility note:

67

-- ------------------------------

68

-- In order to retain compatibility to Telos MobHealth you will have to

69

-- support both : a) the direct access to "MobHealthDB" and b) the

70

-- indirect access using the functions below. Here is an example of

71

-- how to do that (works for all 3 functions):

72

--

73

-- if MobHealth_PPP then

74

-- ... code that uses "MobHealth_PPP()"

75

-- else

76

-- ... your old code that uses "MobHealthDB"

77

-- end

78

--

79

-- To make it easier for you I have decided to simply supply you with the

80

-- entire necessary source code right here, for free. Go to section 4 and

81

-- simply copy the source code of the 3 local functions you find there

82

-- into your own AddOn. They are 100% compatible with the interface of

83

-- the 3 functions that I offer right here in section 2.

84

--

85

-----------------------------------------------------------------------------

86

-- function MobHealth_GetTargetCurHP()

87

--

88

-- Return current health points value for the current target as an integer

89

-- value. Return nil if there is no current target.

90

--

91

-- Example:

92

-- local targetCurrentHealth = MobHealth_GetTargetCurHP();

93

-- if targetCurrentHealth then

94

-- .......

95

-- end

96

-----------------------------------------------------------------------------

97

-

98

-----------------------------------------------------------------------------

99

-- function MobHealth_GetTargetMaxHP()

100

--

101

-- Return maximum health points value for the current target as an integer

102

-- value. Return nil if there is no current target.

103

--

104

-- Example:

105

-- local targetMaxHealth = MobHealth_GetTargetMaxHP();

106

-- if targetMaxHealth then

107

-- .......

108

-- end

109

-----------------------------------------------------------------------------

110

--

111

-----------------------------------------------------------------------------

112

-- function MobHealth_PPP( index )

113

--

114

-- Return the Points-Per-Percent (PPP) value for a Mob identified by its index.

115

-- The index is the concatination of the Mob name and the Mob level (see

116

-- example below). 0 is returned if the PPP value is not available for

117

-- the given index. The example also shows how to calculate the actual

118

-- health points from the health percentage and the PPP value

119

--

120

-- Example:

121

-- local name = UnitName("target");

122

-- local level = UnitLevel("target");

123

-- local index = name..":"..level;

124

-- local ppp = MobHealth_PPP( index );

125

-- local healthPercent = UnitHealth("target");

126

-- local curHealth = math.floor( healthPercent * ppp + 0.5);

127

-- local maxHealth = math.floor( 100 * ppp + 0.5);

128

-----------------------------------------------------------------------------

129

--

130

-- ==========================================================================

131

132

133

-- ==========================================================================

134

-- Section 3 : Functions for accessing ALL MobInfo data

135

-- ==========================================================================

136

--

137

-- Please ALWAYS use these functions for accessing the data in the MobInfo

138

-- database. This is the only safe and reliable way to access the MobInfo

139

-- data. For reasons of optimisation or extension the database variable(s)

140

-- might change spontaneously in layout and/or name. Using the interface

141

-- functions gives you the guarantee that you always get returned the

142

-- correct data.

143

--

144

-----------------------------------------------------------------------------

145

-- MI2_GetMobData( mobName, mobLevel [, unitId] )

146

--

147

-- Get and return all the data that MobInfo knows about a given mob.

148

-- This is an externally available interface function that can be

149

-- called by other AddOns to access MobInfo data. It should be fast,

150

-- efficient, and easy to use

151

--

152

-- The data describing a Mob is returned in table form as described below.

153

--

154

-- To identify the mob you must supply its name and level. You can

155

-- optionally supply a "unitId" to get additional info:

156

-- mobName : name of mob, eg. "Forest Lurker"

157

-- mobLevel : mob level as integer number

158

-- unitId : optional WoW unit identification, should be either

159

-- "target" or "mouseover"

160

--

161

-- Examples:

162

-- A. mobData = MI2_GetMobData( "Forest Lurker", 10 )

163

-- B. mobData = MI2_GetMobData( "Forest Lurker", 10, "target" )

164

--

165

-- Return Value:

166

-- The return value is a LUA table with one table entry for each value that

167

-- MobInfo can know about a Mob. Note that table entries exist ONLY if the

168

-- corresponding value has actually been collected for the given Mob.

169

-- Unrecorded values do NOT exist in the table and thus evaluate to a NIL

170

-- expression.

171

--

172

-- Values you can get without "unitId" (as per Example A above):

173

-- mobData.healthMax : health maximum

174

-- mobData.xp : experience value

175

-- mobData.kills : number of times current player has killed this mob

176

-- mobData.minDamage : minimum damage done by mob

177

-- mobData.maxDamage : maximum damage done by mob

178

-- mobData.dps : dps of Mon against current player

179

-- mobData.loots : number of times this mob has been looted

180

-- mobData.emptyLoots : number of times this mob gave empty loot

181

-- mobData.clothCount : number of times this mob gave cloth loot

182

-- mobData.copper : total money loot of this mob as copper amount

183

-- mobData.itemValue : total item value loot of this mob as copper amount

184

-- mobData.mobType : mob type for special mobs: 1=normal, 2=rare/elite, 3=boss

185

-- mobData.r1 : number of rarity 1 loot items (grey)

186

-- mobData.r2 : number of rarity 2 loot items (white)

187

-- mobData.r3 : number of rarity 3 loot items (green)

188

-- mobData.r4 : number of rarity 4 loot items (blue)

189

-- mobData.r5 : number of rarity 5 loot items (purple)

190

-- mobData.itemList : table that lists all recorded items looted from this mob

191

-- table entry index gives WoW item ID,

192

-- table entry value gives item amount

193

--

194

-- Additional values you will get with "unitId" (as per Example B above):

195

-- mobData.class : class of mob as localized text

196

-- mobData.healthCur : current health of given unit

197

-- mobData.manaCur : current mana of given unit

198

-- mobData.manaMax : maximum mana for given unit

--

-- Code Example:

--

-- local mobData = MI2_GetMobData( "Forest Lurker", 10 )

203

--

204

-- if mobData.xp then

205

-- DEFAULT_CHAT_FRAME:AddMessage( "XP = "..mobData.xp )

206

-- end

207

--

208

-- if mobData.copper and mobData.loots then

209

-- local avgLoot = mobData.copper / mobData.loots

210

-- DEFAULT_CHAT_FRAME:AddMessage( "average loot = "..avgLoot )

211

-- end

212

-----------------------------------------------------------------------------

213

--

214

-- ==========================================================================

215

216

217

-- ==========================================================================

218

-- Section 4 : Free Source Code for Accessing MobHealth in a Compatible Way

219

-- ==========================================================================

220

--

221

-- Simply copy the entire 3 function source code given below into your own

222

-- AddOn and then call the 3 functions whenever you have to access MobHealth

-- data.

--

-----------------------------------------------------------------------------

228

-- My_MobHealth_PPP( index )

229

--

230

-- Return the Points-Per-Percent (PPP) value for a Mob identified by its index.

231

-- The index is the concatination of the Mob name and the Mob level (see

232

-- example below). 0 is returned if the PPP value is not available for

233

-- the given index. The example also shows how to calculate the actual

234

-- health points from the health percentage and the PPP value

235

--

236

-- Example:

237

-- local name = UnitName("target");

238

-- local level = UnitLevel("target");

239

-- local index = name..":"..level;

240

-- local ppp = MobHealth_PPP( index );

241

-- local healthPercent = UnitHealth("target");

242

-- local curHealth = math.floor( healthPercent * ppp + 0.5);

243

-- local maxHealth = math.floor( 100 * ppp + 0.5);

244

-----------------------------------------------------------------------------

245

local function My_MobHealth_PPP( index )

246

if MobHealth_PPP then

247

return MobHealth_PPP( index );

248

else

249

if( index and MobHealthDB[index] ) then

250

local s, e, pts, pct = string.find(MobHealthDB[index], "^(%d+)/(%d+)$");

251

if( pts and pct ) then

252

pts = pts + 0;

253

pct = pct + 0;

254

if( pct ~= 0 ) then

return pts / pct;

end

end

end

return 0;

end

end -- of My_MobHealth_PPP

262

263

264

-----------------------------------------------------------------------------

265

-- My_MobHealth_GetTargetCurHP()

266

--

267

-- Return current health points value for the current target as an integer

268

-- value. Return nil if there is no current target.

269

--

270

-- Example:

271

-- local targetCurrentHealth = MobHealth_GetTargetCurHP();

272

-- if targetCurrentHealth then

273

-- .......

274

-- end

275

-----------------------------------------------------------------------------

276

local function My_MobHealth_GetTargetCurHP()

277

if MobHealth_GetTargetCurHP then

278

return MobHealth_GetTargetCurHP();

279

else

280

local name = UnitName("target");

281

local level = UnitLevel("target");

282

local healthPercent = UnitHealth("target");

283

if name and level and healthPercent then

284

local index = name..":"..level;

285

local ppp = MobHealth_PPP( index );

286

return math.floor( healthPercent * ppp + 0.5);

end

end

return 0;

end -- of My_MobHealth_GetTargetCurHP()

291

292

293

-----------------------------------------------------------------------------

294

-- My_MobHealth_GetTargetMaxHP()

295

--

296

-- Return maximum health points value for the current target as an integer

297

-- value. Return nil if there is no current target.

298

--

299

-- Example:

300

-- local targetMaxHealth = MobHealth_GetTargetMaxHP();

301

-- if targetMaxHealth then

302

-- .......

303

-- end

304

-----------------------------------------------------------------------------

305

local function My_MobHealth_GetTargetMaxHP()

306

if MobHealth_GetTargetMaxHP then

307

return MobHealth_GetTargetMaxHP();

308

else

309

local name = UnitName("target");

310

local level = UnitLevel("target");

311

if name and level then

312

local index = name..":"..level;

313

local ppp = MobHealth_PPP( index );

314

return math.floor( 100 * ppp + 0.5);

end

end

return 0;

end -- of My_MobHealth_GetTargetMaxHP()

319

320

--

321

-- ==========================================================================

vanilla-wow-addons – Blame information for rev 1