✨ React Slime Simulation ✨

A highly customizable React component to simulate the fascinating behavior of unicellular organisms (like Physarum polycephalum or "slime mold") directly in your browser using Canvas. Create organic and interactive visualizations!

➡️ demo GIF here! ⬅️

🚀 Key Features

• Canvas Simulation: Efficient rendering using requestAnimationFrame.
• Highly Configurable: Adjust dozens of parameters to influence behavior and appearance.
• Custom Starting Shape: Use your own SVG to define the initial agent area.
• Random Default Behavior: Get unique simulations every time without effort.
• Brush Interaction: Influence the simulation in real-time with your mouse.
• Easy Integration: Simple React component to add to your projects.
• Lightweight: No heavy external dependencies (React is a peerDependency).

📦 Installation

npm install react-slime-simulation
# or
yarn add react-slime-simulation

💻 Basic Usage

Import the component and add it to your application. By default, it will use random parameters and the built-in SVG.

import React from "react";
import SlimeSimulation from "react-slime-simulation";
import "./App.css"; // Make sure the container can take up space

function App() {
  return (
    <div style={{ width: "100vw", height: "100vh", overflow: "hidden" }}>
      <SlimeSimulation />
    </div>
  );
}

export default App;

⚙️ API & Props

The simulation behavior can be finely tuned via props.

| Prop | Type | Default | Description | | :------------------ | :------ | :----------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | | useRandomDefaults | boolean | true | If true, ignores other parameter props and generates random values on each mount (original default behavior). If false, uses the provided prop values. | | svgShape | string | Built-in SVG (see source code) | A string containing the complete SVG markup (...) to define the starting area. If invalid, agents appear randomly. | | initialAgents | number | Random (600-1100) | Number of agents in the simulation. Significantly impacts performance. | | sensorOffset | number | Random (5-29) | Distance at which agents "sense" traces ahead of them. | | agentSpeed | number | Random (0.8-1.9) | Movement speed of agents per frame. | | trailStrength | number | Random (0.5-2.9) | Amount of "trail" left by an agent at each step. | | evaporationRate | number | Random (0.005-0.044) | Rate at which trails evaporate each frame. | | edgeAvoidance | number | Random (0.0-0.9) | Strength with which agents try to avoid the edges of the simulation area. | | escapeThreshold | number | Random (0.5-1.0) | Trace density threshold that triggers an agent's "escape" behavior. | | baseHue | number | Random (0-359) | Base HSL hue for the trail color. | | hueRange | number | Random (30-89) | Range of hue variation around baseHue, based on trace intensity. | | lightnessRange | number | Random (20-49) | Range of lightness variation (L in HSL) around 50%, based on trace intensity. | | brushSize | number | 4 | Radius (in simulation pixels) of the mouse influence area. | | brushStrength | number | 1.5 | Strength with which the mouse leaves trails. | | pixelScale | number | 6 | Scaling factor. The simulation runs at windowWidth / pixelScale pixels wide. Decreasing increases resolution but reduces performance. | | edgeThreshold | number | 3 | Distance (in simulation pixels) to edges triggering edgeAvoidance logic. | | reshuffleCount | number | 10 | Number of times agents are initially repositioned for the "mixing" visual effect. | | startDelay | number | 500 | Delay in milliseconds before the main animation loop starts after initialization. |

Important Note on useRandomDefaults: When useRandomDefaults is true (default), values you pass for initialAgents, sensorOffset, agentSpeed, etc., will be ignored. Set useRandomDefaults to false to use your own custom values.

🎨 Advanced Customization

Using Specific Settings

import SlimeSimulation from "react-slime-simulation";

function MyCustomSimulation() {
  const settings = {
    useRandomDefaults: false,
    initialAgents: 450,
    agentSpeed: 1.1,
    evaporationRate: 0.025,
    pixelScale: 7,
    baseHue: 180,
    hueRange: 15,
    trailStrength: 1.8,
  };

  return <SlimeSimulation {...settings} />;
}

Using a Custom SVG

Define your SVG shape as a string. Make sure the SVG has a fill to ensure rasterization works.

import SlimeSimulation from "react-slime-simulation";

function MySVGShapeSimulation() {
  const customSvg = `
    <svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
      <circle cx="50" cy="50" r="45" fill="#555" />
    </svg>
  `;

  const settings = {
    useRandomDefaults: false,
    initialAgents: 600,
    svgShape: customSvg,
    baseHue: 300,
  };

  return <SlimeSimulation {...settings} />;
}

🙌 Contributing

Contributions are welcome! If you have ideas for improvements, bug fixes, or new features:

1. Fork the repository: https://github.com/LightInn/ReactSlimeSimulation.git
2. Create your feature branch (git checkout -b feature/my-awesome-feature)
3. Commit your changes (git commit -am 'Add my awesome feature')
4. Push to the branch (git push origin feature/my-awesome-feature)
5. Open a Pull Request!

Feel free to open an Issue to discuss major changes beforehand.

📜 License

This project is licensed under the MIT License. See the LICENSE file for more details.