⚛️ What is Atomic?

Atomic is an architectural framework for game development in Unity and C#, built around the idea of constructing game systems from atomic elements — modular units represented as constants, variables, events, actions, and functions.

The framework reduces coupling and simplifies dependency management by separating data and logic. This allows developers to focus on implementing gameplay mechanics instead of maintaining architecture.

---

📑 Table of Contents

• Requirements
• Installation
• Unity Quick Start
  • Code Generation Setup
  • Creating a Character
  • Adding Keyboard Input
• Tutorials
• API Reference
• Sample Projects
  • Beginner Sample
  • Top-Down Shooter Sample
  • RTS Sample
• Best Practices
• Performance
• Useful Links
• License
• Contact

---

📝 Requirements

The Atomic Framework requires Unity 6+ or .NET 7+.
Make sure your development environment meets these requirements before using the framework.

Recommended Tools

Although not required, the following tools significantly improve the development experience with Atomic:

• Odin Inspector

For better debugging, configuration, and visualization of your game state in the Unity Editor.
Atomic works perfectly without Odin, but using it makes data inspection and live tweaking much easier.

• Atomic Rider Plugin

For enhanced code generation and workflow integration with Rider IDE. While Unity itself provides basic support, the Atomic Rider Plugin makes development smoother and more powerful. Available on JetBrains or GitHub.

• Rider IDE

It is strongly recommended to use Rider 2025 instead of Visual Studio, since Visual Studio does not support the Atomic Plugin. For code generation directly through Unity, refer to the separate article in the documentation.

---

📦 Installation

• Option #1. Download source code with game examples
• Option #2. Download Atomic.unitypackage or AtomicNonUnity.zip from release notes
• Option #3: Install via Unity Package Manager using the Git URL: https://github.com/StarKRE22/Atomic.git?path=Assets/Plugins/Atomic

---

🚀 Unity Quick Start

This section provides a hands-on introduction to using the Atomic Framework inside Unity. You’ll learn how to set up code generation, create your first entity, and implement a simple movement mechanic — all directly from Rider IDE using the Atomic plugin.

I. Code Generation Setup

Before you start creating gameplay mechanics, you need to configure the data generation process. The Atomic Framework supports automatic generation of extension methods for entities, which helps eliminate hard-coded values and “magic constants”, while ensuring type safety when working with data.

Step 1. Setup Atomic Plugin

In Rider IDE, go to Preferences → Plugins → Marketplace and search for Atomic or install directly via reference

Step 2. Create a Configuration File

1. Right-click on the desired scripts directory in Rider.
2. Select New → Atomic File from the context menu.

Once clicked, a configuration window will open. Fill it out and click Create.

This creates an .atomic configuration file for Entity API generation:

namespace: SampleGame
className: EntityAPI
directory: Assets/Scripts/
aggressiveInlining: true
unsafe: false
entityType: IEntity

imports:

tags:
# Add your tags here
# - Player
# - Enemy

values:
# Add your values here
# - health: float
# - position: Vector3

Tip

You can create multiple .atomic files to make your project easier to maintain and extend.

Step 3. Configure your entity API by editing parameters as needed.

Option	Description	Default
directory	Output path for the generated file	–
className	Name of the generated class and file	–
namespace	Namespace of the generated class	–
entityType	Entity type (can be IEntity or a custom type inheriting from it)	IEntity
aggressiveInlining	Adds [MethodImpl(MethodImplOptions.AggressiveInlining)] to extension methods (true/false)	false
unsafe	Uses GetValueUnsafe instead of GetValue (faster but uses unsafe cast)	false
imports	List of namespaces (using) required for code generation	–
tags	List of tags to generate	–
values	List of values to generate, in the format Name: Type	–

Step 4. Generate extension methods

Press Ctrl + Shift + G while in the .atomic file

• Required for first-time generation
• Can be used anytime to force regeneration

The plugin automatically updates existing C# files when saving .atomic changes

• Only works for existing files
• Can be enabled / disabled in plugin settings

Important

To generate the file, you need to add at least one property in the values section or a tag in the tags section. Without adding a property, the code generator will not produce any output!

II. Creating a Character

In this section, we’ll walk through the complete process of creating a character entity in Unity using Rider IDE and the Atomic plugin. Step by step, we’ll set up an entity, generate its data through the Atomic configuration file, and implement a simple movement mechanic.

By the end of this section, you’ll have a working character that moves in the specified direction demonstrating how Atomic’s code generation and entity-based architecture streamline gameplay logic creation.

Step 1. Creating a game object

In the Scene Hierarchy, right-click and choose 3D Object → Capsule to create a new game object.

