Standard Physics Layers

We provide a standardized set of physics layers using Unity's physics system. These layers facilitate consistent collision detection and physics interactions across different components of the SDK.

Overview

Standard physics layers are defined in the StandardPhysicsLayerType enum and provide a foundation for:

• Interaction detection
• Movement validation
• Teleport targeting
• Collision handling

The layers are managed through the StandardPhysicsLayerUtils class which provides utilities for working with these layers in a type-safe way.

Layer Types

The package defines the following standard physics layers:

Layer Name	Purpose	Default Layer Index
Interactor	For colliders that can interact with other entities	10
Interactable	For colliders that can be interacted with	11
TeleportTarget	For colliders that can be teleported on	12
MovementBlocker	For colliders that block player movement	13
Disabled	For colliders that are momentarily disabled	14

Using Standard Layers

Getting Layer Indices

Use StandardPhysicsLayerUtils.GetLayerIndex() to get the Unity layer index for a standard layer:

int interactorLayer = StandardPhysicsLayerUtils.GetLayerIndex(StandardPhysicsLayerType.Interactor);
gameObject.layer = interactorLayer;

Getting Layer Names

Get the string name of a standard layer using GetLayerName():

string layerName = StandardPhysicsLayerUtils.GetLayerName(StandardPhysicsLayerType.TeleportTarget);

Getting Layer Masks

Create layer masks for physics queries using GetLayerMask():

// Create a mask for a single layer
int singleLayerMask = StandardPhysicsLayerUtils.GetLayerMask(StandardPhysicsLayerType.Interactable);
 
// Combine multiple layer masks
int combinedMask = 
    StandardPhysicsLayerUtils.GetLayerMask(StandardPhysicsLayerType.Interactor) | 
    StandardPhysicsLayerUtils.GetLayerMask(StandardPhysicsLayerType.Interactable);

Getting Layer Information

Get information about all standard layers using GetLayerInfo():

StandardPhysicsLayerInfo[] layerInfo = StandardPhysicsLayerUtils.GetLayerInfo();
foreach(var info in layerInfo) {
    Debug.Log($"Layer {info.Name} has index {info.Index}");
}

Collision Filters

When using DOTS Physics, you can create collision filters that use the standard layers:

var filter = new CollisionFilter {
    BelongsTo = (uint)StandardPhysicsLayerUtils.GetLayerMask(StandardPhysicsLayerType.Interactor),
    CollidesWith = (uint)StandardPhysicsLayerUtils.GetLayerMask(StandardPhysicsLayerType.Interactable)
};

Best Practices

1. Use Constants: Always use the StandardPhysicsLayerType enum rather than hardcoded layer indices.
2. Layer Setup: Ensure Unity's layer configuration matches the SDK's expected layer indices (10-14).
3. Filter Composition: When creating collision filters, consider which layers should interact and compose filters accordingly.
4. Scene Setup: Assign appropriate layers to scene objects during setup rather than at runtime.

Common Patterns

Interaction Detection

// Setting up an interactor collider
public class InteractorSetup : MonoBehaviour 
{
    void Reset()
    {
        gameObject.layer = StandardPhysicsLayerUtils.GetLayerIndex(StandardPhysicsLayerType.Interactor);
    }
}

Teleport Target Setup

// Setting up a teleport target floor
public class TeleportFloorSetup : MonoBehaviour
{
    void Reset() 
    {
        gameObject.layer = StandardPhysicsLayerUtils.GetLayerIndex(StandardPhysicsLayerType.TeleportTarget);
    }
}

Movement Validation

// Creating a DOTS physics filter for movement validation
public static CollisionFilter CreateMovementFilter()
{
    return new CollisionFilter {
        BelongsTo = (uint)StandardPhysicsLayerUtils.GetLayerMask(StandardPhysicsLayerType.Interactor),
        CollidesWith = (uint)StandardPhysicsLayerUtils.GetLayerMask(StandardPhysicsLayerType.MovementBlocker)
    };
}

Additional Considerations

Performance

• Layer checks are fast but should still be used judiciously in performance-critical code
• Consider using broad phase checks before detailed layer-specific tests
• Cache layer masks when performing repeated checks

Extensibility

• New layer types can be added to StandardPhysicsLayerType if needed
• Maintain backwards compatibility when modifying layer definitions
• Document any changes to layer behavior or indices