{"id":22472528,"url":"https://github.com/ericbatlle/unityneuralnetwork","last_synced_at":"2025-08-02T10:30:45.796Z","repository":{"id":124125254,"uuid":"230755183","full_name":"EricBatlle/UnityNeuralNetwork","owner":"EricBatlle","description":"🧠🤖Unity Neural Network (Genetic, Unsupervised)","archived":false,"fork":false,"pushed_at":"2020-08-12T16:14:27.000Z","size":8021,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-24T19:41:00.419Z","etag":null,"topics":["csharp","genetic-neural-network","machine-learning","ml-agents","neural-network","unity","unsupervised-learning"],"latest_commit_sha":null,"homepage":"","language":"ShaderLab","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/EricBatlle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-12-29T13:37:57.000Z","updated_at":"2025-03-24T05:03:35.000Z","dependencies_parsed_at":"2024-01-26T19:24:07.515Z","dependency_job_id":null,"html_url":"https://github.com/EricBatlle/UnityNeuralNetwork","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/EricBatlle/UnityNeuralNetwork","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EricBatlle%2FUnityNeuralNetwork","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EricBatlle%2FUnityNeuralNetwork/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EricBatlle%2FUnityNeuralNetwork/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EricBatlle%2FUnityNeuralNetwork/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EricBatlle","download_url":"https://codeload.github.com/EricBatlle/UnityNeuralNetwork/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EricBatlle%2FUnityNeuralNetwork/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268370694,"owners_count":24239778,"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":"2025-08-02T02:00:12.353Z","response_time":74,"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":["csharp","genetic-neural-network","machine-learning","ml-agents","neural-network","unity","unsupervised-learning"],"created_at":"2024-12-06T12:16:02.543Z","updated_at":"2025-08-02T10:30:42.903Z","avatar_url":"https://github.com/EricBatlle.png","language":"ShaderLab","funding_links":["https://www.buymeacoffee.com/ebatlleclavero","https://github.com/sponsors/EricBatlle","https://paypal.me/EricBatlleClavero?locale.x=es_ES"],"categories":[],"sub_categories":[],"readme":"# UnityNeuralNetwork \n*Created by Eric Batlle Clavero*\n\n A simple **Unity project** that implements a **Genetic Unsupervised NeuralNetwork interface** and includes different and updated scenarios of how to implement it. \n\nBuilded with **C#** from scratch, avoiding complex (and black-boxed) frameworks such as Tensorflow, or PyTorch.\n\n## Video-Example 🎬\n\n\u003cp\u003e\n  \u003cimg src=\"SimpleVideo.gif\" alt=\"simple video gif\"/\u003e\n\u003c/p\u003e\n\n## Donations are appreciated! 💸\n*Remember that are many ways to say thank you.*\n\nIf this repository has been helpful remember to star it and consider buying me a coffee! 😀 \n\u003cp\u003e\n\u003ca href=\"https://www.buymeacoffee.com/ebatlleclavero\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/default-blue.png\" alt=\"Buy Me A Coffee\" width=\"144.6\" height=\"34\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nIf you like my general work and contributions consider [sponsoring me on Github](https://github.com/sponsors/EricBatlle). \n\nBut if you just want to donate straightforward, I also have [PayPal.me](https://paypal.me/EricBatlleClavero?locale.x=es_ES).\n\n## Table of Contents \n\n- [⚙️ How to Use](#how-to-use)\n- [🧬 Which kind of NeuralNetwork is this one](#which-kind-of-neuralnetwork-is-this-one-)\n- [🤖 What is an Agent](#what-is-an-agent-)\n- [🏋️‍♂️ How the Manager train the Agents](#how-the-manager-train-the-agents)\n- [📜 UNN Explanations](#unn-explanations-)\n- [🧠 Transferable Brains](#transferable-brains-)\n- [Thanks](#thanks)\n\n## How to Use ⚙️\n\nIf you want to open the project, you need to have **Unity** installed with the **2017 version or higher**.\n\nOnce you have Unity installed, **open the project**, select the example scene that you want and **click Play**.\n\nIf you only want to scratch the code, either inside the unity project or simply dragging the **.cs** classes on your editor, you have to watch on to the classes located on ``Assets/Scripts``. \n\nScripts are divided in **3 folders:**\n\n* ``UNN``, here are the important ones, it includes all the interfaces, classes and editor scripts to use and implement the agents, neural networks, managers, etc. More explained below on - [UNN Explanations](#unn-explanations-).\n\n* ``Utils``, includes a couple of scripts to facilitate some coding tasks like JSON serialization, or new Unity PropertyAttributes.\n\n* ``Examples``, includes scripts used on the example scenes, really useful to see how to implement the scripts from ``UNN``.\n\n## Which kind of NeuralNetwork is this one 🧬\n\nThe neural network used in this project is an **Unsupervised** one, meaning that you do not need to control (or supervise) the agents that are training. \nInstead you program them to work **on their own** to discover new ways to reach the objective.\n\nIt is also a **Genetic** neural network, meaning that the agents will be inflicted by operators which are bio-inspired. In this case they will be polished due to **Mutations** and **Selections**.\n\n## What is an Agent 🤖\n\u003cp\u003e\n  \u003cimg align=\"right\" src=\"Agent3D.PNG\" alt=\"3D Agent picture\"/\u003e\n\u003c/p\u003e\n\n**Agents are the entities generated by the Manager** that will try to achieve the goal stablished by his own (the Manager).\n\nEvery Agent will **have his own NeuralNetwork** that acts as a brain. This NeuralNetwork will be the responsible to generate neural network outputs given some inputs. Those outputs will affect the behaviour of the Agent, for example, deciding the direction of its move.\n\n**Life-cycle** of an Agent:\n\n* **Collect environment information**. Such as the current position of the objective.\n* **Set new inputs**. From the collected information.\n* **Generate Outputs**. Based on the inputs introduced on the network.\n* **Make an Action**. Performs an output-based action, like increase agent speed or position.\n* **Calculate his reward**. Depending on his action, the reward will be bigger or lower. This will be used to score the agent success.\n* 🔄 **Restarts the process**.\n\n## How the Manager trains the Agents 🏋️‍♂️\n\nThe behaviour of the scene will be controlled by a **Manager**, his behaviour will follow these steps:\n\n* **Creates** a population of **agents**.\n* **Scores** them depending on their behaviour.\n* **Selects** after a while **the better half** of the agents based on their score.\n* **Removes** the **worst half** of the population.\n* **Duplicates** the remaining agents (**the first half**).\n* **Mutates** the new **duplicated agents**.\n* 🔄**Restarts the process**.\n\n\n\n\n## UNN Explanations 📜\n\nUNN is the directory that contains the base classes to inherit or implement new functionalities if you want to extend your own scenario.\n\nThe scripts included on the directory, appart from the Editor ones are:\n\n### ``NeuralNetwork.cs``\nThis is the class structured to include the Neural Network topology, with layers, neurons and connections. It also includes the functionalities to Save and Load generated networks.\n\n#### ``NeuralNetworkSerializer.cs`` \nThis class is needed to serialize/deserialize NeuralNetworks cause Unity do not allow the automatically serialization of jagged array or complex structs. It also uses my own JsonManager, one of my [SimpleUnityUtils](https://github.com/ls29322/SimpleUnityUtils), explained and used on the repo.\n\nThe way to correctly **serialize and deserialize** a NeuralNetwork is the following: \n\n```cs\n\n//Serialize\nstring jsonString = JsonManager.SerializeToJson\u003cSerializableNeuralNetwork\u003e(net.Serialized());\n\n//Deserialize\nSerializableNeuralNetwork sNet = JsonManager.DeserializeFromJson\u003cSerializableNeuralNetwork\u003e(jsonString);\n\n```\n\n### ``AgentsManager.cs``\nThis **abstract** class includes the training cycle explained in [How The Manager train the Agents](#how-the-manager-train-the-agents). The only thing to be aware is that even being an abstract class, there are 2 virtual functions that should be override if you want to extend this class:\n\n```cs\n/// \u003csummary\u003e\n/// Create agent Game Object and set his parent.\n/// Also set his neural network and the inputs it will use.\n/// \u003c/summary\u003e\n/// \u003cparam name=\"agentNumber\"\u003ePosition of the agent in the current agents list\u003c/param\u003e\n/// \u003creturns\u003e\u003c/returns\u003e\nprotected virtual Agent CreateAgentGO(int agentNumber)\n\n/// \u003csummary\u003e\n/// Create agent Game Object and set his parent.\n/// Also set his neural network and the inputs it will use.\n/// The neural network is initially setted from an external neural network file.\n/// \u003c/summary\u003e\n/// \u003cparam name=\"agentNumber\"\u003e\u003c/param\u003e\n/// \u003cparam name=\"neuralNetworkToLoad\"\u003e\u003c/param\u003e\n/// \u003creturns\u003e\u003c/returns\u003e\nprotected virtual Agent CreateAgentGO(int agentNumber, TextAsset neuralNetworkToLoad)\n```\n\nThe 3rd overrideable method called **CreateSeparatedAgentGO()** is only needed in the  case that you don't want to use a Manager in your scene to create the agent spawned.\n\nThe Manager class can Start the training when the scene starts if the checkbox **trainOnStart** is marked, or if it is not checked, it has an interactable buttons to start the train, to stop the training cycle, to restart it or to resume.\n\n###  ``Agent.cs``\n\nThis abstract class includes all the agents life-cycle explained in [What is an Agent](#what-is-an-agent-). It includes all the cycle abstract methods required to implement a new agent.\n\n```cs\nprotected abstract void CollectEnvironmentInformation();\nprotected abstract void SetNewInputs();\nprotected abstract void AgentAction();\nprotected abstract float CalculateFitnessGain();\n```\n\n## Transferable Brains 🧠\nAll the agents NeuralNetworks can be serialized and deserialized, that means that you can leave an agent training, and then press the button **Save Neural Network** to store the trained neural network on a JSON file in the ``Assets`` directory.\n\nThis JSONed brain can be later introduced on a new agent, to let him start to learn from the point the other agent left. The way to do that is link the **TextAsset** JSON file into the **LoadedNeuralNetwork** editor variable space and press the button **Load Neural Network**.\n\n\u003cp\u003e\n  \u003cimg src=\"TransferableBrains.PNG\" alt=\"UnityEditor save load neuralnetwrok\"/\u003e\n\u003c/p\u003e\n\n## Thanks \nSome of the work here has been inspired from the project [ml-agents](https://github.com/Unity-Technologies/ml-agents) made it from the Unity people. In fact the appearance of the Simple3D agents is exactly the same as their own.\n\nAlso the bases to code this neural network in C# have been inspired from the Youtube videos created by \n [Dani](https://www.youtube.com/channel/UCIabPXjvT5BVTxRDPCBBOOQ) and [TheOne](https://www.youtube.com/channel/UCWbkocGpP_8R5ZS1VpuusRA).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericbatlle%2Funityneuralnetwork","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fericbatlle%2Funityneuralnetwork","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericbatlle%2Funityneuralnetwork/lists"}