Fuel Flow Rules (0.24.2)

[Kasuha]

I started this thread as a help for players with their problems with liquid fuel and oxidizer routing around the ship as the mechanic for that is sometimes counterintuitive and confusing. I used many clues and theories posted by various people all around the forums but in the end I figured out most details using my own experiments. Special thanks go to Rhomphaia who helped me figure out fuel flow between parent and child parts (Rule 7) and to Padishar for pointing out inconsistencies with parts that contain fuel and are not fuel crossfeed capable.

Later over the time I figured out other resources may not be always as straightforward as they seem so I added chapters for other resources as well - monopropellant and xenon as well as intake air and electric charge.

All rules are documented using experimental crafts which you can download (with a few exceptions) and use to verify the mechanic yourself.

Liquid Fuel & Oxidizer

Note: as of 0.24.2, neither Vernor Engine (RCS unit powered by liquid fuel and oxidizer) nor O-10 MonoPropellant Engine (engine fueled by monopropellant) draw fuel according to these rules and follow rules for Monopropellant instead. [Experiment] [Experiment]

Each engine does a depth-first recursive scan of the ship for fuel it needs. If it uses two fuel types (liquid fuel/oxidizer), it does two separate scans, one for each fuel type. [Experiment]

The scan starts on the engine body, i.e. the engine part itself.

Result of the scan from each part is list of fuel tanks. The engine then uses the final list to draw fuel from each listed tank evenly (i.e. the same amount from each). [Experiment]

Rules are evaluated in order for each part. If a rule involves scanning other parts, the progress is saved with that part and continues at the same point after scanning of other parts is finished. If the rule's condition is matched, the rule returns a list and evaluation is terminated for the part. Otherwise the evaluation continues with further rule.

Rule 1: Each part can be only visited once, If it is visited for second time in particular search it returns empty list.

Rule 2: Part performs scan on start of every fuel pipe ending in it. This scan is done in order in which pipes were installed ([Experiment]). Then it makes an union of fuel tank sets each pipe scan returned. If the resulting list is not empty, it is returned as result.

Note: as of 0.23.5, this rule does not check fuel crossfeed setting of the part. [Experiment]

Rule 3: Rule removed as result of this [Experiment].

Rule 4: If the part is fuel crossfeed capable ([Experiment]), it performs scan on each of its axially mounted neighbors.

Couplers (bicoupler, tricoupler, ...) are an exception, they only scan one attach point on the single attachment side, skip the points on the side where multiple points are. [Experiment]

Again, the part creates union of scan lists from each of its neighbor and if it is not empty, returns this list.

The order in which mount points of a part are scanned appears to be fixed and defined by the part specification file. [Experiment]

Rule 5: If the part is fuel container for searched type of fuel (i.e. it has capability to contain that type of fuel and the fuel type was not disabled [Experiment]) and it contains fuel, it returns itself.

Rule 6: If the part is fuel container for searched type of fuel (i.e. it has capability to contain that type of fuel and the fuel type was not disabled) but it does not contain the requested fuel, it returns empty list. [Experiment]

Rule 7: If the part is fuel crossfeed capable ([Experiment]), radially attached to another part and it is child of that part in the ship's tree structure, it scans its parent and returns whatever the parent scan returned. [Experiment] [Experiment]

Rule 8: If all preceding rules failed, part returns empty list.

Fuel Flow and Docking

There are three important facts related to fuel scan and ship docking:

Fact 1: When two ships dock together, they become single ship with single root part. That may change parent/child relations between parts and may change how fuel is accessible to engines drawing fuel using Rule 7. [Experiment]

Fact 2: When docking two ships together using multiple docking ports at once, only one docking connection allows fuel transfer. All other docking ports, even though docked and having physical strength in their connection, cannot transfer fuel between each other. [Experiment]

Fact 3: Attached docking ports (from VAB) behave like normal axially connected parts. When docking ports are docked and they provide fuel transfer (see Fact 2), they behave as if there are two fuel pipes between them, one in each direction. This mostly affects parts directly (radially) attached to them or parts connected directly with the docking port via fuel pipe. [Experiment]

Common Errors

If the ship is symmetric, it will draw fuel symmetrically

This is about the most common misconception about fuel distribution. The important thing here is, the fuel scan itself is not symmetric. Out of multiple ways it can traverse the ship structure, it always goes one way first, and another way later. If it meets already scanned parts on the second way, it skips them (Rule 1) instead of searching them again. This means that any fuel drawn from this second way will not come from any parts which were accessible the first way.

