Configuring Waterfall Plumes
ROWaterfall is a ModuleManager patchset used by RO to easily and uniformly apply Waterfall and audio effects to engines. It is compatible with RealPlume: If Waterfall Core is installed in addition to RealPlume, engines without Waterfall configurations will continue to use RealPlume, and engines with Waterfall configurations will use Waterfall.
ROWaterfall provides the ROWaterfall node to specify effects, an example of which is below:
@PART[ROE-RD107]:BEFORE[ROWaterfall]:NEEDS[Waterfall]
{
ROWaterfall
{
template = waterfall-kerolox-lower-1
audio = pump-fed-heavy-1
transform = RD-107A-MainFXTransform
position = 0,0,0.48
rotation = 0,0,0
scale = 1.3,1.3,1.3
glow = _yellow
ExtraTemplate
{
template = waterfall-kerolox-vernier-2
transform = RD-107A-VernierFXTransform
position = 0,0,0.29
rotation = 0,0,0
scale = 2.5,2.5,2
}
}
}
ROWaterfall will produce a Module[ModuleWaterfallFX] node and an EFFECTS node from this patch.
Note that, by default, ROWaterfall removes all existing effects (stock, RealPlume, and handwritten Waterfall). However, is is still possible to use ROWaterfall along with other effect providers.
There can only be one ROWaterfall node in each part. If more complex plumes are needed, extra ModuleWaterfallFXes can be added manually.
An ROWaterfall node can contain the following keys and nodes:
Key or node name |
Required | Default value |
Description |
|---|---|---|---|
autoConfig |
No | None | Apply a predefined set of switchable plumes. This key will automatically configure template, audio, MainPlumeTemplate {}, and ModuleEngineConfigs integration. The position, rotation, and scale values should be configured against the "default" variant, which can be viewed GameData/RealismOverhaul/Waterfall_Configs/_Processor/15_auto-config.cfg. Currently, two values are possible: rcs (default variant rowaterfall-rcs-cold-gas-1) and genericThruster (default variant waterfall-hypergolic-white-upper-1). |
template |
Yes | N/A | The desired Waterfall template name. Default Waterfall templates can be found in GameData/Waterfall/Templates, and RO provides supplemental templates under Waterfall_Configs/_Templates. |
controllerSet |
No | Automatically selected based on template
|
Specifies the set of CONTROLLERs to be inserted. ROWaterfall will determine a suitable set based on the main template (see Waterfall_Configs/_Processor/90_controllers.cfg) or fall back to a default set (which is generally adequate). To specify that no controllers be inserted, set the value of this key to custom. |
audio |
No | None | The audio template to use, a selection of which are available in Waterfall_Configs/_Audio. While not strictly required, omitting this key will result in a silent engine. |
moduleID |
No | Part's name
|
Override the moduleID of the generated ModuleWaterfallFX. |
engineID |
No | basicEngine |
Set the engineID used for the throttle controller, if one is present. |
transform |
No | thrustTransform |
Set the value of overrideParentTransform on the main template. If the template is an RCS template, then the thrusterTransformName key of the RCS controller will also be set to this value. |
position |
No | 0,0,0 |
Set the position of the main template. |
rotation |
No | 0,0,0 |
Set the rotation of the main template. |
scale |
No | 1,1,1 |
Set the scale of the main template. |
glow |
No | None | Add a nozzle glow that appears at the same position and has the same size as the base of the main template. See nozzle glow for information on usage. |
glowStretch |
No | 1 |
This key applies a multiplier to the length of the generated glow. It is useful for very short nozzles, where the default length might result in unsightly clipping. |
ExtraTemplate {} |
No | None | This node can be used to add extra templates (ex. for verniers) to the generated ModuleWaterfallFX. The template key is required. The transform, position, rotation, and scale keys are optional and will inherit from the parent configuration if not specified. The template should use the same controllers as the main template. If not, you can add additional controllers manually. Multiple ExtraTemplate nodes may be used. |
MainPlumeVariant {} |
No | None | Define a plume variant that can be automatically selected based on fuel type. This requires B9PartSwitch; thus the node should be declared with :NEEDS[B9PartSwitch]. See fuel-based plume switching for information on usage. Multiple MainPlumeVariant nodes may be present. |
defaultMainPlumeVariantName |
No | Automatically generated from template
|
Override the name of the default plume variant, which will otherwise be a shortened version of the template name. |
useRelativeScaling |
No | false |
Do not use this unless you know what you are doing. It causes plume dimensions to be interpreted as relative to the parent transform, the chief use-case being working around plume sizing errors resulting from non-uniform scaling of the part. |
Adding a glow key will insert a "glow" template into the plume. This serves to provide a smooth transition between the plume and the inside of the engine bell, especially for plumes using dynamic shaders. It is recommended that a glow be added to all engine parts, regardless of whether the engine has an emissive.
The glow key takes values of two forms:
-
_<color>, referencing one of thewaterfall-nozzle-glow-<color>-1templates -
ro-<name>, referencing one of therowaterfall-glow-<name>templates
Setting this key to any other value will result in undefined behavior.
You can reference the Plume Templates section for the appearance of these glows.
By default, the length of the generated glow will be twice the nozzle diameter (which is computed as the average of the x and y scales).
Glows that require more complicated configuration (ex. custom positioning) should be added manually using an ExtraTemplate node.
ROWaterfall supports plume switching based on the engine's RFMEC configuration if B9PartSwitch is installed. Variants/subtypes can be declared using the MainPlumeVariant node (see above), and the template declared in the parent ROWaterfall node is considered the default variant.
In the absence of B9PartSwitch, the default variant will be used for all fuel types.
This node takes the following keys:
-
name: Required; must be unique. -
template: Required. -
position,rotation, andscale: Optional; will inherit from the default variant if not set. -
glowRecolor: Optional; takes the same values asglow. Used to replace the glow color of the default variant. It only has an effect if the default variant already has aglowdeclared.
If B9PartSwitch is installed and there are MainPlumeVariants present, ROWaterfall will produce a ModuleB9PartSwitch with moduleID rowaterfallMainPlumeSwitch. For each MainPlumeVariant, ROWaterfall will generate a SUBTYPE with the same name that switches the TEMPLATEs in the Waterfall module appropriately. It will also produce a default subtype with a name derived from its template (unless overridden using the defaultMainPlumeVariantName key in the parent ROWaterfall node).
Furthermore, ROWaterfall will set up ModuleEngineConfigs's B9PS integration by setting the b9psModuleID key and assigning each CONFIG to use the default variant.
Note that ExtraTemplates are not directly switchable using MainPlumeVariant; this must be done by manually modifying the generated switcher.
Each ModuleEngineConfigs CONFIG not using the default variant must specify the name of the variant to use with the rowaterfallVariant key. (If a config does not set a variant, it will use the default variant as specified above.) The key should be set in the :BEFORE[ROWaterfall] pass.
The below configuration gives the LR-87 engine a kerolox plume variant, activated when the LR87-AJ-3 and LR87-AJ-9-Kero configurations are selected:
@PART[ROE-LR87]:BEFORE[ROWaterfall]:NEEDS[Waterfall]
{
ROWaterfall
{
template = waterfall-hypergolic-aerozine50-lower-1
audio = pump-fed-lr87
position = 0,0,0.69
rotation = 0, 0, 0
scale = 0.85, 0.85, 0.85
glow = _white
ExtraTemplate
{
template = waterfall-hypergolic-vernier-upper-2
transform = newThrustTransform
position = 0,0,0.011
rotation = 0, 0, 0
scale = 0.9, 0.9, 0.8
}
MainPlumeVariant:NEEDS[B9PartSwitch]
{
name = kerolox
template = waterfall-kerolox-lower-4
position = 0,0,0.69
rotation = 0, 0, 0
scale = 2.05, 2.05, 2.05
glowRecolor = _yellow
}
}
@MODULE[ModuleEngineConfigs]:NEEDS[B9PartSwitch]
{
@CONFIG[LR87-AJ-3]
{
%rowaterfallVariant = kerolox
}
@CONFIG[LR87-AJ-9-Kero]
{
%rowaterfallVariant = kerolox
}
// ROWaterfall will set all other configs to use the default aerozine50 plume.
}
}
In addition to the templates provided by Waterfall, ROWaterfall also ships a number of supplemental templates.
(Unrealistic-looking) template modified from waterfall-rcs-jet-1 for cold gas generic thrusters.
IMAGE: TODO
These effects are recolors of the glows shipped with Waterfall.
Currently provided colors:
-
cold-gas: Dim white glow. -
hydrolox-blue: Less brightly cyan blue glow for upper-stage hydrolox engines. -
hydrolox-red-blue: Transitions from red at sea-level to blue in vacuum, for sea-level hydrolox plumes. -
hypergolic-az50: Yellow-orangish, for use specifically with aerozine50-NTO plumes. -
hypergolic-white: White, without a yellow tinge, for use with generic hypergolic/monopropellant plumes. methalox-bluemethalox-purplentr-
pentaborane: Fantastically toxic. -
srm: Bright yellow-white.
From left to right: hydrolox-blue, hydrolox-red-blue at sea level, hydrolox-red-blue in vacuum, hypergolic-az50, hypergolic-white, methalox-blue, methalox-purple, ntr.
Another take on an authentic SSME plume. Images courtesy Aviation366 on Discord.
Orange hypergolic plume with prominent shock diamonds, inspired by SpaceX SuperDraco thrusters.
Courtesy Spaceman Spiff.
Modified from waterfall-hydrazine-monopropellant-upper-1 to be slightly less RCS-like and oriented in the correct direction.
Modified from BDB_nuclear_PBR_vac to be slightly more fanned-out and easier to place.
A pack of recolored RCS plumes for different fuel types.
From left to right: hypergolic-2 (Shuttle-inspired), hypergolic-1, hydrazine-1, cold-gas-1.
A solid kick stage template inspired by vacuum chamber testing images of the Castor 30 motor.
BDB_HTP_vernierBDB_HTP_vernierVacBDB_nuclear_PBR_sustainer_LOXaug
ROWaterfall will generate audio effects using the default node names: running, engage, disengage, and flameout.
The following generic templates are available:
pressure-fed-1pump-fed-very-light-1pump-fed-light-1pump-fed-medium-1pump-fed-heavy-1pump-fed-very-heavy-1rcs-jet-1
The series of pump-fed effects are increasingly crackly, based on sound effects from Rocket Sound Enhancement (shipped as part of Waterfall).
There are also the following specialized effects for use:
-
pump-fed-f1, which is extra crackly and energetic. pump-fed-gamma-
pump-fed-lr87, with the real "whoop" startup sound. -
pump-fed-raptor, with real sound effects from SpaceX test footage. pump-fed-stentor
An engine that uses a non-default running effect name will not have sound. If this is the case, either set the running effect name to running or manually rename the generated running effect node.
RealPlume effects (PLUME, PLUME_TEMPLATE) and handwritten Waterfall configs (ModuleWaterfallFX) can be added in the :AFTER[ROWaterfall] pass if they need to coexist with ROWaterfall. If they are added any earlier, they will be deleted by ROWaterfall in :FOR[ROWaterfall].
Alternatively, to force an existing Waterfall or RealPlume config to be kept, add the rowaterfallKeep key to it (the value does not matter).
Stock (including audio) effects can be added in :AFTER[ROWaterfall] as long as they have a different name than the ones used by ROWaterfall. Otherwise, see modifying effects generated by ROWaterfall.
You can either choose to modify the existing handwritten configs to be the right size, or re-configure the part entirely with ROWaterfall.
Warning: This can be fragile and is generally not recommended; do so at your own risk.
Modifications to effects (ModuleWaterfallFX and EFFECTS) generated by ROWaterfall can be done in :AFTER[zROWaterfall_Post]. (This was historically done in :AFTER[zROWaterfall_99_Finalize]. While this still works, it is not recommended.)
The below example modifies an ExtraTemplate for the kerolox plume variant:
@PART[ROE-LR87]:AFTER[zROWaterfall_Post]:NEEDS[Waterfall,B9PartSwitch]
{
@MODULE[ModuleB9PartSwitch]:HAS[#moduleID[rowaterfallMainPlumeSwitch]]
{
@SUBTYPE[kerolox]
{
@MODULE
{
@DATA
{
@TEMPLATE:HAS[#templateName[waterfall-hypergolic-vernier-upper-2]]
{
@templateName = waterfall-kerolox-vernier-2
@position = 0,0,0
@rotation = 0, 0, 0
@scale = 1.85, 1.85, 1.5
}
}
}
}
}
}
The below example changes the running effect name to rcs:
@PART[ROC-CSTSM]:AFTER[zROWaterfall_Post]:NEEDS[Waterfall]
{
@EFFECTS
{
@running
{
|_ = rcs
}
}
}
By convention, templates provided by ROWaterfall should have names beginning with rowaterfall.
Templates should be numbered starting from 1, with the exception of "specialty" templates. There should only be one canonical version of each "specialty" template (ex. the SSME plume). Art changes should be made to the existing version in a backwards-compatible way (ex. not changing the "base size" of the plume), such that the interpretation stays consistent across all parts using that template.
For easy placement and configuration, new templates should generally have a z-position of 0 and avoid using large values of FadeIn. This is to ensure that there is a clearly defined boundary to be matched to the nozzle and that the position of the base of the plume does not move when the plume is scaled.
All nozzle glows should have the same default position and size (that is, the visual size and position when position, rotation, and scale are all their default values) as the glows shipped with Waterfall. This is required for glow rescaling to work.
The Waterfall wiki contains more information on creating templates.
By default, ROWaterfall manages the insertion of CONTROLLERs into the Waterfall module. Unless directed not to do so (via controllerSet = custom), ROWaterfall will insert either the controllers that it knows to be suitable for a particular main template or the following set of fallbacks:
CONTROLLER
{
name = atmosphereDepth
linkedTo = atmosphere_density
}
CONTROLLER
{
name = throttle
linkedTo = throttle
engineID = #$/ROWaterfall/engineID$
}
CONTROLLER
{
name = random
linkedTo = random
range = 0,1
}
If your template requires a specific controller setup, specify it in _Processor/90_controllers.cfg by adding a new controllerSet default (ex. @ROWaterfall:HAS[#template[your-template]] { &controllerSet = your-set-name }) to the top of the file, and the corresponding CONTROLLER insertion below:
@PART:HAS[@ROWaterfall:HAS[#controllerSet[your-set-name]]]:FOR[zROWaterfall_90_Controllers]:NEEDS[Waterfall]
{
@MODULE[ModuleWaterfallFX]:HAS[#__rowaterfall]
{
// Your controllers
}
}
In general, controllerSets should be named according to the controllers they contain (ex. atmo-thrust-basicRand), unless they are for a specific template.
The blocks in 90_controllers.cfg should be sorted alphabetically.
If the template is expected to be used with engines, you should configure it for glow resizing in _Processor/39_glow-resize.cfg. The algebraic manipulations will vary by plume (you can reference existing computations), but the result should be that the glow has the same diameter as the base of the plume and that its top surface coincides with the base of the plume. In other words, if the plume is made to fit the edge of the nozzle, the glow should fill the inside of the nozzle without clipping.