Model Reference: Neighbor Discovery

One of the basic abilities of amoebot particles is detecting neighbor amoebots and reading their states. This page explains how this is done in algorithm code.

The simplest way to check whether there is a neighbor amoebot in a specific position is the HasNeighborAt(Direction d, bool head) method. Given the direction and an optional head or tail flag specifying an adjacent position, this method will return true if there is an amoebot at that position. In addition to just finding neighbors, an amoebot can also read its neighbors' state attributes. For this, you first have to get a reference to the neighbor using the GetNeighborAt(Direction d, bool head) method, and then you need to typecast the reference to the type of your algorithm class to access its attributes. For example:

public class MyAlgorithm : ParticleAlgorithm {
    public ParticleAttribute<int> myInt;  // We want to read this attribute of our neighbor
    ...
    public override void ActivateBeep() {
        ...
        // Check if we have a neighbor in East direction
        if (HasNeighborAt(Direction.E)) {
            // Get the neighbor reference and typecast it
            MyAlgorithm nbr = (MyAlgorithm)GetNeighborAt(Direction.E);
            // Returns myInt.GetValue()
            int nbrAttribute = nbr.myInt;
        }
        ...
    }
}

When reading a neighbor's attributes, only their values from the beginning of the current round are available, even if that amoebot changes the values in this round. In other words, you cannot call GetCurrentValue() on attributes of neighboring amoebots (see the attributes reference page for details).

If the neighboring amoebot is expanded, it might be of interest whether the neighboring part is the amoebot's head or tail. To find out, you can use the IsHeadAt(Direction dir, bool head) and IsTailAt(Direction dir, bool head) methods. These are especially helpful for planning handover movements.

Advanced Neighbor Discovery

In some cases, it is necessary to find neighbors with a specific property, find the first neighbor in a specific region or even all neighbors at once. The algorithm API provides several advanced methods that can be useful in such cases. They all make use of the Neighbor<T> struct, which contains not just a neighbor reference, but also the direction and head/tail information identifying the neighbor's location. Since it is generic, the neighbor reference already has the correct type, meaning that the typecast is not necessary when using this struct. All of the advanced neighbor discovery methods use this struct as return types.

Here is a short overview of the advanced discovery methods (you can read more about them in the API documentation):