Configuring Waterfall Plumes - KSP-RO/RealismOverhaul GitHub Wiki

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:

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 the waterfall-nozzle-glow-<color>-1 templates
• ro-<name>, referencing one of the rowaterfall-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, and scale: Optional; will inherit from the default variant if not set.
• glowRecolor: Optional; takes the same values as glow. Used to replace the glow color of the default variant. It only has an effect if the default variant already has a glow declared.

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-blue
• methalox-purple
• ntr
• 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.

More images here.

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_vernier
• BDB_HTP_vernierVac
• BDB_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-1
• pump-fed-very-light-1
• pump-fed-light-1
• pump-fed-medium-1
• pump-fed-heavy-1
• pump-fed-very-heavy-1
• rcs-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.