Components: 🎚️Toggles

From Cosmoteer Wiki
< Modding‎ | Components(Redirected from Components: 🎚️Toggles)
Modding/Components/Toggles
Jump to navigation Jump to search

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.

We will 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.

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


Multitoggle

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

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.
CalloutIconNote.png
Info
ToggleTrigger inherits from OperationalPartComponent, so there are more parameters that can be set, as seen in the example.

((TBA))