• Installation Guide
  • Amoebot Model
  • User Guide
  • Model Reference
  • Dev Guide
  • API Documentation
Search Results for

    Show / Hide Table of Contents
    • Architecture Overview
    • Simulator
      • History
      • Save and Load
      • User API
      • Round Simulation
      • Reflection
      • Error Handling
    • User Interface
    • Input Handling
    • Render System
      • Unity Rendering Basics
      • Background Renderer
      • UI Renderer
      • Object Renderer
      • Particle Renderer
        • Particles
        • Shader Example
        • Circuits and Bonds
        • Data Structures and Interface

    Developer Guide: User API

    An integral part of the simulation environment is the user interface for programming particle algorithms. This API provides all functionality necessary for controlling the particle behavior while preventing access to the simulator's internals as far as possible. It also includes a system for writing custom particle system generation methods, allowing users to define precisely what the initial configuration should look like.

    This page explains some technical details of how these two parts of the API are realized.

    Particle Algorithm API

    The particle algorithm API is defined by the ParticleAlgorithm class. It defines all properties and methods available to the algorithm developer by inheritance: Algorithms are always defined as subclasses of ParticleAlgorithm. The class only has a single data member, which is a reference to the Particle controlled by the algorithm. Since this member is private, it cannot be accessed by any subclass. There is a 1:1 relation between the ParticleAlgorithm and the Particle class, i.e., instances of this class are always created in pairs and the link between them is never broken. The Particle instance represents the particle in the system and stores its data while the ParticleAlgorithm instance defines its behavior.

    All methods in the API are directly passed through to the Particle or the ParticleSystem class, where they are handled accordingly. For most methods, it is first checked whether the particle is currently active (i.e., being activated) using its isActive flag. This flag is set to true by the particle system before its activation method is called and reset to false afterwards. With this system, it is prevented that a particle calls API methods on its neighbors, because only one particle is active at a time. Similarly, the system's InMovePhase and InBeepPhase flags are used to ensure that API methods are called in the correct activation method, i.e., expansions and contractions should not be triggered in the beep activation.

    Many of the method calls do not immediately take effect in the particle's state but only schedule an action that should be carried out after all particles have been activated. For example, any movement scheduled by a particle must be delayed until all movement activations have been simulated because the particle's neighbors should not see the changed position until the next round. This feature is explained in more detail on the round simulation page.

    Attributes

    As explained on the attributes reference page, the state of a particle algorithm is defined by its attributes. Attributes are similar to fields of a class, but they are created differently and provide some additional functionality. We use a hierarchy of classes to implement all required features of the attributes:

    Particle Attribute Hierarchy

    The IParticleAttribute interface defines how all attributes can be used internally by the system. It is implemented by the non-abstract classes in the hierarchy, all of which are derived from several abstract classes defining their features. The interface is not generic (it does not specify a type parameter), but it declares a GetAttributeType method so the type of the attribute is still available.

    At the top of the hierarchy, the abstract ParticleAttributeBase class defines the most common fields of all attributes, a Particle reference and the attribute's name. Immediately below that, the abstract and generic ParticleAttribute<T> class declares the methods available to the algorithm developer. The attribute fields of the algorithm class always have the type ParticleAttribute<T>, where T is the type of value that the attribute stores. Accordingly, all CreateAttributeXYZ methods of the ParticleAlgorithm class have a specification of ParticleAttribute<T> as their return type, even though they return objects of the types at the bottom of the hierarchy.

    One level below this, the abstract and generic ParticleAttributeWithHistory<T> class adds functionality that should only be available to the internal system class, not the algorithm developer. This includes the history and save/load features, some parts of the IParticleAttribute interface and some additional methods used to implement the round simulation.

    Finally, the ParticleAttribute_XYZ classes at the bottom of the hierarchy specialize the above classes for the supported attribute data types. These classes are not abstract or generic and they implement the required functionality that is specific to their data types. For example, the ParticleAttribute_PinConfiguration class uses an alternative method of storing its history of pin configurations, which is only necessary for this type of attribute.

    Internally, the Particle class uses a list of IParticleAttributes to manage its attributes. When the algorithm calls an attribute creation method, the static ParticleAttributeFactory class creates an object for the requested type and adds it to the particle's list of attributes. The class also ensures that attributes are only created in the algorithm's constructor (using the Particle's inConstructor flag) and their names do not collide with the reserved attribute names Chirality and Compass Dir. These names are reserved so that the particle's chirality and compass direction can be accessed like regular attributes, even though they have a different internal representation.

    The attribute classes additionally have some special features implementing simulation-specific functionality, which is discussed on the round simulation page.

    System Initialization API

    Algorithm developers can use the custom initialization feature to define the initial system configuration manually and to add custom parameters to the particles. The main part of this feature is the abstract InitializationMethod class. It is similar to the ParticleAlgorithm class in that the developer creates a subclass of InitializationMethod to implement the custom initialization procedure. The class provides several interface methods like AddParticle(...) and PlaceParallelogram(...) that can be used by the subclass's Generate() method to define the initial particle system. All of these interface methods directly refer to the ParticleSystem to apply the corresponding changes to the current system.

    In Init Mode, the particle system uses the InitializationParticle class instead of Particle to represent its particles. More precisely, it actually uses the OpenInitParticle class, which inherits from InitializationParticle but provides more direct access to its internal data, making it easier to manipulate. The InitializationParticle class is abstract and provides the interface for the developer. It is a simplified version of the main Particle class, lacking all functionality that is not required in Init Mode. Objects of this type act as placeholders in the initialization system that are replaced by proper particles when the simulation starts.

    The InitializationParticle class uses its own list of attributes to represent the initialization parameters. They are initialized to match the parameters of the selected algorithm's Init(...) method and they can be updated using the particle's SetAttribute(string name, object value) and SetAttributes(object[] values) methods in the custom initialization code. When the simulation starts, the values of these attributes are passed to the Init(...) method's parameters of each new particle. This task is performed by the ParticleFactory class. Many of the features in this system, like creating attributes according to the Init(...) method's parameters, are handled by the reflection helper methods, which are explained on their own page.

    In this article
    Back to top AmoebotSim 2.0 Documentation v1.11
    Copyright © 2025 AmoebotSim 2.0 Authors
    Generated by DocFX