# TypeDef Documentation

## Contents

[toc]

## C# Game Engine

### EntityCreator

#### CreateEntity

Instantiates a TypeDef, setting up the properties and calling Initialize with the provided position.

Parameters:
- string name: The name of the TypeDef being instantiated.
- Vector\<float> position: The position to created the entity at.

EntityConfig.LoadedEntityDefs[name].InstantiateAt(position);

### IInstantiable

IInstantiable is the interface that represents a TypeDef. Anything referenced in a TypeDef file needs to implement IInstantiable in order for it to be able to be created.

#### TypeDef

A property that represents what TypeDef represents this entity. Added in #167.
This property exists in order to replace the use of Types, as the TypeDef system does not use unique Types for each instantiated object.

EntityDef TypeDef { get; set; }

#### SetProperty

SetProperty is used during object initialization to set the properties of an object as they are defined in the XML file.

The name is the identifier of the property that needs to be set.
The property is the object that should be stored in that property.

Property is the result of GetValue called on whatever propertyDef defines that property. It requires casting to the proper type.

void SetProperty(string name, object property);

---

##### Change Proposal

Replace set property with a property registering method.

void RegisterProperties();

class Instantiable : IInstantiable
{

    private string StringProperty { get; private set; }
    private int IntProperty { get; private set; }
    private Class ClassProperty { get; private set; }
    
    public void RegisterProperties()
    {
        RegisterProperty<string>(value => { StringProperty = value; });
        RegisterProperty<int>(value => { IntProperty = value; });
        RegisterProperty<Class>(value => { ClassProperty = value; });
    }
    
}

---

#### Initialize

Initialize is called at the end of object instantiation, once all the properties have been set.

The most common use for this method is to put the created entity in the location provided by initializePosition.

void Initialize(Vector<float> initializePosition);

#### PreInitialize

Pre-initialize is called at the start of object instantiation, before any of the properties have been set.

void PreInitialize(Vector<float> initializePosition);

## Writing TypeDefs

TypeDef is the name for the XML storage of Entities. The name of the first child attribute does not matter.

<Entities>
    <Entity>
        ...
    </Entity>
    <Banana>
        ...
    </Banana>
</Entities>

Entity and Banana will be treated the same.

### Boolean Types

Boolean types can be written by simply writing true or fals.e

<VarName>true</VarName>
<VarName>false</VarName>

### Numerical Types

Basic numerical types can be parsed by inserting a number in the text space between a tag.

<VarName>0</VarName>
<VarName>5.1</VarName>
<VarName>5.128673</VarName>
<VarName>-6</VarName>

### Text Types

Any text that isn't a boolean or numerical will be saved into a string.

<VarName>Any text</VarName>

### Entity / Class Types

Internally Entity and Classes are treated as the same thing.

When the parent of an entity/class tag is instantiated, the parent or class associated with this variable will also be instantiated.

Example:

class ClassA : IInstantiable
{
    
    ClassB Variable { get; private set; }
    
    ...
    
}

class ClassB : IInstantiable
{
    
    int IntegerProperty { get; private set; }
    
    ...
    
}

When the ClassA class is created, ClassB will be instantiated with whatever values are provided.

<Entity Class="ClassA">
    <Variable Class="ClassB">
        <IntegerProperty>5</IntegerProperty>
    </Variable>
</Entity>

Note that currently there is no way to store a TypeDef for instantiation later, this needs implementing. (If we want to store an entityDef but not instantiate it, and only instantiate it when called, this is not possible)

### List Types

ListDefs are returned as a list of objects when GetValue is called on them.
They are defined by a parent component with ListEntry in their children.

<VariableName>
    <ListEntry>Value1</ListEntry>
    <ListEntry>Value2</ListEntry>
    <ListEntry>Value3</ListEntry>
</VariableName>

Note that the contents of list entries are defs themselves, so can contain complex types including entities and other lists.

<VariableName>
    <ListEntry>
        <AnotherList>
            <ListEntry>5</ListEntry>
            <ListEntry>10</ListEntry>
            <ListEntry>15</ListEntry>
        </AnotherList>
    </ListEntry>
</VariableName>

### Enumerable Types

Enum types do not need to be specified, as they are infered from the variable type with whatever the enum property is being applied to.

Enum types are specified by having a set of EnumValue children containing the name of the flag to add.

enum EnumExample
{
    FLAG_SAMPLE
}

class ExampleClass : IInstantiable
{
    EnumExample Flags { get; private set; }
}

<Flags>
    <EnumValue>FLAG_SAMPLE</EnumValue>
</Flags>

### Constants

The constant property can reference a value stored in a seperate place.

The constant referenced has to be defined in a constants file somewhere.

<Constants>
    <Constant Name="CONSTANT_NAME">
        273.15
    </Constant>
</Constants>

...

<VarName>
    <Constant Name="CONSTANT_NAME" />
</VarName>

During parsing `<Constant Name="CONSTANT_NAME" />` is replaced with 273.15.

### Property Types

Property is the default type that the xml variables will be saved as when the parser cannot determine the type of what is being represented in the XML file.

When GetValue() is called on a property type, the PropertyDef is returned without anything being created or parsed.

This can happen when a tag has children and doesn't have any of the following properties:
- Does not have the 'Name' attribute. (Is not a top level entity)
- Does not have the 'Class' attribute. (Is not an EntityDef)
- Does not have 'Components' as a parent element. (Is not a Component)
- Does not have 'ListEntry' as a child element. (Is not a list)
- Does not have 'DictEntry' as a child element. (Is not a dictionary)
- Does not have 'EnumValue' as a child element. (Is not an enum)
- Does not have 'Constant' as a child element. (Does not contain a constant)

<Property>
    <IntegerElement>5</IntegerElement>
    <StringElement>Hello!</StringElement>
</Property>

When parsed this will return a propertyDef with the Name 'Property' and 2 children Properties:
- An integerDef containing 5.
- A stringDef containing "Hello!"

### Special Tags

#### Components

Children elements of the components tag will be treated as classes rather than variable names. Any child component of the \<Components> tag is assumed to be a class.

<Components>
    <ComponentClassName>
        ...
    </ComponentClassName>
</Components>

## Potential Issues

This code should work?

<Entity Name="Thing">
    <PropertyEntity ParentName="Thing" />
</Entity>

## Changes Required

- ParentName (Cannot be instantiated on getValue() as this would allow for a self referencing loop of death) and Class tags are treated inconsistently.
- There is no way to store an entityDef, as they are automatically instantiated when GetValue() is called.
- Why is there no way to initialize things that don't have a position (data vs entities)?