Custom Entities API

OOP-style entity system for creating reusable entity classes with methods, members, and inheritance.

For complete API documentation, see README.md.

Naming Conventions

Member Constants

Use m_ prefix with Hungarian notation type prefix:

pawn
1// Format: m_{Type}{Name}
2new const m_flDamage[] = "flDamage";     // float - damage amount
3new const m_flSpeed[] = "flSpeed";       // float - movement speed
4new const m_pTarget[] = "pTarget";       // pointer - target entity
5new const m_bGuided[] = "bGuided";       // bool - auto-guidance enabled
6new const m_iType[] = "iType";           // int - entity type

Method Constants

Use PascalCase name only (no prefix):

pawn
1new const Launch[] = "Launch";
2new const Explode[] = "Explode";
3new const CanTakeDamage[] = "CanTakeDamage";

Class Registration

pawn
1public plugin_precache() {
2  // Precache resources BEFORE registration
3  precache_model(g_szModel);
4  precache_sound(g_szExplodeSound);
5  
6  // Register class with optional preset base class
7  CE_RegisterClass(ENTITY_NAME);
8  // Or extend: CE_RegisterClass(ENTITY_NAME, CE_Class_BaseItem);
9  
10  // Implement base methods (override virtual methods)
11  CE_ImplementClassMethod(ENTITY_NAME, CE_Method_Create, "@Entity_Create");
12  CE_ImplementClassMethod(ENTITY_NAME, CE_Method_Spawn, "@Entity_Spawn");
13  CE_ImplementClassMethod(ENTITY_NAME, CE_Method_Touch, "@Entity_Touch");
14  CE_ImplementClassMethod(ENTITY_NAME, CE_Method_Think, "@Entity_Think");
15  CE_ImplementClassMethod(ENTITY_NAME, CE_Method_Killed, "@Entity_Killed");
16  
17  // Register custom methods
18  CE_RegisterClassMethod(ENTITY_NAME, Launch, "@Entity_Launch", CE_Type_Cell);
19  
20  // Bind map key-values to members
21  CE_RegisterClassKeyMemberBinding(ENTITY_NAME, "damage", m_flDamage, CEMemberType_Float);
22}

Members Usage

Get Member

pawn
1static szModel[64]; CE_GetMemberString(this, CE_Member_szModel, szModel, charsmax(szModel));
2static Float:vecMins[3]; CE_GetMemberVec(this, CE_Member_vecMins, vecMins);
3new Float:flDamage = CE_GetMember(this, m_flDamage);
4new iType = CE_GetMember(this, m_iType);

Set Member

pawn
1CE_SetMemberString(this, CE_Member_szModel, g_szModel);
2CE_SetMemberVec(this, CE_Member_vecMins, Float:{-8.0, -8.0, 0.0});
3CE_SetMember(this, m_flDamage, 50.0);
4CE_SetMember(this, m_iType, 1);

Conditions

When you need to get float member value in conditions or for other inline operations you should explicitly provide Float: tag to make sure compiler will use correct type.

pawn
1if (Float:CE_GetMember(this, m_flNextUpdate) <= get_gametime()) {
2  // Do something
3}

Method Implementation

Create Method (Constructor)

Set up default member values. Never modify pev/engine data here.

pawn
1@Entity_Create(const this) {
2  CE_CallBaseMethod();
3  
4  // Set built-in members
5  CE_SetMemberString(this, CE_Member_szModel, g_szModel);
6  CE_SetMemberVec(this, CE_Member_vecMins, Float:{-8.0, -8.0, 0.0});
7  CE_SetMemberVec(this, CE_Member_vecMaxs, Float:{8.0, 8.0, 16.0});
8  
9  // Set custom members
10  CE_SetMember(this, m_flDamage, 50.0);
11  CE_SetMember(this, m_flSpeed, 1000.0);
12  
13  // ❌ WRONG: Don't use set_pev/engfunc here
14  // set_pev(this, pev_movetype, MOVETYPE_FLY);
15}

