Class Suboracle<T>

Base class for all suboracles. A suboracle encapsulates a subtask on a group of member particles. Each member particle owns its own suboracle instance (created in the particle constructor) that stores per-particle state via ParticleAttribute<T> attributes. One designated member — the representative — drives the subtask: its Init(List<T>) method receives the full member list, and its Activate() method is called round-by-round until the subtask completes, either by a [Oracle] method on the owning ParticleAlgorithm or inside another Suboracle<T>. A suboracle instance on a representative can be reused, but needs to be resetted via Reset() before re-initialisation.

Inheritance

object

Suboracle<T>

MonotoneToLine

Parallelogram

Rule12

Rule3abc

Rule3de

Spiral

Trapezoid

Triangle

Unrolling

Shear

Namespace: AS2.Suboracles

Assembly: .dll

Syntax

public abstract class Suboracle<T> where T : Suboracle<T>

Type Parameters

Name	Description
T	The derived suboracle type (CRTP pattern).

Constructors

Suboracle(Particle)

Initialises a new suboracle instance associated with the given particle. Can only be called during the particle's constructor phase.

Declaration

public Suboracle(Particle rep)

Parameters

Type	Name	Description
Particle	rep	The particle that owns this suboracle.

Exceptions

Type	Condition
SimulatorStateException	Thrown if called outside the constructor phase.

Fields

currentBreakpoint

Declaration

private string currentBreakpoint

Field Value

Type	Description
string

isActive

Declaration

private bool isActive

Field Value

Type	Description
bool

lastActivatedRound

Declaration

private int lastActivatedRound

Field Value

Type	Description
int

members

The list of member suboracles that participate in this suboracle instance.

Declaration

protected List<T> members

Field Value

Type	Description
List<T>

particle

Declaration

private Particle particle

Field Value

Type	Description
Particle

representative

The ParticleAlgorithm that owns this suboracle instance and serves as the representative for the subtask. Activate() is called on the representative's instance, which coordinates actions across all members.

Declaration

protected ParticleAlgorithm representative

Field Value

Type	Description
ParticleAlgorithm

unitVectors

Declaration

private Vector2Int[] unitVectors

Field Value

Type	Description
Vector2Int[]

Methods

Activate()

Activates the suboracle for the current round. Needs to be called on the representative's instance. Calls OnActivate() to perform the subtask logic. If OnActivate() returns true, the suboracle automatically deactivates (marks itself as finished).

Declaration

public bool Activate()

Returns

Type	Description
bool	true if the suboracle has finished its subtask; false if more rounds are needed.

Remarks

If called multiple times within the same round, subsequent calls are ignored.

Exceptions

Type	Condition
SimulatorStateException	Thrown if the suboracle has not been initialised.

FindValidAttributeName(string)

Finds an attribute name that is not taken yet by appending a number to the end of the given name.

Declaration

protected string FindValidAttributeName(string name)

Parameters

Type	Name	Description
string	name	The base name of the attribute.

Returns

Type	Description
string	Either name if the name is not taken yet, or name with an appended number to avoid duplicate attribute names.

FinishedLastRound()

Checks whether this suboracle finished its subtask in the previous round.

Declaration

public bool FinishedLastRound()

Returns

Type	Description
bool	true if the suboracle was active last round and is now inactive (i.e., finished); false otherwise.

GetCurrentBreakpoint()

Returns the currently set breakpoint name, or null if none is set.

Declaration

public string GetCurrentBreakpoint()

Returns

Type	Description
string	The current breakpoint name, or null.

GetGridPos(ParticleAlgorithm[][])

Finds the grid position (x, y) of the representative particle within a member grid previously built by MemberGrid(Direction, Direction, bool).

Declaration

public Vector2Int GetGridPos(ParticleAlgorithm[][] memberGrid)

Parameters

Type	Name	Description
ParticleAlgorithm[][]	memberGrid	The grid to search in.

Returns

Type	Description
Vector2Int	The (x, y) position of this particle in the grid.

Exceptions

Type	Condition
SimulatorStateException	Thrown if this particle is not found in the grid.

GetMember(ParticleAlgorithm)

Gets the suboracle instance associated with the given particle algorithm.

Declaration

public T GetMember(ParticleAlgorithm p)

Parameters

Type	Name	Description
ParticleAlgorithm	p	The particle algorithm to look up.

Returns

Type	Description
T	The suboracle instance, or null if not found.

GetMemberAlgorithms()

Returns a list of all particle algorithms that are members of this suboracle.

Declaration

