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
23 * For more information on these, see the HL2SDK (public/edict.h)
25 #define FL_EDICT_CHANGED (1<<0) /**< Game DLL sets this when the entity state changes
26 Mutually exclusive with FL_EDICT_PARTIAL_CHANGE. */
27 #define FL_EDICT_FREE (1<<1) /**< this edict if free for reuse */
28 #define FL_EDICT_FULL (1<<2) /**< this is a full server entity */
29 #define FL_EDICT_FULLCHECK (0<<0) /**< call ShouldTransmit() each time, this is a fake flag */
30 #define FL_EDICT_ALWAYS (1<<3) /**< always transmit this entity */
31 #define FL_EDICT_DONTSEND (1<<4) /**< don't transmit this entity */
32 #define FL_EDICT_PVSCHECK (1<<5) /**< always transmit entity, but cull against PVS */
33 #define FL_EDICT_PENDING_DORMANT_CHECK (1<<6)
34 #define FL_EDICT_DIRTY_PVS_INFORMATION (1<<7)
35 #define FL_FULL_EDICT_CHANGED (1<<8)
38 * Returns the maximum number of entities.
40 * @return Maximum number of entities.
42 native GetMaxEntities();
45 * Returns the number of entities in the server.
47 * @return Number of entities in the server.
49 native GetEntityCount();
52 * Returns whether or not an entity is valid. Returns false
53 * if there is no matching CBaseEntity for this edict index.
55 * @param edict Index of the entity/edict.
56 * @return True if valid, false otherwise.
58 native bool:IsValidEntity(edict);
61 * Returns whether or not an edict index is valid.
63 * @param edict Index of the edict.
64 * @return True if valid, false otherwise.
66 native bool:IsValidEdict(edict);
69 * Returns whether or not an entity is a valid networkable edict.
71 * @param edict Index of the edict.
72 * @return True if networkable, false if invalid or not networkable.
74 native bool:IsEntNetworkable(edict);
77 * Creates a new edict (the basis of a networkable entity)
79 * @return Index of the edict, 0 on failure.
84 * Removes an edict from the world.
86 * @param edict Index of the edict.
88 * @error Invalid edict index.
90 native RemoveEdict(edict);
93 * Returns the flags on an edict. These are not the same as entity flags.
95 * @param edict Index of the entity.
96 * @return Edict flags.
97 * @error Invalid edict index.
99 native GetEdictFlags(edict);
102 * Sets the flags on an edict. These are not the same as entity flags.
104 * @param edict Index of the entity.
105 * @param flags Flags to set.
107 * @error Invalid edict index.
109 native SetEdictFlags(edict, flags);
112 * Retrieves an edict classname.
114 * @param edict Index of the entity.
115 * @param clsname Buffer to store the classname.
116 * @param maxlength Maximum length of the buffer.
117 * @return True on success, false if there is no classname set.
119 native bool:GetEdictClassname(edict, String:clsname[], maxlength);
122 * Retrieves an entity's networkable serverclass name.
123 * This is not the same as the classname and is used for networkable state changes.
125 * @param edict Index of the entity.
126 * @param clsname Buffer to store the serverclass name.
127 * @param maxlength Maximum lnegth of the buffer.
128 * @return True on success, false if the edict is not networkable.
129 * @error Invalid edict index.
131 native bool:GetEntityNetClass(edict, String:clsname[], maxlength);
134 * @section Entity offset functions
136 * Offsets should be specified in byte distance from the CBaseEntity
137 * structure, not short (double byte) or integer (four byte) multiples.
138 * It is somewhat common practice to use offsets aligned to their final
139 * type, and thus make sure you are not falling to this error in SourceMod.
140 * For example, if your "integer-aligned" offset was 119, your byte-aligned
141 * offset is 119*4, or 476.
143 * Specifying incorrect offsets or the incorrect data type for an offset
144 * can have fatal consequences. If you are hardcoding offsets, and the
145 * layout of CBaseEntity does not match, you can easily crash the server.
147 * The reasonable bounds for offsets is greater than or equal to 0 and
148 * below 32768. Offsets out of these bounds will throw an error. However,
149 * this does not represent any real range, it is simply a sanity check for
150 * illegal values. Any range outside of the CBaseEntity structure's private
151 * size will cause undefined behaviour or even crash.
155 * Marks an entity as state changed. This can be useful if you set an offset
156 * and wish for it to be immediately changed over the network. By default this
157 * is not done for offset setting functions.
159 * @param edict Index to the edict.
160 * @param offset Offset to mark as changed. If 0,
161 * the entire edict is marked as changed.
163 * @error Invalid entity or offset out of bounds.
165 native ChangeEdictState(edict, offset = 0);
168 * Peeks into an entity's object data and retrieves the integer value at
171 * @param entity Edict index.
172 * @param offset Offset to use.
173 * @param size Number of bytes to read (valid values are 1, 2, or 4).
174 * @return Value at the given memory location.
175 * @error Invalid entity or offset out of reasonable bounds.
177 native GetEntData(entity, offset, size=4);
180 * Peeks into an entity's object data and sets the integer value at
183 * @param entity Edict index.
184 * @param offset Offset to use.
185 * @param size Number of bytes to write (valid values are 1, 2, or 4).
186 * @param changeState If true, change will be sent over the network.
187 * @return Value at the given memory location.
188 * @error Invalid entity or offset out of reasonable bounds.
191 native SetEntData(entity, offset, value, size=4, bool:changeState=false);
194 * Peeks into an entity's object data and retrieves the float value at
197 * @param entity Edict index.
198 * @param offset Offset to use.
199 * @return Value at the given memory location.
200 * @error Invalid entity or offset out of reasonable bounds.
202 native Float:GetEntDataFloat(entity, offset);
205 * Peeks into an entity's object data and sets the integer value at
208 * @param entity Edict index.
209 * @param offset Offset to use.
210 * @param changeState If true, change will be sent over the network.
211 * @return Value at the given memory location.
212 * @error Invalid entity or offset out of reasonable bounds.
215 native SetEntDataFloat(entity, offset, Float:value, bool:changeState=false);
218 * Peeks into an entity's object data and retrieves the entity handle
219 * info at the given offset.
221 * @param entity Edict index.
222 * @param offset Offset to use.
223 * @return Entity index at the given location, or 0 if none.
224 * @error Invalid entity or offset out of reasonable bounds.
226 native GetEntDataEnt(entity, offset);
229 * Peeks into an entity's object data and sest the entity handle info
230 * at the given offset.
232 * @param entity Edict index.
233 * @param offset Offset to use.
234 * @param other Entity index to set, or 0 to clear.
235 * @param changeState If true, change will be sent over the network.
237 * @error Invalid entity or offset out of reasonable bounds.
239 native SetEntDataEnt(entity, offset, other, bool:changeState=false);
242 * Peeks into an entity's object data and retrieves the vector at the
244 * @note Both a Vector and a QAngle are three floats. This is a
245 * convenience function and will work with both types.
247 * @param entity Edict index.
248 * @param offset Offset to use.
249 * @param vec Vector buffer to store data in.
251 * @error Invalid entity or offset out of reasonable bounds.
253 native GetEntDataVector(entity, offset, Float:vec[3]);
256 * Peeks into an entity's object data and sets the vector at the given
258 * @note Both a Vector and a QAngle are three floats. This is a
259 * convenience function and will work with both types.
261 * @param entity Edict index.
262 * @param offset Offset to use.
263 * @param vec Vector to set.
264 * @param changeState If true, change will be sent over the network.
266 * @error Invalid entity or offset out of reasonable bounds.
268 native SetEntDataVector(entity, offset, const Float:vec[3], bool:changeState=false);
271 * Given a ServerClass name, finds a networkable send property offset.
272 * This information is cached for future calls.
274 * @param cls Classname.
275 * @param prop Property name.
276 * @return An offset, or -1 on failure.
278 native FindSendPropOffs(const String:cls[], const String:prop[]);
281 * Wrapper function for finding a send property for a particular entity.
283 * @param ent Entity index.
284 * @param prop Property name.
285 * @return An offset, or -1 on failure.
287 stock GetEntSendPropOffs(ent, const String:prop[])
291 if (!GetEntityNetClass(ent, cls, sizeof(cls)))
296 return FindSendPropOffs(cls, prop);
300 * Gets a network property as an integer; wrapper around GetEntData().
302 * @param entity Edict index.
303 * @param prop Property to use.
304 * @param size Number of bytes to read (valid values are 1, 2, or 4).
305 * @return Value at the given property offset.
306 * @error Invalid entity or property not found.
308 stock GetEntProp(entity, const String:prop[], size=4)
310 new offs = GetEntSendPropOffs(entity, prop);
313 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
315 return GetEntData(entity, offs, size);
319 * Sets a network property as an integer; wrapper around GetEntData().
321 * @param entity Edict index.
322 * @param prop Property to use.
323 * @param size Number of bytes to write (valid values are 1, 2, or 4).
324 * @error Invalid entity or offset out of reasonable bounds.
327 stock SetEntProp(entity, const String:prop[], value, size=4)
329 new offs = GetEntSendPropOffs(entity, prop);
332 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
334 return SetEntData(entity, offs, value, size, true);
338 * Gets a network property as a float; wrapper around GetEntDataFloat().
340 * @param entity Edict index.
341 * @param prop Property to use.
342 * @return Value at the given property offset..
343 * @error Invalid entity or offset out of reasonable bounds.
345 stock Float:GetEntPropFloat(entity, const String:prop[])
347 new offs = GetEntSendPropOffs(entity, prop);
350 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
352 return GetEntDataFloat(entity, offs);
356 * Sets a network property as a float; wrapper around SetEntDataFloat().
358 * @param entity Edict index.
359 * @param prop Property to use.
360 * @param value Value to set.
362 * @error Invalid entity or offset out of reasonable bounds.
364 stock SetEntPropFloat(entity, const String:prop[], Float:value)
366 new offs = GetEntSendPropOffs(entity, prop);
369 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
371 return SetEntDataFloat(entity, offs, value, true);
375 * Gets a network property as a handle entity; wrapper around GetEntDataEnt().
377 * @param entity Edict index.
378 * @param prop Property to use.
379 * @return Entity index at the given property, or 0 if none.
380 * @error Invalid entity or offset out of reasonable bounds.
382 stock GetEntPropEnt(entity, const String:prop[])
384 new offs = GetEntSendPropOffs(entity, prop);
387 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
389 return GetEntDataEnt(entity, offs);
393 * Sets a network property as a handle entity; wrapper around SetEntDataEnt().
395 * @param entity Edict index.
396 * @param prop Property to use.
397 * @param other Entity index to set, or 0 to unset.
399 * @error Invalid entity or offset out of reasonable bounds.
401 stock SetEntPropEnt(entity, const String:prop[], other)
403 new offs = GetEntSendPropOffs(entity, prop);
406 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
408 return SetEntDataEnt(entity, offs, other, true);
412 * Gets a network property as a vector; wrapper around GetEntDataVector().
413 * @note Both a Vector and a QAngle are three floats. This is a
414 * convenience function and will work with both types.
416 * @param entity Edict index.
417 * @param prop Property to use.
418 * @param vec Vector buffer to store data in.
420 * @error Invalid entity or offset out of reasonable bounds.
422 stock GetEntPropVector(entity, const String:prop[], Float:vec[3])
424 new offs = GetEntSendPropOffs(entity, prop);
427 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
429 return GetEntDataVector(entity, offs, vec);
433 * Sets a network property as a vector; wrapper around SetEntDataVector().
434 * @note Both a Vector and a QAngle are three floats. This is a
435 * convenience function and will work with both types.
437 * @param entity Edict index.
438 * @param prop Property to use.
439 * @param vec Vector to set.
441 * @error Invalid entity or offset out of reasonable bounds.
443 stock SetEntPropVector(entity, const String:prop[], const Float:vec[3])
445 new offs = GetEntSendPropOffs(entity, prop);
448 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
450 return SetEntDataVector(entity, offs, vec, true);
