3 * =============================================================================
4 * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
5 * =============================================================================
7 * This file is part of the SourceMod/SourcePawn SDK.
9 * This program is free software; you can redistribute it and/or modify it under
10 * the terms of the GNU General Public License, version 3.0, as published by the
11 * Free Software Foundation.
13 * This program is distributed in the hope that it will be useful, but WITHOUT
14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
18 * You should have received a copy of the GNU General Public License along with
19 * this program. If not, see <http://www.gnu.org/licenses/>.
21 * As a special exception, AlliedModders LLC gives you permission to link the
22 * code of this program (as well as its derivative works) to "Half-Life 2," the
23 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
24 * by the Valve Corporation. You must obey the GNU General Public License in
25 * all respects for all other code used. Additionally, AlliedModders LLC grants
26 * this exception to all derivative works. AlliedModders LLC defines further
27 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
28 * or <http://www.sourcemod.net/license.php>.
33 #if defined _entity_included
36 #define _entity_included
39 * Property types for entities.
43 Prop_Send = 0, /**< This property is networked. */
44 Prop_Data = 1, /**< This property is for save game data fields. */
48 * @section For more information on these, see the HL2SDK (public/edict.h)
50 #define FL_EDICT_CHANGED (1<<0) /**< Game DLL sets this when the entity state changes
51 Mutually exclusive with FL_EDICT_PARTIAL_CHANGE. */
52 #define FL_EDICT_FREE (1<<1) /**< this edict if free for reuse */
53 #define FL_EDICT_FULL (1<<2) /**< this is a full server entity */
54 #define FL_EDICT_FULLCHECK (0<<0) /**< call ShouldTransmit() each time, this is a fake flag */
55 #define FL_EDICT_ALWAYS (1<<3) /**< always transmit this entity */
56 #define FL_EDICT_DONTSEND (1<<4) /**< don't transmit this entity */
57 #define FL_EDICT_PVSCHECK (1<<5) /**< always transmit entity, but cull against PVS */
58 #define FL_EDICT_PENDING_DORMANT_CHECK (1<<6)
59 #define FL_EDICT_DIRTY_PVS_INFORMATION (1<<7)
60 #define FL_FULL_EDICT_CHANGED (1<<8)
64 PropField_Unsupported, /**< The type is unsupported. */
65 PropField_Integer, /**< Valid for SendProp and Data fields */
66 PropField_Float, /**< Valid for SendProp and Data fields */
67 PropField_Entity, /**< Valid for Data fields only (SendProp shows as int) */
68 PropField_Vector, /**< Valid for SendProp and Data fields */
69 PropField_String, /**< Valid for SendProp and Data fields */
70 PropField_String_T, /**< Valid for Data fields. Read only.
71 Note that the size of a string_t is dynamic, and
72 thus FindDataMapOffs() will return the constant size
73 of the string_t container (which is 32 bits right now).
82 * Returns the maximum number of entities.
84 * @return Maximum number of entities.
86 native GetMaxEntities();
89 * Returns the number of entities in the server.
91 * @return Number of entities in the server.
93 native GetEntityCount();
96 * Returns whether or not an entity is valid. Returns false
97 * if there is no matching CBaseEntity for this edict index.
99 * @param edict Index of the entity/edict.
100 * @return True if valid, false otherwise.
102 native bool:IsValidEntity(edict);
105 * Returns whether or not an edict index is valid.
107 * @param edict Index of the edict.
108 * @return True if valid, false otherwise.
110 native bool:IsValidEdict(edict);
113 * Returns whether or not an entity is a valid networkable edict.
115 * @param edict Index of the edict.
116 * @return True if networkable, false if invalid or not networkable.
118 native bool:IsEntNetworkable(edict);
121 * Creates a new edict (the basis of a networkable entity)
123 * @return Index of the edict, 0 on failure.
125 native CreateEdict();
128 * Removes an edict from the world.
130 * @param edict Index of the edict.
132 * @error Invalid edict index.
134 native RemoveEdict(edict);
137 * Returns the flags on an edict. These are not the same as entity flags.
139 * @param edict Index of the entity.
140 * @return Edict flags.
141 * @error Invalid edict index.
143 native GetEdictFlags(edict);
146 * Sets the flags on an edict. These are not the same as entity flags.
148 * @param edict Index of the entity.
149 * @param flags Flags to set.
151 * @error Invalid edict index.
153 native SetEdictFlags(edict, flags);
156 * Retrieves an edict classname.
158 * @param edict Index of the entity.
159 * @param clsname Buffer to store the classname.
160 * @param maxlength Maximum length of the buffer.
161 * @return True on success, false if there is no classname set.
163 native bool:GetEdictClassname(edict, String:clsname[], maxlength);
166 * Retrieves an entity's networkable serverclass name.
167 * This is not the same as the classname and is used for networkable state changes.
169 * @param edict Index of the entity.
170 * @param clsname Buffer to store the serverclass name.
171 * @param maxlength Maximum lnegth of the buffer.
172 * @return True on success, false if the edict is not networkable.
173 * @error Invalid edict index.
175 native bool:GetEntityNetClass(edict, String:clsname[], maxlength);
178 * @section Entity offset functions
180 * Offsets should be specified in byte distance from the CBaseEntity
181 * structure, not short (double byte) or integer (four byte) multiples.
182 * It is somewhat common practice to use offsets aligned to their final
183 * type, and thus make sure you are not falling to this error in SourceMod.
184 * For example, if your "integer-aligned" offset was 119, your byte-aligned
185 * offset is 119*4, or 476.
187 * Specifying incorrect offsets or the incorrect data type for an offset
188 * can have fatal consequences. If you are hardcoding offsets, and the
189 * layout of CBaseEntity does not match, you can easily crash the server.
191 * The reasonable bounds for offsets is greater than or equal to 0 and
192 * below 32768. Offsets out of these bounds will throw an error. However,
193 * this does not represent any real range, it is simply a sanity check for
194 * illegal values. Any range outside of the CBaseEntity structure's private
195 * size will cause undefined behaviour or even crash.
199 * Marks an entity as state changed. This can be useful if you set an offset
200 * and wish for it to be immediately changed over the network. By default this
201 * is not done for offset setting functions.
203 * @param edict Index to the edict.
204 * @param offset Offset to mark as changed. If 0,
205 * the entire edict is marked as changed.
207 * @error Invalid entity or offset out of bounds.
209 native ChangeEdictState(edict, offset = 0);
212 * Peeks into an entity's object data and retrieves the integer value at
215 * @param entity Edict index.
216 * @param offset Offset to use.
217 * @param size Number of bytes to read (valid values are 1, 2, or 4).
218 * @return Value at the given memory location.
219 * @error Invalid entity or offset out of reasonable bounds.
221 native GetEntData(entity, offset, size=4);
224 * Peeks into an entity's object data and sets the integer value at
227 * @param entity Edict index.
228 * @param offset Offset to use.
229 * @param size Number of bytes to write (valid values are 1, 2, or 4).
230 * @param changeState If true, change will be sent over the network.
231 * @return Value at the given memory location.
232 * @error Invalid entity or offset out of reasonable bounds.
235 native SetEntData(entity, offset, any:value, size=4, bool:changeState=false);
238 * Peeks into an entity's object data and retrieves the float value at
241 * @param entity Edict index.
242 * @param offset Offset to use.
243 * @return Value at the given memory location.
244 * @error Invalid entity or offset out of reasonable bounds.
246 native Float:GetEntDataFloat(entity, offset);
249 * Peeks into an entity's object data and sets the integer value at
252 * @param entity Edict index.
253 * @param offset Offset to use.
254 * @param changeState If true, change will be sent over the network.
255 * @return Value at the given memory location.
256 * @error Invalid entity or offset out of reasonable bounds.
259 native SetEntDataFloat(entity, offset, Float:value, bool:changeState=false);
262 * This function is deprecated. Use GetEntDataEnt2 instead, for
263 * reasons explained in the notes.
265 * Note: This function returns 0 on failure, which may be misleading,
266 * as the number 0 is also used for the world entity index.
268 * Note: This function makes no attempt to validate the returned
269 * entity, and in fact, it could be garbage or completely unexpected.
271 * @param entity Edict index.
272 * @param offset Offset to use.
273 * @return Entity index at the given location, or 0 if none.
274 * @error Invalid entity or offset out of reasonable bounds.
276 #pragma deprecated Use GetEntDataEnt2() instead.
277 native GetEntDataEnt(entity, offset);
280 * This function is deprecated. Use SetEntDataEnt2 instead, for
281 * reasons explained in the notes.
283 * Note: This function uses 0 as an indicator to unset data, but
284 * 0 is also the world entity index. Thus, the a property cannot
285 * be set to the world entity using this native.
287 * @param entity Edict index.
288 * @param offset Offset to use.
289 * @param other Entity index to set, or 0 to clear.
290 * @param changeState If true, change will be sent over the network.
292 * @error Invalid entity or offset out of reasonable bounds.
294 #pragma deprecated Use SetEntDataEnt2() instead.
295 native SetEntDataEnt(entity, offset, other, bool:changeState=false);
298 * Peeks into an entity's object data and retrieves the entity index
299 * at the given offset.
301 * Note: This will only work on offsets that are stored as "entity
302 * handles" (which usually looks like m_h* in properties). These
303 * are not SourceMod Handles, but internal Source structures.
305 * @param entity Edict index.
306 * @param offset Offset to use.
307 * @return Entity index at the given location. If there is no entity,
308 * or the stored entity is invalid, then -1 is returned.
309 * @error Invalid input entity, or offset out of reasonable bounds.
311 native GetEntDataEnt2(entity, offset);
314 * Peeks into an entity's object data and sets the entity index at the
317 * Note: This will only work on offsets that are stored as "entity
318 * handles" (which usually looks like m_h* in properties). These
319 * are not SourceMod Handles, but internal Source structures.
321 * @param entity Edict index.
322 * @param offset Offset to use.
323 * @param other Entity index to set, or -1 to clear.
324 * @param changeState If true, change will be sent over the network.
326 * @error Invalid input entity, or offset out of reasonable bounds.
328 native SetEntDataEnt2(entity, offset, other, bool:changeState=false);
331 * Peeks into an entity's object data and retrieves the vector at the
333 * @note Both a Vector and a QAngle are three floats. This is a
334 * convenience function and will work with both types.
336 * @param entity Edict index.
337 * @param offset Offset to use.
338 * @param vec Vector buffer to store data in.
340 * @error Invalid entity or offset out of reasonable bounds.
342 native GetEntDataVector(entity, offset, Float:vec[3]);
345 * Peeks into an entity's object data and sets the vector at the given
347 * @note Both a Vector and a QAngle are three floats. This is a
348 * convenience function and will work with both types.
350 * @param entity Edict index.
351 * @param offset Offset to use.
352 * @param vec Vector to set.
353 * @param changeState If true, change will be sent over the network.
355 * @error Invalid entity or offset out of reasonable bounds.
357 native SetEntDataVector(entity, offset, const Float:vec[3], bool:changeState=false);
360 * Peeks into an entity's object data and retrieves the string at
363 * @param entity Edict index.
364 * @param offset Offset to use.
365 * @param buffer Destination string buffer.
366 * @param maxlen Maximum length of output string buffer.
367 * @return Number of non-null bytes written.
368 * @error Invalid entity or offset out of reasonable bounds.
370 native GetEntDataString(entity, offset, String:buffer[], maxlen);
373 * Peeks into an entity's object data and sets the string at
376 * @param entity Edict index.
377 * @param offset Offset to use.
378 * @param buffer String to set.
379 * @param maxlen Maximum length of bytes to write.
380 * @param changeState If true, change will be sent over the network.
381 * @return Number of non-null bytes written.
382 * @error Invalid entity or offset out of reasonable bounds.
384 native SetEntDataString(entity, offset, const String:buffer[], maxlen, bool:changeState=false);
391 * Given a ServerClass name, finds a networkable send property offset.
392 * This information is cached for future calls.
394 * Note, this function may return offsets that do not work!
395 * If a property is nested beneath a parent object, the resulting offset
396 * will be invalid for direct use with data functions. Therefore, you
397 * should use FindSendPropInfo() instead. An example of such a property is
398 * CTFPlayer::DT_LocalPlayer.m_nDisguiseClass on Team Fortress.
400 * @param cls Classname.
401 * @param prop Property name.
402 * @return An offset, or -1 on failure.
404 native FindSendPropOffs(const String:cls[], const String:prop[]);
407 * Given a ServerClass name, finds a networkable send property offset.
408 * This information is cached for future calls.
410 * Note: This function will correctly compute nested offsets, unlike
411 * FindSendPropOffs(). YOU SHOULD NOT use this function to self-compute
412 * nested offsets. For example, it is okay to add indexes for arrays,
413 * but not to add DT_LocalPlayer to m_nDisguiseClass.
415 * @param cls Classname.
416 * @param prop Property name.
417 * @param type Optional parameter to store the type.
418 * @param num_bits Optional parameter to store the number of bits the field
419 * uses, if applicable (otherwise 0 is stored). The number
420 * of bits varies for integers and floats, and is always 0
422 * @param local_offset Optional parameter to store the local offset, as
423 * FindSendPropOffs() would return.
424 * @return On success, returns an absolutely computed offset.
425 * If no offset is available, 0 is returned.
426 * If the property is not found, -1 is returned.
428 native FindSendPropInfo(const String:cls[],
430 &PropFieldType:type=PropFieldType:0,
435 * Given an entity, finds a datamap property offset.
436 * This information is cached for future calls.
438 * @param entity Entity index.
439 * @param prop Property name.
440 * @param type Optional parameter to store the type.
441 * @param num_bits Optional parameter to store the number of bits the field
442 * uses. The bit count will either be 1 (for boolean) or
443 * divisible by 8 (including 0 if unknown).
444 * @return An offset, or -1 on failure.
446 native FindDataMapOffs(entity,
448 &PropFieldType:type=PropFieldType:0,
452 * Wrapper function for finding a send property for a particular entity.
454 * @param ent Entity index.
455 * @param prop Property name.
456 * @param actual Defaults to false for backwards compatibility.
457 * If true, the newer FindSendPropInfo() function
459 * @return An offset, or -1 on failure.
461 stock GetEntSendPropOffs(ent, const String:prop[], bool:actual=false)
465 if (!GetEntityNetClass(ent, cls, sizeof(cls)))
472 return FindSendPropInfo(cls, prop);
476 return FindSendPropOffs(cls, prop);
481 * Retrieves an integer value from an entity's property.
483 * This function is considered safer and more robust over GetEntData,
484 * because it performs strict offset checking and typing rules. There is a
485 * very minor performance hit from this.
487 * @param entity Entity/edict index.
488 * @param type Property type.
489 * @param prop Property name.
490 * @param size Number of bytes to write (valid values are 1, 2, or 4).
491 * This value is auto-detected, and the size parameter is
492 * only used as a fallback in case detection fails.
493 * @return Value at the given property offset.
494 * @error Invalid entity or property not found.
496 native GetEntProp(entity, PropType:type, const String:prop[], size=4);
499 * Sets an integer value in an entity's property.
501 * This function is considered safer and more robust over SetEntData,
502 * because it performs strict offset checking and typing rules. There is a
503 * very minor performance hit from this.
505 * @param entity Entity/edict index.
506 * @param type Property type.
507 * @param prop Property name.
508 * @param size Number of bytes to write (valid values are 1, 2, or 4).
509 * This value is auto-detected, and the size parameter is
510 * only used as a fallback in case detection fails.
511 * @error Invalid entity or offset out of reasonable bounds.
514 native SetEntProp(entity, PropType:type, const String:prop[], any:value, size=4);
517 * Retrieves a float value from an entity's property.
519 * This function is considered safer and more robust over GetEntDataFloat,
520 * because it performs strict offset checking and typing rules. There is a
521 * very minor performance hit from this.
523 * @param entity Entity/edict index.
524 * @param type Property type.
525 * @param prop Property name.
526 * @return Value at the given property offset.
527 * @error Invalid entity or offset out of reasonable bounds.
529 native Float:GetEntPropFloat(entity, PropType:type, const String:prop[]);
532 * Sets a float value in an entity's property.
534 * This function is considered safer and more robust over SetEntDataFloat,
535 * because it performs strict offset checking and typing rules. There is a
536 * very minor performance hit from this.
538 * @param entity Entity/edict index.
539 * @param type Property type.
540 * @param prop Property name.
541 * @param value Value to set.
543 * @error Invalid entity or offset out of reasonable bounds.
545 native SetEntPropFloat(entity, PropType:type, const String:prop[], Float:value);
548 * Retrieves an entity index from an entity's property.
550 * This function is considered safer and more robust over GetEntDataEnt*,
551 * because it performs strict offset checking and typing rules. There is a
552 * very minor performance hit from this.
554 * @param entity Entity/edict index.
555 * @param type Property type.
556 * @param prop Property name.
557 * @return Entity index at the given property.
558 * If there is no entity, or the entity is not valid,
559 * then -1 is returned.
560 * @error Invalid entity or offset out of reasonable bounds.
562 native GetEntPropEnt(entity, PropType:type, const String:prop[]);
565 * Sets an entity index in an entity's property.
567 * This function is considered safer and more robust over SetEntDataEnt*,
568 * because it performs strict offset checking and typing rules. There is a
569 * very minor performance hit from this.
571 * @param entity Entity/edict index.
572 * @param type Property type.
573 * @param prop Property name.
574 * @param other Entity index to set, or -1 to unset.
576 * @error Invalid entity or offset out of reasonable bounds.
578 native SetEntPropEnt(entity, PropType:type, const String:prop[], other);
581 * Retrieves a vector of floats from an entity, given a named network property.
583 * This function is considered safer and more robust over GetEntDataVector,
584 * because it performs strict offset checking and typing rules. There is a
585 * very minor performance hit from this.
587 * @param entity Entity/edict index.
588 * @param type Property type.
589 * @param prop Property name.
590 * @param vec Vector buffer to store data in.
592 * @error Invalid entity, property not found, or property not
593 * actually a vector data type.
595 native GetEntPropVector(entity, PropType:type, const String:prop[], Float:vec[3]);
598 * Sets a vector of floats in an entity, given a named network property.
600 * This function is considered safer and more robust over SetEntDataVector,
601 * because it performs strict offset checking and typing rules. There is a
602 * very minor performance hit from this.
604 * @param entity Entity/edict index.
605 * @param type Property type.
606 * @param prop Property name.
607 * @param vec Vector to set.
609 * @error Invalid entity, property not found, or property not
610 * actually a vector data type.
612 native SetEntPropVector(entity, PropType:type, const String:prop[], const Float:vec[3]);
615 * Gets a network property as a string.
617 * @param entity Edict index.
618 * @param type Property type.
619 * @param prop Property to use.
620 * @param buffer Destination string buffer.
621 * @param maxlen Maximum length of output string buffer.
622 * @return Number of non-null bytes written.
623 * @error Invalid entity, offset out of reasonable bounds, or property is not a valid string.
625 native GetEntPropString(entity, PropType:type, const String:prop[], String:buffer[], maxlen);
628 * Sets a network property as a string.
630 * This cannot set property fields of type PropField_String_T (such as "m_target").
631 * To set such fields, you should use DispatchKeyValue() from SDKTools.
633 * @param entity Edict index.
634 * @param type Property type.
635 * @param prop Property to use.
636 * @param buffer String to set.
637 * @return Number of non-null bytes written.
638 * @error Invalid entity, offset out of reasonable bounds, or property is not a valid string.
640 native SetEntPropString(entity, PropType:type, const String:prop[], const String:buffer[]);
643 * Copies an array of cells from an entity at a given offset.
645 * @param entity Entity index.
646 * @param offset Offset to use.
647 * @param array Array to read into.
648 * @param arraySize Number of values to read.
649 * @param dataSize Size of each value in bytes (1, 2, or 4).
651 * @error Invalid entity or offset out of reasonable bounds.
653 stock GetEntDataArray(entity, offset, array[], arraySize, dataSize=4)
655 for (new i=0; i<arraySize; i++)
657 array[i] = GetEntData(entity, offset + i*dataSize, dataSize)
662 * Copies an array of cells to an entity at a given offset.
664 * @param entity Entity index.
665 * @param offset Offset to use.
666 * @param array Array of values to copy.
667 * @param arraySize Number of values to copy.
668 * @param dataSize Size of each value in bytes (1, 2, or 4).
669 * @param changeState True to set the network state as changed; false otherwise.
671 * @error Invalid entity or offset out of reasonable bounds.
673 stock SetEntDataArray(entity, offset, const array[], arraySize, dataSize=4, bool:changeState=false)
675 for (new i=0; i<arraySize; i++)
677 SetEntData(entity, offset + i*dataSize, array[i], dataSize, changeState);
