As my final blogpost I’ll share what documentation I currently have for my XML tool, as well as the links to the documents in which I am working.
The documentation is split into two areas, the programming side, which utilizes XML definitions and provides additional functionality for their equations, and the XML side.
Programming side can be found here:
Design side can be found here:
A project to help test and check out the system can be downloaded here:
The XML Property Set system allows for groups (named property sets) of values (named properties) to be defined through an XML file and loaded into the game. It also allows for the defining of interactions between different groups which may have requirements based on current properties, modify properties and be given custom delays.
In our game, property sets are used to contain a lot of information behind agents, buildings, signs and transport structures.
One of the benefits of using this sort of system rather than setting values within the editor is that the tool parses formulas. (For example, ‘GenerateName(Random(3, 8))’ would return a randomly generated orc name of a length of 3, 4, 5, 6 or 7. Another example is when an agent acts upon a healing building, actor.health could be set to ‘Min(actor.health + healer.healAmount, actor.maxHealth’). This provides a lot of potential functionality behind how orcs are affected by various things.
Please note from this point on it is merely a copy paste from the documents, which I recommend you read instead.
The code side
Implementing a new XML accessible function
Introduction
Implementing a new function for XML is extremely easy to do. Quite simply, the method to add a new function should be called in a GameSystem loaded before the XmlLoader system and is used as follows:
CalculatedValue.AddFunction(“MyFunctionName”, MyFunctionForXml);
where MyFunctionForXml is of the following format:
void MyFunctionForXml(Stack<object> stack, PropertySet actingCarrier, PropertySet targetCarrier);
Stack can be found in System.Collections.Generic, and PropertySet can be found in the Orcward namespace.
Returning a value
To have your function return a value, that value must be pushed onto stack. For example:
void Return10 (Stack<object> stack, PropertySet actingCarrier, PropertySet targetCarrier)
{
stack.Push(10);
}
Given the system is based predominantly on strings and integers, in most cases they are the values you will be returning. That being said, it is possible to return any type from a function, although it would have to be used within another function which expects that type as a parameter.
Handling parameters
There is no limit as to how many parameters your function can have. Parameters are accessed by popping values (and casting them) from the stack in the order you wish them to be passed. It is important that regardless of the state of the game, each implementation of the function will pop the same parameters every time it is called.
void Random (Stack<object> stack, PropertySet actingCarrier, PropertySet targetCarrier)
{
int min = (int)stack.Pop();
int max = (int)stack.Pop();
stack.Push(Random.Range(min, max));
}
Accessing Property Sets
In the case where you wish to access the property sets related to the current equation, they’re passed as parameters. Although they are usually not needed, they could be used for a functions such as “ActorsGreatestStat”.
Returning multiple parameters
In some cases you may find it needed to return multiple parameters. Although this should generally be avoided (try having two different functions?), it may be necessary at times. When returning multiple values, make sure you push them onto the stack in the opposite order to that which they would be accessed. It is also important that you then clearly document that the function returns two values, and will count as two parameters for any function it is passed into.
For example, if a function ‘Return3And10′ happened to return 3 and 10 each time it were called, first 10 would be pushed, followed by 3. It could then be used as two integer parameters in the Random function for example.
Random(Return3And10())
The above equation would return a value between 3 and 10.
More information about actually using the PropertySet (and other) class(es) to come.
The XML side
There are 3 main tags that can be found in a file. These are Container, PropertySet and Interaction. Within these sets, other tags may be available (Property, Modifier, Requirement, etc.)
Container
A container is a set of one or more tags. They bring the benefit of replacing the name ‘this’ within their contents with the containers name. Although the use may not immediately appear apparent, as you read on you will notice how it can rapidly speed up production, and help in the sorting of tags.
In theory, a file itself is a Container, with a name given by the XML file name (eg. the file test.xml is a container named ‘test’), but due to the nature of XML, the file Container can only hold one child tag. Due to this, files will generally use that one child tag, to create a container.
Example within “examplemachine.xml”
<Container name=”this”>
<!– Container contents go here –>
</Container>
By naming this root container ‘this’, it has adopted the name of the parent container (in this case, the file container). This means the container is named ‘examplemachine’.
Property Sets
A Property Set is (as suggested), a set of Properties. When defining a Property Set, you give it a name and if needed, the Property Set it extends.
Defining a Property Set
A Property Set is defined as follows. The entire ‘extends’ attribute is removed if the Property Set does not extend any other set.
<PropertySet name=”setname” extends=”parentset”>
<!– Properties go here –>
<!– Interactions go here –>
</PropertySet>
Extension
When a Property Set extends another Property Set, all Properties and Interactions involving that set are inherited. Any Properties then defined within the set that share a name with a Property in a parent set will override them. Interactions can also be overriden
Properties
The main feature of a Property Set, is the Properties. A Property is a value (usually an integer) that belongs to the set. For example, an ‘orc’ PropertySet might have a ‘health’ Property.
Defining a Property
Properties are defined as follows.
<PropertySet name=”exampleset”>
<Property name=”exampleproperty” type=”int” value=”10″/>
</PropertySet>
Interactions
An Interaction is as the name suggests, an interaction between two Property Sets. Each Interaction can have multiple Requirements that must be met to be carried out, and multiple Modifiers which are called if the Requirements are met. If the requirements are met, an optional delay may be carried out before the modifiers are called.
<PropertySet name=”exampleset”>
<Interaction with=”otherset” name=”dothing” delay=”1000″>
<!– Requirements go here –>
<!– Modifiers go here –>
</Interaction>
</PropertySet>
Requirements
Requirements define condition that must be met for an interaction to take place. It’s worth noting due to the use of XML, less than must be represented by ‘<’ rather than ‘<’.
<Requirement check=”machine.stock < machine.maxstock”/>
Modifiers
Modifiers define changes to properties upon the interaction between two property set.
<Modifier target=”machine.stock” value=”machine.maxstock + 1″/>
