Getting Started

Getting Started with Atomic Plugin

This guide will help you create your first .atomic file and generate extension methods for the Atomic Framework.

Prerequisites

• JetBrains Rider 2025.1 or later
• Atomic Plugin installed
• Atomic Framework added to your project
• C# project open in Rider

Step 1: Create an Atomic File

Method 1: Using the New File Menu

1. Right-click on your project or folder in the Solution Explorer
2. Select New → Atomic File
3. Enter a name (e.g., PlayerComponents.atomic)
4. Click OK

Method 2: Manual Creation

1. Create a new file with .atomic extension
2. The plugin will automatically recognize it

Step 2: Configure Your Entity API

Here's a minimal example to get started:

namespace: MyGame.Components
className: EntityExtensions
entityType: IEntity

tags:
  - Player

values:
  - Health: int

Required Fields

Field	Description	Example
namespace	C# namespace for generated code	MyGame.Components
className	Name of the generated static class	EntityExtensions
entityType	The base type for your entities	IEntity, GameObject

Step 3: Generate the Code

🆕 Editor Notification Panel (v0.1.5+)

When you open an .atomic file, you'll see a notification panel at the top with helpful actions:

• First-time generation: Shows "Generate API" button
• Existing file: Shows "Regenerate API" button
• Quick actions: "Open Generated File" and "Delete Generated File" buttons
• Status info: Displays auto-generation status

Manual Generation

1. Open your .atomic file
2. Use one of these methods:
   • Click the "Generate API" button in the notification panel
   • Press Ctrl+Shift+G
   • Right-click and select Generate Entity API
3. Check the notification for success/errors

Automatic Generation

• Important: Auto-generation only works after the first manual generation
• If enabled in settings, code regenerates automatically when you save the file
• The notification panel shows when auto-generation is active

Step 4: Use the Generated Code

The plugin generates extension methods you can use immediately:

using MyGame.Components;

public class GameLogic
{
    public void InitializePlayer(Entity entity)
    {
        // Tag methods
        entity.AddPlayerTag();
        
        // Value methods
        entity.SetHealth(100);
        
        if (entity.HasPlayerTag())
        {
            var health = entity.GetHealth();
            // ...
        }
    }
}

Complete Example

Input: Components.atomic

namespace: Game.Components
className: EntityExtensions
entityType: IEntity
directory: Generated
aggressiveInlining: true

imports:
  - System
  - UnityEngine
  - System.Collections.Generic
  - Atomic.Entities

tags:
  - Player
  - Enemy
  - Projectile
  - Pickup

values:
  - Health: int
  - Position: Vector3
  - Velocity: Vector3
  - Damage: float
  - Name: string
  - Inventory: List<Item>

Generated Methods

For each tag, you get:

• bool HasPlayerTag()
• void AddPlayerTag()
• void DelPlayerTag()

For each value, you get:

• int GetHealth()
• void SetHealth(int value)
• void AddHealth()
• bool HasHealth()
• void DelHealth()
• bool TryGetHealth(out int value)

Next Steps

• Learn about Atomic File Syntax
• Explore Advanced Features
• See Generated Code Examples
• Configure Plugin Settings

Tips

1. Use IntelliSense: Type Ctrl+Space in .atomic files for auto-completion
2. Organize by Feature: Create multiple .atomic files for different systems
3. Version Control: Commit .atomic files, exclude generated .cs files
4. Performance: Enable aggressiveInlining for hot paths

Common Patterns

Component Groups

// Physics.atomic
values:
    Position: Vector3
    Rotation: Quaternion
    Velocity: Vector3
    AngularVelocity: Vector3

// Combat.atomic  
values:
    Health: int
    Armor: int
    Damage: int
    AttackSpeed: float

System-Specific APIs

// AISystem.atomic
tags:
    AIControlled
    Patrolling
    Attacking
    
values:
    AIState: AIStateEnum
    Target: Entity
    PatrolPath: Vector3[]

Need Help?

• Check the Troubleshooting Guide
• Read the FAQ
• Report issues on GitHub