iOS Developer Library — Prerelease

Developer

SpriteKit Framework Reference SKFieldNode Class Reference

Options
Deployment Target:

On This Page
Language:

SKFieldNode

A SKFieldNode applies physics effects to physics bodies within a specific part of the scene.

There are many different kinds of field nodes that can be created, each with different effects. The Creating Field Nodes section lists the field types you can create using Sprite Kit, including a type that allows you to apply custom forces to physics bodies. Instantiate the appropriate kind of field node and then add it to the scene’s node tree.

When the scene simulates physics effects, a field node applies its effect to a physics body so long as the following things are true:

  • The field node is in the scene’s node tree.

  • The field node’s enabled property is YEStrue.

  • The physics body is attached to a node that is in the scene’s node tree.

  • The physics body is located inside the field node’s region (see region).

  • The physics body is not located inside the region of another field node whose exclusive property is set to YEStrue.

  • A logical AND operation between the field node’s categoryBitMask property and the physics body’s fieldBitMask property results in a nonzero value.

  • Creates a field node that applies a force that resists the motion of physics bodies.

    Declaration

    Swift

    class func dragField() -> SKFieldNode

    Objective-C

    + (SKFieldNode * _Nonnull)dragField

    Return Value

    A new drag field node.

    Discussion

    The force is applied in the opposite direction of the physics body’s velocity property and has a magnitude proportional to the field’s strength property and the physics body’s speed. (Stoke’s Law)

    Availability

    Available in iOS 8.0 and later.

  • Creates a field node that applies an electrical force proportional to the electrical charge of physics bodies. This field models the first part of the Lorentz equation.

    Declaration

    Swift

    class func electricField() -> SKFieldNode

    Objective-C

    + (SKFieldNode * _Nonnull)electricField

    Return Value

    A new electric field node.

    Discussion

    The force points toward the field node’s position and has a magnitude proportional to the field’s strength property and the physics body’s charge property. The falloff property of an electrical field node is set by default to 2.

    Availability

    Available in iOS 8.0 and later.

  • Creates a field node that accelerates physics bodies in a specific direction.

    Declaration

    Swift

    class func linearGravityFieldWithVector(_ direction: vector_float3) -> SKFieldNode

    Objective-C

    + (SKFieldNode * _Nonnull)linearGravityFieldWithVector:(vector_float3)direction

    Parameters

    direction

    The direction and magnitude of the gravitational force. The values represent the acceleration of the field in meters per second squared. For example, to simulate earth’s gravity, specify (0, -9.8).

    Return Value

    A new linear gravity field node.

    Discussion

    If the field node is rotated, the direction of its gravity field is also rotated. The calculated force is proportional to the physics body’s mass (meaning that the acceleration applied to all affected physics bodies is a constant).

    Availability

    Available in iOS 8.0 and later.

  • Creates a field node that applies a magnetic force based on the velocity and electrical charge of the physics bodies. This field models the second part of the Lorentz equation.

    Declaration

    Swift

    class func magneticField() -> SKFieldNode

    Objective-C

    + (SKFieldNode * _Nonnull)magneticField

    Return Value

    A new magnetic field node.

    Discussion

    The force generated by this field is directed on a line that is determined by calculating the cross-product between the direction of the the physics body’s velocity property and a line traced between the field node and the physics body. The force has a magnitude proportional to the field’s strength property and the physics body’s charge and velocity properties. The falloff property of a magnetic field node is set by default to 2.

    Availability

    Available in iOS 8.0 and later.

  • Creates a field node that applies a randomized acceleration to physics bodies. Use a noise field to simulate effects such as fireflies or snow.

    Declaration

    Swift

    class func noiseFieldWithSmoothness(_ smoothness: CGFloat, animationSpeed speed: CGFloat) -> SKFieldNode

    Objective-C

    + (SKFieldNode * _Nonnull)noiseFieldWithSmoothness:(CGFloat)smoothness animationSpeed:(CGFloat)speed

    Parameters

    smoothness

    The smoothness of the noise used to generate the forces. This parameter should be a value between 0.0 and 1.0, where 1.0 represents a uniform smoothness.

    speed

    The speed at which the noise field should change. A value of 0.0 means that the field should not animate at all.

    Return Value

    A new noise field node.

    Discussion

    The acceleration is proportional to the field strength in a pseudo-random direction. The calculated force is proportional to the physics body’s mass (meaning that the acceleration applied to all affected physics bodies is a constant).

    Availability

    Available in iOS 8.0 and later.

  • Creates a field node that accelerates physics bodies toward the field node.

    Declaration

    Swift

    class func radialGravityField() -> SKFieldNode

    Objective-C

    + (SKFieldNode * _Nonnull)radialGravityField

    Return Value

    A new radial gravity field node.

    Discussion

    The strength of the field measures the acceleration of the field in meters per second squared. A positive number indicates that the body is accelerating toward the field node. The calculated force is proportional to the physics body’s mass (meaning that the acceleration applied to all affected physics bodies is a constant). The falloff property of a radial gravity field node is set by default to 2.

    Availability

    Available in iOS 8.0 and later.

  • Creates a field node that applies a spring-like force that pulls physics bodies toward the field node.

    Declaration

    Swift

    class func springField() -> SKFieldNode

    Objective-C

    + (SKFieldNode * _Nonnull)springField

    Return Value

    A new spring field node.

    Discussion

    The strength of the field measures the strength of the spring. A positive number indicates that the body is accelerating toward the field node. The falloff property of a spring field node is set by default to 1.

    Availability

    Available in iOS 8.0 and later.

  • Creates a field node that applies a randomized acceleration to physics bodies. The acceleration’s magnitude is proportional to a body’s velocity.

    Declaration

    Swift

    class func turbulenceFieldWithSmoothness(_ smoothness: CGFloat, animationSpeed speed: CGFloat) -> SKFieldNode

    Objective-C

    + (SKFieldNode * _Nonnull)turbulenceFieldWithSmoothness:(CGFloat)smoothness animationSpeed:(CGFloat)speed

    Parameters

    smoothness

    The smoothness of the noise used to generate the forces. This parameter should be a value between 0.0 and 1.0, where 1.0 represents a uniform smoothness.

    speed

    The speed at which the noise field should change. A value of 0.0 means that the field should not animate at all.

    Return Value

    A new turbulence field node.

    Availability

    Available in iOS 8.0 and later.

  • Creates a field node that sets the velocity of physics bodies that enter the node’s area. The value is determined by a texture lookup based on the physics body’s location relative to the node.

    Declaration

    Swift

    class func velocityFieldWithTexture(_ velocityTexture: SKTexture) -> SKFieldNode

    Objective-C

    + (SKFieldNode * _Nonnull)velocityFieldWithTexture:(SKTexture * _Nonnull)velocityTexture

    Parameters

    velocityTexture

    A normal texture used to specify the velocities at different points in the field.

    Return Value

    A new velocity field node.

    Discussion

    When a physics body is affected, its new velocity in each frame is calculated by performing a texture lookup (treating the value as a normal vector) and then multiplying that vector by the strength of the field. The field has an implicit size (region) equal to the size of the texture; physics bodies outside this area are unaffected by the field node.

    Availability

    Available in iOS 8.0 and later.

    See Also

    texture

  • Creates a field node that gives physics bodies a constant velocity.

    Declaration

    Swift

    class func velocityFieldWithVector(_ direction: vector_float3) -> SKFieldNode

    Objective-C

    + (SKFieldNode * _Nonnull)velocityFieldWithVector:(vector_float3)velocityVector

    Parameters

    velocityVector

    The velocity that any affected physics bodies will have.

    Return Value

    A new velocity field node.

    Availability

    Available in iOS 8.0 and later.

    See Also

    direction

  • Creates a field node that applies a perpendicular force to physics bodies.

    Declaration

    Swift

    class func vortexField() -> SKFieldNode

    Objective-C

    + (SKFieldNode * _Nonnull)vortexField

    Return Value

    A new vortex field node.

    Discussion

    The strength of the field measures the acceleration of the field in meters per second squared (meaning that similar to gravity, all physics bodies are affected equally). The physics body is accelerated along the perpendicular of the line between the field node’s position and the position of the physics body. A positive field strength indicates the body is accelerated in a counter-clockwise direction. The falloff property of a vortex field node is set by default to 2.

    Availability

    Available in iOS 8.0 and later.

  • Creates a field node that calculates and applies a custom force to the physics body.

    Declaration

    Swift

    class func customFieldWithEvaluationBlock(_ block: SKFieldForceEvaluator) -> SKFieldNode

    Objective-C

    + (SKFieldNode * _Nonnull)customFieldWithEvaluationBlock:(SKFieldForceEvaluator _Nonnull)block

    Parameters

    block

    A custom block to be executed when a physics body is affected by the field. Your block should calculate and return the force to be applied to the body.

    Return Value

    A new custom field node.

    Availability

    Available in iOS 8.0 and later.

  • A Boolean value that indicates whether the field is active.

    Declaration

    Swift

    var enabled: Bool

    Objective-C

    @property(nonatomic, getter=isEnabled) BOOL enabled

    Availability

    Available in iOS 8.0 and later.

  • A Boolean value that indicates whether the field node should override all other field nodes that might otherwise affect physics bodies.

    Declaration

    Swift

    var exclusive: Bool

    Objective-C

    @property(nonatomic, getter=isExclusive) BOOL exclusive

    Discussion

    If the value is set to YEStrue and a physics body is within this field’s region, all other field nodes that might otherwise affect this body are ignored. The default value is NOfalse.

    If you set this property to YEStrue on multiple field nodes within a scene, their regions should not overlap. If they do, the results are undefined.

    Availability

    Available in iOS 8.0 and later.

  • The area (relative to the node’s origin) that the field affects.

    Declaration

    Swift

    var region: SKRegion?

    Objective-C

    @property(nonatomic, retain) SKRegion * _Nullable region

    Discussion

    A field node applies its effect to all physics bodies that are partially or completely inside its region. The default value is a region of infinite size.

    Availability

    Available in iOS 8.0 and later.

  • The minimum value for distance-based effects.

    Declaration

    Swift

    var minimumRadius: Float

    Objective-C

    @property(nonatomic) float minimumRadius

    Discussion

    When the distance between the node and a physics body is calculated, any distance shorter than the value stored in the minimumRadius property is treated as if it is equal to it. The default value is a very small (but nonzero) value.

    Availability

    Available in iOS 8.0 and later.

    See Also

    falloff

  • A mask that defines which categories this field belongs to.

    Declaration

    Swift

    var categoryBitMask: UInt32

    Objective-C

    @property(nonatomic) uint32_t categoryBitMask

    Discussion

    Every field in a scene can be assigned to up to 32 different categories, each corresponding to a bit in the bit mask. The mask values are not predetermined by Sprite Kit. You define the mask values that are used in your game. The field node’s categoryBitMask property is compared to a physics body’s fieldBitMask property using a logical AND operation. If the result is nonzero, the field is applied to the physics body.

    The default value is 0xFFFFFFFF (all bits set).

    Availability

    Available in iOS 8.0 and later.

  • The strength of the field.

    Declaration

    Swift

    var strength: Float

    Objective-C

    @property(nonatomic) float strength

    Discussion

    The default value is 1.0. There’s no specific unit of measurement for this property because the actual effect is dependent on the kind of field node being created. In practice, the best approach is to experiment with different field strengths and use them to determine the proper value empirically.

    Availability

    Available in iOS 8.0 and later.

  • The exponent that defines the rate of decay for the strength of the field as the distance increases between the node and the physics body being affected.

    Declaration

    Swift

    var falloff: Float

    Objective-C

    @property(nonatomic) float falloff

    Discussion

    When the force of a field node is calculated, the force is multiplied by pow(distance - minRadius, -falloff). The default falloff value is 0, which indicates that no attenuation takes place. Some types of field nodes ignore the falloff parameter entirely, while others change the default value to something that is more logical for that type of field node.

    Availability

    Available in iOS 8.0 and later.

