Overview & Hierarchy

Overview

XML is used in the Alamo engine as both a data set and a scripting language. All of the game data, object data and effects are done in XML. Internally we call it the effects system because if used well it can reproduce pretty much anything you want to do without requiring changing the underlying code of the game.

This document does not cover the entire expanse of the effects system as that would likely require hundreds of pages. Instead, this document will give you an overview of the basics that will allow you to replace, add or change data to mod the existing game.

Hierarchy

The effects system has a hierarchy that must be followed. Each type in the hierarchy can be referenced by any other type to create chains of data that work together. Knowing where the references exist is very important for getting the effects you want. This list starts from the highest level to the lowest.

File

Each XML file represents a single complete item or a set of similarly themed items. In order for an XML file to be recognized by the game, it must appear in the GameObjectFiles.XML master file (with some exceptions). Note that standard mods likely will not require this step, but if you are doing more in-depth changes you may need to reference this file.

Object

An object is an item that can function on its own in the game. For example, a Tank unit is an object, and a superweapon ability is an object. Note that objects can be linked together to form functionality, but can be dropped in a game without those links and still function. For example, I can make a tank unit without the cannon attack ability and drop it in the game. It won’t fire a weapon without the ability, but it can still roll around on the map. There are multiple object types that determine which components can be added to them – examples include Unit, Building, Ability, Prop, etc.

Component

A component is a pre-coded block of XML that adds a specific type of functionality to an object. Objects are made up of multiple components. For example, the WalkLocomotorComponent allows a unit to move around, and the SelectComponent allows the unit to be selected and details select rings and visuals. Not all units can use all components; for example, you can’t add the WalkLocomotorComponent to a Building since buildings don’t move. Each component has a set list of tags that are used to define the parameter of the behavior.

Effect Generator

An effect generator is a trigger that activates an effect based on the parameters that you set up. Effect generators must be tied to some action to activate them. Effect generators can do MANY things, but they do require a great deal of knowledge about the system to use well and won’t be covered in detail in this document.

Effects

Effects are the actions taken when an effect generator is triggered. Generators can have multiple effect classes within them, and effect classes can trigger new generators. Effects can’t do anything without a generator to trigger them. Effects are generally a one-shot occurrence unless paired with an ability.

Ability

Abilities are an action that a unit or the player can use repeatedly. Abilities can be autonomous (like a tank firing its cannon) or require player input (like a superweapon). Most abilities are one of two types: Weapon (where a unit or object fires something) or Effect (where a unit or object activates something unique). Like effects, abilities can be set up with specific parameters required to fire them, but unlike effects, abilities can fire themselves over and over.

Object States

Object states are flags that can be used for many purposes including target filtering, effect generator activation, build restrictions, etc. All object states for the game are listed in one place: ObjectStates.XML

Attributes

Attributes are variables that take numeric values. They can be used in formulas, used to track progression, used as limits to construction, etc. Like Object States, they are generally used as part of the effects system to further tune effects to the desired outcome.

Tags

The term “tag” refers to specific data settings that can be applied within a component. Tags are generally unique to a specific component, though not always. For example, in the WalkLocomotorComponent you will find the tag MaxSpeed – this sets how fast the unit will move.

Note that tags do not always have to belong to a component. In some cases, tags are used as pure data lists. A major example of this is in the file GameConstants.XML which is just a long list of tags that set data points that are used for the entire game rather than specific objects.

In most cases, if you want to mod something, you will be changing or adding data to one or all of the items in the hierarchy list. Below we will give you examples of how you would approach different situations to change or add data to the game.