Spawn Method

Configure engine properties after entity is fully created:

pawn
1@Entity_Spawn(const this) {
2  CE_CallBaseMethod();
3  
4  set_pev(this, pev_movetype, MOVETYPE_FLY);
5  set_pev(this, pev_solid, SOLID_BBOX);
6  set_pev(this, pev_nextthink, get_gametime() + 0.1);
7}

Think Method

Recurring logic with static variables for performance:

pawn
1@Entity_Think(const this) {
2  static Float:flSpeed; flSpeed = CE_GetMember(this, m_flSpeed);
3  static pOwner; pOwner = pev(this, pev_owner);
4  static Float:vecOrigin[3]; pev(this, pev_origin, vecOrigin);
5  
6  // Entity logic...
7  
8  CE_CallBaseMethod();
9  set_pev(this, pev_nextthink, get_gametime() + 0.1);
10}

Touch Method

Handle collisions:

pawn
1@Entity_Touch(const this, const pTarget) {
2  CE_CallBaseMethod(pTarget);
3  
4  if (pev(pTarget, pev_solid) < SOLID_BBOX) return;
5  
6  static pOwner; pOwner = pev(this, pev_owner);
7  static Float:flDamage; flDamage = CE_GetMember(this, m_flDamage);
8  
9  if (IS_PLAYER(pTarget)) {
10    ExecuteHamB(Ham_TakeDamage, pTarget, this, pOwner, flDamage, DMG_GENERIC);
11  }
12  
13  ExecuteHamB(Ham_Killed, this, 0, 0);
14}

Killed Method

Handle entity destruction:

pawn
1@Entity_Killed(const this, const pKiller) {
2  static Float:vecOrigin[3]; pev(this, pev_origin, vecOrigin);
3  
4  // Play explosion effect
5  emit_sound(this, CHAN_BODY, g_szExplodeSound, VOL_NORM, ATTN_NORM, 0, PITCH_NORM);
6  
7  CE_CallBaseMethod(pKiller);
8}

Creating Entities

pawn
1new pEntity = CE_Create(ENTITY_NAME, vecOrigin);
2if (pEntity != FM_NULLENT) {
3  CE_SetMember(pEntity, m_flDamage, 100.0);
4  set_pev(pEntity, pev_owner, pPlayer);
5  dllfunc(DLLFunc_Spawn, pEntity);
6}

Calling Methods

pawn
1// Call custom method
2CE_CallMethod(pEntity, Launch, pTarget);
3
4// Call method and get return value
5new bool:bCanDamage = CE_CallMethod(pEntity, CanTakeDamage, pAttacker);

Calling Parent Methods

Always call CE_CallBaseMethod() to invoke parent implementation:

pawn
1@Entity_TakeDamage(const this, const pInflictor, const pAttacker, Float:flDamage, iDamageBits) {
2  if (!CE_CallMethod(this, CanTakeDamage, pInflictor, pAttacker)) return;
3  
4  CE_CallBaseMethod(pInflictor, pAttacker, flDamage, iDamageBits);
5}

Entity Hooks (External Plugins)

Listen to entity events from other plugins:

pawn
1public plugin_init() {
2  CE_RegisterClassNativeMethodHook(ENTITY_NAME, CE_Method_Spawn, "CEHook_Projectile_Spawn");
3  CE_RegisterClassNativeMethodHook(ENTITY_NAME, CE_Method_Spawn, "CEHook_Projectile_Spawn_Post", true);
4}
5
6public CEHook_Projectile_Spawn(const pEntity) {
7  // React to entity spawn (pre-hook)...
8}
9
10public CEHook_Projectile_Spawn_Post(const pEntity) {
11  // React after entity spawn (post-hook)...
12}

Hook callback naming: CEHook_{EntityName}_{Method} (add _Post suffix for post-hooks)

pawn
1public CEHook_Projectile_Touch(const pProjectile, const pToucher)
2public CEHook_ItemPickup_Spawn(const pEntity)

