# PHASESwitchNodeDefinition A node that passes invocation to only one of its child nodes. ``` class PHASESwitchNodeDefinition ``` ## Overview A switch node takes a different path in a sound-event hierarchy depending on the value that the app supplies for the node’s switch metaparameter. You define the available paths ahead of time by calling [`addSubtree(_:switchValue:)`](/documentation/PHASE/PHASESwitchNodeDefinition/addSubtree(_:switchValue:)) at least twice and supplying the subtree’s unique string name as the switch value. When your app invokes a sound event at runtime, PHASE checks the value of [`switchMetaParameterDefinition`](/documentation/PHASE/PHASESwitchNodeDefinition/switchMetaParameterDefinition) to determine which path to take.  ### Switch Between Mulitple Node Trees For example, the following diagram represents a node tree that plays one of three grass or sidewalk footstep sounds, depending on the app’s current state. The app sets a value for the switch-node metaparameter according to the terrain on which the player in a game currently stands.  The following code creates a random node subtree for each terrain type and adds each one as a subtree to the switch node. ```swift // Set up the sampler nodes for the "grass" group of sounds. let grassFootstep1 = PHASESamplerNodeDefinition(soundAssetIdentifier:"GrassOne" , mixerDefinition: myMixer) let grassFootstep2 = PHASESamplerNodeDefinition(soundAssetIdentifier:"GrassTwo" , mixerDefinition: myMixer) // Create a random node and assign the grass samplers to it. let grassRandomNode = PHASERandomNodeDefinition(identifier: "grassRandomNode") grassRandomNode.addSubtree(grassFootstep1, weight: 10) grassRandomNode.addSubtree(grassFootstep2, weight: 5) // Set up the sampler nodes for the "cobblestone" group of sounds. let cobblestoneFootstep1 = PHASESamplerNodeDefinition(soundAssetIdentifier: "CobblestoneOne", mixerDefinition: myMixer) let cobblestoneFootstep2 = PHASESamplerNodeDefinition(soundAssetIdentifier: "CobblestoneTwo", mixerDefinition: myMixer) // Create a random node and assign the cobblestone samplers to it. let cobblestoneRandomNode = PHASERandomNodeDefinition(identifier: "cobblestoneRandomNode") cobblestoneRandomNode.addSubtree(cobblestoneFootstep1, weight: 4) cobblestoneRandomNode.addSubtree(cobblestoneFootstep2, weight: 2) // Create a metaparameter definition named "terrain" for the sound event. let terrainSwitchParameter = PHASEStringMetaParameterDefinition(value: "cobblestone", identifier:"terrain") // Create a switch node and provide the metaparameter. let terrainSwitchNode = PHASESwitchNodeDefinition(switchMetaParameterDefinition: terrainSwitchParameter) // Add two random nodes as the metaparameter toggle options. terrainSwitchNode.addSubtree(cobblestoneRandomNode, switchValue: "cobblestone") terrainSwitchNode.addSubtree(grassRandomNode, switchValue: "grass") // Set the terrain metaparameter to play the sound event. var footstepEvent: PHASESoundEvent! do { footstepEvent = try PHASESoundEvent(engine: myEngine, assetIdentifier: "footStepEventAsset") } catch { fatalError("Failed to create sound event.") } // Set the terrain to grass. if let metaparameter = footstepEvent.metaParameters["terrain"] { metaparameter.value = "grass" } // Invoke the sound event and hear noise for the selected terrain. footstepEvent.start() ``` > Tip: > The ``doc://com.apple.phase/documentation/PHASE/PHASESoundEvent/metaParameters`` objects affect only one sound event. To propagate a metaparameter change to multiple sound events, register the metaparameter globally using ``doc://com.apple.phase/documentation/PHASE/PHASEAssetRegistry/registerGlobalMetaParameter(metaParameterDefinition:)``, and change its value through the asset registry’s ``doc://com.apple.phase/documentation/PHASE/PHASEAssetRegistry/globalMetaParameters`` dictionary. ## Topics ### Creating a Node [`- initWithSwitchMetaParameterDefinition:`](/documentation/PHASE/PHASESwitchNodeDefinition/init(switchMetaParameterDefinition:)) Creates a node that invokes a child node based on the value of the given parameter. [`- initWithSwitchMetaParameterDefinition:identifier:`](/documentation/PHASE/PHASESwitchNodeDefinition/init(switchMetaParameterDefinition:identifier:)) Creates a named node that invokes a child node based on the value of the given parameter. ### Managing Child Nodes [`switchMetaParameterDefinition`](/documentation/PHASE/PHASESwitchNodeDefinition/switchMetaParameterDefinition) The meta parameter that holds the name of the child node to invoke. [`- addSubtree:switchValue:`](/documentation/PHASE/PHASESwitchNodeDefinition/addSubtree(_:switchValue:)) Adds a child node with the given switch value. ## Relationships ### Conforms To [`CVarArg`](/documentation/Swift/CVarArg) [`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible) [`Hashable`](/documentation/Swift/Hashable) [`Equatable`](/documentation/Swift/Equatable) [`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible) [`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol) ### Inherits From [`PHASESoundEventNodeDefinition`](/documentation/PHASE/PHASESoundEventNodeDefinition) --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)