Guide for dataset contribution

This page describes the data structure used by OpenRTS.

• Dataset is engine-independant,
• Stored in XML catalogs,
• Editable at runtime.

It is stored in assets/data directory. Whatever the files' names, the directories, and the place you store a XML definition, the engine will read everything at every change, and rebuild the library with all defintions.

That means you can store all units in a file and all weapons in another, or mix a unit with its weapons, turrets, projectiles... in a single file. All in any directory tree.

Each file must have a markup, containing all definitions like this :

<catalog>
    <[definition type] id="[definition id]">
        <[field1] value="..."/>
        <[field2].../>
        ...
    </[definition type]>
</catalog>

For on type there must be only one ID. For example, you may have a unit with ID="tank", and an actor with ID="tank", but if you have two units with ID="tank", then the engine will keep only the last read.

Note that XML interpreter is case sensitive.

Unit

<Unit id="tank">
    <UIName value="simple combat armored vehicle"/>
    <Race value="human"/>
    <Radius value="0.8"/>
    <Speed value="4"/>
    <Mass value="1"/>
    <MaxHealth value="120"/>
    <MoverLink value="myMover"/>
    <WeaponList WeaponLink="Canon" TurretLink="TankTurret"/>
    <WeaponList WeaponLink="Machinegun" TurretLink="MountedMachingun"/>
    <WeaponList WeaponLink="FrontLaser"/>
    <ActorLink value="Tank"/>
</Unit>

Required value :

• MoverLink, indicates the mover to use (see #Mover)
• ActorLink, indicates the model actor to use (see #Actor)
• MaxHealth, maximum amount of health the unit have
• Radius, collision size of the unit
• Mass, to add acceleration/deceleration, and inertia in turns
• Speed, in meters by second Optional value :
• WeaponList, as many as needed, each contains a WeaponLink (see #Weapon) and an otional TurretLink (see #Turret)
• UIName, as shown in the graphic user interface
• Race

Weapon

<Weapon id="TankCanon">
    <UIName value="ubber powerful canon"/>
    <EffectLink value="StdDamage"/>
    <Range value="5"/>
    <ScanRange value="7"/>
    <Period value="1.2"/>
    <ActorLink value="TankCanonMainActor"/>
    <SourceBone value="BMuzzle01"/>
    <DirectionBone value="BMuzzleVec01"/>
</Weapon>

Weapon is defined with an effect to trigger, an actor to play and some values.

Range is the distance in meter under which it is possible to fire. ScanRange is the distance at which the weapon asks the unit to move to get closer to the target. Period is the minimum time between two shots.

Source and direction bone are used for projectile launcher. The projectile will be spawned according to that bones.

Turret

<Turret id="Turret">
    <Speed value="200"/>
    <IdleSpeed value="20"/>
    <OnIdle value="ResetOnMove"/>
    <BoneName value="BTurret01"/>
</Turret>

Turret doesn't link to anything and is defined by some values.

Speed is the rotation speed when the weapon ask for a rotation, in degrees by second. Idle speed is the rotation speed when spinning, or resetting to the default position.

OnIdle is the behavior of the turret when weapon doesn't ask anything.

• "Reset" : turret returns to the default position if weapon doesn't ask anything.
• "ResetOnMove" : reset only if unit moves and weapon doesn't ask anything.
• "Spin" : turret spins. Set a negative IdleSpeed to spin counter clockwise.
• "Hold" : turret never get back to the defaut position.

Projectile

<Projectile id="Projectile">
    <Speed value="4"/>
    <Mass value="1"/>
    <Precision value="Center"/>
    <MoverLink value="Projectile"/>
    <ActorLink value="StdMissile"/>
</Projectile>

Very similar to a Unit, Projectile is defined by a mover, an actor, and few values.

Speed is in meter by second. Mass allow to add inertia and acceleration.

Precision can be changed to add randomness on the arrival point :

• "Center" : the projectile will seek the exact center of the target.
• "InRadius" : will seek a point inside the target bounding circle.
• other value : will seek a point inside a circle around the target of the specified radius.

Mover

Effect

Actor

MapStyle

CliffShape

NaturalFace

ManmadeFace

Trinket