Skip to content

Guide for dataset contribution

Jump to bottom Edit New page
Benoît edited this page Jun 16, 2015 · 25 revisions

Attention: This page is now marked as depreceated. In future we will get a editor to handle all the things for you ;-)

This page describes the data structure used by OpenRTS.

Generality

  • 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.
  • ActorLink : Indicates the model actor to use.
  • 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 weapon ID and an optional turret ID.
  • UIName : Show up in the graphic user interface.
  • Race : The tech-tree containing that unit.

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

  • ActorLink : An Actor to launch at firing, ie. an animation or a particle.
  • 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.
  • ActorLink : Indicates the model actor to use.
  • 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

Effects create interactions between battlefield's components. An effect have a single behavior according to it's type (see below), and may launch one or more children effects to form a chain (or a tree).

Initially, an effect is launched with :

  • a source, for exemple a unit, a building, or a player,
  • a target, a unit, a building, a point on the map,

and gives it to all it's children.

There are many types of effects :

DamageEffect

<Effect id="PunchDamage">
  <Type value="Damage"/>
  <Amount value="9"/>
</Effect>

Required values :

  • Type : "Damage" to indicate it is a DamageEffect.
  • Amount : The amount of life to subtract to the target health.

LauncherEffect

<Effect id="StdLauncher">
  <Type value="Launcher"/>
  <EffectLinkList value="StdDamage"/>
  <EffectLinkList.../>
  <ProjectileLink value="StdProjectile"/>
</Effect>

Required values :

  • Type : "Launcher" to indicate it is a LauncherEffect.
  • EffectLinkList : The effect to trigger at projectile arrival.
  • ProjectileLink : ID of the projectile

Note : the projectile does NOT launch its own effect. It only sends a message to the launcher effect when it arrives (or gives up).

PersistentEffect

<Effect id="DoubleShot">
  <Type value="Persistent"/>
  <PeriodCount value="2"/>
  <DurationList value="0"/>
  <DurationList value="0.5"/>
  <DurationList.../>
  <RangeList value="0"/>
  <RangeList value="0.1"/>
  <RangeList.../>
  <EffectLinkList value="ShotEffect"/>
  <EffectLinkList value="ShotEffect"/>
  <EffectLinkList.../>
</Effect>

Required values :

  • Type : "Persistent" to indicate it is a PersistentEffect.
  • PeriodCount : the total number of children effects to launch.
  • DurationList : the time to wait before next period. You can specify as many as you need.
  • RangeList : a random delay (from 0 to value) to add to the corresponding period. You can specify as many as you need.
  • EffectLinkList : the effect to launch at the corresponding period. You can specify as many as you need.

Note : the period count is priority. If you specifiy more durations than the count, some won't be triggered. If you specify a larger count, durations will be cycled.

Note : you may specify different numbers of durations, ranges, and effects. The tables will by cycled independently of each other. This may lead to unexpected result, but can be usefull to add variety or stochasticity.

SpawnEffect

Not yet implemented. Will allow to create a new unit.

BuffEffect

Not yet implemented. Will allow to change any caracteristic of the source or target.

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>

Required values :

  • Type : "Particle" to indicate it is a ParticleActor.
  • SpritePath : Where to found the particle sprite file.
  • MaxCount : The maximum number of particle living at the same time for this emitter.
  • PerSecond : Particles to spawn by seconds.
  • MinLife : Min duration of a particle. Life is randomly choosen between min and maxfor each particle.
  • MaxLife : Max duration.
  • StartSize : Particles' size at spawn.
  • EndSize : Size at end of life.
  • StartColor : Particles' color at spawn. including alpha.
  • EndColor : Color at end of life.

Optional Values :

  • RotationSpeed : Particles may spin around. Set a negative value to rotate in the other direction. "0" by default.
  • EmissionBone : The name of the bone on the parent model, where the emitter emits. Default : the center of the parent model .
  • DirectionBone : The name of the bone that indicate the direction. Default : a vector in front of the parent model.
  • NbCol : For multiple sprites, the number of columns inside the image.
  • NbRow : For multiple sprites, the number of rows inside the image.
  • RandomSprite : The particle picks a sprite randomly inside the image and keep it.
  • Velocity : The initial speed of the particle in meter by second. "0" by default.
  • Fanning : An angle in degrees to vary the velocity direction. 20 will make a cone, 180 half a sphere, 360 all around.
  • Duration : The life time of the particle emitter in millisecond. "0" means it emits only one particle. By default, the particle emitter will live until the actor stops playing.
  • Gravity : If true, the particles fall. False by default. There is currently no way to set the particle's mass.
  • Facing :
  • Default : The particles' sprite face the camera.
  • "Velocity" : The particles face the velocity vector direction.
  • "Horizontal" : The particles face the sky.
  • Add : Set to false to allow particles' transparency.
  • StartVariation : Distance to specify a sphere around the emitter. The particle will be spawned at any point inside that sphere.

Note : If using an animated sprite, the image will be read from left to right and top to bottom.

SoundActor

<Actor id="TankExplosion">
    <Type value="Sound"/>
    <SoundPath value="monoexplosion1.wav"/>
    <Volume value="1"/>
    <Looping value="false"/>
    <Positional value="true"/>
</Actor>

Required values :

  • Type : "Sound" to indicate it is a SoundActor.
  • SoundPath : Where to find the sound's file.

Optional values :

  • Volume : Default is 1.
  • Positionnal : The sound will be played louder if the camera is near the source. False by default.
  • Looping : The sound will be repeated infinitly. False by default

Note : OpenRTS supports only OGG and WAV formats.

MapStyle

