ent_create(STRING* filename, VECTOR* position,
EVENT action): ENTITY*
ent_createlocal(STRING* filename, VECTOR* position,
EVENT action): ENTITY*
Creates a model, sprite,
terrain or map entity,
either from an external file, or from a predefined primitve shape.
The given action will start immediately after
creation,
with the
my
pointer set to the created entity, and
you set to the creating entity (if any).
The instruction returns a pointer to the created entity that can be used for
setting further entity parameters
after the entity function was run.
ent_create creates a global entity on
the server and on all connected clients. ent_createlocal creates the entity on the local machine only.
A local entity is
not transmitted to the server, and thus not visible on other clients. The local
entity
function runs on the
local machine only. Local entities can be used for advanced particle effects,
player weapons or the like. In a single player system, both instructions are
identical.
Parameters:
filename
- name of the entity file to be created
(char* or STRING*);
or a primitive entity shape (see below);
or NULL for creating a dummy entity.
position
- inital position of the entity.
action
- action of the entity, or NULL for no action.
Returns:
Pointer to the created entity.
Modifies:
hit (when preload_mode is at 7 or above).
Speed:
Slow
with hard disk access
when the entity file was not yet used in this level; medium
when the file is loaded from the level cache.
Remarks:
-
The following file formats are supported: wmb (map entities), hmp (terrain), mdl, x, obj (models), tga, pcx, bmp, dds (sprites). Note that some formats have restrictions, f.i. the obj format requires loading the skin through ent_setskin, and the compressed dds format offers no access to single pixels of the bitmap.
A cache with hash function is used for storing the file when it was already loaded before; for this, file names must not exceed 30 characters.
-
The following primitive shapes are supported: CUBE_MDL (a 16x16x16 cube model with no skin); SPHERE_MDL (a sphere model with 16 quants diameter); SHADOW_DDS (a 128x128 transparent sprite with a dark spot in the center, used for decal shadows).
They are automatically replaced by external files named "cube.mdl", "sphere.mdl", "shadow.dds" when those files are found in the project folder.
- A level must be loaded before creating level entities.
Thus the ent_create functions can not be called immediately
on the
client before it's connected to the server. In a multiplayer system, wait
after level_load and session_connect until dplay_status is at 6 or above before creating
entities.
- Creating map entities (.wmb)
also creates all sub-entities stored in the map.
-
Creating a terrain entity runs the entity action already before the terrain is placed in the level. This allows the action to set the terrain scale, which can not be changed afterwards. A8
Terrain entities without external files can be created with ent_createterrain.
- A local entities' action runs only on the client
who has created it. Local entities perform collision detection,
but are passable for global entities
because they don't exist on the server.
-
On a single player system, the entity function is started immediately when the
entity is created. On multiplayer systems,
entity functions are started on the server only as long as dplay_localfunction is not set. Due to the transmission time, the start of the entity function on the server can occur up to 0.5 seconds later after entity creation on the client.
-
On multiplayer systems,
it can take up to 0.5 seconds until the created entity is copied to
all connected machines. During that
time, the entity handle can not be used, entity skills can not
be sent (►send_skill()) and the client_id parameter is not set. client_id can be polled for determining when the entity is ready on all machines: while (my.client_id != dplay_id) wait(1); .
- The entity file is stored in an internal cache for speeding
up subsequent creation of similar entities. This cache is cleared by level_load.
In A8 the collision hull of the first frame is also stored in the cache, speeding up subsequent creation of similar entities even more when they are not scaled (scale_x vector at 1,1,1).
-
When preload_mode is set, the entity mesh and textures are created immediately after ent_create. Otherwise, mesh and textures are only created when the entity is seen the first time, which can lead to a brief delay when this happens for many entities. When preload_mode is set at 7, the environment lighting is also created. This requires an internal c_trace call and modifies the hit struct.
-
Every created entity consumes about 4 kB memory. More memory is consumed for the bones tree when it uses bones animation, for the collision hull when it uses collision detection, and for the mesh when it is cloned.
-
When collision_mode is set above zero, a collision hull is created for the entity. This consumes some time and memory, dependent on the size of the entity mesh. For maximum creation speed and minimum memory impact, set collision_mode at 0 before creating the entity, and set it back afterwards.
-
Dummy entities (to be used
f.i. for for dynamic lights
)
can be created by passing NULL for the file name. A dummy entity
has all entity parameters, but is always
invisible and passable.
- The entity can be removed by
ent_remove.
Example:
you = ent_create ("flash.pcx", temp, flash_action);
See also:
ENTITIES, ent_morph, ent_purge,
ent_preload,
ent_remove,
ent_createterrain,
ent_createlayer, level_load,
preload_mode
► latest
version online