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 sest 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);
283 * Given a ServerClass name, finds a networkable send property offset.
284 * This information is cached for future calls.
286 * @param cls Classname.
287 * @param prop Property name.
288 * @return An offset, or -1 on failure.
290 native FindSendPropOffs(const String:cls[], const String:prop[]);
293 * Wrapper function for finding a send property for a particular entity.
295 * @param ent Entity index.
296 * @param prop Property name.
297 * @return An offset, or -1 on failure.
299 stock GetEntSendPropOffs(ent, const String:prop[])
303 if (!GetEntityNetClass(ent, cls, sizeof(cls)))
308 return FindSendPropOffs(cls, prop);
312 * Gets a network property as an integer; wrapper around GetEntData().
314 * @param entity Edict index.
315 * @param type Property type.
316 * @param prop Property to use.
317 * @param size Number of bytes to read (valid values are 1, 2, or 4).
318 * @return Value at the given property offset.
319 * @error Invalid entity or property not found.
321 stock GetEntProp(entity, PropType:type, const String:prop[], size=4)
323 new offs = GetEntSendPropOffs(entity, prop);
326 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
328 return GetEntData(entity, offs, size);
332 * Sets a network property as an integer; wrapper around GetEntData().
334 * @param entity Edict index.
335 * @param type Property type.
336 * @param prop Property to use.
337 * @param size Number of bytes to write (valid values are 1, 2, or 4).
338 * @error Invalid entity or offset out of reasonable bounds.
341 stock SetEntProp(entity, PropType:type, const String:prop[], value, size=4)
343 new offs = GetEntSendPropOffs(entity, prop);
346 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
348 return SetEntData(entity, offs, value, size, true);
352 * Gets a network property as a float; wrapper around GetEntDataFloat().
354 * @param entity Edict index.
355 * @param type Property type.
356 * @param prop Property to use.
357 * @return Value at the given property offset..
358 * @error Invalid entity or offset out of reasonable bounds.
360 stock Float:GetEntPropFloat(entity, PropType:type, const String:prop[])
362 new offs = GetEntSendPropOffs(entity, prop);
365 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
367 return GetEntDataFloat(entity, offs);
371 * Sets a network property as a float; wrapper around SetEntDataFloat().
373 * @param entity Edict index.
374 * @param type Property type.
375 * @param prop Property to use.
376 * @param value Value to set.
378 * @error Invalid entity or offset out of reasonable bounds.
380 stock SetEntPropFloat(entity, PropType:type, const String:prop[], Float:value)
382 new offs = GetEntSendPropOffs(entity, prop);
385 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
387 return SetEntDataFloat(entity, offs, value, true);
391 * Gets a network property as a handle entity; wrapper around GetEntDataEnt().
393 * @param entity Edict index.
394 * @param type Property type.
395 * @param prop Property to use.
396 * @return Entity index at the given property, or 0 if none.
397 * @error Invalid entity or offset out of reasonable bounds.
399 stock GetEntPropEnt(entity, PropType:type, const String:prop[])
401 new offs = GetEntSendPropOffs(entity, prop);
404 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
406 return GetEntDataEnt(entity, offs);
410 * Sets a network property as a handle entity; wrapper around SetEntDataEnt().
412 * @param entity Edict index.
413 * @param type Property type.
414 * @param prop Property to use.
415 * @param other Entity index to set, or 0 to unset.
417 * @error Invalid entity or offset out of reasonable bounds.
419 stock SetEntPropEnt(entity, PropType:type, const String:prop[], other)
421 new offs = GetEntSendPropOffs(entity, prop);
424 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
426 return SetEntDataEnt(entity, offs, other, true);
430 * Gets a network property as a vector; wrapper around GetEntDataVector().
431 * @note Both a Vector and a QAngle are three floats. This is a
432 * convenience function and will work with both types.
434 * @param entity Edict index.
435 * @param type Property type.
436 * @param prop Property to use.
437 * @param vec Vector buffer to store data in.
439 * @error Invalid entity or offset out of reasonable bounds.
441 stock GetEntPropVector(entity, PropType:type, const String:prop[], Float:vec[3])
443 new offs = GetEntSendPropOffs(entity, prop);
446 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
448 return GetEntDataVector(entity, offs, vec);
452 * Sets a network property as a vector; wrapper around SetEntDataVector().
453 * @note Both a Vector and a QAngle are three floats. This is a
454 * convenience function and will work with both types.
456 * @param entity Edict index.
457 * @param type Property type.
458 * @param prop Property to use.
459 * @param vec Vector to set.
461 * @error Invalid entity or offset out of reasonable bounds.
463 stock SetEntPropVector(entity, PropType:type, const String:prop[], const Float:vec[3])
465 new offs = GetEntSendPropOffs(entity, prop);
468 ThrowError("Property \"%s\" not found for entity %d", prop, entity);
470 return SetEntDataVector(entity, offs, vec, true);
