3 * ===============================================================
4 * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
5 * ===============================================================
7 * This file is part of the SourceMod/SourcePawn SDK. This file may only be used
8 * or modified under the Terms and Conditions of its License Agreement, which is found
9 * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins
10 * may change at any time. To view the latest information, see:
11 * http://www.sourcemod.net/license.php
16 #if defined _entity_included
19 #define _entity_included
22 * Property types for entities.
26 Prop_Send = 0, /**< This property is networked. */
27 Prop_Data = 1, /**< This property is for saved game files. */
31 * For more information on these, see the HL2SDK (public/edict.h)
33 #define FL_EDICT_CHANGED (1<<0) /**< Game DLL sets this when the entity state changes
34 Mutually exclusive with FL_EDICT_PARTIAL_CHANGE. */
35 #define FL_EDICT_FREE (1<<1) /**< this edict if free for reuse */
36 #define FL_EDICT_FULL (1<<2) /**< this is a full server entity */
37 #define FL_EDICT_FULLCHECK (0<<0) /**< call ShouldTransmit() each time, this is a fake flag */
38 #define FL_EDICT_ALWAYS (1<<3) /**< always transmit this entity */
39 #define FL_EDICT_DONTSEND (1<<4) /**< don't transmit this entity */
40 #define FL_EDICT_PVSCHECK (1<<5) /**< always transmit entity, but cull against PVS */
41 #define FL_EDICT_PENDING_DORMANT_CHECK (1<<6)
42 #define FL_EDICT_DIRTY_PVS_INFORMATION (1<<7)
43 #define FL_FULL_EDICT_CHANGED (1<<8)
46 * Returns the maximum number of entities.
48 * @return Maximum number of entities.
50 native GetMaxEntities();
53 * Returns the number of entities in the server.
55 * @return Number of entities in the server.
57 native GetEntityCount();
60 * Returns whether or not an entity is valid. Returns false
61 * if there is no matching CBaseEntity for this edict index.
63 * @param edict Index of the entity/edict.
64 * @return True if valid, false otherwise.
66 native bool:IsValidEntity(edict);
69 * Returns whether or not an edict index is valid.
71 * @param edict Index of the edict.
72 * @return True if valid, false otherwise.
74 native bool:IsValidEdict(edict);
77 * Returns whether or not an entity is a valid networkable edict.
79 * @param edict Index of the edict.
80 * @return True if networkable, false if invalid or not networkable.
82 native bool:IsEntNetworkable(edict);
85 * Creates a new edict (the basis of a networkable entity)
87 * @return Index of the edict, 0 on failure.
92 * Removes an edict from the world.
94 * @param edict Index of the edict.
96 * @error Invalid edict index.
98 native RemoveEdict(edict);
101 * Returns the flags on an edict. These are not the same as entity flags.
103 * @param edict Index of the entity.
104 * @return Edict flags.
105 * @error Invalid edict index.
107 native GetEdictFlags(edict);
110 * Sets the flags on an edict. These are not the same as entity flags.
112 * @param edict Index of the entity.
113 * @param flags Flags to set.
115 * @error Invalid edict index.
117 native SetEdictFlags(edict, flags);
120 * Retrieves an edict classname.
122 * @param edict Index of the entity.
123 * @param clsname Buffer to store the classname.
124 * @param maxlength Maximum length of the buffer.
125 * @return True on success, false if there is no classname set.
127 native bool:GetEdictClassname(edict, String:clsname[], maxlength);
130 * Retrieves an entity's networkable serverclass name.
131 * This is not the same as the classname and is used for networkable state changes.
133 * @param edict Index of the entity.
134 * @param clsname Buffer to store the serverclass name.
135 * @param maxlength Maximum lnegth of the buffer.
136 * @return True on success, false if the edict is not networkable.
137 * @error Invalid edict index.
139 native bool:GetEntityNetClass(edict, String:clsname[], maxlength);
142 * @section Entity offset functions
144 * Offsets should be specified in byte distance from the CBaseEntity
145 * structure, not short (double byte) or integer (four byte) multiples.
146 * It is somewhat common practice to use offsets aligned to their final
147 * type, and thus make sure you are not falling to this error in SourceMod.
148 * For example, if your "integer-aligned" offset was 119, your byte-aligned
149 * offset is 119*4, or 476.
151 * Specifying incorrect offsets or the incorrect data type for an offset
152 * can have fatal consequences. If you are hardcoding offsets, and the
153 * layout of CBaseEntity does not match, you can easily crash the server.
155 * The reasonable bounds for offsets is greater than or equal to 0 and
156 * below 32768. Offsets out of these bounds will throw an error. However,
157 * this does not represent any real range, it is simply a sanity check for
158 * illegal values. Any range outside of the CBaseEntity structure's private
159 * size will cause undefined behaviour or even crash.
163 * Marks an entity as state changed. This can be useful if you set an offset
164 * and wish for it to be immediately changed over the network. By default this
165 * is not done for offset setting functions.
167 * @param edict Index to the edict.
168 * @param offset Offset to mark as changed. If 0,
169 * the entire edict is marked as changed.
171 * @error Invalid entity or offset out of bounds.
173 native ChangeEdictState(edict, offset = 0);
176 * Peeks into an entity's object data and retrieves the integer value at
179 * @param entity Edict index.
180 * @param offset Offset to use.
181 * @param size Number of bytes to read (valid values are 1, 2, or 4).
182 * @return Value at the given memory location.
183 * @error Invalid entity or offset out of reasonable bounds.
185 native GetEntData(entity, offset, size=4);
188 * Peeks into an entity's object data and sets the integer value at
191 * @param entity Edict index.
192 * @param offset Offset to use.
193 * @param size Number of bytes to write (valid values are 1, 2, or 4).
194 * @param changeState If true, change will be sent over the network.
195 * @return Value at the given memory location.
196 * @error Invalid entity or offset out of reasonable bounds.
199 native SetEntData(entity, offset, value, size=4, bool:changeState=false);
202 * Peeks into an entity's object data and retrieves the float value at
205 * @param entity Edict index.
206 * @param offset Offset to use.
207 * @return Value at the given memory location.
208 * @error Invalid entity or offset out of reasonable bounds.
210 native Float:GetEntDataFloat(entity, offset);
213 * Peeks into an entity's object data and sets the integer value at
216 * @param entity Edict index.
217 * @param offset Offset to use.
218 * @param changeState If true, change will be sent over the network.
219 * @return Value at the given memory location.
220 * @error Invalid entity or offset out of reasonable bounds.
223 native SetEntDataFloat(entity, offset, Float:value, bool:changeState=false);
226 * Peeks into an entity's object data and retrieves the entity handle
227 * info at the given offset.
229 * @param entity Edict index.
230 * @param offset Offset to use.
231 * @return Entity index at the given location, or 0 if none.
232 * @error Invalid entity or offset out of reasonable bounds.
234 native GetEntDataEnt(entity, offset);
237 * Peeks into an entity's object data and sets the entity handle info
238 * at the given offset.
240 * @param entity Edict index.
241 * @param offset Offset to use.
242 * @param other Entity index to set, or 0 to clear.
243 * @param changeState If true, change will be sent over the network.
245 * @error Invalid entity or offset out of reasonable bounds.
247 native SetEntDataEnt(entity, offset, other, bool:changeState=false);
250 * Peeks into an entity's object data and retrieves the vector at the
252 * @note Both a Vector and a QAngle are three floats. This is a
253 * convenience function and will work with both types.
255 * @param entity Edict index.
256 * @param offset Offset to use.
257 * @param vec Vector buffer to store data in.
259 * @error Invalid entity or offset out of reasonable bounds.
261 native GetEntDataVector(entity, offset, Float:vec[3]);
264 * Peeks into an entity's object data and sets the vector at the given
266 * @note Both a Vector and a QAngle are three floats. This is a
267 * convenience function and will work with both types.
269 * @param entity Edict index.
270 * @param offset Offset to use.
271 * @param vec Vector to set.
272 * @param changeState If true, change will be sent over the network.
274 * @error Invalid entity or offset out of reasonable bounds.
276 native SetEntDataVector(entity, offset, const Float:vec[3], bool:changeState=false);
279 * Peeks into an entity's object data and retrieves the string at
282 * @param entity Edict index.
283 * @param offset Offset to use.
284 * @param buffer Destination string buffer.
285 * @param maxlen Maximum length of output string buffer.
286 * @return Number of non-null bytes written.
287 * @error Invalid entity or offset out of reasonable bounds.
289 native GetEntDataString(entity, offset, String:buffer[], maxlen);
292 * Peeks into an entity's object data and sets the string at
295 * @param entity Edict index.
296 * @param offset Offset to use.
297 * @param buffer String to set.
298 * @param maxlen Maximum length of bytes to write.
299 * @param changeState If true, change will be sent over the network.
300 * @return Number of non-null bytes written.
301 * @error Invalid entity or offset out of reasonable bounds.
303 native SetEntDataString(entity, offset, const String:buffer[], maxlen, bool:changeState=false);
310 * Given a ServerClass name, finds a networkable send property offset.
311 * This information is cached for future calls.
313 * @param cls Classname.
314 * @param prop Property name.
315 * @return An offset, or -1 on failure.
317 native FindSendPropOffs(const String:cls[], const String:prop[]);
320 * Given an entity, finds a datamap property offset.
321 * This information is cached for future calls.
323 * @param entity Entity index.
324 * @param prop Property name.
325 * @return An offset, or -1 on failure.
327 native FindDataMapOffs(entity, const String:prop[]);
330 * Wrapper function for finding a send property for a particular entity.
332 * @param ent Entity index.
333 * @param prop Property name.
334 * @return An offset, or -1 on failure.
336 stock GetEntSendPropOffs(ent, const String:prop[])
340 if (!GetEntityNetClass(ent, cls, sizeof(cls)))
345 return FindSendPropOffs(cls, prop);
349 * Gets a network property as an integer; wrapper around GetEntData().
351 * @param entity Edict index.
352 * @param type Property type.
353 * @param prop Property to use.
354 * @param size Number of bytes to read (valid values are 1, 2, or 4).
355 * @return Value at the given property offset.
356 * @error Invalid entity or property not found.
358 stock GetEntProp(entity, PropType:type, const String:prop[], size=4)
366 offs = GetEntSendPropOffs(entity, prop);
370 offs = FindDataMapOffs(entity, prop);
374 ThrowError("Invalid Property type %d", type);
380 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
383 return GetEntData(entity, offs, size);
387 * Sets a network property as an integer; wrapper around GetEntData().
389 * @param entity Edict index.
390 * @param type Property type.
391 * @param prop Property to use.
392 * @param size Number of bytes to write (valid values are 1, 2, or 4).
393 * @error Invalid entity or offset out of reasonable bounds.
396 stock SetEntProp(entity, PropType:type, const String:prop[], value, size=4)
404 offs = GetEntSendPropOffs(entity, prop);
408 offs = FindDataMapOffs(entity, prop);
412 ThrowError("Invalid Property type %d", type);
418 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
421 return SetEntData(entity, offs, value, size, true);
425 * Gets a network property as a float; wrapper around GetEntDataFloat().
427 * @param entity Edict index.
428 * @param type Property type.
429 * @param prop Property to use.
430 * @return Value at the given property offset.
431 * @error Invalid entity or offset out of reasonable bounds.
433 stock Float:GetEntPropFloat(entity, PropType:type, const String:prop[])
441 offs = GetEntSendPropOffs(entity, prop);
445 offs = FindDataMapOffs(entity, prop);
449 ThrowError("Invalid Property type %d", type);
455 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
458 return GetEntDataFloat(entity, offs);
462 * Sets a network property as a float; wrapper around SetEntDataFloat().
464 * @param entity Edict index.
465 * @param type Property type.
466 * @param prop Property to use.
467 * @param value Value to set.
469 * @error Invalid entity or offset out of reasonable bounds.
471 stock SetEntPropFloat(entity, PropType:type, const String:prop[], Float:value)
479 offs = GetEntSendPropOffs(entity, prop);
483 offs = FindDataMapOffs(entity, prop);
487 ThrowError("Invalid Property type %d", type);
493 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
496 return SetEntDataFloat(entity, offs, value, true);
500 * Gets a network property as a handle entity; wrapper around GetEntDataEnt().
502 * @param entity Edict index.
503 * @param type Property type.
504 * @param prop Property to use.
505 * @return Entity index at the given property, or 0 if none.
506 * @error Invalid entity or offset out of reasonable bounds.
508 stock GetEntPropEnt(entity, PropType:type, const String:prop[])
516 offs = GetEntSendPropOffs(entity, prop);
520 offs = FindDataMapOffs(entity, prop);
524 ThrowError("Invalid Property type %d", type);
530 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
533 return GetEntDataEnt(entity, offs);
537 * Sets a network property as a handle entity; wrapper around SetEntDataEnt().
539 * @param entity Edict index.
540 * @param type Property type.
541 * @param prop Property to use.
542 * @param other Entity index to set, or 0 to unset.
544 * @error Invalid entity or offset out of reasonable bounds.
546 stock SetEntPropEnt(entity, PropType:type, const String:prop[], other)
554 offs = GetEntSendPropOffs(entity, prop);
558 offs = FindDataMapOffs(entity, prop);
562 ThrowError("Invalid Property type %d", type);
568 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
571 return SetEntDataEnt(entity, offs, other, true);
575 * Gets a network property as a vector; wrapper around GetEntDataVector().
576 * @note Both a Vector and a QAngle are three floats. This is a
577 * convenience function and will work with both types.
579 * @param entity Edict index.
580 * @param type Property type.
581 * @param prop Property to use.
582 * @param vec Vector buffer to store data in.
584 * @error Invalid entity or offset out of reasonable bounds.
586 stock GetEntPropVector(entity, PropType:type, const String:prop[], Float:vec[3])
594 offs = GetEntSendPropOffs(entity, prop);
598 offs = FindDataMapOffs(entity, prop);
602 ThrowError("Invalid Property type %d", type);
608 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
611 return GetEntDataVector(entity, offs, vec);
615 * Sets a network property as a vector; wrapper around SetEntDataVector().
616 * @note Both a Vector and a QAngle are three floats. This is a
617 * convenience function and will work with both types.
619 * @param entity Edict index.
620 * @param type Property type.
621 * @param prop Property to use.
622 * @param vec Vector to set.
624 * @error Invalid entity or offset out of reasonable bounds.
626 stock SetEntPropVector(entity, PropType:type, const String:prop[], const Float:vec[3])
634 offs = GetEntSendPropOffs(entity, prop);
638 offs = FindDataMapOffs(entity, prop);
642 ThrowError("Invalid Property type %d", type);
648 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
651 return SetEntDataVector(entity, offs, vec, true);
655 * Gets a network property as a string.
657 * @param entity Edict index.
658 * @param type Property type.
659 * @param prop Property to use.
660 * @param buffer Destination string buffer.
661 * @param maxlen Maximum length of output string buffer.
662 * @return Number of non-null bytes written.
663 * @error Invalid entity, offset out of reasonable bounds, or property is not a valid string.
665 native GetEntPropString(entity, PropType:type, const String:prop[], String:buffer[], maxlen);
668 * Sets a network property as a string.
670 * @param entity Edict index.
671 * @param type Property type.
672 * @param prop Property to use.
673 * @param buffer String to set.
674 * @return Number of non-null bytes written.
675 * @error Invalid entity, offset out of reasonable bounds, or property is not a valid string.
677 native SetEntPropString(entity, PropType:type, const String:prop[], const String:buffer[]);