These properties are associated with specific types of field nodes.

Data Types

  • A floating point vector type used to perform physics calculations.

    Declaration

    Objective-C

    typedef __attribute__((__ext_vector_type__(3))) float vector_float3;

    Import Statement

    Objective-C

    @import SpriteKit;

    Availability

    Available in iOS 8.0 and later.

  • The definition for a custom block that processes a single physics body’s interaction with the field.

    Declaration

    Swift

    typealias SKFieldForceEvaluator = (vector_float3, vector_float3, Float, Float, NSTimeInterval) -> vector_float3

    Objective-C

    typedef vector_float3 (^SKFieldForceEvaluator)(vector_float3 position, vector_float3 velocity, float mass, float charge, NSTimeInterval time);

    Discussion

    The block parameters are defined as follows:

    position

    The position of the physics body. The coordinates are assumed to be in the following order: x, y, z. In Sprite Kit, the z coordinate is always 0.

    velocity

    The velocity of the physics body. The coordinates are assumed to be in the following order: dx, dy, dz. In Sprite Kit, the dz coordinate is always 0.

    mass

    The mass of the physics body.

    charge

    The charge of the physics body.

    time

    The amount of time that has passed since the last time the simulation was executed.

    Your block should perform any force calculations you are interested in and return the resulting force.

    Import Statement

    Objective-C

    @import SpriteKit;

    Swift

    import SpriteKit

    Availability

    Available in iOS 8.0 and later.