public List<ParticleAlgorithm> GetMemberAlgorithms()

Returns

Type	Description
List<ParticleAlgorithm>	A list of ParticleAlgorithm instances, or an empty list if no members are set.

GetSuboracles<U>(List<ParticleAlgorithm>, Func<T, U>)

Converts a list of ParticleAlgorithm instances into a list of target suboracles of type U. For each particle algorithm, the member is looked up and the selector is applied to retrieve the owned suboracle.

This is the primary way to pass members to a nested suboracle's Init(List<T>) method: the outer suboracle collects its members' particle algorithms, then calls GetSuboracles(members, m => m.nestedSuboracle) to obtain the typed list required by the nested suboracle.

Declaration

public List<U> GetSuboracles<U>(List<ParticleAlgorithm> ps, Func<T, U> suboracle) where U : Suboracle<U>

Parameters

Type	Name	Description
List<ParticleAlgorithm>	ps	The list of ParticleAlgorithm instances to convert.
Func<T, U>	suboracle	A selector function that maps from this suboracle type (T) to the target suboracle type (U), e.g. m => m.parallelogram.

Returns

Type	Description
List<U>	A list of target suboracle instances (null entries from non-members are omitted).

Type Parameters

Name	Description
U	The type of the target suboracle.

Init(List<T>)

Initialises the suboracle with an optional list of member particles. Marks the suboracle as active, ready to be activated in subsequent rounds.

Declaration

public void Init(List<T> memberParticles)

Parameters

Type	Name	Description
List<T>	memberParticles	The list of member suboracles participating in this operation.

Exceptions

Type	Condition
SimulatorStateException	Thrown if the suboracle is already active, or if memberParticles contains null entries.

IsActive()

Returns whether this suboracle is currently active (has been initialised and not yet finished).

Declaration

public bool IsActive()

Returns

Type	Description
bool	true if the suboracle is active; false otherwise.

IsMember(ParticleAlgorithm)

Checks whether the given particle algorithm is a member of this suboracle.

Declaration

public bool IsMember(ParticleAlgorithm p)

Parameters

Type	Name	Description
ParticleAlgorithm	p	The particle algorithm to check.

Returns

Type	Description
bool	true if p is a member; false otherwise.

MemberGrid(Direction, Direction, bool)

Builds a 2D grid of member particles projected onto a coordinate system defined by the given y- and x-axes. Each grid cell contains the ParticleAlgorithm of the particle whose head (or optionally tail) occupies that position. Empty cells are null.

Declaration

public ParticleAlgorithm[][] MemberGrid(Direction yAxis = Direction.NNE, Direction xAxis = Direction.NONE, bool includeTail = false)

Parameters

Type	Name	Description
Direction	yAxis	The direction to use as the y-axis (default: NNE).
Direction	xAxis	The direction to use as the x-axis (default: y-axis rotated 60° counter-clockwise).
bool	includeTail	If true, also place the particle in the cell occupied by its tail.

Returns

Type	Description
ParticleAlgorithm[][]	A 2D array [y][x] of ParticleAlgorithm references, or null for empty cells.

Remarks

The grid origin is shifted so the minimum coordinates are at index 0.

OnActivate()

Virtual method that derived suboracles override to implement their subtask logic. Called once per round by Activate().

Declaration

protected virtual bool OnActivate()

Returns

Type	Description
bool	true if the subtask is complete and the suboracle should deactivate; false if more rounds are needed.

Reset()

Resets the suboracle to its initial inactive state, clearing all members and resetting lastActivatedRound.

Declaration

public void Reset()

RotateAxes(Vector2Int, Direction, Direction)

Rotates a position vector from the standard coordinate system into a custom coordinate system defined by two axes. Uses the inverse of the 2x2 matrix formed by the unit vectors of the new axes.

Declaration

private Vector2Int RotateAxes(Vector2Int pos, Direction newXAxis, Direction newYAxis)

Parameters

Type	Name	Description
Vector2Int	pos	The position vector to rotate.
Direction	newXAxis	The direction of the new x-axis.
Direction	newYAxis	The direction of the new y-axis.

Returns

Type	Description
Vector2Int	The position expressed in the new coordinate system.

Exceptions

Type	Condition
SimulatorStateException	Thrown if the two axes are parallel.

SetBreakpoint(string)

Sets a named breakpoint on this suboracle. The breakpoint is stored locally and must be checked by the associated ParticleAlgorithm instance to trigger pausing.

Declaration

protected void SetBreakpoint(string name)

Parameters

Type	Name	Description
string	name	The name of the breakpoint.