[Example]

It Ends Here

Another common error is the idea that if a fuel pipe ends in a fuel tank, it will draw the fuel from that fuel tank. That's also not true because the fuel tank undergoes the same fuel scan rules like every other part and drawing fuel from itself is only Rule 5. If it finds fuel any other way - particularly using Rule 2 or especially Rule 4, it uses that instead of itself. This most commonly occurs when the fuel tank is attached axially to crossfeed capable part which is not a fuel tank.

[Example] [Example]

Monopropellant & Xenon

With 0.23.5 (ARM pack), Monopropellant and Xenon are no longer drawn evenly from all containers around the ship. Instead, they are drawn depending on their placement in the ship, with decouplers separating individual levels of priority.

Note that I ran majority of experiments with Monopropellant as it is significantly easier to set up and deplete.

Drawing Rules

(mostly established by two experiments - Monopropellant [Experiment] and Xenon [Experiment])

• Containers get assigned priority according to number of decouplers or separators between them and ship's root part
  
• Containers with greatest priority (number of decouplers and separators between them and root part) are drawn first
  
• Resource is drawn evenly (equal amount) from all containers which are enabled, contain the resource, and are on the same priority level (supplementary [Experiment])
  
• Drawing from containers with lower priority only starts when all containers with higher priority are completely depleted
  

What is NOT involved

• Launch clamps do not count as decouplers [Experiment] [Experiment]
  
• Docking ports play no role [Experiment]
  
• Struts and fuel pipes play no role [Experiment]
  
• Parts without fuel crossfeed play no role [Experiment]
  
• Placement of engines plays no role [Experiment]
  
• Orientation of decouplers plays no role [Experiment]
  
• Staging setup plays no role [Experiment]
  

Gotchas

Root part change - if a ship docks with another ship, its root part may change. Drawing of monopropellant and xenon then may get affected by it.

The game however seems to restore the original root part of the docked ship when the connection is undocked. [Experiment]

Probes and landers - probes and landers attached through a decoupler get higher priority in drawing monopropellant and xenon over the main body of the ship and may get their supply depleted. As a countermeasure, it is possible to either disable their monopropellant/xenon tanks before undocking them, or have them attached via a docking port which puts them on the same priority level as the main ship.

Intake Air & Electric Charge

Intake Air and Electric charge are usually considered intermittent resources, ships often have their sources (intakes, solar panels, RTGs, engines, ...), storage (intakes, batteries, ...) and consumers (engines, reaction wheels, lights, ...).

When there is sufficient amount of resource available in the storage, all consumers take full amount they need and this consumption is distributed over all storage parts. Similarly when there is sufficient supply of the resource, it is stored in all storage parts all over the ship. Distribution rules in such case are hard to figure out and are not important so I am not dealing with them.

Serious situation occurs when there is some supply of the resource, but not sufficient to satisfy demands of all consumers. This situation leads to uneven thrust or asymmetric flameouts of engines, both jets and ion engines. It may also lead to the situation when ship's probe core is unpowered while its lights are still shining.

Both intake air and electric charge follow the same rules and important parts here are sources and consumers.

For intake air, sources are air intakes and consumers are jet engines.

For electric charge, sources are RTGs, solar panels, and some engines, and consumers are ion engines, probe cores, reaction wheels, lights etc.

What is important is the order in which parts (sources and consumers) were installed on the ship.

Order of storage parts is not important.

For simplicity and since that is the more serious issue in most cases, the following description refers to air intakes and jet engines [Experiment]. Notice though that the situation is the same for electricity as well [Experiment].

• The ship is scanned starting with first placed part and ending with last placed part.
  
• If the part is an air intake, its contents is added to a pool of intake air available.
  
• If the part is an air consuming engine, amount required by the engine is removed from the pool and given to the engine. If there is not enough air in the pool at the moment, the engine gets what is left in the pool.
  
• If there is any intake air left in the pool after scanning all parts, the scan runs again starting from first part of the ship. In this second run, leftover air is distributed over engines which don't have their demands satisfied yet - again in order in which they were attached to the ship.
  

Edited August 24, 2014 by Kasuha

[Kasuha]

Explanation: what is axial mounting

Axial mounting is the usual way of ship construction using attaching parts to other parts via their mounting points, visualised in VAB/SPH as green balls.

