-
Notifications
You must be signed in to change notification settings - Fork 112
etg_user_guide
\
Events and effects are created using a text editor such as SlickEdit. These files are of type .ETG. They are then ‘made’ using nmake.exe and the makefile in DataSrc/ETG. This creates a file of type .EBG which is what the game loads.
\
As a general rule, to following conventions apply to ETG script files:
-
Line comments can be created using the ‘//’.
-
Multi-line comments can be created with the ‘/* Comment here */’ convention.
-
C preprocessor directives, such as #include, #define, #if and #error are all available.
-
There is only ever 1 statement per line. ‘’ count as statements. Lines can be blank, however.
-
Blocks of like statements are grouped together in braces ‘’. These are also used to delimit conditional code such as in an ‘if’ or ‘alternate’.
-
Statements with parameters usually have parentheses ‘()’ surrounding the parameters.
-
Expressions (mathematical expressions and constant numbers) are surrounded by brackets ‘[]’. No variables are permitted in expressions because these are evaluated at load time.
-
Before anything is defined in an effect the ‘effectStart’ or ‘eventStart’ must appear.
-
All expression blocks can be in multiple parts. For example, there can be two ‘variable’ blocks.
-
‘effectStart’ or ‘eventStart’ declares the start of an effect or event. The name with which it will be called is defined by the file. The parameters to these statements are the parameters to the effect, separated by spaces.
-
‘variable’ block contains all variable definitions.
-
‘startup’ contains statements executed at startup of the effect, i.e. when it is created.
-
‘eachFrame’ contains statements executed each frame.
-
‘timeIndex’ like ‘eachFrame’ is executed each frame but contains time index operations.
\
All variable definitions can be defined in effect declaration (‘effectStart’, ‘eventStart’), ‘variable’ blocks or outside any blocks. In the effect declaration, they are parameters to the effect passed from the game code. In variable blocks they are variables or effectors local to that effect. When outside all code blocks, they are for defining constant data such as animation sequences. In variable blocks or parameter declarations, they can be inialized by providing a number after the ‘=
‘. For constants, however, there is no name or ‘=’ and it must have a number.
\
Here are the variable types available and examples of how to use them:
Type
declaration example
variable example
constant example
32-bit integer
int LOD
int counter = 1
int 23456
32-bit floating-point
float size
float temp
float 3.5423
color
RGB color
RGB color = col256(200, 54, 20)
RGB col256(200, 54, 20)
color/alpha
RGBA color
RGBA color = cola256(200, 54, 20, 128)
RGBA col256a(200, 54, 20, 128)
texture declaration
subTextureDWORD(TexName00, 32768, 1)
\
Labels have 3 uses in ETG files. They are used to pass a reference to constants or variables and they are used for branching. The syntax is the same for all cases, however: label(<labelName>). For code labels, forward references are permitted, but not for variable of constant labels.
\
There are several types of conditionals in ETG. The syntax for these different statements differs considerably. Here are the different statements and how they work.
Type
Required context
Example
Notes
Comparison
Any code block
if (a = b)
{
…statements
}
else
{
…statements
}
Can be nested, else is optional.
Alternate
Any code block.
alternate
{
alt1(1):
…statements
alt2(6):
…statements
}
Can be nested. See later comments on interpretation of the ‘altn()’ statement. Which one to execute chosen at random at effect startup.
Case statement
Any code block
caseof(<integer var>)
{
case(0):
…statements
case(1):
…statements
}
Which one to execute chosen based upon value of variable.
Time-index effector
Time index block
timblock(size)
{
time(0, 10)
time(1.5, 120)
}
Only effect variable between stated time and previous time.
One-time conditional
eachFrame or timeIndex blocks
at(1.4)
{
delete()
}
Executes the code only once at the given time.
Many-time conditional
eachFrame or timeIndex blocks
every(.2)
{
…statements
}
Executes with a frequency of 1/stated time.
\
Program-like branching can be performed within an effect. Branching can jump between code blocks and takes several forms. Have a look-see:
Type
Example
Notes
Standard branch
goto(standardLabel)
\
Subroutine branch
call(standardSub)
Like ‘gosub’ in BASIC
Subroutine return
return
\
Stop processing effect for this frame
end()
Only stops processing this particular code block
Stop processing effect permanently
delete()
Deletes the effect from the universe
Pause execution till next frame
yield()
Not implemented
\
\
\
\
These functions can be used to modify the current effect. They are most useful at startup of the effect to modify it’s physics attributes derived from the parent ship.
Name
Context
Example
Notes
particleBlocks
Anywhere
particleBlocks(12)
Changes number of particle systems effect can spawn. Default is 8.
effChangeLOF
anywhere
effeChangeLOF(theta, mu)
Adjusts the LOF from the current.
\
\
\
\
\
\
\
\
\
\
\
\
effOffsetLOF
startup mostly
effOffsetLOF(10.5)
Moves the effect forward or back.
effOffsetR
startup
effOffsetR(R, theta, mu)
adjust location of effect in cylindrical coordinates
effOffsetXYZ
startup
effOffsetXYZ(x, y, z)
adjust location of effect in cartsian coords
effOffsetVelLOF
startup
effOffsetVelLOF(-125)
offset (add) effect velocity
effOffsetVelR
startup
effOffsetVelR(R, theta, mu)
offset(add) effect velocity.
EffScaleVelocity
startup
effScaleVelocity(0.95)
multiply scale by a certain amount
effOffsetSpin
startup
effOffsetSpin(2.5)
impart a spin(radians/second) to an effect
effOffsetTime
startup, mostly
effOffsetTime(-1)
Adds to the time of an effect to allow delays etc.
\
\
\
\
\
\
\
\
\
Some effects are designed to borrow particle system parameters from the effect which spawned them. Besides all the particle system parameters which are relevant, some parameters of the spawned effect can be modified. Here is a list of the parameters which can be modified. This relieves the effect from doing these things itself. Their parameters are identical to the previous list, except they are named differently.
Name
Purpose
setEffOffsetLOF
New effect offset from current effect.
SetEffChangeLOF
Change new LOF coordinate system.
SetEffOffsetR
Radial offset of position
setEffOffsetXYZ
Offset new position
setEffOffsetVelLOF
Offset velocity
setEffOffsetVelR
\
setEffOffsetSpin
New spin rate
setEffOffsetTime
New time offset
setEffOffsetDrag
Added to drag of current effect
setEffDrag
Absolute drag
setEffDefaults
Zero out all these parameters.
\
\
\
There are many functions for tweaking the many parameters of particle systems. These functions must be called before the particle system is created in order to have an effect. These parameters also are retained internally which means that if an effect doesn’t set the defaults, it will get particle system parameters from the previous effect or event which set them. These functions can be called anywhere particle systems can be created (startup or eachFrame blocks). Following is a list of how to set them.
Name
Purpose
parameters
Ranges/Units
Default
setDefaults
sets all particle system parameters to defaults
none
\
yes, thanks!
SetDrag
Sets drag on the particles
drag
0(infinite drag)..1(zero drag)
0
setScale
Size of particles
size
m
4
setScaleDist
Scale distribution
+dist
scale deviation in meters
2
setDeltaScale
Change in size
delta
m/s
0
setDeltaScaleDist
Distribution of above
\
\
\
Functions below determine particle distribution
setDistributionType
Control type of distribution
symbol
DIST_CYL,DIST_SPR,DIST_RING
DIST_CYL
setOffsetLOF
Initial offset along LOF
offset
m
0
setOffsetR
initial offset about LOF
radius
m
0
setOffsetTheta
angle about R to offset
angular offset
rad
0
setOffsetArray
Add an x,y,z to the position of each point in a particle system
array of points (constants)
None
setDeltaLOF
initial distribution from offsetLOF
offset
m
0
setDeltaLOFDist
distribution for above
\
\
\
setDeltaR
initial distribution about
radius
m
1
setDeltaLOFDist
variance for above
\
\
\
setDeltaR
initial angular delta from offsetR
startAngle, endAngle
rad
0, 2*PI
setDeltaRDist
distribution for above
\
\
0, 2*PI
setVelLOF
velocity along LOF
velocity
m/s
17?
SetVelLOFDist
variance from above
\
\
1
setVelR
radial velocity
velocity
m/s
0.45
setVelRDist
variance for above
\
\
\
setDeltaVelLOF
acceleration along LOF
acceleration
m/s^s^
.5
setDeltaVelLOFDist
variance for above
\
\
0
setDeltaVelR
acceleration about LOF
acceleration
m/s^s^
0
deltaVelRDist
variance for above
\
\
0
\
\
\
\
\
Functions below determine particle attributes
setLength
length of lines
length
m
0.8
setLengthDist
variance
\
\
0.3
setColor
particle color
4 floats
0..1 per channel
.8,.8,.8,1
setColorDist
variance for above
4 floats
-1..1
0,0,0,0
setDeltaColor
rate of change
4 floats
delta/s
0,0,0,0
setDeltaColorDist
Distribution for above
4 floats
\
0,0,0,0
setLighting
Flag as effected by light
BOOL (nonzero int is true)
True, False
FALSE
setIllum
self-illimination
float
0..1
1
setIllumDist
variance
\
\
0
setDeltaIllum
change over time
float
delta/s
0
setDeltaIllumDist
variance
\
\
0
setLifespan
duration for particles
float
seconds
2
setLifespanDist
variance
\
\
.4
setWaitSpan
time to wait before particles start
float
seconds
0
setWaitSpanDist
variance
\
\
0
setCircleSlices
number of polygon slices in circle
int
3+
16
setMeshData
set the mesh used by mesh particles
name
any mesh loaded previously
none
setMorphTarget
sets the morph target for a mesh particle
name
any mesh, but must match mesh already set
none
setMorphTime
sets the time taken to perform the morph
float
seconds (>0)
1
setTumbleSpeed
sets the rate at which mesh rotates
3 floats
rad/s for x, y, z
0, 0, 0
setTexture
set texture for sprites
name
any previously loaded texture
none (draws circle)
setAnimation
set animation sequence for sprites
animation (startAnimation)
set a texture animation
none
setAnimateRate
set speed of animation
float
seconds/frame (>0)
.5
setAnimFrame
animation frame to start from
int
>=0
0
setSpriteRotAngle
initial angle of sprite rotation
float
rad
0
setSpriteRotAngleDist
variance of above
\
\
0
setSpriteDeltaRot
speed of continued rotation
float
rad/sec
0
setSpriteDeltaRotDist
variance of above
float
\
0
\
There are several functions for creating particles. The only parameters to these functions is the number of particles to create and a variance on the number of particles. The particles are created with the previously set parameters from the preceding table. The return value from these functions is an integer which can be used as a ‘handle’ to change parameters (see next section).
\
Name
Purpose
Notes
createCircles
Creates a set of circular particles.
Same as createSprites() but with no texture
createPoints
creates a set of points with size.
size is actual pixel size, which it gets from scale
createLines
Creates lines with size.
width comes from scale parameter
createSprites
Create sprites
Needs a texture or animation to be specified.
createMeshes
Create mesh particles.
Needs a mesh to have been specified.
createEffects
Spawn effects using particle distributions.
Also has an effect name as a parameter. Does not return a handle.
createZybots
Creates a particle system using Zybots® as particles.
Uses default logic for animating the Zybots.
createLights
Creates light particles.
Not to be implemented initially.
\
\
\
\
A currently running particle system can have certain attributes modified. This is done with a special set of functions which modify the parameters of all particles in a particle system. This functionality is provided as a way to perform complex animations which cannot be performed with the standard particle system parameters. These functions will set the parameter for all particles in a particle system so some are not suitable for certain distributions, such as time offset distributions. The actual particle system to modify is referenced by an integer which is returned from the function which created the particle system. This integer is always the first parameter.
\
Name
Purpose
Notes
modifyDrag
Change drag of particles
\
modifyScale
Change size of particles
\
modifyDeltaScale
\
\
modifyColor
Change the color/alpha
\
modifyDeltaColor
Change color change
\
modifyLighting
Change lighting flag
\
modifyIllumination
Change self-illumination
\
modifyDeltaIllimination
Change self-illumination delta
\
modifyLifespan
Change duration of particles
\
modifyMesh
Change mesh
Can be used for animation
modifyMorphTarget
sets the morph target for a mesh particle
any mesh, but must match mesh already set
modifyMorphTime
sets the time taken to perform the morph
seconds (>0)
modifyTumbleSpeed
sets the rate at which mesh rotates
rad/s for x, y, z
modifyTexture
Change texture
Can be used for animation, or will replace a current running texture animation.
modifyAnimation
Change animation of textures
Will replace a current static texture.
modifyAnimFrame
Set current animation frame.
\
\
\
\
modifyLength
Change length of lines
\
modifyVelocity
Change a particle’s speed.
Multiply velocity by parameter
modifyDeltaVelocity
Change acceleration
Multiply acceleration by parameter
modifyRotAngle
Change sprite rotation angle
rad
modifyRotAngleDelta
Change sprite rotation speed
rad/s
\
\
\
\
\
\
\
There are a number of other functions and operations available if so desired. Here is a listing of what other features are available.
Name
Purpose
Usage
Notes
nop
no-operation, but I’m not sure why you’d do this
nop
Performs no operation.
DeleteParentShip
Delete parent ship
deleteParentShip()
used when ships are exploding
inc
increment an integer
frame <- inc(frame)
\
dec
decrement an integer
\
\
div/fdiv
divide integer/floats
size <- fdiv(parentSize, 10)
\
mult/fmult
multiply numbers
\
\
add/fadd
add numbers
\
\
sub/fsub
subtract numbers
\
\
random
choose random integer
switch <- random(10, 20)
Chooses a number in a range (inclusive exclusive)
frandom
choose a random float
opacity <- frandom(.5, 1.0)
this one is inclusive/inclusive
prandom
choose a random percentage (0..1)
opacity <- prandom(50, 100)
inclusive/inclusive
spawn
create a new effect or event
spawn(smallboom.ebg, LOD, size)
LOD parameter will almost always be there
\
\
\
\
\
\
\
\
\