Step 2. Adding the Entity Component

In the Inspector window of the created object, go to Atomic → Entities → Entity to add the Entity component.

Make sure the following checkboxes are enabled:

• useUnityLifecycle — the entity updates along with the MonoBehaviour lifecycle.
• installOnAwake — the entity is constructed during the Awake phase.

Step 3. Generate Data

Add the following properties to the configuration file EntityAPI.atomic:

• Transform : Transform
• MoveDirection: IVariable<Vector3>
• MoveSpeed: IValue

namespace: SampleGame
className: EntityAPI
directory: Assets/Scripts/
aggressiveInlining: true
unsafe: false
entityType: IEntity

imports:
  - Atomic.Entities
  - Atomic.Elements

tags:

# Add properties
values:
  Transform: Transform
  MoveSpeed: IValue<float>
  MoveDirection: IVariable<Vector3>

Step 4. Creating the Movement Mechanic

Let’s write a behaviour that will move our entity in the direction of its movement:

// Controller that moves entity by its direction
public sealed class MoveBehaviour : IEntityInit, IEntityFixedTick
{
    private Transform _transform;
    private IValue<float> _moveSpeed;
    private IVariable<Vector3> _moveDirection;

    // Called when Start() is invoked
    public void Init(IEntity entity)
    {
        _transform = entity.GetTransform();
        _moveSpeed = entity.GetMoveSpeed();
        _moveDirection = entity.GetMoveDirection();
    }

    // Called when FixedUpdate() is invoked
    public void FixedTick(IEntity entity, float deltaTime)
    {
        Vector3 direction = _moveDirection.Value;
        if (direction != Vector3.zero) 
            _transform.position += _moveSpeed.Value * deltaTime * direction;
    }
}

Important

It’s important to note that in the Atomic approach, the developer always works with data abstractions represented as reference-type wrappers.

This design greatly simplifies project maintenance, testing, and multiplayer development, as it removes the tight coupling to data storage methods that is typical for component-based ECS architectures.

A simple example: Under the IValue<T> interface, you can substitute either a Variable<T> or a Const<T> implementation.

Step 5. Creating the Installer

To add the data and movement logic to the entity, let’s create a script that will inject the corresponding atomic elements and behaviour into it.

// Populates entity with tags, values and behaviours
public sealed class CharacterInstaller : SceneEntityInstaller
{
   [SerializeField] private Transform _transform;
   [SerializeField] private Const<float> _moveSpeed = 5.0f;
   [SerializeField] private Variable<Vector3> _moveDirection = Vector3.forward;

   public override void Install(IEntity entity)
   {
       // Add properties to a character
       entity.AddTransform(_transform);
       entity.AddMoveSpeed(_moveSpeed);
       entity.AddMoveDirection(_moveDirection);
       
       // Add behaviours to a character
       entity.AddBehaviour<MoveBehaviour>();
   }
}

Step 6. Configuring the Game Object

Next, add the CharacterInstaller component to your entity through the Inspector and configure its settings.

Step 7. Connecting the Installer to the Entity

To link the CharacterInstaller to the Entity component, drag and drop it into the Scene Installers field.

Step 8. Running the Character

In the Unity Editor, press Play to verify that the character starts moving forward.

III. Adding Keyboard Input

Next, we’ll look at how to implement movement control using the WASD or arrow keys and show how to modify entity structure through code.

Step 1. Create an Input Controller

public class InputBehaviour : IEntityInit, IEntityTick
{
    private const string HORIZONTAL = "Horizontal";
    private const string VERTICAL = "Vertical";
    
    private ISetter<Vector3> _moveDirection;
    
    public void Init(IEntity entity)
    {
        _moveDirection = entity.GetMoveDirection();
    }

    public void Tick(IEntity entity, float deltaTime)
    {
        float dx = Input.GetAxis(HORIZONTAL);
        float dz = Input.GetAxis(VERTICAL);
        _moveDirection.Value = new Vector3(dx, 0, dz);
    }
}

Important

Here, it’s important to note that to change the entity’s data, we simply modify the value through its reference. No SetMoveDirection to the IEntity is required.

Step 2. Add the InputBehaviour

Next, let’s register the InputBehaviour inside the CharacterInstaller:

public sealed class CharacterInstaller : SceneEntityInstaller
{
    [SerializeField] private Transform _transform;
    [SerializeField] private Const<float> _moveSpeed = 5.0f;
    [SerializeField] private Variable<Vector3> _moveDirection = Vector3.zero;

