Highlighting Entities

The Highlight feature provides visual feedback when entities are hovered, selected, or in other notable states. It includes a default implementation using outlines but can be extended for different visual styles.

Core Components

Highlightable

The base component that controls highlight state:

public struct Highlightable : IComponentData
{
    public bool IsEnabled;      // Whether highlighting should be active
    public float Intensity;     // Used for smooth transitions
}

We provide a built-in system that uses this to highlight interactables that are currently being hovered.

Outlines

The default implementation uses the Outline feature to show highlights:

• Outlines animate smoothly in/out when highlight state changes
• Works with both single meshes and hierarchies
• Customizable thickness and color via outline material

Extending the System

Custom Visual Effects

You can implement alternative highlight visuals by creating systems that react to Highlightable state:

// Example: Color-shift highlighting
public partial struct ColorHighlightSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        foreach (var (highlight, material) in 
            SystemAPI.Query<RefRO<Highlightable>, RefRW<MaterialPropertyColor>>())
        {
            var targetColor = highlight.ValueRO.IsEnabled ? 
                new float4(1, 0.5f, 0, 1) :  // Highlighted color
                new float4(1, 1, 1, 1);      // Normal color
                
            material.ValueRW.Value = math.lerp(
                material.ValueRO.Value,
                targetColor,
                SystemAPI.Time.DeltaTime * 5f);
        }
    }
}

Custom Highlight Triggers

You can also create systems that enable highlights based on custom conditions:

// Example: Distance-based highlighting
public partial struct ProximityHighlightSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        var playerPosition = SystemAPI.GetSingleton<PlayerPosition>();
        
        foreach (var (highlightable, transform) in 
            SystemAPI.Query<RefRW<Highlightable>, RefRO<LocalToWorld>>())
        {
            var distance = math.distance(
                transform.ValueRO.Position, 
                playerPosition.Value);
                
            highlightable.ValueRW.IsEnabled = distance < 2f;
        }
    }
}

Best Practices

• Consider performance when choosing highlight effects for large numbers of entities
• Implement highlight effects on the client side only
• Use the built-in outline system as a reference for implementing new highlight effects

Example: Complete Highlight Setup

// Authoring component
public class CustomHighlightableAuthoring : MonoBehaviour
{
    public Color HighlightColor = Color.yellow;
    public bool EnableOnStart = false;
    
    private class Baker : Baker<CustomHighlightableAuthoring>
    {
        public override void Bake(CustomHighlightableAuthoring authoring)
        {
            var entity = GetEntity(TransformUsageFlags.Dynamic);
            
            AddComponent(entity, new Highlightable
            {
                IsEnabled = authoring.EnableOnStart,
                Intensity = authoring.EnableOnStart ? 1f : 0f
            });
            
            // Add your custom highlight components
            AddComponent(entity, new CustomHighlightEffect
            {
                Color = authoring.HighlightColor
            });
        }
    }
}