🎚️Toggles

A toggle is a component that can be used to get a response on the current state of the part. It can be referenced so that conditional things may happen or not happen.

This is a vast and very useful topic.

• 
• 
• 
• 
• 
• 
• 

Toggles or Related

Work in Progress

This list is currently work-in-progress. Some things may be missing.

Feel free to contribute to make it better!

• PartBuffToggle
• CommandToggle
• CrewDestinationProximityToggle
• PartCrew (for manning parts)
• PartToggleEffectsRules
• FtlDrive (for hyperjumps)
• ComponentPresenceToggle
• DistanceThreshold
• DoorPresenceToggle
• PartDebugToggle (for testing and debugging)
• PartHealthToggle
• PartModeToggle
• PartMultiToggle alias MultiToggle
• PartOnFireToggle (for fires)
• PartStaticToggle alias StaticToggle (for testing and debugging, or forcing a state - great modding tool)
• PartThresholdToggle (not limited to distance)
• PartTimer
• PartToggledComponents alias ToggledComponents (e.g. Boost Thruster's toggled thruster components)
• PartToggleProxy (also see Proxies)
• PartToggleTriggerRules alias ToggleTrigger
• PartTransformMatch alias TransformMatch (for following things)
• PartTriggeredToggle

Perhaps more surprisingly :

• BaseResourceStorage (yes, it has the functionality)
• ResourceConverter
• BeamEmitter
• DirectControlToggle (for Direct Control)
• Weapon (modding)

But also :

• PartUIToggle
• ToggleButton (e.g. Widgets)
• ToggledImageButton (e.g. game speed mods)
• PartToggleGUIRules (e.g. GameGUIRules ; technology unlocks ; B&B techs)

And :

• The UIToggleModePair struct

Additionally :

• IPartComponentToggle : the interface many ^{(all of them?)} implement.

Also, these use toggles :

• PartToggleEffectsRules alias ToggleEffects
• PartGraphicsRules
• WeaponAutoTargetRules

Here, we will particularly look at Multitoggles and ToggleTriggers.

Why use them?

One use case is to find out whether a given part is currently "operational" (meaning working properly). The quite standard "multitoggle" IsOperational component is normally used to that end.

Example 1 - Roof Light

Here is the IsOperational component from the roof_light part :

IsOperational
	{
		Type = MultiToggle
		Toggles = [PowerToggle, CommandToggle]
		Mode = All
	}

This toggle-type component can then be referenced in another component with the following syntax : OperationalToggle = IsOperational

IsOperational will return (means "be" in this context) either "True", or "False". This allows access to that information on-demand.

Because of the Mode = All line, the list of toggles it references (acting as "conditions") must all return True. Other valid values for "Mode" are "Any" and "None".
It is possible to simply list 1 condition even when using Mode = All.

Here is the list of toggle conditions in the example, representing 2 conditions : Toggles = [PowerToggle, CommandToggle]

In other words, for this part to be considered "operational", the part must be turned On, and its "command" must also be. Then the light must shine.

To achieve this, the Graphics component thus references it like so :

Graphics
	{
		Type = Graphics
		Location = [.5, .5]
		OperationalToggle = IsOperational // ← here
		Floor
		{
			//...
		}
		Walls
		{
			//...
		}
		OperationalLighting
		{
			//...
		}
		Roof
		{
			//...
		}
		OperationalRoofDoodad
		{
			//...
		}
	}

Example 2 - Chaingun

Here is a Multitoggle from the Chaingun's main part to demonstrate some original but legal syntax.

ShellIsFullyOpenAndLeftMagNotPullingLeft
		{
			Type = MultiToggle
			Toggles = [IsShellFullyOpen, {Toggle = IsLeftMagazineBeingPulledLeft, Invert = true}]
			Mode = All
		}

Making your own Toggles

You can create whole new toggles just like you would create any other component, by just adding the block of code in the Components section of the part's code.

Warning

Make sure to give it a different name from any other component already present.

Static Toggle

A part sub-component that stores a single unchanging toggle on/off value usable by other components.

This is pretty much the "modder special", I don't think the base game uses it. You make it always true or false as you wish.

For example, just pasting this code in your part allows you to make any toggled thing always On (even better than IsOperational) :

AlwaysOnToggle
{
	Type = StaticToggle
	ToggleOn = true
}

Multitoggle

^{Code location (what's this?): Cosmoteer.Ships.Parts.Logic.PartMultiToggle}

A part sub-component that combines multiple other toggle components into a single toggle component.

MyNewToggle1
	{
		Type = MultiToggle
		Toggles = [MyCondition1, MyCondition2, Mycondition3]
		Mode = Any
	}

MyNewToggle2
	{
		Type = MultiToggle
		Toggles = [MyNewToggle1]
		Mode = All
	}

ToggleTrigger

^{Code location (what's this?): Cosmoteer.Ships.Parts.Logic.PartToggleTrigger}

A part sub-component trigger that is triggered whenever a toggle component changes toggle state.

In other words, these make things happen when something changes.

Example ToggleTrigger

This is a component from thruster_boost.rules.

BoostOffInstantDrainTrigger
	{
		Type = ToggleTrigger
		Toggle = BoostOffInstantDrainToggles // ← the referenced toggle is a multitoggle
		TriggerWhenOn = false
		TriggerWhenOff = true
		OperationalToggle = FullAmmoToggle
		InvertOperationalToggle = true
	}

You may have figured it out, but if you haven't, this will be used as the trigger of the component that removes all power from the thruster. This is what happens in-game if you turn a boosting thruster off, or cancel its boost.
That component is itself toggled On based on the state of the multitoggle BoostOffInstantDrainToggle. However, it's using the optional parameters TriggerWhenOn and TriggerWhenOff to invert its own functionality. This means when it's turned On, it doesn't cause anything to happen, but when it's turned Off, it does.
In combination with the multitoggle, that means the thruster will be drained when any of the conditions in BoostOffInstantDrainToggle are false, causing it to become false because it has Mode = "All". This in turn makes BoostOffInstantDrainTrigger false, which is what makes it fire as we saw above.

Additionally, the InvertOperationalToggle parameter means that it will never do anything if the condition "FullAmmo" is true. In other words it only works when the thruster's battery is not full.
You can test this by activating the boost then deactivating it or turning the thruster Off, all while the game is paused and the battery is full.

Parameters

There are currently 2 available parameters specific to ToggleTrigger.

• Optional :
  • TriggerWhenOn (True / False) : If True, when the toggle is turned On, the trigger fires. This is the normal behavior. Set to False to disable it.
  • TriggerWhenOff (True / False) : If True, when the toggle is turned Off, the trigger fires. This is less common, and is usually asociated with TriggerWhenOn set to False. In combination, these 2 parameters reverse the default functionality as seen in the example above.

Info

ToggleTrigger inherits from OperationalPartComponent, so there are more parameters that can be set, as seen in the example.

Quick examples

For copy-pasting.

Health toggle

To make a part stop working when damaged.

HealthToggle
{
    Type = HealthToggle
    MinHealthFraction = 50%
    MaxHealthFraction = 100%
}

Work in Progress

This subsection is currently work-in-progress: Some things may be missing.

Feel free to contribute to make it better!