Code Customization

This guide covers the recommended approaches for customizing Compass Navigator Pro behavior through code, ordered from simplest to most advanced.

1. Events

The simplest way to react to compass activity. Subscribe to UnityEvents on the CompassPro instance to run your code when something happens, without modifying any source files.

UI Creation Events

These events fire when the compass creates UI elements for a POI. Use them to customize icons or indicators right after they are instantiated:

Example: Add a pulsing effect to boss icons

void Start() {
    CompassPro compass = CompassPro.instance;
    compass.OnCompassBarIconCreated.AddListener(CustomizeIcon);
    compass.OnMiniMapIconCreated.AddListener(CustomizeIcon);
}

void CustomizeIcon(CompassProPOI poi, GameObject iconGO) {
    if (poi.CompareTag("Boss")) {
        iconGO.AddComponent<PulseAnimation>();
    }
}

See the Scripting Support page for the complete list of events.

2. Partial Classes

CompassPro is declared as a partial class, which means you can extend it by adding your own partial class file. This lets you add new methods, properties, or fields to the compass without modifying any existing source files.

How it works

1. Create a new C# file anywhere in your project (outside the CompassNavigatorPro folder so updates don't overwrite it).
2. Declare a partial class with the same namespace and class name.
3. Add your custom methods or properties.

Example: Add a helper method

// File: MyCompassExtensions.cs (in your own scripts folder)
using UnityEngine;

namespace CompassNavigatorPro {

    public partial class CompassPro {

        public void HighlightNearestPOI(float radius, Color color) {
            foreach (var poi in activePOIs) {
                var state = poi.GetState(compassGroup);
                if (state.distanceToFollow < radius) {
                    poi.tintColor = color;
                }
            }
        }
    }
}

When to use partial classes: When you need to add new functionality that reads compass state or manages your own data alongside the compass. This approach cannot override existing behavior - for that, use virtual methods.

3. Virtual Methods & Subclassing

For full control over compass behavior, create a subclass of CompassPro. Key methods are marked protected virtual, allowing you to override them. Your subclass survives asset updates since it lives in your own scripts folder.

Setup

1. Create a new script that inherits from CompassPro.
2. Replace the CompassPro component on your compass GameObject with your subclass.
3. The inspector works automatically with subclasses.

Factory Methods

Override these to control how UI elements are created:

Update Methods

Override these to change how the compass updates each frame:

Computation Methods

Override these to change how positions and compass points are calculated:

Visibility & Effects

Example: Full custom subclass

// File: MyCompass.cs (in your own scripts folder)
using UnityEngine;
using CompassNavigatorPro;

public class MyCompass : CompassPro {

    public GameObject bossIconPrefab;

    // Use different prefabs based on POI type
    protected override GameObject CreateCompassBarIcon(CompassProPOI poi) {
        if (poi.CompareTag("Boss") && bossIconPrefab != null) {
            return Instantiate(bossIconPrefab, transform);
        }
        return base.CreateCompassBarIcon(poi);
    }

    // Add fade animation on visibility change
    protected override bool ToggleCompassBarIconVisibility(
            CompassProPOI poi, CompassProPOIState state, bool visible) {
        bool changed = base.ToggleCompassBarIconVisibility(poi, state, visible);
        if (changed && state.compassIconRT != null) {
            var cg = state.compassIconRT.GetComponent<CanvasGroup>();
            if (cg != null) {
                StartCoroutine(FadeCanvasGroup(cg, visible ? 1f : 0f, 0.3f));
            }
        }
        return changed;
    }
}

Choosing the Right Approach

Need	Approach
React to compass activity (POI visited, icon created)	Events - subscribe and respond
Add new methods or properties to CompassPro	Partial class - extend without modifying
Change how icons/indicators look or are created	Events (simple) or Factory method overrides (advanced)
Change core behavior (positioning, visibility, layout)	Subclass with virtual method overrides
Replace the entire update loop for a system	Subclass overriding Update methods

All three approaches keep your customizations in separate files that are not affected by asset updates.