Adding a Plume to an Engine - KSP-RO/RealPlume GitHub Wiki

Generic Configs

There are two benefits to using the generic configs. First, it's a lot less work to add a plume to an engine, only having to specify a few parameters to adjust the plume to fit the engine. Second, if we discover an inaccuracy in one of the plumes, the fix can be applied to every plume in the set by changing one config, rather than combing every engine config for the fix.

Step 1 - Select your engine

If you don't know what the engine is titled in its part file, add a .cfg file in your GameData directory with the following text in it:

@PART[*]:FINAL
{
    title = #$name$
}

This will replace the in-game title of the engine with the title used in the part file. Conveniently, it also sorts the parts in-game in alphabetical order.

Step 2 - Select a Prefabbed Plume

In general, you should select a plume based on the fuel your engine uses, and the atmospheric condition in which the engine is to be used. For our example, we're going to configure the LR-79 (Which uses the stock MainSail part as a basis). It's a first-stage engine, and the particular config we'll be working with uses Kerosene and Liquid Oxygen, so we'll be using the Kerolox-Lower prefab config.

Some guidelines to selecting a good plume to use, if you're not using RealFuels:

  • Kerolox - High Thrust, low efficiency
  • Cryogenic - Cryogenic fueled based engines
  • Hydrolox - Low Thrust, High efficiency
  • Hypergolic - High Thrust, low efficiency, long storage time
  • NTR - Nuclear Thermal Rocket (like the NERVA)
  • Lower - First stage engines, optimized for 1 atmosphere
  • Upper - Upper stage engines, optimized for upper atmosphere and vacuum
  • OMS - Lander and maneuvering engines, optimized for vacuum
  • Vernier - Small attitude engines for launch vehicles
  • Hall - Ring-shaped ion thruster
  • Gridded - Filled in circle-shaped ion thruster

Have a look at this page for the currently available prefab plumes.

Step 3 - Add the Plume to the Part

This part is pretty easy. Add a config to the GameData/RealismOverhaul/SmokeScreen_EffectCfgs/ directory (preferrably in a sub-directory named after the mod you're working with). Here's what we're adding for the LR-79 - contained in liquidengine1-2.cfg (re-target for your part name instead of liquidEngine1-2, and mention what the engine actually is, as shown):

Do note that all fields with letters (not numbers) are case sensitive, this includes the name, and transformName at present.

The localPosition and flarePosition, plumePosition, smokePosition fields are interchangable but not compatible. Generally, it is better to use the separate flare, plume and smoke positions, as it is much easier to adjust the overall plume appearance without requiring additional Module Manager passes that add to the overall patching overhead (more of that later). Please note that new parameters like lampPosition, blazePosition exist in the new plumes added in v12.0.0 It is recommended to check this page for a sample config before using them: Previews and sample configs

Sample RealPlume config:

@PART[liquidEngine1-2]:FOR[RealPlume]:NEEDS[SmokeScreen]
{
    PLUME
    {
        name = Kerolox-Lower                // Pre-fabbed plume you want.
        transformName = thrustTransform     // The engine thrust transform to attach the plume.
        localRotation = 0.0, 0.0, 0.0       // Optional - Any rotation needed (global).
        localPosition = 0.0, 0.0, 1.0       // Position of the engine plume (global).
        flarePosition = 0.0, 0.0, 1.0       // Optional - Position of the engine flare (if localPosition is not used).
        flareScale = 1.0                    // Optional - Scale of the engine flare (if localPosition is not used).
        plumePosition = 0.0, 0.0, 2.0       // Optional - Position of the engine plume (if localPosition is not used).
        plumeScale = 1.0                    // Optional - Scale of the engine plume (if localPosition is not used).
        smokePosition = 0.0, 0.0, 1.5       // Optional - Position of the engine smoke (if localPosition is not used).
        fixedScale = 1.0                    // Size adjustment to resize to engine (global).
        energy = 1.0                        // Adjust length of plume (global).
        speed = 1.0                         // Adjust speed to fit resize, generally close to 1:1 with scale (global).
        emissionMult = 0.5                  // Optional - Density of the plume particles (global).
    }

    @MODULE[ModuleEngines*]
    {
        %powerEffectName = Kerolox-Lower
        !runningEffectName = DELETE
    }
}

For engines that have multiple engine configurations available (like with the Realism Overhaul engines), some additional patching work is required:

    @MODULE[ModuleEngineConfigs]
    {
        //Add the effect to every engine config.

        @CONFIG,*
        {
            %powerEffectName = Kerolox-Lower
        }
    }

Alternately, you can add multiple PLUME blocks if the different ModuleEngineConfigs CONFIGs use different fuels, or are designed for different stages / atmospheric conditions. To do this, call out the different plumes like so:

    @MODULE[ModuleEngineConfigs]
    {
        // Add the Kerolox-Lower effect to this specific engine configuration.

        @CONFIG[F-1A]
        {
            %powerEffectName = Kerolox-Lower
        }

        // Add the Hydrolox-Lower effect to this specific engine configuration.

        @CONFIG[RS-25D]
        {
            %powerEffectName = Hydrolox-Lower
        }
    }

Finally, double check in the original part file for the transformName. Nearly always called out as thrustVectorTransformName = thrustTransform, but there are exceptions often enough to warrant the double-check. The thrustVectorTransformName always resides in the ModuleEngines, ModuleEnginesFX, or ModuleEnginesRF node, and it references the title given to the thrust vector in the part's game model.

A nice easy way to find out exactly what it's called is to open ModuleManager's ModuleManager.ConfigCache in a text editor and search for your part's name in that file.

Step 4 - Tweak the plume to match the Part

Once you have your part set up with a config, it's time to go in-game and see our handiwork (and size the plume to match the part). Your setup in-game should look something like this (I normally do the plume configs at night, since they're easiest to see against the black sky, but screenshots look a little better during the day):

