Skip to content

Commit a9f3e5b

Browse files
author
Red Eclipse
committed
Build docs:164 from ac91e7e88dbd3e5e7a421439d5e222c0a9aabc63
1 parent 304b189 commit a9f3e5b

File tree

1 file changed

+130
-30
lines changed

1 file changed

+130
-30
lines changed

‎docs/editing/Fx.md‎

Lines changed: 130 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,8 @@ allowing for further creative customization of various audio/visual aspects of t
1717

1818
## Current support and usage
1919

20-
FX system is currently only used to script effects for weapons and projectiles.
21-
It will soon be extended to further remove hardcoded effects, as well as allow for model embedding and creation of map FX.
20+
FX system is currently only used to script effects for weapons, projectiles and entities.
21+
It may be expanded for creation of map FX in the future.
2222

2323
# The innerworkings
2424

@@ -103,12 +103,22 @@ Effects can be scheduled in various ways. To change how timing functions on an e
103103
Setting interval to a value of `1` implies a standard, non-periodic emission. Default: `1`.
104104
* `emittimeliness` - when enabled, makes sure a periodic emission will be able to finish its full cycle (`emitlen`) before trying to perform it.
105105
Generally, should only be used in cases when an emitter life is known. In other cases, emitters' life may be prolonged/refreshed (e.g. for projectiles), negating the need to have `activelen` predetermined, unless desired otherwise. Default: `0`.
106-
* `emitdelay`- postpones the emission by a given time in milliseconds. Default: `0`.
106+
* `emitdelay` - postpones the emission by a given time in milliseconds. Default: `0`.
107107
* `emitparent` - when enabled, automatically schedules emission to synchronize with a parent effect. Useful when a parent effect emits periodically (uses `emitinterval`).
108108
Default: `0`.
109109
* `emitsingle` - when enabled, prevents an effect from being prolonged/refreshed. Default: `0`.
110110
* `emitrestart` - when enabled, resets time-driven parameters (such as interpolation or fade-in) on effect prolong/refresh. Default: `0`.
111111
* `emitmove` - as opposed to rest being `integer` type, this one is `float`, when set above `0`, only allows emission when emitter moves at a given speed. Default: `0`.
112+
* `emitparam` - only allows emission when internal emitter parameter (see *"Internal parameters"*) of a given index (`integer`) becomes larger than 0. Default: `-1`.
113+
114+
## Iteration
115+
116+
Effect emissions can also be repeated by iterating an effect. It allows you to create repeated patterns using a single effect instance.
117+
118+
* `iter` - how many times an effect should be emitted. Default: `1`.
119+
* `iteroffset` - position vector offset between each emission. Default: `0, 0, 0`.
120+
121+
You can also modulate various properties by interpolating the values by the iteration. (*see "Property modifiers"*)
112122

113123

114124
### Example 1: single-shot emission for 1 second
@@ -150,6 +160,61 @@ Various properties can also have modifiers applied such as interpolation or rand
150160
**NOTE: In the supplied example a minimum interval of `2` is used, to ensure the emission is treated as periodic. Remember, value of `1` implies standard emission!**
151161
Emission will occur randomly from 2 to 1000 milliseconds (the random value is added to the base value).
152162

