Class PolymorphicAction<T>

A decorator to enable subtype polymorphism for action classes.

By convention, concrete action subclasses are named with verb phrases, e.g., Heal, Sell.

One downside of this compared to the vanilla IAction is the fact that it uses reflection under the hood. This may cause compatibility issues on certain platforms, and is slightly slower.

Inheritance

Object

PolymorphicAction<T>

Implements

IAction

Inherited Members

Object.Equals(Object)

Object.Equals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Object.ReferenceEquals(Object, Object)

Object.ToString()

Namespace: Libplanet.Action

Assembly: Libplanet.dll

Syntax

public sealed class PolymorphicAction<T> : IAction where T : IAction

Type Parameters

Name	Description
T	An action base class which implements IAction and has subclasses. Usually an abstract class.

Remarks

Every concrete action subclass of T has to be marked with the ActionTypeAttribute. Even if a superclass is marked with the ActionTypeAttribute its subclass also should be marked with the ActionTypeAttribute if it is concrete.

Examples

The following example shows how polymorphic actions look like (compare this with an IAction example without subtype polymorphism):

using System;
using System.Collections.Immutable;
using Libplanet;
using Libplanet.Action;

// Instead of having multiple in-game actions in a class,
// in this example, we declare one abstract base class
// and its three concrete subclasses.
public abstract class ActionBase : IAction
{
    public ActionBase() { }

    public ActionBase(Address targetAddress)
    {
        TargetAddress = targetAddress;
    }

    public Address TargetAddress { get; private set; }

    // Leaves Execute() abstract so that concrete subclasses
    // implement their own logic.
    public abstract IAccountStateDelta Execute(IActionContext context);

    IImmutableDictionary<string, object> IAction.PlainValue =>
        ImmutableDictionary<string, object>.Empty
            .Add("target_address", TargetAddress);

    void IAction.LoadPlainValue(
        IImmutableDictionary<string, object> plainValue)
    {
        TargetAddress = (Address)plainValue["target_address"];
    }
}

// PolymorphicAction<T> requires concrete action classes marked with
// ActionTypeAttribute.
// There is only one required parameter to ActionTypeAttribute,
// which takes a unique identifier of the action type.
// This is used for serialization and deserialization under the hood.
[ActionType("create_character")]
public sealed class CreateCharacter : ActionBase
{
    public override IAccountStateDelta Execute(IActionContext context)
    {
        var state = (ImmutableDictionary<string, uint>)
            context.PreviousStates.GetState(TargetAddress);
        if (!TargetAddress.Equals(context.Signer))
            throw new Exception(
                "TargetAddress of CreateCharacter action only can be " +
                "the same address to the Transaction<T>.Signer."
            );
        else if (!(state is null))
            throw new Exception("Character was already created.");
        return context.PreviousStates.SetState(
            TargetAddress,
            ImmutableDictionary<string, uint>.Empty.Add("hp", 20)
        );
    }
}

[ActionType("attack")]
public sealed class Attack : ActionBase
{
    public override IAccountStateDelta Execute(IActionContext context)
    {
        var state = (ImmutableDictionary<string, uint>)
            context.PreviousStates.GetState(TargetAddress);
        return context.PreviousStates.SetState(
            TargetAddress,
            state.SetItem("hp", Math.Max(state["hp"] - 5, 0))
        );
    }
}

[ActionType("heal")]
public sealed class Heal : ActionBase
{
    public override IAccountStateDelta Execute(IActionContext context)
    {
        var state = (ImmutableDictionary<string, uint>)
            context.PreviousStates.GetState(TargetAddress);
        return context.PreviousStates.SetState(
            TargetAddress,
            state.SetItem("hp", Math.Min(state["hp"] + 5, 20))
        );
    }
}

Constructors

PolymorphicAction()

Do not use this constructor. Use PolymorphicAction(T) instead.

Declaration

[Obsolete]
public PolymorphicAction()

PolymorphicAction(T)

Creates a new PolymorphicAction<T> instance wrapping an innerAction.

Declaration

public PolymorphicAction(T innerAction)

Parameters

Type	Name	Description
T	innerAction	An instance of T (or one of its subtypes) to wrap.

Exceptions

Type	Condition
MissingActionTypeException	Thrown when the class of the given innerAction is not annotated with ActionTypeAttribute.

Properties

InnerAction

The wrapped action object of T (or one of its subtypes).

Declaration

public T InnerAction { get; }

Property Value

Type	Description
T

PlainValue

Serializes values bound to an action, which is held by properties (or fields) of an action, so that they can be transmitted over network or saved to persistent storage.

Serialized values are deserialized by LoadPlainValue(IImmutableDictionary<String, Object>) method later.

It uses .NET's built-in serialization mechanism.

Declaration

public IImmutableDictionary<string, object> PlainValue { get; }

Property Value

Type	Description
IImmutableDictionary<String, Object>	A value which encodes this action's bound values (held by properties or fields). It has to be serializable.

See Also

LoadPlainValue(IImmutableDictionary<String, Object>)

Methods

Execute(IActionContext)

Executes the main game logic of an action. This should be deterministic.

Through the context object, it receives information such as a transaction signer, its states immediately before the execution, and a deterministic random seed.

Other “bound” information resides in the action object in itself, as its properties (or fields).

A returned AddressStateMap object functions as a delta which shifts from previous states to next states.

Declaration

public IAccountStateDelta Execute(IActionContext context)

Parameters

Type	Name	Description
IActionContext	context	A context object containing addresses that signed the transaction, states immediately before the execution, and a PRNG object which produces deterministic random numbers. See IActionContext for details.

Returns

Type	Description
IAccountStateDelta	A map of changed states (so-called "dirty").

Remarks

This method should be deterministic: for structurally (member-wise) equal actions and IActionContexts, the same result should be returned.

For randomness, never use Random nor any other PRNGs provided by other than Libplanet. Use Random instead.

Also do not perform I/O operations such as file system access or networking. These bring an action indeterministic.

See Also

IActionContext

LoadPlainValue(IImmutableDictionary<String, Object>)

Deserializes serialized data (i.e., data PlainValue property made), and then fills this action's properties (or fields) with the deserialized values.

Declaration

public void LoadPlainValue(IImmutableDictionary<string, object> plainValue)

Parameters

Type	Name	Description
IImmutableDictionary<String, Object>	plainValue	Data (made by PlainValue property) to be deserialized and assigned to this action's properties (or fields).

See Also

PlainValue

Operators

Implicit(T to PolymorphicAction<T>)

For convenience, an inner action T can be implicitly casted to PolymorphicAction<T>.

Declaration

public static implicit operator PolymorphicAction<T>(T innerAction)

Parameters

Type	Name	Description
T	innerAction	An instance of T (or one of its subtypes) to wrap.

Returns

Type	Description
PolymorphicAction<T>	A PolymorphicAction<T> wrapping the given innerAction.

Exceptions

Type	Condition
MissingActionTypeException	Thrown when the class of the given innerAction is not annotated with ActionTypeAttribute.

Implements

IAction