The best way to identify something is by its name. Because of this, entities and components are generally required to be named, as are items in the level file and TemplateManager. This chapter discusses how names work and how to look things up by name.
Names, Templates, and Entities
When you instantiate entities from a level file, they are automatically registered with the NameManager under the name specified in the level data. However, there is a key point to be aware of. No matter what, when you create a new entity, it will be registered under the name specified in the level file.
However, the way that the entity was defined controls how closely the engine checks what is going on. If you use an <entity> tag, then the engine assumes you only want one of that entity around at a time. This is what you want for things like the scene, or one-off level elements. If you try to make two of the same <entity>, then it will report an error.
However, for entities like bullets, you will probably want many in the world at a time. For these types of entities, you should use the <template> tag, which causes the engine to simply reassign its name with no error message.
Looking Up Entities
<!-- An empty, named entity. -->
<!-- Components would go here, although an empty entity is valid. -->
// How to look it up from code: var namedEntity:IEntity = PBE.lookupEntity("NamedEntity");
<!-- How to reference an entity from XML. -->
<!-- EntityReference is a field of type IEntity. The entityName attribute indicates that we want to set it to a reference to the named entity.-->
Looking up an entity by name is simple. You can do it from code, or via the level file.
Looking Up Components
<!-- A named entity, with some named components. -->
<!-- The type of these components are irrelevant for the examples in this section. -->
// Looking up a component by type and entity name. This returns component "A". var componentA:ExampleComponent = PBE.lookupComponentByType("NamedEntity", ExampleComponent) as ExampleComponent; // Look up a component by entity name and component name. This returns component "B". var componentB:AnotherComponent = PBE.lookupComponentByName("NamedEntity", "B") as AnotherComponent; // You can also look up components on an entity (either your owner as shown // here, or a reference gotten via the NameManager or another means). This // code snippet would have to be run from a component in NamedEntity, as // otherwise owner would not reference the right thing. var componentA:ExampleComponent = owner.lookupComponentByName("A");
You can look up components by name in several ways. You can look them up in code or XML. You can also look them up via the NameManager, or via methods on IEntity.
You can also look up another component by type, as mentioned in the component chapter.
<!-- How to reference a component from XML. -->
<!-- This is a component that we will reference by name in the other component. --> <!-- ComponentReference is a field that has a component type (ExampleComponent in this case). The entityName attribute indicates that we want to look up the first component with matching type on the named entity.--> <!-- Another ComponentReference is a field that has a component type (AnotherComponent in this case). entityName is as above, but componentName lets you indicate the specific component you want, based on name. --> <!-- Finally, you can reference components on the same entity as you by only using the componentName attribute. -->