Guide for dataset contribution

This page describes the data structure used by OpenRTS.

• Dataset is engine-independent.
• 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 definitions.

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 each definition 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 only keep the last read.

In the nomenclature :

• "Link" is a parameter containing the ID of another definition.
• "List" is a parameter that may be used many times (see examples below).

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>

A Unit is the base component of an army, controllable by a player or an AI.

Required values :

• 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 : Meters by second.

Optional values :

• WeaponList : Can be added multiple time, each contains a WeaponLink (see #Weapon) and an optional TurretLink (see #Turret).
• UIName : Show up 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>

A weapon is a mechanism held by an unit, that launch an effect automatically. A weapon may shot at enemies, throw projectiles, heal allies...

Required values :

• EffectLink : The effect to launch at firing (see #Effect).
• ActorLink : An Actor to launch at firing, like an animation of a particle (see #Actor).
• Range : How far the weapon can shoot.
• ScanRange : How far the unit start moving to get in range.
• Period : Delay between two attack.

Optional values :

• SourceBone : The projectile source.
• DirectionBone : The projectile initial direction.
• UIName : Is shown in the graphic user interface.

Note : if a projectile is launched and there is no source or direction bone, the projectile will be fired from the center and the direction of the unit.

Turret

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

Turret is a mobile part of an unit (rotating around Z). It is used by a weapon to aim without rotating the unit itself. Turrets are useful to allow shooting while moving, or to make slow unit able to aim fast enemies.

Required values :

• Speed : Rotation speed when the weapon ask for an orientation, in radians per second.
• IdleSpeed : Rotation speed on reseting or spinning.
• OnIdle is the behavior of the turret when weapon doesn't ask anything :

• "Reset" : Turret returns to the default position.
• "ResetOnMove" : Reset only if unit moves.
• "Spin" : Turret spins. Set a negative IdleSpeed to spin counter clockwise.
• "Hold" : Turret never get back to the default position.

• BoneName : Name of the bone who will be used to rotate the turret model.

Projectile

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

Projectiles are flying (or falling) objects that are launched at a target like a point on the ground, or a Unit to seek. They launch an effect at arrival.

Required values :

• MoverLink : Indicates the mover to use (see #Mover).
• ActorLink : Indicates the model actor to use (see #Actor).
• Mass : To add acceleration/deceleration, and inertia in turns.
• Speed : In meters by second.
• Precision, define where the projectile should land, allows randomness on the arrival point :

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

Mover

<Mover id="GroundProne">
    <PathfindingMode value="Walk"/>
    <Heightmap value="Ground"/>
    <StandingMode value="Prone"/>
</Mover>

Movers are used to move things like units or projectile on the battlefield.

Required values :

• PathFindingMode, indicates how the mover get through the map :

• "Walk" : Find a way through all terrain obstacles.
• "Fly" : Go strait to the destination.
• "Fall" : Can jump off cliffs. (not yet implemented)
• "Jump" : Can jump on and off cliffs. (not yet implemented)
• "Stride" : Cliffs are not obstacles. (not yet implemented)

• Heightmap, indicates mover's altitude :

• "Ground" : Stay on the ground.
• "Sky" : Stay in the sky.
• "Air" : Can fly at any altitude (projectiles).

• StandingMode, specifies if the mover up vector must follow the terrain slope :

• "Stand" : Stay always vertical (typically a person).
• "Prone" : Tilt to follow the terrain (typically a vehicle).

Effect

Actor

Actors are used to represent anything on the battlefield. It may be a model to draw, a sound to play, a particle effect to emit, an animation to trigger... Everything that need to be drawn or played need an actor.

There are many types of actors :

ModelActor

<Actor id="Aircraft">
    <Type value="Model"/>
    <ModelPath value="dir/aircraft.mesh.xml"/>
    <Scale value="1"/>
</Actor>

Required values :

• Type : "Model" to indicate it is a ModelActor.
• ModelPath : Where to find the model's file.

Optional values :

• Scale : 0.5 is half the size, 2 is double size. Default is 1.
• ScaleX/ScaleY/ScaleZ : To set different scales on each axis.

AnimationActor

<Actor id="Run">
    <Type value="Animation"/>
    <AnimName value="run"/>
    <Speed value="2"/>
    <Cycle value="Cycle"/>
</Actor>

Required values :

• Type : "Animation" to indicate it is an AnimationActor.
• AnimName : Name of the animation to launch.
• Speed : To accelerate or slow the animation.
• Cycle, indicates what to do at the end of the animation :

• "Once" : Do nothing.
• "Loop" : Play again.
• "Cycle" : Play backward.

ParticleActor

<Actor id="Machinegun">
    <Type value="Particle"/>
    <SpritePath value="particles/flame.png"/>
    <NbCol value="2"/>
    <NbRow value="2"/>
    <Velocity value="5"/>
    <Fanning value="0.1"/>
    <Duration value="100"/>
    <MaxCount value="30"/>
    <PerSecond value="100"/>
    <StartSize value="0.2"/>
    <EndSize value="0.1"/>
    <StartColor R="255" G="255" B="0" A="180"/>
    <EndColor R="255" G="0" B="0" A="255"/>
    <MinLife value="0.2"/>
    <MaxLife value="0.6"/>
</Actor>

If using an animated particle, the image will be read from left to right and top to bottom. (?)

Required values :

• Type : "Particle" to indicate it is a ParticleActor.
• SpritePath : Where to found the particle sprite file.
• Velocity : (?)
• Fanning : (?)
• Duration : Effect duration (?)
• MaxCount : (?)
• PerSecond : Particle to spawn by seconds (?)
• MinLife : Min duration of a particle (?)
• MaxLife : Max duration of a particle (?)

Optional Values :

• StartSize : Particle size at spawn.
• EndSize : Particle size before destroy.
• StartColor : Particle Color on spawn.
• EndColor : Particle Color before destroy.
• NbCol value : Column inside the image if animated.
• NbRow value : Row inside the image if animated.

MapStyle

CliffShape

NaturalFace

ManmadeFace

Trinket