Class ParticleObject

Represents objects in the particle system that the particles can interact with.

An object is a structure occupying a connected set of grid nodes. Particles can connect to objects through bonds and move the objects using the joint movement mechanisms. Objects also form bonds to each other. A particle can trigger a neighboring object to release all its bonds to other objects.

Inheritance

object

ParticleObject

Implements

IParticleObject

IObjectInfo

IReplayHistory

Namespace: AS2.Sim

Assembly: .dll

Syntax

public class ParticleObject : IParticleObject, IObjectInfo, IReplayHistory

Constructors

ParticleObject(ParticleSystem, ParticleObjectSaveData)

Declaration

private ParticleObject(ParticleSystem system, ParticleObjectSaveData data)

Parameters

Type	Name	Description
ParticleSystem	system
ParticleObjectSaveData	data

ParticleObject(Vector2Int, ParticleSystem, int)

Declaration

public ParticleObject(Vector2Int position, ParticleSystem system, int identifier = 0)

Parameters

Type	Name	Description
Vector2Int	position
ParticleSystem	system
int	identifier

Fields

boundaryEdges

The edges on the boundary of the object, used for collision detection. Every entry (x, y, z) stores a relative node position (x, y) and a cardinal direction code z.

Declaration

private HashSet<Vector3Int> boundaryEdges

Field Value

Type	Description
HashSet<Vector3Int>

color

The current display color of the object.

Declaration

private Color color

Field Value

Type	Description
Color

colorHistory

The history of colors.

Declaration

private ValueHistory<Color> colorHistory

Field Value

Type	Description
ValueHistory<Color>

graphics

The graphics adapter of this object. Used to represent the object in the render system and make visualization updates.

Declaration

public ObjectGraphicsAdapter graphics

Field Value

Type	Description
ObjectGraphicsAdapter

identifier

The object's int identifier. Does not have to be unique.

Declaration

private int identifier

Field Value

Type	Description
int

jmOffset

The absolute offset from the object's initial location that was accumulated by joint movements.

Declaration

public Vector2Int jmOffset

Field Value

Type	Description
Vector2Int

jmOffsetHistory

The history of joint movement offsets. Used for storing animation data.

Declaration

private ValueHistory<Vector2Int> jmOffsetHistory

Field Value

Type	Description
ValueHistory<Vector2Int>

occupiedRel

The list of positions occupied by the object in local coordinates, i.e., relative to the root position.

Declaration

private List<Vector2Int> occupiedRel

Field Value

Type	Description
List<Vector2Int>

position

The global root position of the object. This position marks the origin of the local coordinate system and is always occupied by the object.

Declaration

private Vector2Int position

Field Value

Type	Description
Vector2Int

positionHistory

The history of root positions.

Declaration

private ValueHistory<Vector2Int> positionHistory

Field Value

Type	Description
ValueHistory<Vector2Int>

receivedJmOffset

Indicates whether this object has already received a joint movement offset during the movement simulation.

Declaration

public bool receivedJmOffset

Field Value

Type	Description
bool

releaseBonds

Indicates whether this object should release all bonds to other objects in the current movement simulation. Must be reset after each round.

Declaration

public bool releaseBonds

Field Value

Type	Description
bool

system

Declaration

private ParticleSystem system

Field Value

Type	Description
ParticleSystem

Properties

Color

The display color of the object.

Declaration

public Color Color { get; set; }

Property Value

Type	Description
Color

Identifier

The object's identifier. Can be unique to distinguish all objects from each other or specify different types or groups of objects.

Declaration

public int Identifier { get; set; }

Property Value

Type	Description
int

Position

The current root position of the object.

Declaration

public Vector2Int Position { get; }

Property Value

Type	Description
Vector2Int

Size

The number of nodes occupied by the object.

Declaration

public int Size { get; }

Property Value

Type	Description
int

Methods

AddPosition(Vector2Int)

Adds a new position to the object. The position does not have to be connected to the other positions as long as the object is connected when the simulation starts.

If the object is already registered in the render system, its mesh will be recalculated.

Declaration

public void AddPosition(Vector2Int pos)

Parameters

Type	Name	Description
Vector2Int	pos	The global position that should be added to the object.

AddPositionRel(Vector2Int)

Similar to AddPosition(Vector2Int), but specifies the new position in local coordinates, relative to the object's root position.

Declaration

public void AddPositionRel(Vector2Int posRel)

Parameters

Type	Name	Description
Vector2Int	posRel	The local position that should be added to the object.

CalculateBoundaries(bool)

Calculates all boundaries of the object so that the object can be used in collision checks. This should be called once when the simulation starts and the object is complete.

Declaration

public void CalculateBoundaries(bool debug = false)

Parameters

Type	Name	Description
bool	debug	Whether debug lines showing the detected edges should be drawn.