163+
## Positioning
164+
165+
By default effects will be emitted from the origin position the attached entity and in its direction.
166+
However, this can be overridden with the following properties:
167+
168+
The starting position of an effect is referred to as *position*, *pos* in short or *from*.
169+
The end position of an effect is referred to as *end* or *to*.
170+
171+
* `reloffset` - enforces all position calculations to be done with regards to the entity's direction. Default: `1`.
172+
* `posoffset` - offsets the starting position by a given vector. Default: `0, 0, 0`.
173+
* `endoffset` - offsets the end position by a given vector. Default: `0, 0, 0`.
174+
* `endfrompos` - sets the end position to be the same as the starting position, offset by a given vector. Disabled when vector is `0, 0, 0`. Default: `0, 0, 0`.
175+
* `posfromend` - sets the starting position to be the same as the end position, offset by a given vector. Disabled when vector is `0, 0, 0`. Default: `0, 0, 0`.
176+
* `posflip` - swaps the starting and end positions. Default: `0`.
177+
* `endfromprev` - sets the end position as the starting position from the previous frame. Default: `0`.
178+
* `posfromenttag` - sets the starting position to the position of an entity tag (see *"Entity positions"*). Default: `-1`.
179+
* `endfromenttag` - sets the end position to the position of an entity tag (see *"Entity positions"*). Default: `-1`.
180+
* `posfroment` - sets the starting position to one of the positions of an entity (see *"Entity positions"*). Default: `-1`.
181+
* `endfroment` - sets the end position to one of the positions of an entity (see *"Entity positions"*). Default: `-1`.
182+
183+
### Entity positions
184+
185+
Player entities have a number of predefined positions, which can be used to position effects.
186+
In addition, they also have a number of tags, which are attached to the entity's model bones, and follow the entity's animation.
187+
188+
### Entity position points
189+
190+
| Type | Value | CubeScript handle | Description |
191+
|--------|-------|--------------------|--------------------------------------------|
192+
| Origin | 0 | $FX_ENT_POS_ORIGIN | Origin position of the entity. |
193+
| Bottom | 1 | $FX_ENT_POS_BOTTOM | Bottom position of the entity. |
194+
| Middle | 2 | $FX_ENT_POS_MIDDLE | Middle (by height) position of the entity. |
195+
| Top | 3 | $FX_ENT_POS_TOP | Top position of the entity. |
196+
| Dir | 4 | $FX_ENT_POS_DIR | Origin offset by the entity's direction. |
197+
| Muzzle | 5 | $FX_ENT_POS_MUZZLE | Gun muzzle position of the entity. |
198+
199+
### Entity position tags
200+
201+
| Type | Value | CubeScript handle |
202+
|-----------|-------|-----------------------|
203+
| Camera | 0 | $FX_ENT_TAG_CAMERA |
204+
| Crown | 1 | $FX_ENT_TAG_CROWN |
205+
| Torso | 3 | $FX_ENT_TAG_TORSO |
206+
| Limbs | 5 | $FX_ENT_TAG_LIMBS |
207+
| Waist | 7 | $FX_ENT_TAG_WAIST |
208+
| Muzzle | 8 | $FX_ENT_TAG_MUZZLE |
209+
| Origin | 9 | $FX_ENT_TAG_ORIGIN |
210+
| Eject 1 | 10 | $FX_ENT_TAG_EJECT1 |
211+
| Eject 2 | 11 | $FX_ENT_TAG_EJECT2 |
212+
| Jet left | 12 | $FX_ENT_TAG_JET_LEFT |
213+
| Jet right | 13 | $FX_ENT_TAG_JET_RIGHT |
214+
| Jet back | 14 | $FX_ENT_TAG_JET_BACK |
215+
| Toe left | 15 | $FX_ENT_TAG_TOE_LEFT |
216+
| Toe right | 16 | $FX_ENT_TAG_TOE_RIGHT |
217+
153218
## Property modifiers
154219

155220
As previously mentioned, various properties can have modifiers applied. The availability of modifiers depends on the property.
@@ -172,11 +237,40 @@ Currently, there are two different modifiers available, the list may be expanded
172237
Interpolation (lerp) modifier has the following properties (all are `integer` type):
173238

174239
* `lerptime` - time in milliseconds it takes for the base value to reach the target value. Used only when `lerpmode` is not set to parameter mode. Default: `1000`.
175-
* `lerpmode` - determines interpolation mode, see table below the list for details. Default: `$FX_MOD_LERP_ACTIVE` (`0`).
176-
* `lerpparam` - changes which parameter is used as the interpolator when `lerpmode` in parameter mode. Default: `0`.
177-
* `lerpsquare` - when enabled, changes interpolation model to squared. Default: `0`.
240+
* `lerpmode` - determines interpolation mode, (*see "Interpolation modes"*). Default: `$FX_MOD_LERP_ACTIVE` (`0`).
241+
* `lerpparam` - changes which internal parameter (see *"Internal parameters"*) is used as the interpolator when `lerpmode` in internal parameter mode. Default: `0`.
242+
* `lerpshape` - sets the interpolation shape (*see "Interpolation shapes"*). Default: `$FX_MOD_LERP_SHAPE_LINEAR` (`0`).
243+
244+
### Interpolation modes
245+
246+
| Mode | Value | CubeScript handle | Description |
247+
|--------------------|-------|---------------------|----------------------------------------------------------------------------------|
248+
| Activation | 0 | $FX_MOD_LERP_ACTIVE | Interpolation begins with the activation of the emitter. |
249+
| Emission | 1 | $FX_MOD_LERP_EMIT | Interpolation begins with the scheduled emission of the effect. |
250+
| Internal parameter | 2 | $FX_MOD_LERP_PARAM | Interpolation by using parameter set by `lerpparam` as the factor. |
251+
| Iteration | 3 | $FX_MOD_LERP_ITER | Interpolation by using the iteration progress as the factor. (*see "Iteration"*) |
252+
253+
254+
### Interpolation shapes
255+
256+
| Shape | Value | CubeScript handle | Formula |
257+
|------------|-------|-------------------------------|--------------------|
258+
| Linear | 0 | $FX_MOD_LERP_SHAPE_LINEAR | y = x |
259+
| Square in | 1 | $FX_MOD_LERP_SHAPE_SQUARE_IN | y = x^2 |
260+
| Square out | 2 | $FX_MOD_LERP_SHAPE_SQUARE_OUT | y = 1 - (1 - x)^2 |
261+
| Smooth | 3 | $FX_MOD_LERP_SHAPE_SMOOTH | y = x^2 * (3 - 2x) |
262+
263+
### Example: Interpolating a particle's size
264+
265+
registerfx FX_EXAMPLES_PARTICLE_SIZE_LERP $FX_TYPE_PARTICLE [
266+
fxpropf partsize 0.5
267+
fxpropf partsize 1.0 $FX_MOD_LERP [
268+
fxpropi lerptime 1000
269+
fxpropi lerpshape $FX_MOD_LERP_SHAPE_SMOOTH
270+
]
271+
]
178272

