Scripting
Named entities

1. Introduction

What are all those names in the scripts with a dollar sign ($) in front of them? Those of you who have downloaded the AVI of Charlie Wiederhold's robot "Danny" and have read the comments in the accompanying script will think: "I know! Those are func_scriptobjects". Well... not exactly; a func_scriptobject can indeed be referred to by an $<entityname> but it's far from being the only entity that can be designated this way in a script. This is why I chose to dub them Named entities for lack of a better all-encompassing term.

So exactly what entities can be referred to in a script as a named entity? Pretty much any entity in which the targetname field is implemented. And believe me, that's not only a lot of entities but also a lot of different types of entities: brush models, game models (world objects, monsters, actors), cameras, lights, sounds, path locations and even areaportals!! So func_scriptobject's are really just the tip of the iceberg.

2. What $ really means

How does the targetname of an entity relate to the $<entityname> reference in a script? Simple, the character string that comes right after the $ sign must be the same as the value of the targetname field. Let's look at the same example from intro_start.scr we used at the beginning of the previous section (Threads):

jc_thread:
$jc anim intro_sit_to_stand
end

In the map intro_start.bsp, there is an entity which has a corresponding targetname value:

classname: func_scriptmodel
model: pl_jc.def
origin: -518.00 1442.00 -308.00
angle: 270
anim: intro_sit_idle
targetname: jc

So when you refer to $jc in the script, you are in fact referring to that specific func_scriptmodel entity in the game map. In this case, it's a JC model because the value of the model field is pl_jc.def and the initial animation sequence for the model is an idle, sitting down position because the anim field is set to intro_sit_idle.
The $jc anim intro_sit_to_stand command tells the func_scriptmodel with a targetname value of jc to run the animation sequence intro_sit_to_stand which is the animation of JC rising from his chair.

Note:
All the models and their animation frames are viewable with SinView 1.2b.

3. Types of named entities

Named entities although they are all referred to by their targetname in SinScript, are not all the same in the sense that a certain number of commands will apply to a type but not to another type. Or some will be used at the beginning of a command while some others will be used at the end of the command line. The main idea here is that it's important to know the difference in order to use the syntax properly.

In the previous example, I described in detail the meaning of every key/attribute of the func_scriptmodel entity and what the command in the thread does. Although this was not essential to the understanding of the relation between the script's $<entityname> to entity's targetname, I did it for a reason. In the case of a func_scriptmodel, the anim command is "proper syntax" per se because the entity is designed to be used as a controllable game model in the map. And since the JC model (pl_jc.def) has several animation frame sequences to choose from, the anim command definitely applies in this case. If the func_scriptobject's model key value was set to something like shotgunclip.def (shotgun ammo box) which has only a single frame, the anim command wouldn't apply although the syntax would be "legal".

This example clearly shows that it's tedious at best to draw a clear line between what applies and what doesn't for all the named entities. For now, I will stick to dividing those in coarse categories and try to keep things as consistent as possible within each of the categories. The finer details are covered in the Command reference and the tutorials.

4. Moveable entities

As the name suggests, this includes any named entities than can be moved around but also rotated, instructed to follow paths, shown, hidden or removed entirely from the map. All of those are visible objects by default except for the func_scriptorigin and the func_camera. The func_scriptmodel has the additional capability to be animated when it's model field is set to a monster or actor model. In those cases, it's also possible to customize their AI behavior by using the relevant commands to this effect. Monster and actor entities also have this capability.



5. Effects entities

This includes controllable lights, positionned sound generators, explosion and particle effects and solids that can break, shatter or explode. The areaportal, although not an "game effect" as such, was included in this category but really belongs in a category of it's own. Although some of these entities might be "moveable", they are not really meant to be moved as such.




6. Positional data entities

These entities are refererred to as destination points in SinScript to move game models (actors, monsters, world objects), brush objects and cameras to specific locations on the map or to a marker which defines the starting point of a path to follow (info_splinepath). They can also serve as a directional beacon for a camera to point at. They are not objects and this makes a big difference in the way they are adressed in the script syntax. Most of the time, the reference to these entities is at the trailing end of a command line rather than at the beginning for real objects.

The func_spawn is a special case because it's a location marker for game models that will be spawnwed at some point during the game (it can't be used as a location to move objects to). At first, it can only be referred to by its $<spawntargetname_value> and only one command applies to it: spawn $<spawntargetname_value>. But once the model is spawned, it is then referred to by its $<targetname_value> and all the script commands that apply to game models apply to the func_spawn thereafter. For all intents and purposes, consider the func_spawn as a location marker that turns into a func_scriptmodel after the excution of the spawn command in the script.

Unfortunately, one thing I can't ascertain at this point is whether these entities can themselves be moved or not in the map with script commands. In the context of a game with strong ABO features, it strikes me as logical for this to be the case but I really don't know for sure.




7. Conclusion

That's all for named entities. Of course, there are a lot more details and particularities about many of them. Way too much in fact to cover them all in this one section. Our goal here was to provide you with a perspective on the greater picture and we hope that we have succeded in answering to the question: "what does that $ sign means". Again, I'm sorry for the clunky term "named entities". But since entities such as info_pathnode are so different from actual game objects (models or brushes), I was very reluctant to using the term "named objects" because I felt that it did not accurately describe the entire range of entities that can be referred to with a $ sign in SinScript or the way "real objects" are adressed versus "locations" in the syntax structure.

Previous: Threads Next: Variables