Script: new map entities

Gametype plugins allow to create new entities to be spawned from map files, and to manage their thinking, touching, using, pain and die events.

The way of doing it is quite simple. All the gametype creator has to do is add a new entity to his map. This new entity will have a new entity classname (otherwise it wouldn't be new) which normally wouldn't be recognized by qfusion.

When qfusion is spawning a map and finds a entity with a unknown classname, it will ask the gametype plugin to execute the entity's spawning function. If the script doesn't have it, the entity will be ignored.

The way of creating the spawn function for a new entity type from a gametype script is very simple, all the coder has to do is use the entity's classname as function name.

For example, to a new entity with classname "misc_custom" a spawn function would look like this:

void misc_custom( cEntity @ent )

{

// Do the spawning

}

That's just the spawning, tho. You normally want your entity to execute some actions when touched or damaged. They can be created by adding a function with the event as sufix. Notice that, the only required function to have the entity supported is the spawning one, and all the event functions are optional.

---

These are the events you can create function callbacks for:

• think : Each game frame the entity gets a chance to think. Notice that physics are not handled by the thinking function. The physics are handled by the game code and a gametype scripter changes the entity movetype to choose between the different movement sets. Also note that the thinking process is managed by the entity itself, and it will be called based on the time value assigned into cEntity::nextThink

Example of "misc_custom" entity thinking function:

void misc_custom_think( cEntity @ent )

{

// Do the thinking

}

• touch : The entity has touched some other entity.

Example of "misc_custom" entity touch function:

void misc_custom_touch( cEntity @ent, cEntity @other, const cVec3 @planeNormal, int surfFlags )

{

// Apply the results of being touched

}

• use : The entity is being used. This happens when some other entity is triggered and has this entity as target. Activator is the entity which triggered the entity which uses our entity. As example: A player touches a buttom that uses our misc_custom entity. The player is the "activator", the button is the "other" and misc_custom is the "ent".

Example of "misc_custom" entity use function:

void misc_custom_use( cEntity @ent, cEntity @other, cEntity @activator )

{

// Execute the actions of being used

}

• pain : The entity has received damage. Notice that the damage is already applied to the entity, it's not pain's function mission to add the damage, but to add entity reactions to being damaged. As example, Warsow's func_door entities are activated not only by using, but also by their pain function (so they open when being shot).

Example of "misc_custom" entity pain function:

void misc_custom_pain( cEntity @ent, cEntity @other, float kick, float damage )

{

// Apply the results of being damaged

}

• die : The entity has received damage enough to not have any remaining health. The game code will do nothing, if you want it to die, it must be handled by this function. As example, a brush entity can be made to explode in this function.

Example of "misc_custom" entity die function:

void misc_custom_die( cEntity @ent, cEntity @inflicter, cEntity @attacker )

{

// Apply the results of being killed

}

• stop : The entity has stopped moving.

Example of "misc_custom" entity die function:

void misc_custom_stop( cEntity @ent )

{

// Apply the results of having stop

}