Compost Organism – Culebra Tutorial – Aya Al Homsi

The project developed in Grasshopper represents a compost organism moving through a forest environment, connecting nutrients within the ecosystem. Its purpose is to accelerate the decomposition of organic matter (such as bodies) and to support natural material cycles in the landscape.

The simulation was created using the Culebra plug-in (https://www.complicitmatter.com/culebra-net/), which enables agent-based behavior based on principles of swarm intelligence. The organism’s movement is guided by a system of Points of Interest with a defined threshold, determining the level of attraction and the moment of activation for relocation.

The behavior is based on the principles of flocking and stigmergy. Flocking ensures collective, emergent movement governed by local rules without any central control. Individual agents respond only to their immediate surroundings, resulting in coordinated group behavior.

Stigmergy enables indirect communication through the environment. The organism leaves traces (such as changes in nutrient concentration) that subsequently influence further actions. This creates a self-organizing system capable of producing complex structures without planning or centralized coordination.

As part of the research, three system variations were developed:

large activity / small scale
medium activity / medium scale
small activity / large scale

These scenarios test the relationship between the intensity of agent activity and the spatial scale of their impact within the landscape. The result is a dynamic, adaptive model simulating the ecological intelligence of the forest and its metabolic processes.

CULEBRA

Culebra is a live agent based C# library (Wrapper around Culebra Java library) and
plugin for Grasshopper. It A collection of objects and behaviors for creating dynamic
multi agent interactions. 2D|3D Multi Object Behavior library focused on hybrid
system interactions with custom Visualization, Data, and performance features.

In this project, Culebra is used to simulate a self-organizing composed of multiple agents. The system operates without central control and relies on local interaction rules.

The main behavioral principles applied are stigmergy and flocking.

Flocking governs the collective movement of agents. Each agent responds only to its immediate surroundings, yet together they produce coordinated, emergent motion across the forest landscape.
Stigmergy enables indirect communication through the environment. Agents leave traces that influence future movement, reinforcing paths and intensifying activity in certain areas. This mechanism allows the system to self-organize and create complex spatial patterns without centralized planning.

Code Structure and Simulation Setup

1. Spawn Settings

First, I define the Spawn Settings.
A bounding box establishes the spatial limits in which the simulation takes place. (450x500x851)

Using a Value List, I specify the spawn location mode:

0 = 2D Aligned or 3D Random on Ground

1 = 2D Random Scattered in Box or 3D Random Scattered in Box

I then define the Spawn Count, which determines the number of creepers (agents) generated in the system.

2. Init Settings

In the Init Settings, using Value List I define the fundamental simulation parameters:

Dimensions:

0 = 2D

1 = 3D

Boundary behavior:

0 = Bounce

1 = Respawn

2 = None

The Init Settings component transfers all spawn-related information directly into the Creeper Engine, initializing the agents and their environmental constraints.

3. Move Settings

The Move Settings control the physical dynamics of the agents.
Using number sliders, I define:

Initial Speed / Vector
Maximum Speed
Maximum Force
Velocity Multiplier

These parameters regulate how the agents accelerate, steer, and move through space. The Move Settings are then connected to the Creeper Engine.

4. Behavioral Systems

The behavioral logic consists of two main systems: Stigmergy and Flocking and Attraction Force. Behaviour settings are conected to the Creeper engine through a controler.

Stigmergy Parameters
The stigmergy behavior is controlled through several sliders:
View Angle – Defines the field of vision for each agent.
Cohesion Magnitude – Controls how strongly agents steer toward the average position of nearby agents.
Cohesion Range – Defines the distance threshold within which cohesion is activated.
Separation Magnitude – Controls how strongly agents avoid crowding along trails.
Separation Range – Defines the distance threshold at which separation behavior is triggered.
These parameters regulate how agents react to environmental traces and reinforce emergent trail formation.

Flocking Parameters
The flocking behavior further refines collective movement:
Connect (Boolean Toggle)-True = Connect agent heads visually (displays search radius; significantly reduces performance), False = No visual connectivity

View Angle – Specifies the visual field of each agent.
Search Radius – Defines how far each creeper can perceive other agents.
Align Value – Controls alignment behavior (steering toward the average velocity of neighbors).
Separation Value – Controls avoidance behavior to prevent local crowding.
Cohesion Value – Controls attraction toward the average position of nearby flock members.
Together, these behavioral systems allow the compost organism to operate as a decentralized, self-organizing network, responding dynamically to both environmental conditions and neighboring agents.

attraction forces

I used attraction forces to lift the creepers upward. One set of attractors is placed on the upper plane of the bounding box to pull the agents into vertical space. The second set of attractors is generated using a 3D Populate component, allowing the creepers to interact with each other within the volume.

Targets – A list of target points that the agents are attracted to.
Thresholds – A list of threshold values corresponding to each target, defining the activation distance for attraction.
Attraction Value – A magnitude value specifying the strength of the attraction force.
Max Attraction – The maximum attraction force that can be applied, limiting the intensity of the pull toward targets.
Together, these attraction forces allow the compost organism to expand vertically, interact within a volumetric field, and create more spatially complex movement patterns.

5. Visual Settings

I define the Visual Settings. An important part of this setup is configuring the trail data.

Visual Data

Controls the visual settings for the Creeper Engine Outputs.

Trail Data

Controls the Trail Data for the Visual Settings
Component.

Trail Input – Boolean toggle specifying trail visibility (True = On | False = Off)
Trail Step Input – Integer value defining the minimum number of steps before storing a trail vector (higher values improve performance)
Max Trail Size Input – Integer value specifying the maximum number of trail vectors per object (lower values improve performance)

Gradient Color

controls the Gradient Color trail options for the
Visual Settings Component.

Particle Texture Path – Input the path to the particle texture or PNG file
Red Channel Input – Domain component specifying the minimum and maximum floating-point values for the red channel
Green Channel Input – Domain component specifying the minimum and maximum floating-point values for the green channel
Blue Channel Input – Domain component specifying the minimum and maximum floating-point values for the blue channel
Min Thickness Input – Specifies the minimum thickness of the polyline
Max Thickness Input – Specifies the maximum thickness of the polyline

By following these parameters, your result should look something like this: large activity / small scale

medium activity / medium scale:

If you change your parameters, such as the size of your box, you will need to compensate by adjusting your stigmergy and flocking parameters. For example, the box: 1170 × 1930 × 851. Atraction points count 12+35, spawn count 500.

stigmergy and flocking values:

your result should look something like this:

small activity / large scale

If you change your parameters, such as the size of your box, you will need to compensate by adjusting your stigmergy and flocking parameters. For example, the box: 2460 × 3970 × 130. Atraction points count 12+22, spawn count 500. Spawn location 2D Random Scattered in box or 3D Random Scattered in Box. Dimension 2D.

stigmergy and flocking values: