Interwiki>Silentwings: /* Overall Format */

2020-05-13T14:35:13Z

Overall Format

New page

= CEG Definitions =

==Source==
The engine source code which loads the tags from these files is viewable here:

* {{sourcelink|file=rts/Sim/Projectiles/}}
* {{sourcelink|file=rts/Sim/Projectiles/Unsynced/}}
* {{sourcelink|file=rts/Rendering/GroundFlash.cpp}}

== Data Types ==
CEGs use the following data types:
{{DataTypes}}

You can use [[CEG:Operators]] to define floats that are not fixed.

== CEG Textures ==

* Textures on CEG definitions are referenced by name.
* The list of available textures and their names should be in [[resources.lua]]
* Texture definitions to be used in projectile classes should be placed within the <code>projectiletextures</code> category and textures to be used with [[#CSimpleGroundFlash]] class should be placed within the <code>groundfx</code> category.
* Texture images are usually placed in the "bitmaps" subfolder.

== Overall Format ==

A CEG file contains one or more CEGs. Each CEG follows this format:

<pre>
return {
["ceg_name"] = {
-- EXPLOSION LEVEL
useDefaultExplosions = false,

spawner1_name = {
-- SPAWNER LEVEL
class = "CClassName",
count = 1,
air = true,
ground = true,
water = true,
properties = {
-- CLASS LEVEL
},
},
},
spawner2_name = {
-- SPAWNER LEVEL
-- each spawner follows the above format
},
groundflash = {
-- groundflash is a special spawner name; it always generates a CStandardGroundFlash
-- CStandardGroundFlash properties
},
-- other special spawner names exist, although their use is discouraged in favour of class="CSomeClass"
-- see https://github.com/spring/spring/blob/develop/cont/base/springcontent/gamedata/explosion_alias.lua#L61
},
}
</pre>

== Explosion Level Tags ==
{{tag
|name = useDefaultExplosions
|type = bool
|default = false
|description = If this is set, the CEG will use the default explosion (based on damage and area of effect) in addition to any spawners you define. The default explosions are sometimes very performance heavy, especially for large damage values (leading to higher particle counts).
}}

== Spawner Level Tags ==
A CEG can contain any number of spawners. The name of the spawners don't really matter, as long as it's not <code>groundflash</code>, which has a special meaning. You can think of each spawner as being one component of the overall explosion.

{{tag
|name = class
|type = string
|default = spawner_name
|description = Each spawner has a class that determines what kind of graphical effect it creates. Spring has a number of standard classes that you can choose from. Currently available classes are:
* [[#CExpGenSpawner|CExpGenSpawner]]
* [[#CBitmapMuzzleFlame|CBitmapMuzzleFlame]]
* [[#CExploSpikeProjectile|CExploSpikeProjectile]]
* [[#CHeatCloudProjectile|CHeatCloudProjectile]]
* [[#CSimpleParticleSystem|CSimpleParticleSystem]]
* [[#CSpherePartSpawner|CSpherePartSpawner]]
* [[#CSimpleGroundFlash|CSimpleGroundFlash]]
* [[#CStandardGroundFlash|CStandardGroundFlash]]
}}

{{tag
|name = count
|type = int
|default = 1
|description = The count determines the number of times the spawner will run.
}}

=== Visibility Conditions ===
These determine under what conditions the spawner will run. If you set the condition to true, the spawner will run if the explosion takes place under that condition. If you set more than one condition, the spawner will run if ''any'' of them are true. If you want a spawner to run only if two or more conditions are ''all'' true, you have to do a little trick with the [[#CExpGenSpawner]] class as explained in "suggested use".

{{tag
|name = air
|type = bool
|default = false
|description = The CEG will run if at least 20 [[elmo]]s above ground/sea level.
}}

{{tag
|name = water
|type = bool
|default = false
|description = The CEG will run if in water to a depth of -5 [[elmo]]s.
}}

{{tag
|name = underwater
|type = bool
|default = false
|description = The CEG will run if under water deeper than 5 [[elmo]]s.
}}

{{tag
|name = ground
|type = bool
|default = false
|description = The CEG will run if less than 20 [[elmo]]s above ground.
}}

{{tag
|name = unit
|type = bool
|default = false
|description = The CEG will run if the weapon hits a unit.
}}

{{tag
|name = nounit
|type = bool
|default = false
|description = The CEG will run if the weapon does not hit a unit.
}}

== Class Level Tags ==
=== Common Properties ===
All classes have the following properties, although not all of them use them:

{{tag
|name = alwaysVisible
|type = bool
|default = false
|description = If true, the spawner is always visible, ignoring LoS. Note that prior to 98.0 this did not work correctly.
}}

{{tag
|name = useAirLos
|type = bool
|default = false
|description = Whether the spawner uses air LoS to determine if it is visible. This may allow the spawner to be seen from a further distance than normal.
}}

{{tag
|name = pos
|type = float[3]
|default = {0.0, 0.0, 0.0}
|description = The initial position vector of the spawner.
}}

{{tag
|name = speed
|type = float[3]
|default = {0.0, 0.0, 0.0}
|description = The initial speed vector of the spawner.
}}

{{tag
|name = dir
|type = float[3]
|description = The initial direction vector of the spawner.
}}

=== CExpGenSpawner ===
This is the closest thing CEG has to a function call. Instead of creating a graphical effect on its own, it creates another CEG.

==== Suggested Use ====
* If you use a spawner a lot of times, you may want to make it a separate CEG to avoid having to copy-paste many times.
* This is the only way to truly delay a graphical effect.
* The spawned CEG still checks conditions, so if you want to, say, spawn an effect only if it is in water ''and'' doesn't hit a unit, you can give the CExpGenSpawner <code>nounit = 1;</code> and the spawned <code>CEG water = 1;</code>.
* This allows you to give a set of spawners the same (and possibly random) direction.
* You can animate an explosion flip-book style using delays and several bitmaps.

==== Properties ====

{{tag
|name = delay
|type = int
|default = 1
|description = How long to wait (in frames?) before spawning the CEG.
}}

{{tag
|name = damage
|type = float
|default = 0.0
|description = The CEG will be called with this damage. The CEG doesn't actually deal any damage, but you can use this as a parameter and read it using the [[CEG:Operators#Damage_.28.27d.27.29|'d' operator]].
}}

{{tag
|name = explosionGenerator
|type = string
|default = ""
|description = The name of the CEG you want to spawn.
}}

=== CBitmapMuzzleFlame ===
This creates three rectangular textures at right angles to each other. The {{taglink|frontTexture}} has {{taglink|dir}} as its normal.

==== Suggested Use ====
*Muzzle flames, obviously.
*You can use an upward-pointing CBitmapMuzzleFlame as a simple splash of water or dirt.
*Railgun trails.
*This is the only class that both obeys perspective and allows for a custom texture.

==== Properties ====

{{tag
|name = sideTexture
|type = string
|default = ""
|description = Texture as viewed from the side.
}}

{{tag
|name = frontTexture
|type = string
|default = ""
|description = Texture as viewed from the front.
}}

{{tag
|name = colorMap
|type = string
|default = ""
|description = See [[CColorMap]].
}}

{{tag
|name = size
|type = float
|default = 0.0
|description = The initial width of the muzzle flame.
}}

{{tag
|name = length
|type = float
|default = 0.0
|description = The initial length of the muzzle flame.
}}

{{tag
|name = sizeGrowth
|type = float
|default = 0.0
|description = By the end of its life, the muzzle flame grows to <code>1 + sizeGrowth</code> times its initial {{taglink|size}} and {{taglink|length}}. The flame grows quickly at first and more slowly toward the end.
}}

{{tag
|name = ttl
|type = int
|default = 0
|description = How long the muzzle flame lasts.
}}

{{tag
|name = frontOffset
|type = float
|default = 0.0
|description = Where the frontTexture is along the length of the muzzle flame. <code>0</code> means it is in the back, <code>1</code> is in the front.
}}

=== CExploSpikeProjectile ===

This creates a glowy spike. Note that the spike is two sided, i.e., symmetric about the position of the spawner.

==== Suggested Use ====
* Anything glowy.
* For large, slow missiles, you can try using this as an extended engine flame. Set the width to something fairly large.
* Long and thin spikes will look spiky; meanwhile, shorter and wider spikes look more blobby.
* The colors of spikes add together, so if you have several spikes and all three color channels are non-zero, it will be white in the center.
* The length growth of the spike depends on the norm of the dir vector. The spike does not grow in width.

==== Properties ====
{{tag
|name = length
|type = float
|default = 0.0
|description = The initial length of (half) of the spike (multiplied by {{taglink|dir}}).
}}

{{tag
|name = lengthGrowth
|type = float
|default = dir.Length() * (0.5 + RandFloat() * 0.4)
|description = How much the length increases by per update.
}}

{{tag
|name = width
|type = float
|default = 0.0
|description = Half the initial width of of the spike. This is an absolute value.
}}

{{tag
|name = alpha
|type = float
|default = 0.0
|description = The starting alpha of the spike.
}}

{{tag
|name = alphaDecay
|type = float
|default = 0.0
|description = How quickly the alpha of the spike decreases.
}}

{{tag
|name = color
|type = rgb
|default = {1.0, 0.8, 0.5}
|description = The color of the spike.
}}

=== CHeatCloudProjectile ===

Creates an expanding sprite. Simple but effective.

==== Suggested Use ====
* As the main background to an explosion.

==== Properties ====
{{tag
|name = heat
|type = float
|default = 0.0
|description = Used in alpha calculations. See {{taglink|heatFalloff}}.
}}

{{tag
|name = maxheat
|type = float
|default = 0.0
|description = Used in alpha calculations. See {{taglink|heatFalloff}}.
}}

{{tag
|name = heatFalloff
|type = float
|default = 0.0
|description = This is really confusing way of representing alpha and alphaDecay. Basically <code>alpha = </code>{{taglink|heat}}<code>/</code>{{taglink|maxheat}}, and <code>alphaDecay = </code>{{taglink|heatFalloff}}<code>/</code>{{taglink|maxHeat}}.
}}

{{tag
|name = size
|type = float
|default = 0.0
|description = The initial radius of the heatcloud.
}}

{{tag
|name = sizeGrowth
|type = float
|default = 0.0
|description = The heatcloud grows by this amount every frame.
}}

{{tag
|name = sizeMod
|type = float
|default = 0.0
|description = The size of the heatcloud is multiplied by <code>1 - sizeMod</code>.
}}

{{tag
|name = sizeModMod
|type = float
|default = 0.0
|description = Each frame, {{taglink|sizeMod}} is multiplied by {{taglink|sizeModMod}}.
}}

{{tag
|name = texture
|type = string
|default = "heatcloud" as referenced in [[resources.lua]]
|description = The texture used for the heatcloud.
}}

=== CSimpleParticleSystem ===

Creates a sprite that can undergo complex motion. Probably the most versatile class.

==== Suggested Use ====
* Anything moving that is not doing so at constant velocity.
* If you want something that expands (or shrinks) to some size then stops, set {{taglink|sizeMod}} to something less than <code>1</code>, and {{taglink|sizeGrowth}} to something positive. The particle will grow to a size equal to <code>sizeGrowth / (1 - sizeMod)</code> and stop. The smaller {{taglink|sizeMod}} is, the faster it will reach this size.

==== Properties ====
===== Initial Velocity Properties =====
{{tag
|name = emitVector
|type = float[3]
|default = {0.0, 0.0, 0.0}
|description = The initial direction vector in which the particle is emitted. When spawning CEGs via EmitSfx you can make the particles go into the direction of the emiting piece with {{taglink|emitvector|dir}}. This is useful for e.g. fire coming out of a gun barrel.
}}

{{tag
|name = emitRot
|type = float
|default = 0.0
|description = At what angle to emit the particle relative to {{taglink|emitVector}}. <code>0</code> means that the particle will be emitted in {{taglink|emitVector}}'s direction; <code>180</code> will emit the particle in the opposite direction. <code>90</code> will emit the particle in a random direction perpendicular to {{taglink|emitVector}}, which is good for creating rings.
}}

{{tag
|name = emitRotSpread
|type = float
|default = 0.0
|description = For each particle, a random number between <code>0</code> and {{taglink|emitRotSpread}} is added to the {{taglink|emitRot}}.
}}

{{tag
|name = emitMul
|type = float[3]
|default = {1.0, 1.0, 1.0}
|description = Scales the initial particle velocity; for this property, +y is considered to be in the direction of {{taglink|emitVector}}. Good if you want to create an egg-shaped explosion.
}}

{{tag
|name = particleSpeed
|type = float
|default = 0.0
|description = The particle's initial speed.
}}

{{tag
|name = particleSpeedSpread
|type = float
|default = 0.0
|description = For each particle, a random number between <code>0</code> and {{taglink|particleSpeedSpread}} is added to the {{taglink|particleSpeed}}.
}}

===== Movement Properties =====

{{tag
|name = gravity
|type = float[3]
|default = {0.0, 0.0, 0.0}
|description = This will be added to the particle's velocity every frame.
}}

{{tag
|name = airdrag
|type = float
|default = 0.0
|description = The particle's velocity is multiplied by this every frame.
}}

===== Size Properties =====

{{tag
|name = particleSize
|type = float
|default = 0.0
|description = The initial size of the particle.
}}

{{tag
|name = particleSizeSpread
|type = float
|default = 0.0
|description = For each particle, a random number between <code>0</code> and {{taglink|particleSizeSpread}} is added to the {{taglink|particleSize}}.
}}

{{tag
|name = sizeGrowth
|type = float
|default = 0.0
|description = How much the particle grows each frame.
}}

{{tag
|name = sizeMod
|type = float
|default = 0.0
|description = The size of the particle is multiplied by this each frame.
}}

===== Visual Properties =====

{{tag
|name = directional
|type = bool
|default = false
|description = If true, the particle will point in the direction it is moving.
}}

{{tag
|name = texture
|type = string
|default = ""
|description = The texture to use for the particle.
}}

{{tag
|name = colorMap
|type = string
|default = ""
|description = See [[CColorMap]].
}}

===== Life Properties =====

{{tag
|name = numParticles
|type = int
|default = 0
|description = How many particles to create. This is not the same as <code>count</code>; if you spawn multiple particles using <code>count</code>, any [[CEG:Operators]] will be re-evaluated for each particle, whereas if you use {{taglink|numParticles}} they will not be. However, the spread properties are evaluated separately for each particle regardless of which one you use.
}}

{{tag
|name = particleLife
|type = float
|default = 0.0
|description = How long each particle lasts.
}}

{{tag
|name = particleLifeSpread
|type = float
|default = 0.0
|description = For each particle, a random number between <code>0</code> and {{taglink|particleLifeSpread}} is added to the {{taglink|particleLife}}.
}}

=== CSpherePartSpawner ===

Draws an expanding sphere.

==== Suggested Use ====
*Looks like a shockwave.

==== Properties ====

{{tag
|name = alpha
|type = float
|default = 0.0
|description = The alpha of the sphere.
}}

{{tag
|name = ttl
|type = int
|default = 0
|description = Time to live, in frames(?).
}}

{{tag
|name = expansionSpeed
|type = float
|default = 0.0
|description = How quickly the sphere expands.
}}

{{tag
|name = color
|type = rgb
|default = {0.0, 0.0, 0.0}
|description = The color of the sphere.
}}

=== CSimpleGroundFlash ===

Draws an expanding ground texture.

==== Suggested Use ====
* A short groundflash (~8 frames) is good for any explosion that gives off light. You can also use a longer groundflash to suggest the ground is glowing from heat.

==== Properties ====

{{tag
|name = size
|type = float
|default = 0.0
|description = The radius of the particle.
}}

{{tag
|name = sizeGrowth
|type = float
|default = 0.0
|description = How much the particle grows each frame.
}}

{{tag
|name = ttl
|type = int
|default = 0
|description = Time to live, in frames(?).
}}

{{tag
|name = texture
|type = string
|default = ""
|description = The texture to use for the particle.
}}

{{tag
|name = colorMap
|type = string
|default = ""
|description = See [[CColorMap]].
}}

=== CStandardGroundFlash ===
If you name a spawner "groundflash," it will always generate a standard groundflash.

==== Suggested Use ====
A short groundflash (~8 frames) is good for any explosion that gives off light. You can also use a longer groundflash to suggest the ground is glowing from heat.

==== Properties ====

{{tag
|name = flashSize
|type = float
|default = 0.0
|description = The radius of the groundflash.
}}

{{tag
|name = flashAlpha
|type = float
|range = [0, 1]
|default = 0.0
|description = How transparent the groundflash is. Generally the higher the brighter.
}}

{{tag
|name = circleGrowth
|type = float
|default = 0.0
|description = A groundflash can have an additional circle that expands outwards. This controls how fast the circle grows.
}}

{{tag
|name = circleAlpha
|type = float
|range = [0, 1]
|default = 0.0
|description = How transparent the circle is.
}}

{{tag
|name = ttl
|type = int
|default = 0
|description = How long the groundflash lasts.
}}

{{tag
|name = color
|type = rgb
|default = {1.0, 1.0, 0.8}
|description = The color of the groundflash.
}}

=== CSmokeProjectile2 ===
( {{FIXME}} newly added to wiki. someone cross-check then remove this note )

Particles that begin with a hard-coded yellow-red colorfade and then fade to monochrom. (shades of grey)

Movement is influenced by the random wind.
Finer details of visual and position update are best explained by looking at the formulas in <code>CSmokeProjectile2::Update() & CSmokeProjectile2::Draw()</code>

==== Suggested Use ====
Smoke. Smokestacks, rocket exhaust, burning wreckage,...

For a nicer stream of smoke spawn it frequently over multiple frames, otherwise it looks rather bland.

==== Properties ====
{{tag
|name = color
|type = float
|default = 0.5
|description = How dark the final monochrom color of a particle is. 0 is black.
(Use >1 for slightly bugged funnies, like slightly non-monochrome colors or interessting black/white changes.)
}}

{{tag
|name = size
|type = float
|default = 0.0
|description = Size of a particle.
}}

{{tag
|name = ageSpeed
|type = float
|default = 0.5
|description = How fast the particle ages. Every frame: <code>age += ageSpeed</code> The particle is deleted at <code>if (age > 1)</code>
}}

{{tag
|name = glowFalloff
|type = float
|default = 0.0
|description = How fast the particle fades to monochrom.
}}

{{tag
|name = wantedPos
|type = float3
|default = "0,0,0"
|description = In which direction the smoke tends to drift. Less effective in y-coordinate and influenced by random wind.
}}

{{tag
|name = speed
|type = float3
|default = "0,0,0"
|description = <code>wantedPos += speed;</code> How fast and in which vector the particles move.
}}

{{tag
|name = texture
|type = hardcoded
|default = randomly chosen.
|description = Particles randomly pick one of the smoke textures (bitmaps\smoke) and remain with it until death.
}}

=== CSmokeProjectile ===
Monochrome particles that fade out.
A more "primitive" version of CSmokeProjectile2.
No hardcoded red-yellow start but it misses wantedPos to tweak the look a bit more detailed.

==== Suggested Use ====
Smoke.
For a nicer stream of smoke spawn it frequently over multiple frames, otherwise it looks rather bland.

==== Properties ====
{{tag
|name = color
|type = float
|default = 0.5
|description = Brightness of the particle. 0 is black.
}}

{{tag
|name = size
|type = float
|default = 0.0
|description = Size of a particle
}}

{{tag
|name = ageSpeed
|type = float
|default = 0.5
|description = How fast the particle ages. Every frame: <code>age += ageSpeed</code> The particle is deleted at <code>if (age > 1)</code>
}}

{{tag
|name = speed
|type = float3
|default = "0,0,0"
|description = <code>pos += speed;</code> How fast and in which vector the particles move.
}}

{{tag
|name = texture
|type = hardcoded
|default = randomly chosen.
|description = Particles randomly pick one of the smoke textures (bitmaps\smoke) and remain with it until death.
}}

==Examples==


[http://imolarpg.dyndns.org/trac/balatest/browser/trunk/gamedata/explosions 'Balanced Annihilation' CEGs] (TDF format)

[http://code.google.com/p/conflictterra/source/browse/#svn%2Fgames%2FCT%2Fgamedata%2Fexplosions 'Conflict Terra' CEGs]

[https://github.com/EvolutionRTS/Evolution-RTS/tree/master/Gamedata/explosions 'Evolution RTS' CEGs]

[https://github.com/imperialwinter/swiw.sdd/tree/master/gamedata/explosions 'Imperial Winter' CEGs] (TDF format)

[http://code.google.com/p/journeywar/source/browse/#svn%2Ftrunk%2Fgamedata%2Fexplosions 'Journeywar' CEGs]

[http://sourceforge.net/p/mwspring/code/HEAD/tree/effects/ 'MechCommander: Legacy' CEGs] (TDF format)

[https://github.com/spring1944/spring1944/tree/master/effects 'Spring: 1944' CEGs] (TDF format)

[http://code.google.com/p/springtutorialgame/source/browse/#svn%2Ftrunk%2FSpringTutorialGame.sdd%2FGamedata%2Fexplosions 'Spring Tutorial Game' CEGs]

[http://code.google.com/p/xta-springrts/source/browse/#svn%2Ftrunk%2Fgamedata%2Fexplosions 'XTA' CEGs] (TDF format)

[https://github.com/ZeroK-RTS/Zero-K/tree/master/effects 'ZeroK' CEGs]

[[Category:CEG]]

CEG:Defs - Revision history

Qrow: 1 revision imported

Interwiki>Silentwings: /* Overall Format */

← Older revision	Revision as of 22:21, 13 November 2025
(No difference)