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 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, in meters by second

Optional values :

• 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>

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, as 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 of the unit and in its direction.

Turret

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

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 defaut position

• BoneName is the bone to rotate on the Unit's Actor's model

Projectile

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

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, allows 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

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

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

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, set to "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, set to "Animation" to indicate it is an AnimationActor
• AnimName, the 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 it again
• "Cycle" : play it 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>

MapStyle

CliffShape

NaturalFace

ManmadeFace

Trinket