Modding:Behavior Traversal

Behavior Classes

Instances of the following classes delegate some of their methods to a list of behaviors that are attached to the objects. These are the classes that support behaviors.

• Block -> BlockBehavior
• BlockGeneric -> StrongBlockBehavior
• BlockEntity -> BlockEntityBehavior
• BlockEntityFarmland -> CropBehavior
• CollectibleObject -> CollectibleBehavior
• Entity -> EntityBehavior

Full Traversal

The parent calls the list behaviors in a certain order. That order is called the behavior traversal.

The following code is used as an example to explain the behavior traversal. This example shows a full traversal, and for simplicity the handled parameter elided.

public class Derived : Base
{
    public override void Method()
    {
        // Derived.Before
        Base.Method();
        // Derived.After
    }
}

public class Base
{
    public Behavior[] Behaviors;

    public virtual void Method()
    {
        // Base.Before
        foreach (Behavior behavior in Behaviors)
        {
            behavior.Method();
        }
        // Default
    }
}

public class Behavior
{
    public virtual void Method()
    {
        // Behavior
    }
}

The logic in the snippet above runs in this order:

1. Derived.Before
2. Base.Before
3. Behavior1
4. ...BehaviorN
5. Default
6. Derived.After

Block and BlockEntity Traversal

A few methods, such as OnBlockPlaced, exist on both the BlockBehavior and BlockEntityBehavior. In these cases, the Block default logic calls the BlockEntity method, which then delegates to the BlockEntityBehavior. So the full traversal is:

1. DerivedBlock.Before
2. BaseBlock.Before
3. BlockBehavior1
4. ...BlockBehaviorN
5. Default logic => DerivedBlockEntity.Before
6. DerivedBlockEntity.Before
7. BaseBlockEntity.Before
8. BlockEntityBehavior1
9. ...BlockEntityBehaviorN
10. BaseBlockEntity.Default

Combining Return Values

The behavior methods can return values. Since multiple behaviors can be attached to the same object, the base method has to combine the behavior return values. The method of combining the values varies depending on the base method, but typically one of these strategies are used:

• logical and all values -- only valid for methods that return bool
• keep last value

EnumHandling

Most behavior methods support an EnumHandling ref parameter called handled. Note that even though is a ref parameter, it should be treated as an out parameter. Behaviors can use that parameter to indicate two things. 1) should the return value of the behavior method be used or ignored. 2) if any sections of the behavior traversal should be skipped. A section of the traversal is skipped if any of the behaviors request to skip it.

Enum value	Use/ignore return value	Skip traversal steps
PassThrough	ignore	-
Handled	use	-
PreventDefault	use	skip default
PreventSubsequent	use	skip remaining behaviors and default

As described above, as the behaviors are traversed, their return values are combined together. When the default logic is skipped, the combined value is directly returned instead of running the default logic.

In many cases, the default logic just returns the combined value, unless all of the mods specified PassThrough, in which a different default value is returned. For that kind of default logic, Handled and PreventDefault both do the same thing: return the combined value after running the rest of the behaviors.

Wondering where some links have gone?
The modding navbox is going through some changes! Check out Navigation Box Updates for more info and help finding specific pages.