<MapStyle id="RockyDesert">
    <Width value="240"/>
    <Height value="133"/>
    <CliffShapeLink value="StdManmade"/>
    <CliffShapeLink.../>
    <GroundTexture diffuse="textures/grass_diffuse.png" normal="textures/grass_normal.png" scale="8"/>
    <GroundTexture diffuse="textures/dirt_diffuse.png" scale="8"/>
    <GroundTexture.../>
    <CoverTexture diffuse="textures/paving.png" scale="64"/>
    <CoverTexture.../>
</MapStyle>

Required values :

  • CliffShapeLink : a cliff shape that will be available in the editor. You may add up to 8 different cliff shapes.
  • GroundTexture : a texture used to paint the ground. Each GroundTexture contains :
  • a link to a diffuse map,
  • optionally, a link to a normal map,
  • a scale (if 32, the scale will fit 32 times in the map). You may add up to 8 ground textures.

Optional values :

  • Width :
  • Height : Default is 64.
  • CoverTexture : a texture used to paint above the ground. Typically transparent, the cover textures are used to add details on the ground, whatever the ground texture is (dead leafs, tree roots, pavements...) Each CoverTexture contains :
  • a link to a diffuse map,
  • optionally, a link to a normal map,
  • a scale (if 32, the scale will fit 32 times in the map). You may add up to 7 cover textures.

Note : The first cover texture is set to a fully transparent default layer, used to erase other covering textures.

OpenRTS supports many file format for texture. We suggest PNG for tranparent ones, and JPG for others.

You may set up to 12 files for a single material. So the 8 diffuses won't be able to come each with a normal, which would made 16 files. You can have 8 diffuses/4 normals, or 7 diffuses/5 normals, or 6 diffuses/6 normals.

CliffShape

<CliffShape id="RockyCliff">
    <NaturalFaceLink value="NaturalDugFace"/>
    <TrinketList link="FallenRocks" prob="0.2"/>
    <TrinketList.../>
    <RampTrinketList link="DroppingPlant" prob="0.5"/>
    <RampTrinketList.../>
</CliffShape>

Required values :

  • NaturalFaceLink : OR
  • ManmadeFaceLink : the link to the face to use to construct the cliff. See NaturalFace and ManmadeFace

Optional values :

  • TrinketList : a link to a trinket that wil be used to decorate the cliff and it's propabaility to happen. You may specify as many as needed.
  • RampTrinketList : idem for ramps' cliffs.

NaturalFace

<NaturalFace id="NaturalDugFace">
    <Style value="dug1"/>
    <Color R="76" G="63" B="44"/>
    <NoiseX value="0.5"/>
    <NoiseY value="0.5"/>
    <NoiseZ value="0.5"/>
    <RidgeDepth value="0.5"/>
    <RidgePosition value="0.5"/>
</NaturalFace>

Required values :

  • Style : The name of the procedural algorithm ta use for this face.
  • Color : a solid lighned color to apply to the face OR
  • TexturePath : a texture to apply to the face.

Optional values :

  • Noise :
  • NoiseX :
  • NoiseY :
  • NoiseZ : Offset to apply on all/each/certain axes for all vertices in the natural face.
  • RidgeDepth : Offset to apply to the center of the face to accentuate or smooth its curve on salient and corner elements.
  • RidgePosition : Offset to apply to the center of the face to add randomness.

Note : you should spcecify a color OR a texture. Not both. Color will be priority.

ManmadeFace

    <ManmadeFace id="Building">
        <OrthogonalList path="models/env/interior01/wallA.mesh.xml" weight="1"/>
        <OrthogonalList.../>
        <SalientList path="models/env/interior01/wallAngle1A.mesh.xml" weight="1"/>
        <SalientList.../>
        <CornerList path="models/env/interior01/wallAngle2A.mesh.xml" weight="1"/>
        <CornerList.../>
    </ManmadeFace>

Required values :

  • OrthogonalList : A link to a model to use as orthogonal element.
  • SalientList : A link to a model to use as salient element.
  • CornerList : A link to a model to use as corner element.

For each type of cliff, you must specify at least one model, but you can specify as many as you want. The selection will be done randomly, according to the weight. A model with a hight weight will have better chances to be used.

For exemple, if A-model has a weight of 1 and B-model has a weight of 50, the A-model has 1 chance on 51 to be choosen.

Weight must be between 1 and 50 included.

Trinket

    <Trinket id="FallenRock">
        <Editable value="false"/>
        <ModelList value="env/exterior01/rockA.mesh.xml"/>
        <ModelList..."/>
        <Color R="76" G="63" B="44"/>
        <RotationX min="0" max="360"/>
        <RotationZ min="0" max="360"/>

        <PositionX min="-0.2" max="0.2"/>
        <PositionY min="0" max="1"/>
        <PositionZ min="0.2" max="1.2"/>

        <Scale min="0.7" max="1.4"/>
    </Trinket>

Required values :

  • ModelList : The name of a model to use for that trinket. You must specify at least one, and as many as needed.

Optional values :

  • Editable : allow the trinket to be manipulated in the editor. True by default. Uneditable trinkets may be used for automatic grass, or trinkets generated by cliffs' faces.
  • Color : a solid lightned color to apply as a material. Will override the model's material if any.
  • Rotation :
  • RotationX :
  • RotationY :
  • RotationZ : Random rotation between Min and Max values in degrees, to apply to the model. Default is 0.
  • Position :
  • PositionX :
  • PositionY :
  • PositionZ : Random translation between Min and Max values in meters, to apply to the model. Default is 0.
  • Scale :
  • ScaleX :
  • ScaleY :
  • ScaleZ : Random scale between Min and Max values, to apply to the model. Default is 1.

Note : For rotations, positions and scales, you can set one value for each axes or one, two or three values independantly.

Add a custom footer
Add a custom sidebar
Clone this wiki locally