ComputeBoundary(Vector2Int, Direction, HashSet<Vector3Int>, int, int, int[,], bool[,])

Helper method that collects the boundary nodes and direction vectors for the boundary to which the given node belongs.

Declaration

private void ComputeBoundary(Vector2Int start, Direction initialBoundaryDir, HashSet<Vector3Int> edges, int xMin, int yMin, int[,] matrix, bool[,] finishedDirections)

Parameters

Type	Name	Description
Vector2Int	start	The starting node whose boundary should be computed.
Direction	initialBoundaryDir	A cardinal direction that points from start towards the empty space the boundary is adjacent to.
HashSet<Vector3Int>	edges	The set into which the detected edges should be written. The format for each edge is (x, y, z), where (x, y) is the relative position of a boundary node and z is the cardinal direction int of the edge.
int	xMin	The minimum x coordinate of the object's bounding rectangle, used for indexing the object matrix.
int	yMin	The minimum y coordinate of the object's bounding rectangle, used for indexing the object matrix.
int[,]	matrix	The object matrix that maps relative coordinates in the bounding rectangle to node indices.
bool[,]	finishedDirections	A matrix indicating which directions of which node have been considered for boundary detection already. Will be updated with all nodes and directions belonging to the new boundary.

ComputeEdgeMovements()

Computes all edge movements belonging to this object. The edges are computed from the boundaries of the object and their movement is determined by the object's current joint movement offset.

This only works after the boundary edges of the object have been calculated.

Declaration

public EdgeMovement[] ComputeEdgeMovements()

Returns

Type	Description
EdgeMovement[]	An array containing all edge movements of this object for the current round.

ContinueTracking()

Resets the marker to track the latest recorded state and to continue evolving as the simulation progresses.

Declaration

public void ContinueTracking()

Copy()

Creates a copy of this object. The copy is not added to the render system automatically, even if the original has already been added.

Declaration

public ParticleObject Copy()

Returns

Type	Description
ParticleObject	A copy of this object.

CreateFromSaveData(ParticleSystem, ParticleObjectSaveData)

Declaration

public static ParticleObject CreateFromSaveData(ParticleSystem system, ParticleObjectSaveData data)

Parameters

Type	Name	Description
ParticleSystem	system
ParticleObjectSaveData	data

Returns

Type	Description
ParticleObject

CutOffAtMarker()

Deletes all recorded states after the currently marked round.

Declaration

public void CutOffAtMarker()

GenerateSaveData()

Declaration

public ParticleObjectSaveData GenerateSaveData()

Returns

Type	Description
ParticleObjectSaveData

GetFirstRecordedRound()

Returns the first round for which a state has been recorded.

The object cannot be reset to a time before this round.

Declaration

public int GetFirstRecordedRound()

Returns

Type	Description
int	The first round for which a state has been recorded.

GetMarkedRound()

Returns the round that is currently marked.

If the marker is tracking the object's state, this round will increase every time a new value is recorded.

Declaration

public int GetMarkedRound()

Returns

Type	Description
int	The round that is currently marked.

GetOccupiedPositions()

Computes the set of global positions occupied by the object.

Declaration

public Vector2Int[] GetOccupiedPositions()

Returns

Type	Description
Vector2Int[]	An array containing the global grid coordinates of all nodes occupied by the object.

GetRelPositions()

Returns the set of relative positions occupied by the object.

Declaration

public Vector2Int[] GetRelPositions()

Returns

Type	Description
Vector2Int[]	An array containing the grid coordinates of all occupied nodes relative to the object position.

IsAnchor()

Checks whether this object is currently the anchor.

Note that this information is already available in the same round in which the object was made the anchor (unlike, e.g., particle attributes). This depends on the order in which the particles are activated, which the particles can neither control nor find out about.

Declaration

public bool IsAnchor()

Returns

Type	Description
bool	true if and only if the object is the system's anchor.

IsConnected()

Checks whether the object occupies a connected set of grid nodes.

Declaration

public bool IsConnected()

Returns

Type	Description
bool	true if and only if the object is a connected shape.

IsConnected(Vector2Int)

Checks whether the object occupies a connected set of grid nodes if the given node is removed.

Declaration

public bool IsConnected(Vector2Int removedPosition)

Parameters

Type	Name	Description
Vector2Int	removedPosition

Returns

Type	Description
bool	true if and only if the object is still a connected shape after removing the given position.

IsConnected(Vector2Int, bool)

Helper implementing the actual connectivity check. The case that the object occupies only one node and this node is excluded should already have been handled.

Declaration

private bool IsConnected(Vector2Int removedPosition, bool useRemovedPosition = false)

Parameters

Type	Name	Description
Vector2Int	removedPosition	The relative position that should be excluded from the connectivity check. Must be part of the object.
bool	useRemovedPosition	Whether the removed position should be used.

