{"id":33179789,"url":"https://github.com/DylanCope/Evolving-Protozoa","last_synced_at":"2026-01-10T21:01:34.227Z","repository":{"id":39578911,"uuid":"56945187","full_name":"DylanCope/Evolving-Protozoa","owner":"DylanCope","description":"An interactive environment where protozoa-like entities live, die, and have offspring whose behaviours and morphologies can change.","archived":false,"fork":false,"pushed_at":"2023-06-14T22:52:20.000Z","size":24246,"stargazers_count":238,"open_issues_count":12,"forks_count":25,"subscribers_count":18,"default_branch":"master","last_synced_at":"2024-12-06T21:38:24.881Z","etag":null,"topics":["evolutionary-algorithms","simulation"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DylanCope.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-04-23T23:23:56.000Z","updated_at":"2024-12-02T01:08:09.000Z","dependencies_parsed_at":"2023-02-12T03:01:07.765Z","dependency_job_id":null,"html_url":"https://github.com/DylanCope/Evolving-Protozoa","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/DylanCope/Evolving-Protozoa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DylanCope%2FEvolving-Protozoa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DylanCope%2FEvolving-Protozoa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DylanCope%2FEvolving-Protozoa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DylanCope%2FEvolving-Protozoa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DylanCope","download_url":"https://codeload.github.com/DylanCope/Evolving-Protozoa/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DylanCope%2FEvolving-Protozoa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28258096,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-10T02:00:06.867Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["evolutionary-algorithms","simulation"],"created_at":"2025-11-16T03:00:36.842Z","updated_at":"2026-01-10T21:01:34.220Z","avatar_url":"https://github.com/DylanCope.png","language":"Java","funding_links":[],"categories":["人工智能"],"sub_categories":[],"readme":"# Evolving-Protozoa\r\n\r\nCheck the simulation out on YouTube:\r\n\r\n[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/fEDqdvKO5Y0/0.jpg)](https://www.youtube.com/watch?v=fEDqdvKO5Y0)\r\n\r\nCome discuss the project on [discord](https://discord.com/invite/GY5UJxbBnq)!\r\n\r\n\r\n## Overview\r\n\r\nThe aim of this project is to create an environment where protozoa-like entities can evolve their behaviours\r\nand morphologies in order to survive and reproduce. \r\nThe simulation takes place in a 2D environment with Newtonian physics implemented with Verlet integration. \r\nThe following screenshot shows a zoomed-out view of the entire environment. \r\nIn the screenshot below, can see procedurally generated rocks shown as brown-grey triangles that form rigid \r\nboundaries for cells moving around the tank fluids. The bright green cells are plants that serve as a sources \r\nof energy and mass for protozoa. \r\nThese plants emit chemical pheromones that spread through the environment, \r\nand gradients of which can be detected by the protozoa. \r\nThese pheromones are visualised in the screenshot and can be seen as the glowing green trails dispersed \r\naround and behind plant cells.\r\n\r\n## Running the Simulation\r\n\r\n**Prerequisites:** Make sure you have [Java version 9 or greater](https://www.techspot.com/downloads/6463-java-se.html) installed. \r\nIf you don't know how to install it, then hopefully [this tutorial](https://java.tutorials24x7.com/blog/how-to-install-java-16-on-windows) will help you out!\r\n\r\nStart by downloading the latest version from the [Releases page on GitHub](https://github.com/DylanCope/Evolving-Protozoa/releases).\r\nThe program will be downloaded as a ZIP file, so unzip it and locate the `Evolving-Protozoa.jar` file. You should\r\nalso see a `run.bat`, a `saves` folder, and a `config` folder. If you are on Windows, you can launch the simulation by\r\ndouble-clicking the `run.bat`, otherwise, you can manually run the jar file from the terminal using the command in the `run.bat`. \r\nYou should be met with a launch screen where you can reload a previous save or start a new one. \r\n\r\n**Accessing Simulation Data:** The simulation records a lot of data as it runs, and makes back-ups of the tank at various stages. \r\nIn the save's folder you can find CSV files containing the genomes of each protozoan, and overall statistics from the simulation polled\r\nat different moments in time.\r\n\r\n**Configuring the Simulation:** There are various parameters that can be changed by editing the `config/default_settings.yaml` file before creating a new simulation. For an existing save, you can change the parameters by editing the `settings.yaml` file in the folder corresponding to the save. These changes will not take effect until you close and reload the simulation.  \r\n\r\n**Linux:** The project is developed and tested on Windows, but a user has created a [build of the software on the Arch Linux Repository](https://aur.archlinux.org/packages/evolving-protozoa). _Note:_ This is not maintained by the original developer. It may be out-of-date or untested.\r\n\r\n#### Controls\r\n\r\nOnce you have the simulation running, there are a few controls that you might want to\r\nutilise.\r\n\r\n- F1: Toogle Pause\r\n- F10: Toggle rendering chemical grid - useful for increasing performance\r\n- F11: Toggle anti-aliasing - useful for increasing performance\r\n- F12: Toggle showing the UI\r\n\r\n**Using the REPL.**\r\n\r\nAnother useful feature is the ability to interact with the simulation through the \r\ncommandline REPL. You can access it through the terminal that launched the program,\r\nin IntelliJ this will be in the run tab. The REPL is a simple commandline interface,\r\nyou can start by typing help to see the available commands.\r\n\r\n![png](/screenshots/repl.png)\r\n\r\nThe most useful command is the `toggleui` command, which completely closes the program\r\nwindow and runs the simulation headless at maximum speed. The `settime` and `gettime` commands\r\nwill allow you to control the simulation time, i.e. the amount of time that the simulation is\r\nstepped with each update. For instance, `settime 2` will run the simulation twice as fast.\r\nHowever, this can change the behaviour of the simulation and lead to glitchy physics or cells that\r\ndie fast, so be careful. Ancedotally, people have managed to increase it to x10 or x20, and still\r\nget interesting results.\r\n\r\n## Tips for Increasing Performance\r\n\r\nThe simulation requires a relatively powerful machine to run with acceptable framerates, but there are still\r\nseveral options available to increasing the performance.\r\n\r\n- Toggling anti-aliasing makes a big difference for rendering.\r\n- Toggling rendering the background \"pheromones\"/\"chemicals\" dramatically increases FPS.\r\n- Adjust the settings in the `config/default_settings.yaml` file. The following settings are key for performance:\r\n```\r\nphysics_substeps: 3\r\nspatial_hash_resolution: 100\r\nchemical_field_resolution: 400\r\nchemical_update_interval: 10\r\nmax_interact_range: 0.15\r\nmax_protozoa: 1500\r\nmax_plants: 7000\r\nmax_meat: 1000\r\n```\r\n- The first thing to change is to set the `physics_substeps` to 1. This will reduce physics precision,  \r\n  but running the simulation at x1 speed shouldn't result in many problems (you might even be able to get away with x5).\r\n  It will be up to you to experiment with what level of physics bugginess is acceptable.\r\n- Playing with different settings for the `spatial_hash` resolution. Increasing this will generally make collision detection\r\n  faster.\r\n- Decrease `chemical_field_resolution` or turn off the chemical field all together by setting `enable_chemical_field: false`.\r\n- Reducing the maximum number of different cell types can make it easier, however, to get good results you will likely want to fiddle\r\n  with other simulation parameters to ensure that good balances are maintained throughout the simulation. If the protozoans are constantly\r\n  hitting up against the capacity limit it will limit the *selective pressure* of natural selection. In other words, it will be more up-to\r\n  luck whether a protozoan splitting event results in children that survive. This is because the simulation will immediately kill any\r\n  children if adding them to the simulation would exceed the total number of allowed cells of that type. Thus, if you reduce the maximum number\r\n  of protozoans I would also recommend decreasing the `tank_radius` (along with other world generation parameters to get nice terrain), and/or\r\n  the various growth-rate and death-rate parameters.\r\n- Decreasing the `max_interact_range` will reduce the load on the collision detection, but it comes at the price of protozoans that cannot see as far.\r\n- If you are experiencing lag later in the simulation, it might be because of a large number of \"retina\" calculations, so setting\r\n  `max_retina_size` to a lower number may help.\r\n- On some lower end machines, the simulation can get laggier the longer it is run for. This is often fixed by closing the simulation\r\n  and reloading the save.\r\n- Running the simulation on \"headless mode\" by typing `toggleui` in the REPL allows you to leave the simulation running and then\r\n  you can come back it later to look around at what has emerged. If you pause the simulation (pressing F1) it will increase FPS and\r\n  allow you to look around more easily.\r\n\r\n\r\n## Features\r\n\r\nThe primary objective of this project is to investigate the emergence of multicellular structures, \r\ni.e. the development of coordinated groups of attached cells that incur a survival benefit by being attached. \r\nSo far, by implementing cell-adhesion and allowing protozoa to share resources I have seen the \r\nemergence of some quite cool multi-cell behaviour. However, the next step is to achieve cell differentiation \r\nvia the evolution of gene-regulatory networks.\r\n\r\n![png](/screenshots/tank_full_view.png)\r\n\r\nIn the next screenshot we see a close-up of tracking a protozoa in the environment. \r\nThe tracked cell is fixed at the centre of the screen as it moves around, and the neural network that controls \r\nits actions is illustrated on the right-hand side of the screen. \r\nThis network evolved using a variation of the NEAT algorithm.\r\nThe protozoa have a variety of other evolvable traits, including (but not limited to) their size, growth rate, colour,\r\nspeed, herbivore factor, and the growth of offensive spikes for harming and killing other protozoa.  \r\n\r\n![png](/screenshots/tank.png)\r\n\r\nZooming in more on a protozoan, we can see one of their key evolvable traits: vision by light-sensitive \"retinas\". \r\nThese retinas can have variable fields-of-view and acuity, mediated by a ray-casting procedure that feeds into their \r\ncontrol circuits. However, developing such capabilities' comes with a cost. Retinas require a complex molecule call \r\n_retinal_ that is sensitive to light, which itself requires mass and energy to produce from raw material extracted\r\nfrom feeding on plants. The introduction a prerequisite material for developing such a useful trait that has a cost\r\nto produce opens up the interesting possibility for predation as an alternative strategy for meeting the requirement.\r\n\r\n![png](/screenshots/retina_example.png)\r\n\r\nThis final screenshot shots an example of the kinds of multi-cell structures that can evolve in this simulator.\r\nThis is facilitated as the cells have the ability to evolve _Cell-adhesion molecules (CAMs)_ \r\nthat allow them to bind to other cells and transmit mass, energy, signals, and complex molecules.\r\n\r\n![png](/screenshots/evolved_multicells2.png)\r\n\r\n## Next Steps\r\n\r\n* Evolvable gene regulation to promote cell differentiation.\r\n* Temporal control of gene expression ([regulation of transcription](https://en.wikipedia.org/wiki/Transcriptional_regulation)).\r\n* Environmental and internal temperature to add ecological variety and new cell interaction dynamics.\r\n* Signal relaying channels for cells bound together.\r\n* Improved visualisations of protozoa genes.\r\n* Lineage tracking UI tools.\r\n\r\n\r\n## Developer Set-up\r\n\r\nThe simulation is written in Java and uses the built-in Java Swing library for the UI. \r\nI developed this project using the [IntelliJ IDEA](https://www.jetbrains.com/idea/) IDE,\r\nso I recommend doing the same. To get set-up, first clone the repository,\r\nopen the project in IntelliJ, and run the `protoevo.core.Application` class build adding an \r\n\"Application\" build configuration. Be sure to include `-Xmx16G -Dsun.java2d.opengl=true`\r\nas program arguments.\r\n\r\n![png](/screenshots/build_config.png)\r\n\r\nThe dependencies should be handled by Maven. You can check that they are properly configured\r\nby looking at the Modules tab in Project Structure window in IntelliJ.\r\n\r\n![png](/screenshots/project_structure.png)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDylanCope%2FEvolving-Protozoa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDylanCope%2FEvolving-Protozoa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDylanCope%2FEvolving-Protozoa/lists"}