    public override void Install(IEntity entity)
    {
        // Add properties to a character
        entity.AddTransform(_transform);
        entity.AddMoveSpeed(_moveSpeed);
        entity.AddMoveDirection(_moveDirection);
        
        // Add behaviours to a character
        entity.AddBehaviour<MoveBehaviour>();
        entity.AddBehaviour<InputBehaviour>(); // (+)
    }
}

Step 3. Running the Character

In the Unity Editor, press Play to verify that the character moves when pressing the WASD or arrow keys.

---

📖 Tutorials

Get hands-on with the Atomic Framework through practical guides and examples. Each tutorial introduces a specific concept — from the fundamental Atomic approach to advanced topics such as entity interaction and simulation without Unity.

1. What is Atomic Approach
2. Entity API Generation
3. Creating the Entity in Unity
4. Architectural Consistency
5. Interaction Between Entities
6. Minimizing Unity
7. Summary

---

🔍 API Reference

Explore the full Atomic API documentation. The framework is divided into two main modules — Elements and Entities, each responsible for a different level of abstraction.

⚛️ Atomic.Elements

Low-level, composable building blocks — the atomic “elements” that power everything in the framework. Use them to define data, state, logic, and interaction between systems.

• Values — immutable constants and parameters
• Variables — reactive mutable data containers
• Actions — callable commands and procedures
• Functions — encapsulated logic returning results
• Setters — controlled state mutation interfaces
• Requests — deferred actions that can be executed at a later time
• Events — reactive broadcast-based communication
• Time — frame-based and delta-time utilities
• Collections — reactive collections such as arrays, lists, dictionaries, and sets.
• Utilities —utility classes and components

🧬 Atomic.Entities

The high-level architecture layer that combines atomic elements into functional entities. All game objects, systems, UI elements, and application contexts can be represented as entities, each containing state and behaviour.

• Entities — base unit of game logic
• Behaviours — reusable logic modules
• Installers — dependency injection and setup scripts
• Aspects — applies or discards tags, values, and behaviours on an entity
• Factories — entity creation and configuration
• Baking — converting Unity GameObjects into entity
• Pooling — entity reuse and performance optimization
• Collections — high performance set for entities
• Worlds — high performance entity collection with automatic lifecycle
• Registry — central access and lookup
• Filters — runtime querying and filtering
• Triggers — reactive filtering events
• Lifecycle — initialization and update stages
• Views — UI integration and visualization
• Names — converting string-based names into unique integer identifiers
• API Generation — automatic code generation via Atomic plugin and Unity Editor

---

🗂 Sample Projects

This section presents three sample projects, each demonstrating a different level of complexity and use case of the framework. All examples are available inside Assets/Examples.

• Beginner Sample — a simple 2-player mini-game showcasing the core principles of the framework.
• Top-Down Shooter Sample — a more advanced, modular game architecture suitable for mid-sized projects.
• RTS Sample — a large-scale simulation demonstrating high-performance entity management with thousands of units.

---

1️⃣ Beginner Sample

A simple 2-player mini-game designed to introduce the fundamental ideas behind the Atomic framework. Link to the sample.

This sample represents the most basic foundation of the Atomic framework with Unity. It demonstrates how to build gameplay using a universal SceneEntity, showing three minimal entities:

• GameContext
• Character
• Coin

Everything here is intentionally kept as simple and transparent as possible, focusing on the core idea of the atomic approach — how logic can emerge from the composition of small, modular elements.

The project uses code generation in Unity and serves as a minimal example for rapid prototyping within the Atomic ecosystem.

🕹 Gameplay Overview

• Players: Two players share a single arena.
• Goal: Collect more coins than your opponent within a limited time.
• Controls:
  • Player (Blue): Arrow keys
  • Player (Red): W, A, S, D

💡 This Sample Demonstrates

1. Creating and configuring Entity objects in Unity.
2. Structuring a project using the Entity–State–Behaviour pattern.
3. Using atomic elements to drive logic and interaction.
4. Applying code generation for fast and clean iteration.

---

2️⃣ Top-Down Shooter Sample

The Top-Down Shooter demonstrates a more sophisticated and scalable game architecture, suitable for mid-size projects. Link to the sample.

🕹 Gameplay Overview

• Players: Two players in a shared arena.
• Objective: Eliminate your opponent more times than they eliminate you, within a time limit.
• Controls:
  • Player (Blue): Arrow keys to move, Space to shoot
  • Player (Red): W, A, S, D to move, Q to shoot