Most parts have two axial mount points. Hub parts have six, nose cones and some other parts have one.

Couplers (bicoupler, tricoupler) are special in the sense that even though they have multiple axial mount points, they only scan one of them and that's the point which is on the "single" side.

Below is a simple example of axially mounted ship:

Note that radially mounted girder segments, although they are sticked to the surface by the end with an axial mount point, are not mounted to that part by that axial point and that point remains unused. Radial mounting is always mutual, i.e. surface to surface. The image below is NOT an example of axial mounting.

Edited January 1, 2014 by Kasuha

[Kasuha]

Explanation: what is radial mounting

Radial mounting means attaching parts one to another by their surfaces rather than using pre-defined attach points. Number of parts which can be attached is in such case only limited by the area available on the parent part.

For purposes of fuel flow, it is important which part is parent and which is child in radial mounting. During construction, parent child is always the part onto which the other part is mounted. This may, however, change when ships dock one to each other. Docking may therefore have impact on fuel flow within the ship if it relies on Rule 7.

Below is an example of a Jumbo fuel tank (parent part) with a number of parts radially mounted to it.

[Kasuha]

Experiment: N-couplers scan only their single axial point regardless of parent-child relation

In all images below, the command pod is the root of the ship. Notice that engines only have access to fuel if they are on the two-port end of the coupler, meaning the search for fuel only goes through the single-point side, not through the multi-point side.

Craft file of an "equivalent testing craft"

Access to fuel:

No access to fuel:

24-Aug-2014: verified for 0.24.2

Edited August 24, 2014 by Kasuha

[Kasuha]

Experiment: Fuel pipe scan precedes test for crossfeed capability

First image demonstrates that used parts are indeed not crossfeed capable. Second image shows that when a fuel pipe is drawn to them, though, they're able to provide fuel to attached fuel pipes or other parts.

This behavior may be considered a bug and may be fixed in the future. As of 0.23 release it works.

Craft file of equivalent/improved testing craft

24-Aug-2014: verified for 0.24.2

Edited August 24, 2014 by Kasuha

[Kasuha]

Experiment: fuel pipes go first, axial mounting second, radial mounting third

The single part providing all the fuel access in this case is the structural fuselage part. It allows radial scan because it is not fuel tank itself and it is child of the fuel tank to which it is radially mounted (the crew pod is the root of the ship). It provides access to fuel according to Rule 2 first, then according to Rule 5 and in the end according to Rule 7. Notice order in which fuel tanks are emptied.

Craft file of an equivalent test craft

24-Aug-2014: craft file updated; verified for 0.24.2

Edited August 24, 2014 by Kasuha

[Kasuha]

Experiment: Axial mount scan does not depend on parent/child relation

Experiment: Fuel tanks from the final list are drawn evenly regardless of fuel tank size

In the following ship, the command pod is the root part. All fuel is drawn through axial mounting (Rule 5). Notice the engine has drawn 5 units of fuel from each tank.

Craft file of an equivalent/improved testing craft

24-Aug-2014: verified for 0.24.2

Edited August 24, 2014 by Kasuha

[Kasuha]

Experiment: disabling fuel type on tank allows radial scan

Command pod is the root part. FL-T800 tank is full of fuel, small FL-T100 was tweaked to not contain any liquid fuel. When liquid fuel is disabled in it, the engine gains access to liquid fuel in FL-T800.

Craft file of an equivalent/improved test craft

24-Aug-2014: verified for 0.24.2

Edited August 24, 2014 by Kasuha

[Kasuha]

Experiment: fuel lines are scanned in order of placement

The following two pictures show the same design, the only difference is the order in which the two upper fuel lines were placed.

In the first picture, the right fuel line was placed first.

The fuel scan then goes first to the right tank and ends there (the structural part is not crossfeed capable) so the tank provides itself for fuel.

Then fuel scan goes to the left tank and ends there (structural part is not crossfeed capable and right tank behind the pipe was already scanned).

Therefore both fuel tanks are drawn evenly.

In the second picture, the left fuel line was placed first.

The scan goes through the pipe to the left fuel tank, then through the horizontal pipe to the right fuel tank. It ends there, the tank provides itself for fuel.

Then the scan tries to go through the right pipe, but since the right fuel tank was already scanned it provides nothing.

Therefore fuel is drawn from right tank only.

Craft file of an equivalent/improved test craft