179-
## Parameters
273+
## Internal parameters
180274

181275
Certain modifiers (such as interpolation) can use parameters, which are supplied from outside to modulate the behavior of an effect.
182276
The availability of parameters depends entirely on the context where an effect is used, therefore, parameters may share IDs if their usage context differs.
@@ -186,6 +280,7 @@ The availability of parameters depends entirely on the context where an effect i
186280
| Weapon power | Weapon FX | 0 | $W_FX_POWER_PARAM | Cooked weapon power, `0-1`. |
187281
| Projectile lifetime | Projectile life FX | 0 | $P_FX_LIFETIME_PARAM | Lifetime of a projectile, `0-1`, `1` being end of life. |
188282
| Projectile bounce velocity | Projectile bounce FX | 0 | $P_FX_BOUNCE_VEL_PARAM | Bounce velocity of a projectile, `0-1`. |
283+
| Impulse boost | Player impulse FX | 0 | <n/a> | Set to `1` on player impulse boost, is otherwise `0`. |
189284

190285
## Chaining effects
191286

@@ -219,26 +314,31 @@ As mentioned, besides parenting one could define an end-of-life emission, which
219314

220315
These properties are available regardless of the effect type.
221316

222-
| Property name | Type | Min | Default | Max | Modifiers | Description |
223-
|----------------|--------------|----------|---------|---------|--------------|---------------------------------------------------------------------|
224-
| activelen | Integer | 1 | 1 | INT_MAX | Random | Instance active time (ms) (see *"Scheduling and timing effects"*) |
225-
| emitlen | Integer | 1 | 1 | INT_MAX | Random, Lerp | Emission time (ms) (see *"Scheduling and timing effects"*) |
226-
| emitinterval | Integer | 1 | 1 | INT_MAX | Random, Lerp | Emission interval (ms) (see *"Scheduling and timing effects"*) |
227-
| emitdelay | Integer | 0 | 0 | INT_MAX | Random, Lerp | Emission delay (ms) (see *"Scheduling and timing effects"*) |
228-
| emitparent | Integer | 0 | 0 | 1 | | Parent scheduling (see *"Scheduling and timing effects"*) |
229-
| emittimeliness | Integer | 0 | 0 | 1 | | Emission timeliness (see *"Scheduling and timing effects"*) |
230-
| emitsingle | Integer | 0 | 0 | 1 | | Single emission (see *"Scheduling and timing effects"*) |
231-
| emitrestart | Integer | 0 | 0 | 1 | | Reset emit state on prolong (see *"Scheduling and timing effects"*) |
232-
| emitmove | Float | 0 | 0 | FLT_MAX | | Emission speed threshold (see *"Scheduling and timing effects"*) |
233-
| fadein | Integer | 0 | 0 | INT_MAX | | Fade in (ms) |
234-
| fadeout | Integer | 0 | 0 | INT_MAX | | Fade out (ms) |
235-
| blend | Float | 0 | 1 | 1 | Random, Lerp | Blend |
236-
| scale | Float | 0 | 1 | 1 | Random, Lerp | Scale |
237-
| colorized | Integer | 0 | 0 | 1 | | If enabled, colour is taken from the supplied state. |
238-
| reloffset | Integer | 0 | 1 | 1 | | If enabled, offsets are calculated in relation to the direction. |
239-
| posoffset | Float vector | -FLT_MAX | 0 | FLT_MAX | Random, Lerp | Origin position offset |
240-
| endoffset | Float vector | -FLT_MAX | 0 | FLT_MAX | Random, Lerp | Tip position offset |
241-
| endfrompos | Float vector | -FLT_MAX | 0 | FLT_MAX | Random, Lerp | Calculate tip position by offset from origin |
242-
| posfromend | Float vector | -FLT_MAX | 0 | FLT_MAX | Random, Lerp | Calculate origin position by offset from tip |
243-
| posflip | Integer | 0 | 0 | 1 | | Flip origin and tip positions |
244-
| endfromprev | Integer | 0 | 0 | 1 | | Treat previous origin position as the tip position |
317+
| Property name | Type | Min | Default | Max | Modifiers | Description |
318+
|----------------|--------------|----------|---------|---------|--------------|-------------------------------------------------------------------------|
319+
| activelen | Integer | 1 | 1 | INT_MAX | Random | Instance active time (ms) (see *"Scheduling and timing effects"*) |
320+
| emitlen | Integer | 1 | 1 | INT_MAX | Random, Lerp | Emission time (ms) (see *"Scheduling and timing effects"*) |
321+
| emitinterval | Integer | 1 | 1 | INT_MAX | Random, Lerp | Emission interval (ms) (see *"Scheduling and timing effects"*) |
322+
| emitdelay | Integer | 0 | 0 | INT_MAX | Random, Lerp | Emission delay (ms) (see *"Scheduling and timing effects"*) |
323+
| emitparent | Integer | 0 | 0 | 1 | | Parent scheduling (see *"Scheduling and timing effects"*) |
324+
| emittimeliness | Integer | 0 | 0 | 1 | | Emission timeliness (see *"Scheduling and timing effects"*) |
325+
| emitsingle | Integer | 0 | 0 | 1 | | Single emission (see *"Scheduling and timing effects"*) |
326+
| emitrestart | Integer | 0 | 0 | 1 | | Reset emit state on prolong (see *"Scheduling and timing effects"*) |
327+
| emitmove | Float | 0 | 0 | FLT_MAX | | Emission speed threshold (see *"Scheduling and timing effects"*) |
328+
| emitparam | Integer | -1 | -1 | 8 | | Emission internal param trigger (see *"Scheduling and timing effects"*) |
329+
| fadein | Integer | 0 | 0 | INT_MAX | | Fade in (ms) |
330+
| fadeout | Integer | 0 | 0 | INT_MAX | | Fade out (ms) |
331+
| blend | Float | 0 | 1 | 1 | Random, Lerp | Blend |
332+
| scale | Float | 0 | 1 | 1 | Random, Lerp | Scale |
333+
| colorized | Integer | 0 | 0 | 1 | | If enabled, colour is taken from the supplied state. |
334+
| reloffset | Integer | 0 | 1 | 1 | | Offset math in relation to direction (see *"Positioning"*) |
335+
| posoffset | Float vector | -FLT_MAX | 0 | FLT_MAX | Random, Lerp | Start position offset (see *"Positioning"*) |
336+
| endoffset | Float vector | -FLT_MAX | 0 | FLT_MAX | Random, Lerp | End position offset (see *"Positioning"*) |
337+
| endfrompos | Float vector | -FLT_MAX | 0 | FLT_MAX | Random, Lerp | End position by offset from start (see *"Positioning"*) |
338+
| posfromend | Float vector | -FLT_MAX | 0 | FLT_MAX | Random, Lerp | Start position by offset from end (see *"Positioning"*) |
339+
| posflip | Integer | 0 | 0 | 1 | | Flip start and end positions (see *"Positioning"*) |
340+
| endfromprev | Integer | 0 | 0 | 1 | | Previous start position as the end position (see *"Positioning"*) |
341+
| posfromenttag | Integer | -1 | -1 | INT_MAX | Random, Lerp | Start position by entity tag (see *"Positioning"*) |
342+
| endfromenttag | Integer | -1 | -1 | INT_MAX | Random, Lerp | End position by entity tag (see *"Positioning"*) |
343+
| posfroment | Integer | -1 | -1 | INT_MAX | Random, Lerp | Start position by entity (see *"Positioning"*) |
344+
| endfroment | Integer | -1 | -1 | INT_MAX | Random, Lerp | End position by entity (see *"Positioning"*) |

0 commit comments

Comments
 (0)