• Mechanics:
  • Movement: Kinematic character movement with Rigidbody.SweepTest collision handling.
  • Combat: Independent weapon entities firing physical projectiles.
  • Projectile: Kinematic object with trigger collisions and limited lifetime.
  • Respawn: Units reappear at random points after death.
  • Time Limit: The match ends when the timer expires.
• Visualization:
  • Animated characters with sound and VFX.
  • UI displays kills and time remaining.

🧩 Application Structure

• Scenes:
  • Bootstrap — initializes and loads the game.
  • Menu — the main navigation scene.
  • Levels: three stages featuring player and enemy spawning.
• Save System: Remembers the last completed level.
• Loading Tree: Hierarchical scene-loading sequence for structured bootstrapping.

💡 This Sample Demonstrates

1. Designing a complete, scalable game architecture.
2. Implementing an application context using the Entity–State–Behaviour pattern.
3. Building procedural menu systems.
4. Managing complex loading flows with a Loading Tree.
5. Saving and restoring persistent game data.
6. Turning entities into fully featured game objects with animation, VFX, and audio.
7. Managing projectile pools efficiently.
8. Structuring a modular project file system.

---

3️⃣ RTS Sample

The RTS Sample showcases high-performance entity management — running thousands of active units in real time with minimal overhead. Link to the sample.

🕹 Gameplay Overview

• Armies: Two large armies automatically engage in battle — each consisting of infantry, tanks, and buildings.
• Buildings: Have health points and serve as static defense or production units.
• Infantry: Possesses health, performs melee attacks, and seeks the nearest enemy.
• Tanks: Fire projectiles and detect enemies within range.
• Projectiles: Travel toward targets with limited lifetime and cause impact damage.
• CameraControls:
  • Movement: WASD
  • Zoom: Mouse Scroll

🧩 Scenes

• 5000 Units Scene — 5,000 visualized GameObjects for real-time simulation.
• 10000 Units Scene — 10,000 entities simulated without visualization for performance benchmarking.
• Entity Baking Scene — demonstrates converting Unity scene objects into pure C# entities for simulation.

💡 This Sample Demonstrates

1. Running complete game logic in pure C#, using Unity solely for visualization.
2. Employing EntityWorld, EntityFactory, EntityPool, EntityFilter, and EntityTriggers.
3. Using EntityView, EntityViewPool, and EntityCollectionView for rendering and synchronization.
4. Managing 5,000–10,000 active objects efficiently on a single thread.
5. Baking Unity objects into a pure data-driven simulation architecture.

---

📌 Best Practices

This section outlines recommended approaches and patterns when working with the library. Following these practices will help you write modular, testable, and high-performance code, whether you’re developing single-player or multiplayer games.

• Architecture
  • File System Organization
  • Prefer Atomic Interfaces to Concrete Classes
  • Flyweight Pattern for Constants
  • Request-Condition-Action-Event (RCAE) Flow
  • Modular EntityInstallers
  • Upgrading EntityFactory to the Builder
  • Combine EntityPool with EntityFactory
  • Building Entity System with Model & View Separation
  • Overriding EntityFactories with EntityBakers
• Optimization
  • Iterating over Reactive Collections
  • Iterating over Entity Tags, Values and Behaviours
  • Iterating over EntityCollections, Worlds and Filters.
• Features
  • InlineActions with Entities
  • InlineFunctions with Entities
  • Events with Entities
  • Requests with Entities
  • Requests vs Actions
  • Cooldown with Entities
  • Timer vs Cooldown
  • Expressions with Entities
  • Setters with Entities
  • Uninstall Method for EntityInstallers
  • DisposeComposite in EntityInstallers
  • PlayMode & EditMode for EntityInstallers
  • Optional with EntityInstallers
• Extensions
  • Observe Extension Method
  • Constants with AndExpressions
  • [SerializeReference] for CompositeActions
  • [SerializeReference] for LogAction

---

🔥 Performance

This section focuses on runtime efficiency within the framework. It provides detailed benchmarks, comparisons, and implementation notes that highlight how different systems and data structures perform under real-world conditions.

• Atomic.Entities
  • Entity
  • EntityCollection
• Atomic.Elements
  • ReactiveArray
  • ReactiveList
  • ReactiveLinkedList
  • ReactiveDictionary
  • ReactiveHashSet

---

🔗 Useful Links

• Стрим: Введение в фреймворк Atomic
• Хабр: Atomic — свежий взгляд на разработку игр Unity и C#
• Medium: Atomic — a fresh architecture on game development with Unity and C#

---

⚖️ License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2025 Igor Gulkin

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

📧 Contact

Author: Igor Gulkin
Telegram: t.me/starkre22
Email: [email protected]

---

Back to top • Report Issue • Join Discussion