24-Aug-2014: verified for 0.24.2

Edited August 24, 2014 by Kasuha

[Kasuha]

Experiment: fuel scan is done for each fuel type separately

In the following ship, command pod is the root part.

The engine draws liquid fuel from the liquid fuel tank, and oxidizer from the FL-T800 tank. When the liquid fuel in the liquid fuel tank is depleted, the engine stops because it cannot reach liquid fuel in FL-T800 (Rule 6) although it can reach oxidizer in it (Rule 7)

Craft file of an equivalent test craft

24-Aug-2014: verified for 0.24.2

Edited August 24, 2014 by Kasuha

[Kasuha]

Experiment: In multi-docking-port connections, only one connection can transfer fuel

Before docking, neither engine has access to fuel.

After docking, only one engine (that one next to the "main" docking connection) has access to fuel behind the docking port even though both docking ports are docked and provide the "undock" function.

Craft file of an equivalent test craft (does not require flying to space)

24-Aug-2014: verified for 0.24.2

Edited August 24, 2014 by Kasuha

[Kasuha]

Experiment: Parent/child relation and fuel scan conditions depending on Rule 7 may change on docking.

In the example ship, the command pod is initially the root. Both engines have access to fuel because the girder connecting the engine to the fuel tank is the child in both cases. Even after separating the two parts, both engines keep their access to fuel. After docking, though, one of girders becomes a parent to the fuel tank and the corresponding engine loses access to fuel.

[1greywind]

Excellent analysis. And impressive experimental work too.

[Captain Sierra]

I'll make the first vote that this thread needs to be stickied. Excellent work.

[Specialist290]

Impressive work. Definitely one for the Drawing Board

[Sirine]

Experiment: Parent/child relation and fuel scan conditions depending on Rule 7 may change on docking.

In the example ship, the command pod is initially the root. Both engines have access to fuel because the girder connecting the engine to the fuel tank is the child in both cases. Even after separating the two parts, both engines keep their access to fuel. After docking, though, one of girders becomes a parent to the fuel tank and the corresponding engine loses access to fuel.

http://i.imgur.com/Nn23h4j.png

http://i.imgur.com/uR5jeJF.png

http://i.imgur.com/jEwwfnY.png

http://i.imgur.com/rX4Gi3u.png

Now. This explain THIS...http://forum.kerbalspaceprogram.com/threads/60126-LV-N-Engines-no-fuel-after-attachment-on-top

Dev please fix this...its not making sense with docking issues.

@Kasuha Excellent thread.

Please check on this, and specify in which rules that you describe?

http://forum.kerbalspaceprogram.com/threads/60764-No-fuel-for-Engines

Edited January 2, 2014 by Specialist290
Merging sequential posts.

[Kasuha]

Now. This explain THIS...http://forum.kerbalspaceprogram.com/threads/60126-LV-N-Engines-no-fuel-after-attachment-on-top

Actually I don't see how it explains your problems unless the girder became root part of the ship for some reason but I don't see any reason why that should happen.

I remember I was trying to understand what happens with your ship but it's built with so much clipping that it's hard to get a clear picture about what is attached to what. I still don't know what caused that problem.

Please check on this, and specify in which rules that you describe?

http://forum.kerbalspaceprogram.com/threads/60764-No-fuel-for-Engines

All your experiments in that thread follow known rules IMO. They're mainly about Rule 7 and you just need to pay attention to what is parent and what is child in the hierarchy.

[DMagic]

Nice explanation.

It's interesting that the order of fuel pipe placement can have that effect, I didn't expect that.

You should also note that while bi-, tri-, and quad-couplers don't normally allow fuel flow from the multiple connection side to the single connection side, this can be changed in the part .cfg file. There is a line in there specifically addressing this that can be removed ("NoCrossFeedNodeKey = bottom").

Your results may vary as I assume this line was included for a reason, but in my experience fuel usually flows without issue from multiple tanks when this line is removed. I assume you could also add that line to other parts, or change it the top node, if you want to alter fuel flow, of course you might also break things by doing that.

[Kasuha]

You should also note that while bi-, tri-, and quad-couplers don't normally allow fuel flow from the multiple connection side to the single connection side, this can be changed in the part .cfg file. There is a line in there specifically addressing this that can be removed ("NoCrossFeedNodeKey = bottom").

