Entity Pointers
From GameStudio Wiki
Contents |
A word about pointers
In a simplified form, pointers can be understood as items that point to an object. The special thing about pointers is that they are nevertheless not the object itself. If you simply imagine a plastic box standing somewhere on the ground, a pointer to that box would look like an arrow pointing towards it. Of course this is a very short and imprecise explanation. But this little tutorial is aimed at newcomers, so let's leave it at that for a moment.
What entity pointers are
In A6, entity pointers are really nothing different than "names". You assign them to an entity in order to have a name for that entity by which you can later on address it. If you ever dealt with C-Script, you certainly came across one specific pointer known as the "my" pointer. This one is a built-in A6 pointer that always references the entity an action runs on. In other words:
action some_action
{
my.invisible = on;
}
...will reference the entity that has the "some_action" action assigned. By using the dot-operator, that entity's "invisible" property is accessed and set to "on". In plain English, you could translate this piece of code into "Make myself invisible!" From this code snippet you should be able to figure that there generally is no need to deal with entity pointers as long as you want to adress an entity that has an action assigned from within that very same action. But if you want to do something with that particular entity from somewhere else in your code (from within a function for example), you'll have to assign a pointer to the entity. This sort of gives it a name, so you can do whatever you want with that entity from anywhere in your code.
How to use entity pointers
First, you have to define a pointer to be able to use it. You define entity pointers like this:
entity* some_pointer;
Once defined, you may assign the pointer to an entity just like this:
//this action is run by the entity that we want to give a "name" to
action some_action
{
//This will assign the "some_pointer" to this very entity
some_pointer = my;
}
Now if you want to address your entity from somewhere else in your code, let's say from inside a function, you would do the following:
function make_invisible()
{
some_pointer.invisible = on;
}
This has the same effect as writing "my.invisible = on;" inside that entity's action.
Using ent_create
Entity pointers are most commonly used together with ent_create. This has the simple reason that, usually, you do not only want to create an entity, but rather have it do something once created. A look at the manual tells us: ent_create returns a pointer to the newly created entity. Great, isn't it? It's really as simple as that:
//define an entity pointer
entity* some_pointer;
//create an entity and have it rotate
function create_ent_and_rotate()
{
//this assigns the "some_pointer" to the newly created entity
some_pointer = ent_create( "some_model.mdl",camera.x,null );
//now address the new entity through the pointer and make it rotate
while( 1 )
{
some_pointer.pan += time_step * 5;
wait( 1 );
}
}
Passing entity pointers to a function
Entity pointers can be passed to functions just as normal variables. This can be particularly useful in order to avoid unnecessary functions when you could indeed reach your goal with less. Consider the following example:
//define entity pointers
entity* entity_one;
entity* entity_two;
//create entity number one and have it rotate
function create_ent_one_and_rotate()
{
entity_one = ent_create( "one.mdl",camera.x,null );
while( 1 )
{
entity_one.pan += time_step * 5;
wait( 1 );
}
}
//create entity number two and have it rotate
function create_ent_one_and_rotate()
{
entity_two = ent_create( "two.mdl",camera.x,null );
while( 1 )
{
entity_two.pan += time_step * 5;
wait( 1 );
}
}
These two functions do nothing but create an entity and rotate it. As you can see, the "ent_create" statement creates two different models, "one.mdl" and "two.mdl". Nevertheless, the part of the code that rotates the newly created entity is more or less the same in both functions. We could assemble them into a general rotation function that rotates whatever entity you pass to it:
//define entity pointers
entity* entity_one;
entity* entity_two;
//this function rotates the specified entity
function rotate_entity( ent_to_rotate )
{
while( 1 )
{
ent_to_rotate.pan += time_step * 5;
}
}
//create entity number one
function create_ent_one()
{
entity_one = ent_create( "one.mdl",camera.x,null );
//here we call the "rotate_entity" function and hand it over the pointer to the newly created entity
rotate_entity( entity_one );
}
//create entity number two
function create_ent_two()
{
entity_two = ent_create( "two.mdl",camera.x,null );
//here we call the "rotate_entity" function and hand it over the pointer to the newly created entity
rotate_entity( entity_two );
}
This way, you could as well completely get rid of the pointer definitions. Simply write
rotate_entity( ent_create( "one.mdl",camera.x,null ) )to have "ent_create" pass the pointer of the newly created entity directly to the "rotate_entity" function - without storing it in "entity_one" first. Of course, this works completely the same for the second entity.
