Note: For further explaination of how XML loading works, you can read more about it later in this document.
- This is the main way of loading entities into your scene. Once a level editor is created it will be able to load entities using this method as well. Here's the flow on how an Entity and its components are loaded through XML definition
- Entity template file
- An XML file contains a list of all the types of entities in your game. This file's path should be "Content/Entities/EntityTemplates.xml".
- Note: If you would like to change the paths to your definition files, those paths are setup in the Settings.xml file, how the name 'EntityTemplates' must be used for the XML file itself.
Here's an example of two entities that were setup for the demo sample
<Description>A human player</Description>
- Also near the top of the file notice the 'Asset Type' is "QuickStart.Entities.EntityDefinition"
- Each 'Item' in the XML is of the type that is defined by the 'Asset Type', so in this case each item is an
EntityDefinition. Those entity definitions are used to load an Entity in the game.
- Every 'TemplateID' must be unique.
- 'Name' is currently stored in the game but are not used for anything other than reference.
- 'DefinitionXML' is the name of the entity definition XML file. This file must be in the folder specified in the Settings.xml file by 'EntityDefinitionsDirectory'. In the case of the sample demo the path is 'Content/Entities/EntityDefinitions'.
- 'Description' is not stored in-game anywhere, it's just for your reference within the XML file.
- Now that you know how to add an entity to this list, but now you have to give that entity a definition file, which we talk about in the next section 'Entity definitions file'.
- Entity definitions file
- Let's take a look at entity definition for the Wooden Crate in the sample demo. In the Entities.xml it is the entity with a 'TemplateID' of 2. Notice its 'DefinitionXML' is 'Crate'. This means the entity definition file is called Crate.xml. If you look
in Content/Entities/EntityDefinition/Crate.xml. Go ahead and open that file.
- Note: The full path to Crate.xml is 'framework/test/QuickStartSampleGame/Content/Entities/EntityDefinition/Crate.xml'
- Every xml has an 'Asset Type', just like Entities.xml has. In the case of the Entity definitions file, the asset type is "QuickStart.Entities.ComponentDefinition", so basically the entity definition is an array of component definitions, this
will let you define which components are on your entity. The layout is somewhat similar to the Entities.xml layout, here's the Crate.xml file's layout:
- The layout is very simple, you have the 'type' which is the type of component. This matches up with the ComponentType enum located at the top of BaseComponent.cs. And you have the 'XMLDefinitionPath', which is the location of the XML that describes how
that component is defined. (Yes, one more type of XML file, then we're done, I promise).
- Component definition file
- Like the other XML files you'll again notice an 'asset type', the asset type in this case is a 'QuickStart.Components.RenderComponentDefinition'. All component definitions are located in ComponentDefinitions.cs, in the 'Components/ComponentLoadingDefinitions'
folder within the QuickStart_Windows project.
- Based on the entity definition file we have above, we see that the Crate has a render and physics component. Let's take a look at the render component, which has a path of 'Render/WoodenCrateRender'. And remember, the base of the paths are defined in the
Settings.xml, so the full path to the file is 'Content/Entities/ComponentDefinitions/Render/WoodenCrateRender'. If we open up the file we find this:
<MeshColor>1.0 1.0 1.0 1.0</MeshColor>
XNA's XML reader does not accept number suffixes, if you want to specify a float value, like 1.5f, you need to leave the 'f' off of the end or you'll get an error when you try and build the game.
- If you look at the RenderComponentDefinition class within ComponentDefinitions.cs you will see that its variables match the XML perfectly. So what this XML does is define those variables when it loads,
then the RenderComponentDefinition is passed to a
RenderComponent, and its properties are passed to the component, then the component is attached to the entity. This process is done for all components on that entity.
- To recap the entire process of loading an entity and its components from XML, here's the loading steps:
- SceneManager's CreateAndAddEntityByTemplateID() function is called and passed a template ID.
- The template ID matches an entity located within an XML file that contains all entity templates. This file's location is specified by your Settings.xml file.
- An entity template has a 'DefinitionXML', which tells the engine which file contains the list of components that specific entity needs to have loaded onto it. The location of the entity definition xml files is also specified by your Settings.xml file.
- The entity definition XML file has a list of all components on that entity, and each of those components that are listed have an XML file that has the data for all the variables for that component (or the definition that is used to create the component).
- And that's it. It may seem tricky at first, but once you've created a couple of entities you'll find it is actually fairly simple.