Your results may vary as I assume this line was included for a reason, but in my experience fuel usually flows without issue from multiple tanks when this line is removed. I assume you could also add that line to other parts, or change it the top node, if you want to alter fuel flow, of course you might also break things by doing that.

The guide is about stock parts, not about modded.

The reason for it was, I believe, to prevent engines on the end of one stack on the multiside to draw fuel from other stacks. It probably wouldn't cause any problems but it looks very strange if you have four stacks side by side and the engine on the end of one of them draws fuel from the three other stacks first and from its own stack last.

[Kasuha]

Experiment: Docking port fuel transfer

This experiment consists of three parts. First part investigates fuel transfer in docking ports which are not docked, but attached in VAB. Second part investigates fuel transfer in docked docking ports. Third part investigates fuel transfer in docking ports with fuel crossfeed disabled. In all three cases each docking port has one fuel tank axially connected, one fuel tank connected via fuel pipe and one engine connected via fuel pipe.

Part 1: Fuel flow through docking ports attached in VAB.

Docking ports behave normally, i.e. their behavior corresponds to axial connection between them. As the engine draws fuel directly from the docking port, it first draws fuel from the tank attached to it via fuel pipe (Rule 2), then draws fuel through its axial connections (Rule 4), i.e. from the attached fuel tank and from the other docking port, which also first provides fuel from the tank behind fuel pipe and second provides fuel from its axially connected tank.

Situation is symmetrical for both engines, meaning both docking ports behave identically.

Javascript is disabled. View full album

Part 2: Fuel flow through docked docking ports with fuel crossfeed enabled

In this case situation changes and can be best explained by two imaginary fuel pipes connecting the two docking ports.

When an engine starts drawing fuel, it draws the fuel first from both fuel tanks connected to both docking ports via fuel pipe. This can be explained by both docking ports drawing fuel using Rule 2. When fuel from these fuel tanks is depleted, the engine starts drawing fuel from the tank axially attached to the other docking port. This can be explained by the engine's docking port drawing fuel still using Rule 2, but the other docking port already resorting to Rule 4. The tank axially mounted to the engine's docking port is drawn last.

Situation is symmetrical for both engines, meaning again both docking ports behave identically and the "imaginary fuel pipe" between them is in both ways.

The behavior also suggests the two docking ports still behave like two separate parts as for certain time each of them draws fuel using different rule.

Javascript is disabled. View full album

Part 3: Fuel flow through docked docking ports with fuel crossfeed disabled

When fuel crossfeed is disabled, docking ports no longer draw fuel from their axially mounted tanks, but either engine still draws fuel from both tanks connected via fuel pipe to docking ports. Even though the "disable crossfeed" action is only available on one docking port, both block their access to axially connected tanks so they both turn fuel crossfeed incapable. They can however still transfer fuel between each other using Rule 2.

Javascript is disabled. View full album

Edited January 2, 2014 by Kasuha

[BraciaB]

Great work Kasuha, great great work. I wish that devs will fix those issues with fual logic after the docking. I think that this thread, especially your experiments will help in that. I don't quite understand rule number 2. Could You explain that to me once again in simplier words? Thanks in advance.

[Kasuha]

I don't quite understand rule number 2. Could You explain that to me once again in simplier words? Thanks in advance.

Rule 2 applies when there are fuel pipes ending in the part, i.e. when they are set up to "pump fuel" into the part. The part looks up each part that is on the other (draining) end of the pipe and tries to get access to fuel from there. In the end the part makes a list of fuel tanks which are ready to provide fuel through either of those pipes and if it contains at least one fuel tank, it sends this list as a result. If no fuel is accessible this way, the part proceeds to using further rules.

[BraciaB]

Ok, thanks for your answer. If arrows on fuel pipes on both pictures are pointing in the same direction, then why it's important which line was put first? In some cases this irregular draining of fuel may cause unstability and even one sweet kaboom or neverending rolling.

[Kasuha]

What's important about it is that in the experiment (and in many real ship designs), the fuel is drawn from fuel tanks differently based on order in which pipes were installed. That's how it works. It's of course better to avoid having to deal with such nuances but if I'm trying to provide comprehensive info I need to cover that, too.

[BraciaB]

Of course, It's very important to understand those rules. Sometimes people make mistakes designing their ship because they aren't aware of that, and thanks to this tutorial they'll understand what, where and why went wrong. Once again thanks for your help and work on that topic. Thanks to that next time I'll encounter a fuel flow problem I'll know how to solve it.