Returns

Type	Description
bool	true if and only if the object is a connected shape.

IsNeighborPosition(Vector2Int)

Checks whether the given global grid position is adjacent to the object.

Declaration

public bool IsNeighborPosition(Vector2Int pos)

Parameters

Type	Name	Description
Vector2Int	pos	The global grid position to check.

Returns

Type	Description
bool	true if and only if pos is adjacent to at least one position occupied by the object but is not occupied itself.

IsTracking()

Checks whether the object is currently tracking the latest recorded state.

If the object is not tracking, it may not be usable in the regular way until the tracking is continued.

Declaration

public bool IsTracking()

Returns

Type	Description
bool	Whether the marker currently tracks the latest recorded state.

MakeAnchor()

Turns this object into the system's anchor.

Declaration

public void MakeAnchor()

MovePosition(Vector2Int)

Moves the entire object by the given offset. Only affects the object's local data. The object is not automatically moved in the system.

Declaration

public void MovePosition(Vector2Int offset)

Parameters

Type	Name	Description
Vector2Int	offset	The offset vector by which the object should be moved.

MoveTo(Vector2Int)

Moves the entire object to the given position. This can be used in Init Mode to easily create multiple copies of a shape in different locations.

Declaration

public void MoveTo(Vector2Int position)

Parameters

Type	Name	Description
Vector2Int	position	The new position of the object's origin.

MoveToPosition(Vector2Int)

Moves the object to the given global coordinates.

Declaration

public bool MoveToPosition(Vector2Int newPos)

Parameters

Type	Name	Description
Vector2Int	newPos	The global grid coordinates to which the object should be moved.

Returns

Type	Description
bool	true if and only if the object was moved successfully.

OccupiedPositions()

Computes the set of grid nodes occupied by the object.

Declaration

public ICollection<Vector2Int> OccupiedPositions()

Returns

Type	Description
ICollection<Vector2Int>	The global coordinates of all grid nodes occupied by the object.

ReleaseBonds()

Triggers this object to release all bonds to other objects.

Declaration

public void ReleaseBonds()

RemoveFromSystem()

Removes the object from the particle system and the render system.

Declaration

public void RemoveFromSystem()

RemovePosition(Vector2Int)

Removes the given global grid position from the object, if the object remains connected and non-empty.

Note that the object's origin position will change if the node at the origin is removed.

Declaration

public bool RemovePosition(Vector2Int pos)

Parameters

Type	Name	Description
Vector2Int	pos	The global grid position to be removed.

Returns

Type	Description
bool	true if and only if the given position was successfully removed from the object.

RemovePositionRel(Vector2Int)

Removes the given local grid position from the object, if the object remains non-empty.

Note that the object's origin position will change if the node at the origin is removed.

Declaration

public bool RemovePositionRel(Vector2Int pos)

Parameters

Type	Name	Description
Vector2Int	pos	The occupied grid position to remove from the object, relative to the object's origin.

Returns

Type	Description
bool	true if and only if the position was successfully removed from the object.

RenderMovement(bool)

Submits the current joint movement offset to the render system to display a movement animation. This should be called after each round and whenever the simulation state changes.

Declaration

public void RenderMovement(bool withAnimation = true)

Parameters

Type	Name	Description
bool	withAnimation	Whether an animation should be played.

SetColor(Color)

Gives the object a new color. If multiple particles set the same object's color, the one set by the last simulated particle will be used.

Declaration

public void SetColor(Color color)

Parameters

Type	Name	Description
Color	color	The new color of the object.

SetMarkerToRound(int)

Sets the tracking marker to the specified round, restores the state recorded for that point in time, and stops the marker from tracking the latest round.

The target round must not be earlier than the round returned by GetFirstRecordedRound().

Declaration

public void SetMarkerToRound(int round)

Parameters

Type	Name	Description
int	round	The round to which the tracking marker should be set.

ShiftTimescale(int)

Shifts all records as well as the marker by the specified amount of rounds.

Declaration

public void ShiftTimescale(int amount)

Parameters

Type	Name	Description
int	amount	The number of rounds to add to each entry. May be negative.

StepBack()

Moves the marker one round back and restores the object's recorded state for that round. Also stops it from tracking the last round if it was still tracking.

Must not be called when the marker is already at the first recorded round.

Declaration

public void StepBack()

StepForward()

Moves the marker one round forward and restores the object's recorded state for that round. Also stops it from tracking the last round if it was still tracking.

May be ineffective if the object has a hard limit on the last recorded round.

Declaration

public void StepForward()

StoreAndResetMovementInfo()

Stores the current joint movement offset in the object's history and resets the offset and corresponding flag for the next round.

Declaration

public void StoreAndResetMovementInfo()

Implements

IParticleObject

IObjectInfo

IReplayHistory