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.
486 * @param entity Entity/edict index.
487 * @param type Property type.
488 * @param prop Property name.
489 * @param size Number of bytes to write (valid values are 1, 2, or 4).
490 * This value is auto-detected, and the size parameter is
491 * only used as a fallback in case detection fails.
492 * @return Value at the given property offset.
493 * @error Invalid entity or property not found.
495 native GetEntProp(entity, PropType:type, const String:prop[], size=4);
498 * Sets an integer value in an entity's property.
500 * This function is considered safer and more robust over SetEntData,
501 * because it performs strict offset checking and typing rules.
503 * @param entity Entity/edict index.
504 * @param type Property type.
505 * @param prop Property name.
506 * @param size Number of bytes to write (valid values are 1, 2, or 4).
507 * This value is auto-detected, and the size parameter is
508 * only used as a fallback in case detection fails.
509 * @error Invalid entity or offset out of reasonable bounds.
512 native SetEntProp(entity, PropType:type, const String:prop[], any:value, size=4);
515 * Retrieves a float value from an entity's property.
517 * This function is considered safer and more robust over GetEntDataFloat,
518 * because it performs strict offset checking and typing rules.
520 * @param entity Entity/edict index.
521 * @param type Property type.
522 * @param prop Property name.
523 * @return Value at the given property offset.
524 * @error Invalid entity or offset out of reasonable bounds.
526 native Float:GetEntPropFloat(entity, PropType:type, const String:prop[]);
529 * Sets a float value in an entity's property.
531 * This function is considered safer and more robust over SetEntDataFloat,
532 * because it performs strict offset checking and typing rules.
534 * @param entity Entity/edict index.
535 * @param type Property type.
536 * @param prop Property name.
537 * @param value Value to set.
539 * @error Invalid entity or offset out of reasonable bounds.
541 native SetEntPropFloat(entity, PropType:type, const String:prop[], Float:value);
544 * Retrieves an entity index from an entity's property.
546 * This function is considered safer and more robust over GetEntDataEnt*,
547 * because it performs strict offset checking and typing rules.
549 * @param entity Entity/edict index.
550 * @param type Property type.
551 * @param prop Property name.
552 * @return Entity index at the given property.
553 * If there is no entity, or the entity is not valid,
554 * then -1 is returned.
555 * @error Invalid entity or offset out of reasonable bounds.
557 native GetEntPropEnt(entity, PropType:type, const String:prop[]);
560 * Sets an entity index in an entity's property.
562 * This function is considered safer and more robust over SetEntDataEnt*,
563 * because it performs strict offset checking and typing rules.
565 * @param entity Entity/edict index.
566 * @param type Property type.
567 * @param prop Property name.
568 * @param other Entity index to set, or -1 to unset.
570 * @error Invalid entity or offset out of reasonable bounds.
572 native SetEntPropEnt(entity, PropType:type, const String:prop[], other);
575 * Retrieves a vector of floats from an entity, given a named network property.
577 * This function is considered safer and more robust over GetEntDataVector,
578 * because it performs strict offset checking and typing rules.
580 * @param entity Entity/edict index.
581 * @param type Property type.
582 * @param prop Property name.
583 * @param vec Vector buffer to store data in.
585 * @error Invalid entity, property not found, or property not
586 * actually a vector data type.
588 native GetEntPropVector(entity, PropType:type, const String:prop[], Float:vec[3]);
591 * Sets a vector of floats in an entity, given a named network property.
593 * This function is considered safer and more robust over SetEntDataVector,
594 * because it performs strict offset checking and typing rules.
596 * @param entity Entity/edict index.
597 * @param type Property type.
598 * @param prop Property name.
599 * @param vec Vector to set.
601 * @error Invalid entity, property not found, or property not
602 * actually a vector data type.
604 native SetEntPropVector(entity, PropType:type, const String:prop[], const Float:vec[3]);
607 * Gets a network property as a string.
609 * @param entity Edict index.
610 * @param type Property type.
611 * @param prop Property to use.
612 * @param buffer Destination string buffer.
613 * @param maxlen Maximum length of output string buffer.
614 * @return Number of non-null bytes written.
615 * @error Invalid entity, offset out of reasonable bounds, or property is not a valid string.
617 native GetEntPropString(entity, PropType:type, const String:prop[], String:buffer[], maxlen);
620 * Sets a network property as a string.
622 * This cannot set property fields of type PropField_String_T (such as "m_target").
623 * To set such fields, you should use DispatchKeyValue() from SDKTools.
625 * @param entity Edict index.
626 * @param type Property type.
627 * @param prop Property to use.
628 * @param buffer String to set.
629 * @return Number of non-null bytes written.
630 * @error Invalid entity, offset out of reasonable bounds, or property is not a valid string.
632 native SetEntPropString(entity, PropType:type, const String:prop[], const String:buffer[]);
635 * Copies an array of cells from an entity at a given offset.
637 * @param entity Entity index.
638 * @param offset Offset to use.
639 * @param array Array to read into.
640 * @param arraySize Number of values to read.
641 * @param dataSize Size of each value in bytes (1, 2, or 4).
643 * @error Invalid entity or offset out of reasonable bounds.
645 stock GetEntDataArray(entity, offset, array[], arraySize, dataSize=4)
647 for (new i=0; i<arraySize; i++)
649 array[i] = GetEntData(entity, offset + i*dataSize, dataSize)
654 * Copies an array of cells to an entity at a given offset.
656 * @param entity Entity index.
657 * @param offset Offset to use.
658 * @param array Array of values to copy.
659 * @param arraySize Number of values to copy.
660 * @param dataSize Size of each value in bytes (1, 2, or 4).
661 * @param changeState True to set the network state as changed; false otherwise.
663 * @error Invalid entity or offset out of reasonable bounds.
665 stock SetEntDataArray(entity, offset, const array[], arraySize, dataSize=4, bool:changeState=false)
667 for (new i=0; i<arraySize; i++)
669 SetEntData(entity, offset + i*dataSize, array[i], dataSize, changeState);