Check Entity Type

pawn
1// Check if entity is instance of specific class (includes inherited classes)
2if (CE_IsInstanceOf(pEntity, ENTITY_NAME)) {
3  // Entity is of this type or inherits from it
4}
5
6// Get entity classname
7new szClassname[32];
8pev(pEntity, pev_classname, szClassname, charsmax(szClassname));

Suppress Unwanted Entities

Use CE_RegisterNullClass to suppress map/game entities that you don't need:

pawn
1public plugin_precache() {
2  // Suppress CS-specific entities when creating custom game mode
3  CE_RegisterNullClass("armoury_entity");
4  CE_RegisterNullClass("weapon_shield");
5  CE_RegisterNullClass("game_player_equip");
6  CE_RegisterNullClass("player_weaponstrip");
7  CE_RegisterNullClass("hostage_entity");
8  CE_RegisterNullClass("func_buyzone");
9}

Entity Class Aliases

Use CE_RegisterClassAlias to replace map entities with custom implementations:

pawn
1public plugin_precache() {
2  // Replace HL2 entities with custom implementations
3  CE_RegisterClassAlias("item_healthkit", ENTITY(HealthKit));
4  CE_RegisterClassAlias("item_battery", ENTITY(Armor));
5  
6  // Replace CS entities
7  CE_RegisterClassAlias("func_vip_safetyzone", ENTITY(EndRoundTrigger));
8}

Complete Entity Plugin Structure

pawn
1#pragma semicolon 1
2
3#include <amxmodx>
4
5#include <api_custom_entities>
6
7/*--------------------------------[ Constants ]--------------------------------*/
8
9#define ENTITY_NAME "test"
10#define Test "Test"
11
12/*--------------------------------[ Assets ]--------------------------------*/
13
14new const g_szModel[] = "models/w_security.mdl";
15
16/*--------------------------------[ Plugin Initialization ]--------------------------------*/
17
18public plugin_precache() {
19  precache_model(g_szModel);
20
21  CE_RegisterClass(ENTITY_NAME);
22  CE_ImplementClassMethod(ENTITY_NAME, CE_Method_Create, "@Entity_Create");
23  CE_ImplementClassMethod(ENTITY_NAME, CE_Method_Spawn, "@Entity_Spawn");
24
25  CE_RegisterClassMethod(ENTITY_NAME, Test, "@Entity_Test", CE_Type_Cell);
26}
27
28public plugin_init() {
29  register_plugin("[Entity] Test", "1.0.0", "Author");
30}
31
32/*--------------------------------[ Methods ]--------------------------------*/
33
34@Entity_Create(const this) {
35  CE_CallBaseMethod();
36
37  CE_SetMemberVec(this, CE_Member_vecMins, Float:{-4.0, -4.0, -4.0});
38  CE_SetMemberVec(this, CE_Member_vecMaxs, Float:{4.0, 4.0, 4.0});
39  CE_SetMemberString(this, CE_Member_szModel, g_szModel);
40}
41
42@Entity_Spawn(const this) {
43  CE_CallBaseMethod();
44
45  set_pev(this, pev_solid, SOLID_BBOX);
46  set_pev(this, pev_movetype, MOVETYPE_TOSS);
47}
48
49@Entity_Test(const this, iParam) {
50  log_amx("Entity test method called with param: %d", iParam);
51
52  return true;
53}

Best Practices Checklist

• Precache resources BEFORE CE_RegisterClass
• Use Create for member initialization only
• Use Spawn for engine/pev modifications
• Check FM_NULLENT after CE_Create
• Call dllfunc(DLLFunc_Spawn, pEntity) after creating entity
• Use static variables in Think/Touch for performance
• Define member constants with m_ prefix and Hungarian notation
• Define method constants with PascalCase only (no prefix)
• Use CE_RegisterNullClass to suppress unwanted entities
• Use CE_RegisterClassAlias to replace map entities with custom implementations or provide extra classname for existing class