Plume Tweaking Setup

The SmokeScreen window is brought up either from Blizzy's toolbar or via the Mod + P keyboard shortcut. There are generally a few different effects in play, all use the same size scale:

Plume|Flare Alignment image

  • plume - The actual plume. Check this one second, it should line up nicely with the flare effect. Not all engines have flares, in which case check this first.
  • flare - A small spout in the nozzle to represent the high-pressure gas present there. I recommend positioning and sizing this effect, then copying the size / position to the plume config. The prefabs are designed to line up most of the time. Definitely try to size and position it so that the flare is mostly inside the nozzle.
  • slag - An SRB effect, to represent still-burning bits of solid rocket particulate that are expelled with the flames.
  • smoke - The smoke effect for the plume. Not all engines produce visible smoke.

If your effects don't show up here, see the Troubleshooting section at the end.

As suggested, we're sizing the flare effect. Click Open Config Editor to open the text window where we can tweak the config in-game, Click Import to import the pre-fabbed config. You'll notice that all the parameters we set above are listed at the top of the config. You'll also notice the huge list of parameters that have already been fine-tuned in the pre-fab config. Aren't you glad you don't have to tweak those? There are several parameters we can set to adjust the plume to the engine:

  • localRotation = x,y,z - Optional. More often than not, you don't need to touch this parameter. This rotates the effect. Set x,y,z as a unit vector in the direction you want the plume to point.
  • localPosition = x,y,z - Where to place the starting point of the plume. Adjust this first. You most likely want to adjust the z parameter, Positive is in the direction of thrust.
  • fixedScale = F - How big the effect should be, it's multiplicative. 1 is no change.
  • energy = E - How long the plume particles should last, also multiplicative. 1 is no change.
  • speed = S - How fast the particles should move, also multiplicative. 1 is no change.

Everything past this should be ignored, unless you want to copy the config and make your own. Let's see what we're dealing with for this config. Set Atmo Density to 1, and Power (Throttle) to 1 (you may have to turn on manual inputs here).

Plume-Tweaks-initial

Right off the bat, it looks like the scale is slightly too big, and we're a bit too low. Setting:

localPosition = 0.0, 0.0, 1.85
fixedScale = 0.75

Lines it up a bit better:

Plume-Tweaks-Better

If you want, you can drag the Atmo Density slider to make sure it stays lined up as the plume expands in lower density atmospheres. All plumes should be designed so that if it's lined up at sea level, it'll stay aligned at other pressures as well.

If you get something like this at lower AtmoDensity:

Plume-Tweaks-Too-Slow

It means your plume is moving too slowly for the expansion, you should adjust your speed parameter slightly larger. Alternately, if your plume is too stretched, like this:

Plume-Tweaks-Too-Fast

Then it might be a good idea to reduce the speed parameter. Finally, if your plume is a little short, or a little long, adjust the energy parameter to match.

Step 5 - Saving Your Tweaks

The final step is to save your adjustments into the config file. Go back to the config we created earlier, and add the new values in.

liquidengine1-2.cfg:

