Welcome, please login or register

PushButton Engine: Table of Contents » Names

Names

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 &;lt;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

Looking up an entity by name is simple. You can do it from code, or via the level file.

      
      <entity name="NamedEntity">
         
      </entity>      
   
      // How to look it up from code: 
      var namedEntity:IEntity = PBE.lookupEntity("NamedEntity");
   
      
      <entity name="ExampleEntity">
         <component name="NameExampleComponent">
            
            <EntityReference entityName="NamedEntity"/>
         </component>
      </entity>
   

Looking Up Components

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.

      <!-- A named entity, with some named components. -->
      <entity name="NamedEntity">
         <!-- The type of these components are irrelevant for the examples in this section. -->
         <component type="ExampleComponent" name="A"/>
         <component type="AnotherComponent" name="B"/>
         <component type="AnotherComponent" name="C"/>
      </entity>      
   
      // 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 also look up another component by type, as mentioned in the component chapter.

      
      <entity name="ExampleEntity">
      
         
         <component type="AnotherComponent" name="D"/>
         <component name="ComponentNameExampleComponent">

             
            <ComponentReference entityName="NamedEntity"/>

            
            <AnotherComponentReference entityName="NamedEntity" componentName="C"/>
            
            
            <YetAnotherComponentReference componentName="D"/>

         </component>
      </entity>