3 * =============================================================================
4 * SourceMod (C)2004-2011 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 value Value to set.
230 * @param size Number of bytes to write (valid values are 1, 2, or 4).
231 * @param changeState If true, change will be sent over the network.
232 * @return Value at the given memory location.
233 * @error Invalid entity or offset out of reasonable bounds.
236 native SetEntData(entity, offset, any:value, size=4, bool:changeState=false);
239 * Peeks into an entity's object data and retrieves the float value at
242 * @param entity Edict index.
243 * @param offset Offset to use.
244 * @return Value at the given memory location.
245 * @error Invalid entity or offset out of reasonable bounds.
247 native Float:GetEntDataFloat(entity, offset);
250 * Peeks into an entity's object data and sets the float value at
253 * @param entity Edict index.
254 * @param offset Offset to use.
255 * @param value Value to set.
256 * @param changeState If true, change will be sent over the network.
257 * @return Value at the given memory location.
258 * @error Invalid entity or offset out of reasonable bounds.
261 native SetEntDataFloat(entity, offset, Float:value, bool:changeState=false);
264 * This function is deprecated. Use GetEntDataEnt2 instead, for
265 * reasons explained in the notes.
267 * Note: This function returns 0 on failure, which may be misleading,
268 * as the number 0 is also used for the world entity index.
270 * Note: This function makes no attempt to validate the returned
271 * entity, and in fact, it could be garbage or completely unexpected.
273 * @param entity Edict index.
274 * @param offset Offset to use.
275 * @return Entity index at the given location, or 0 if none.
276 * @error Invalid entity or offset out of reasonable bounds.
278 #pragma deprecated Use GetEntDataEnt2() instead.
279 native GetEntDataEnt(entity, offset);
282 * This function is deprecated. Use SetEntDataEnt2 instead, for
283 * reasons explained in the notes.
285 * Note: This function uses 0 as an indicator to unset data, but
286 * 0 is also the world entity index. Thus, a property cannot
287 * be set to the world entity using this native.
289 * @param entity Edict index.
290 * @param offset Offset to use.
291 * @param other Entity index to set, or 0 to clear.
292 * @param changeState If true, change will be sent over the network.
294 * @error Invalid entity or offset out of reasonable bounds.
296 #pragma deprecated Use SetEntDataEnt2() instead.
297 native SetEntDataEnt(entity, offset, other, bool:changeState=false);
300 * Peeks into an entity's object data and retrieves the entity index
301 * at the given offset.
303 * Note: This will only work on offsets that are stored as "entity
304 * handles" (which usually looks like m_h* in properties). These
305 * are not SourceMod Handles, but internal Source structures.
307 * @param entity Edict index.
308 * @param offset Offset to use.
309 * @return Entity index at the given location. If there is no entity,
310 * or the stored entity is invalid, then -1 is returned.
311 * @error Invalid input entity, or offset out of reasonable bounds.
313 native GetEntDataEnt2(entity, offset);
316 * Peeks into an entity's object data and sets the entity index at the
319 * Note: This will only work on offsets that are stored as "entity
320 * handles" (which usually looks like m_h* in properties). These
321 * are not SourceMod Handles, but internal Source structures.
323 * @param entity Edict index.
324 * @param offset Offset to use.
325 * @param other Entity index to set, or -1 to clear.
326 * @param changeState If true, change will be sent over the network.
328 * @error Invalid input entity, or offset out of reasonable bounds.
330 native SetEntDataEnt2(entity, offset, other, bool:changeState=false);
333 * Peeks into an entity's object data and retrieves the vector at the
335 * @note Both a Vector and a QAngle are three floats. This is a
336 * convenience function and will work with both types.
338 * @param entity Edict index.
339 * @param offset Offset to use.
340 * @param vec Vector buffer to store data in.
342 * @error Invalid entity or offset out of reasonable bounds.
344 native GetEntDataVector(entity, offset, Float:vec[3]);
347 * Peeks into an entity's object data and sets the vector at the given
349 * @note Both a Vector and a QAngle are three floats. This is a
350 * convenience function and will work with both types.
352 * @param entity Edict index.
353 * @param offset Offset to use.
354 * @param vec Vector to set.
355 * @param changeState If true, change will be sent over the network.
357 * @error Invalid entity or offset out of reasonable bounds.
359 native SetEntDataVector(entity, offset, const Float:vec[3], bool:changeState=false);
362 * Peeks into an entity's object data and retrieves the string at
365 * @param entity Edict index.
366 * @param offset Offset to use.
367 * @param buffer Destination string buffer.
368 * @param maxlen Maximum length of output string buffer.
369 * @return Number of non-null bytes written.
370 * @error Invalid entity or offset out of reasonable bounds.
372 native GetEntDataString(entity, offset, String:buffer[], maxlen);
375 * Peeks into an entity's object data and sets the string at
378 * @param entity Edict index.
379 * @param offset Offset to use.
380 * @param buffer String to set.
381 * @param maxlen Maximum length of bytes to write.
382 * @param changeState If true, change will be sent over the network.
383 * @return Number of non-null bytes written.
384 * @error Invalid entity or offset out of reasonable bounds.
386 native SetEntDataString(entity, offset, const String:buffer[], maxlen, bool:changeState=false);
393 * Given a ServerClass name, finds a networkable send property offset.
394 * This information is cached for future calls.
396 * Note, this function may return offsets that do not work!
397 * If a property is nested beneath a parent object, the resulting offset
398 * will be invalid for direct use with data functions. Therefore, you
399 * should use FindSendPropInfo() instead. An example of such a property is
400 * CTFPlayer::DT_LocalPlayer.m_nDisguiseClass on Team Fortress.
402 * @param cls Classname.
403 * @param prop Property name.
404 * @return An offset, or -1 on failure.
406 native FindSendPropOffs(const String:cls[], const String:prop[]);
409 * Given a ServerClass name, finds a networkable send property offset.
410 * This information is cached for future calls.
412 * Note: This function will correctly compute nested offsets, unlike
413 * FindSendPropOffs(). YOU SHOULD NOT use this function to self-compute
414 * nested offsets. For example, it is okay to add indexes for arrays,
415 * but not to add DT_LocalPlayer to m_nDisguiseClass.
417 * @param cls Classname.
418 * @param prop Property name.
419 * @param type Optional parameter to store the type.
420 * @param num_bits Optional parameter to store the number of bits the field
421 * uses, if applicable (otherwise 0 is stored). The number
422 * of bits varies for integers and floats, and is always 0
424 * @param local_offset Optional parameter to store the local offset, as
425 * FindSendPropOffs() would return.
426 * @return On success, returns an absolutely computed offset.
427 * If no offset is available, 0 is returned.
428 * If the property is not found, -1 is returned.
430 native FindSendPropInfo(const String:cls[],
432 &PropFieldType:type=PropFieldType:0,
437 * Given an entity, finds a datamap property offset.
438 * This information is cached for future calls.
440 * @param entity Entity index.
441 * @param prop Property name.
442 * @param type Optional parameter to store the type.
443 * @param num_bits Optional parameter to store the number of bits the field
444 * uses. The bit count will either be 1 (for boolean) or
445 * divisible by 8 (including 0 if unknown).
446 * @return An offset, or -1 on failure.
448 native FindDataMapOffs(entity,
450 &PropFieldType:type=PropFieldType:0,
454 * Given an entity, finds a nested datamap property offset.
455 * This information is cached for future calls.
457 * @param entity Entity index.
458 * @param prop Property name.
459 * @param type Optional parameter to store the type.
460 * @param num_bits Optional parameter to store the number of bits the field
461 * uses. The bit count will either be 1 (for boolean) or
462 * divisible by 8 (including 0 if unknown).
463 * @param local_offset Optional parameter to store the local offset, as
464 * FindDataMapOffs() would return.
465 * @return An offset, or -1 on failure.
467 native FindDataMapInfo(entity,
469 &PropFieldType:type=PropFieldType:0,
474 * Wrapper function for finding a send property for a particular entity.
476 * @param ent Entity index.
477 * @param prop Property name.
478 * @param actual Defaults to false for backwards compatibility.
479 * If true, the newer FindSendPropInfo() function
481 * @return An offset, or -1 on failure.
483 stock GetEntSendPropOffs(ent, const String:prop[], bool:actual=false)
487 if (!GetEntityNetClass(ent, cls, sizeof(cls)))
494 return FindSendPropInfo(cls, prop);
498 return FindSendPropOffs(cls, prop);
503 * Retrieves an integer value from an entity's property.
505 * This function is considered safer and more robust over GetEntData,
506 * because it performs strict offset checking and typing rules.
508 * @param entity Entity/edict index.
509 * @param type Property type.
510 * @param prop Property name.
511 * @param size Number of bytes to write (valid values are 1, 2, or 4).
512 * This value is auto-detected, and the size parameter is
513 * only used as a fallback in case detection fails.
514 * @param element Element # (starting from 0) if property is an array.
515 * @return Value at the given property offset.
516 * @error Invalid entity or property not found.
518 native GetEntProp(entity, PropType:type, const String:prop[], size=4, element=0);
521 * Sets an integer value in an entity's property.
523 * This function is considered safer and more robust over SetEntData,
524 * because it performs strict offset checking and typing rules.
526 * @param entity Entity/edict index.
527 * @param type Property type.
528 * @param prop Property name.
529 * @param value Value to set.
530 * @param size Number of bytes to write (valid values are 1, 2, or 4).
531 * This value is auto-detected, and the size parameter is
532 * only used as a fallback in case detection fails.
533 * @param element Element # (starting from 0) if property is an array.
534 * @error Invalid entity or offset out of reasonable bounds.
537 native SetEntProp(entity, PropType:type, const String:prop[], any:value, size=4, element=0);
540 * Retrieves a float value from an entity's property.
542 * This function is considered safer and more robust over GetEntDataFloat,
543 * because it performs strict offset checking and typing rules.
545 * @param entity Entity/edict index.
546 * @param type Property type.
547 * @param prop Property name.
548 * @param element Element # (starting from 0) if property is an array.
549 * @return Value at the given property offset.
550 * @error Invalid entity or offset out of reasonable bounds.
552 native Float:GetEntPropFloat(entity, PropType:type, const String:prop[], element=0);
555 * Sets a float value in an entity's property.
557 * This function is considered safer and more robust over SetEntDataFloat,
558 * because it performs strict offset checking and typing rules.
560 * @param entity Entity/edict index.
561 * @param type Property type.
562 * @param prop Property name.
563 * @param value Value to set.
564 * @param element Element # (starting from 0) if property is an array.
566 * @error Invalid entity or offset out of reasonable bounds.
568 native SetEntPropFloat(entity, PropType:type, const String:prop[], Float:value, element=0);
571 * Retrieves an entity index from an entity's property.
573 * This function is considered safer and more robust over GetEntDataEnt*,
574 * because it performs strict offset checking and typing rules.
576 * @param entity Entity/edict index.
577 * @param type Property type.
578 * @param prop Property name.
579 * @param element Element # (starting from 0) if property is an array.
580 * @return Entity index at the given property.
581 * If there is no entity, or the entity is not valid,
582 * then -1 is returned.
583 * @error Invalid entity or offset out of reasonable bounds.
585 native GetEntPropEnt(entity, PropType:type, const String:prop[], element=0);
588 * Sets an entity index in an entity's property.
590 * This function is considered safer and more robust over SetEntDataEnt*,
591 * because it performs strict offset checking and typing rules.
593 * @param entity Entity/edict index.
594 * @param type Property type.
595 * @param prop Property name.
596 * @param other Entity index to set, or -1 to unset.
597 * @param element Element # (starting from 0) if property is an array.
599 * @error Invalid entity or offset out of reasonable bounds.
601 native SetEntPropEnt(entity, PropType:type, const String:prop[], other, element=0);
604 * Retrieves a vector of floats from an entity, given a named network property.
606 * This function is considered safer and more robust over GetEntDataVector,
607 * because it performs strict offset checking and typing rules.
609 * @param entity Entity/edict index.
610 * @param type Property type.
611 * @param prop Property name.
612 * @param vec Vector buffer to store data in.
613 * @param element Element # (starting from 0) if property is an array.
615 * @error Invalid entity, property not found, or property not
616 * actually a vector data type.
618 native GetEntPropVector(entity, PropType:type, const String:prop[], Float:vec[3], element=0);
621 * Sets a vector of floats in an entity, given a named network property.
623 * This function is considered safer and more robust over SetEntDataVector,
624 * because it performs strict offset checking and typing rules.
626 * @param entity Entity/edict index.
627 * @param type Property type.
628 * @param prop Property name.
629 * @param vec Vector to set.
630 * @param element Element # (starting from 0) if property is an array.
632 * @error Invalid entity, property not found, or property not
633 * actually a vector data type.
635 native SetEntPropVector(entity, PropType:type, const String:prop[], const Float:vec[3], element=0);
638 * Gets a network property as a string.
640 * @param entity Edict index.
641 * @param type Property type.
642 * @param prop Property to use.
643 * @param buffer Destination string buffer.
644 * @param maxlen Maximum length of output string buffer.
645 * @param element Element # (starting from 0) if property is an array.
646 * @return Number of non-null bytes written.
647 * @error Invalid entity, offset out of reasonable bounds, or property is not a valid string.
649 native GetEntPropString(entity, PropType:type, const String:prop[], String:buffer[], maxlen, element=0);
652 * Sets a network property as a string.
654 * This cannot set property fields of type PropField_String_T (such as "m_target").
655 * To set such fields, you should use DispatchKeyValue() from SDKTools.
657 * @param entity Edict index.
658 * @param type Property type.
659 * @param prop Property to use.
660 * @param buffer String to set.
661 * @return Number of non-null bytes written.
662 * @error Invalid entity, offset out of reasonable bounds, or property is not a valid string.
664 native SetEntPropString(entity, PropType:type, const String:prop[], const String:buffer[]);
667 * Retrieves the count of values that an entity property's array can store.
669 * @param entity Entity/edict index.
670 * @param type Property type.
671 * @param prop Property name.
672 * @return Size of array (in elements) or 1 if property is not an array.
673 * @error Invalid entity or property not found.
675 native GetEntPropArraySize(entity, PropType:type, const String:prop[]);
678 * Copies an array of cells from an entity at a given offset.
680 * @param entity Entity index.
681 * @param offset Offset to use.
682 * @param array Array to read into.
683 * @param arraySize Number of values to read.
684 * @param dataSize Size of each value in bytes (1, 2, or 4).
686 * @error Invalid entity or offset out of reasonable bounds.
688 stock GetEntDataArray(entity, offset, array[], arraySize, dataSize=4)
690 for (new i=0; i<arraySize; i++)
692 array[i] = GetEntData(entity, offset + i*dataSize, dataSize)
697 * Copies an array of cells to an entity at a given offset.
699 * @param entity Entity index.
700 * @param offset Offset to use.
701 * @param array Array of values to copy.
702 * @param arraySize Number of values to copy.
703 * @param dataSize Size of each value in bytes (1, 2, or 4).
704 * @param changeState True to set the network state as changed; false otherwise.
706 * @error Invalid entity or offset out of reasonable bounds.
708 stock SetEntDataArray(entity, offset, const array[], arraySize, dataSize=4, bool:changeState=false)
710 for (new i=0; i<arraySize; i++)
712 SetEntData(entity, offset + i*dataSize, array[i], dataSize, changeState);
717 * Gets the memory address of an entity.
719 * @param entity Entity index.
720 * @return Address of the entity.
721 * @error Invalid entity.
723 native Address:GetEntityAddress(entity);
726 * Retrieves the classname of an entity.
727 * This is like GetEdictClassname(), except it works for ALL
728 * entities, not just edicts.
730 * @param entity Index of the entity.
731 * @param clsname Buffer to store the classname.
732 * @param maxlength Maximum length of the buffer.
733 * @return True on success, false if there is no classname set.
735 stock bool:GetEntityClassname(entity, String:clsname[], maxlength)
737 return !!GetEntPropString(entity, Prop_Data, "m_iClassname", clsname, maxlength);