@PART[liquidEngine1-2]:FOR[RealPlume]:NEEDS[SmokeScreen]
{
    PLUME
    {
        name = Kerolox-Lower
        transformName = thrustTransform
        localRotation = 0.0, 0.0, 0.0
        localPosition = 0.0, 0.0, 1.85
        fixedScale = 1.0
        energy = 1.0
        speed = 1.0
    }

    @MODULE[ModuleEngines*]
    {
        %powerEffectName = Kerolox-Lower
        !runningEffectName = DELETE
    }

    @MODULE[ModuleEngineConfigs]
    {
        @CONFIG,*
        {
            %powerEffectName = Kerolox-Lower
        }
    }
}

And save your config! That's it, you're done! In this case you don't need to tweak any of the other effects, since the same scaling is applied to them. If you decide to use the dedicated plume fields for the flare, plume and smoke effects then you will have to tweak each one of them separately.

Happy Plume Configuring!

Full Configs

The SmokeScreen thread is a great starting point. It's likely I'll just provide screenshots to Sarbian and direct you there forever.

Troubleshooting

In creating these configs, I've run into a few issues with easy solutions.

I edited the config file, and use the ALT+F11 ModuleManager Reload, now no particles show up!

Don't know why this happens, but it does sometimes. I suspect the particles got unloaded out of RAM somehow. Relaunch the game, and it'll be resolved.

My effects aren't showing up at all!

Most often, this is due to a misnamed transformName. Check the part config in the ModuleManager.ConfigCache to make sure you have the correct one. Also can be due to not adding the %powerEffectName to your current engine config, make sure you added that correctly:

    @MODULE[ModuleEngines*]
    {
        %powerEffectName = Kerolox-Lower
    }

    @MODULE[ModuleEngineConfigs]
    {
        @CONFIG[RD-180]
        {
            %powerEffectName = Kerolox-Lower
        }
    }

If all that fails, it could be because of a typo in the generic pre-fabbed effect itself. This is relatively unlikely, since it'd affect a great many other parts. Check in on the RealismOverhaul IRC channel and see if this is the case so we can fix it.

The plume and flare effects still don't line up quite right.

Sometimes, for oddly shaped nozzles or for some size scales, you still don't get the plume to look exactly how you want. In the case that flare/plumePosition and flare/plumeScale are not enough, you can tweak parameters after the fact like so:

@PART[PartName]:FOR[zzRealPlume]
{
    @EFFECTS
    {
        @EffectName
        {
            @MODEL_MULTI_SHURIKEN_PERSIST[flare]
            {
                @fixedScale = 200
                %offset = 199
            }
        }
    }
}

Replace the PartName with your part config name and the EffectName with the name of the effect that the engine uses (Kerolox-Lower, Hydrolox-Upper etc).

The engine doesn't sound right!

Each prefab plume config has its own set of sounds, and RealPlume is smart enough to only apply one set of sounds to a part (since that can't be swapped out by ModuleEngineConfigs). RealPlume will apply the first sound set in alphabetical order (IE, if you have one Hydrolox config, and one Kerolox config, the Hydrolox sounds will be applied, and the Kerolox sounds ignored). If you supply your own sounds in an EFFECTS node, RealPlume will use your sounds instead and ignore its own.

Note that this only applies for engage, disengage, and flameout. The running sound is part of the particular plume config, and will need to be overwritten in an :FOR[zzRealPlume] ModuleManager node if you want to change the prefab sound.

The Plume doesn't look right, RABBLE RABBLE RABBLE!

That's exactly why we created this generic plume process, if there are tweaks to a generic plume's appearance that you think should be made, make 'em, and submit it as a pull request. We'll be happy to have it!

Description of ModuleManager Passes for RealPlume

  • :BEFORE[RealPlume] - Not all that special. Anything that needs to do things before PLUME nodes.
  • :FOR[RealPlume] - Apply your PLUME nodes here.
  • :AFTER[RealPlume] - EFFECTS Remover pass goes here, this should remove all previously existing EFFECTS nodes on parts with new PLUME nodes.
  • :BEFORE[zRealPlume] - Nothing special here.
  • :FOR[zRealPlume] - Catchall plume configs go here in Realism Overhaul, anything without an EFFECTS node here gets a nice generic plume.
  • :AFTER[zRealPlume] - PLUME nodes are expanded via ModuleManager here, this is where the actual EFFECTS configs are added.
  • :BEFORE[zzRealPlume] - Nothing special here.
  • :FOR[zzRealPlume] - Adjust the EFFECTS nodes and engine sounds here.
  • :AFTER[zzRealPlume] - Nothing special here.