Atomic.CodeGen 2.1.5

Atomic.CodeGen - Entity API Code Generator

Standalone code generator for Atomic Entity Framework. Generates extension methods from C# attribute definitions, works independently of Unity.

Features

• ✅ Unity-independent - Works without Unity running
• ✅ IDE Integration - Rider, Visual Studio, VS Code support with automatic .csproj file management
• ✅ Type-Safe - Roslyn-based C# parsing
• ✅ Cross-Platform - .NET 8+ (Windows, macOS, Linux)
• ✅ Fast - Incremental generation
• ✅ Auto .csproj Integration - Generated files automatically added to project files for IDE recognition

Installation

Atomic.CodeGen is distributed as a .NET tool - a cross-platform command-line tool that works on Windows, macOS, and Linux.

Prerequisites

• .NET 8.0 SDK or later (Download)

Option 1: Global Installation (Recommended)

Install once, use anywhere on your system:

dotnet tool install -g Atomic.CodeGen

Update to latest version:

dotnet tool update -g Atomic.CodeGen

Option 2: Local Installation (Project-Specific)

Install per Unity project for version consistency:

# In your Unity project root
dotnet new tool-manifest  # Only needed once
dotnet tool install --local Atomic.CodeGen

Run with:

dotnet tool run atomic-codegen generate
# or
dotnet atomic-codegen generate

Update:

dotnet tool update --local Atomic.CodeGen

Option 3: Local NuGet Package (Development/Testing)

For development or testing unreleased versions:

# Build the package
cd Tools/Atomic.CodeGen
dotnet pack -c Release

# Install from local package
dotnet tool install --global --add-source ./nupkg Atomic.CodeGen

# Update from local package
dotnet tool update --global --add-source ./nupkg Atomic.CodeGen

Verify Installation

atomic-codegen --version
# Output: 1.4.0

Quick Start

1. Initialize Configuration

cd /path/to/unity/project
atomic-codegen init

This creates atomic-codegen.json with default settings.

2. Create Entity API Definition

// Assets/Game/Scripts/GameplayEntityAPI.cs
using Atomic.Entities;
using UnityEngine;

[EntityAPI(
    Namespace = "Game.Entities",
    ClassName = "GameplayEntityAPI",
    Directory = "Assets/Game/Scripts/Generated",  // Required
    AggressiveInlining = true,
    UnsafeAccess = true
)]
internal class GameplayEntityAPI_Definition
{
    enum Tags
    {
        Player,
        Enemy,
        Damagable,
        Dead
    }

    class Values
    {
        int Health;
        float Speed;
        Transform TargetTransform;
        GameObject Prefab;
    }
}

3. Generate

atomic-codegen generate

This creates Assets/Game/Scripts/Generated/GameplayEntityAPI.cs with:

public static class GameplayEntityAPI
{
    public static readonly int Player;
    public static readonly int Health;
    // ... more fields

    static GameplayEntityAPI()
    {
        Player = NameToId(nameof(Player));
        Health = NameToId(nameof(Health));
        // ... initialization
    }

    // Tag extensions
    public static bool HasPlayerTag(this IEntity entity) => entity.HasTag(Player);
    public static bool AddPlayerTag(this IEntity entity) => entity.AddTag(Player);
    // ...

    // Value extensions
    public static int GetHealth(this IEntity entity) => entity.GetValueUnsafe<int>(Health);
    public static ref int RefHealth(this IEntity entity) => ref entity.GetValueUnsafe<int>(Health);
    public static void SetHealth(this IEntity entity, int value) => entity.SetValue(Health, value);
    // ...
}

Commands

init - Initialize Configuration

atomic-codegen init [--project <path>]

Creates atomic-codegen.json configuration file.

generate - Generate Once

atomic-codegen generate [--project <path>] [--verbose]

Scans and generates all Entity API files.

scan - Dry Run

atomic-codegen scan [--project <path>] [--verbose]

Scans for definitions without generating (useful for validation).

Configuration

atomic-codegen.json example:

{
  "version": "1.0",
  "projectRoot": ".",
  "scanPaths": [
    "Assets/**/*EntityAPI*.cs",
    "Packages/**/*EntityAPI*.cs"
  ],
  "excludePaths": [
    "**/obj/**",
    "**/Library/**",
    "**/Temp/**",
    "**/*.g.cs",
    "**/*.generated.cs"
  ],
  "verbose": false,
  "formatting": {
    "useTabs": false,
    "indentSize": 4,
    "newLine": "\r\n"
  }
}

Configuration Fields:

• scanPaths - Glob patterns for finding EntityAPI definition files
• excludePaths - Patterns to exclude from scanning
• verbose - Enable detailed logging
• formatting - Code style options (tabs/spaces, indent size, line endings)

IDE Integration

Automatic .csproj Integration (v1.4.0+)

Generated files are automatically added to your .csproj files, making them immediately visible in IDEs without Unity running.

How it works:

1. By default, the tool auto-detects all .csproj files that contain your EntityAPI definition source file
2. Generated files are added as <Compile> items to all detected projects
3. IDEs like Rider immediately recognize the files for IntelliSense and navigation
4. If you want to override and target a specific project, use the TargetProject parameter

Auto-detection (Default):

[EntityAPI(
    Namespace = "Game",
    ClassName = "MyAPI",
    Directory = "Assets/Generated"
    // No TargetProject specified - auto-detects all projects containing this file
)]

Manual override:

[EntityAPI(
    Namespace = "Game",
    ClassName = "MyAPI",
    Directory = "Assets/Generated",
    TargetProject = "Assembly-CSharp.csproj"  // Only add to this specific project
)]

Benefits:

• ✅ IntelliSense works immediately
• ✅ Navigate to generated code from Rider
• ✅ No Unity restart required
• ✅ Automatically works with multi-project setups
• ✅ Orphaned files are automatically cleaned up when source is deleted

JetBrains Rider

Method 1: File Watcher (Auto-Generate on Save)

1. Settings → Tools → File Watchers → +
2. Configure:
   • Name: Atomic CodeGen
   • File type: C# files
   • Scope: Project Files
   • Program: dotnet
   • Arguments: tool run atomic-codegen generate --project $ProjectFileDir$
   • Working directory: $ProjectFileDir$
   • Advanced Options:
     • ✅ Auto-save edited files
     • ✅ Trigger on external changes
     • ❌ Trigger immediately (optional)
     • ❌ Create output file from stdout

Method 2: External Tool

1. Settings → Tools → External Tools → +
2. Configure:
   • Name: Generate Entity API
   • Program: dotnet
   • Arguments: tool run atomic-codegen generate
   • Working directory: $ProjectFileDir$
3. Use: Tools → External Tools → Generate Entity API

Visual Studio Code

.vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Atomic: Generate Entity API",
      "type": "shell",
      "command": "dotnet tool run atomic-codegen generate",
      "problemMatcher": [],
      "group": {
        "kind": "build",
        "isDefault": false
      }
    }
  ]
}

Run: Terminal → Run Task → Atomic: Generate Entity API

Visual Studio

Method 1: Pre-Build Event

Project Properties → Build Events → Pre-build event:

dotnet tool run atomic-codegen generate --project $(SolutionDir)

Method 2: MSBuild Integration

Create Directory.Build.targets in project root:

<Project>
  <Target Name="AtomicCodeGen" BeforeTargets="BeforeBuild">
    <Exec Command="dotnet tool run atomic-codegen generate --project $(MSBuildProjectDirectory)" />
  </Target>
</Project>

Attribute Reference

[EntityAPI(
    Namespace = "YourNamespace",       // Required: Generated class namespace
    ClassName = "YourAPI",              // Required: Generated class name
    Directory = "Assets/Scripts/Gen",   // Required: Output directory for generated file
    TargetProject = "MyProject.csproj", // Optional: Specific .csproj to link (auto-detects if not specified)
    EntityType = typeof(IEntity),       // Optional: Entity type (default: typeof(IEntity))
    AggressiveInlining = true,          // Optional: Add [MethodImpl] (default: true)
    UnsafeAccess = true,                // Optional: Enable ref returns (default: true)
    ExcludeImports = new[] {            // Optional: Exclude namespaces from auto-detection
        "SomeNamespace"
    }
)]

Note on Imports:

• Imports are now auto-detected from using directives in your source file
• No need to manually specify Imports parameter (deprecated)
• Use ExcludeImports to prevent specific namespaces from being included
• Auto-excluded: Atomic.Entities, System.Runtime.CompilerServices, UnityEditor

Example:

using UnityEngine;              // ✅ Auto-detected
using System.Collections.Generic; // ✅ Auto-detected
using MyGame.Utils;             // ✅ Auto-detected

[EntityAPI(
    Namespace = "Game",
    ClassName = "MyAPI",
    Directory = "Assets/Gen",  // Required
    ExcludeImports = new[] { "MyGame.Utils" }  // ❌ Excluded from generated file
)]
class MyAPI_Definition { ... }

Tags Enum

enum Tags
{
    Player,      // Generates: HasPlayerTag(), AddPlayerTag(), DelPlayerTag()
    Enemy,
    Collectible
}

Values Class

class Values
{
    int Health;           // Generates: GetHealth(), SetHealth(), HasHealth(), etc.
    float Speed;
    Transform Target;
    GameObject Prefab;
}

Supports:

• Primitives: int, float, bool, string
• Unity types: GameObject, Transform, Vector3, etc.
• Generic types: List<T>, Dictionary<K,V>
• Custom types: Any C# type
• Nullable types: int?, Vector3?

Best Practices

1. Naming Convention

Use suffix _Definition to avoid naming conflicts:

[EntityAPI(ClassName = "GameplayEntityAPI")]
class GameplayEntityAPI_Definition  // Won't conflict with generated class
{
    // ...
}

2. Organize by Domain

Assets/Game/Scripts/
├── Player/
│   └── PlayerEntityAPI.cs
├── Enemy/
│   └── EnemyEntityAPI.cs
└── Generated/
    ├── PlayerEntityAPI.cs     (generated)
    └── EnemyEntityAPI.cs      (generated)

3. Git Ignore Generated Files (Optional)

.gitignore:

# Atomic CodeGen
**/Generated/*EntityAPI.cs

Or commit them for team consistency.

Troubleshooting

"No Entity API definitions found"

• Ensure classes have [EntityAPI] attribute
• Check scanPaths in atomic-codegen.json
• Run atomic-codegen scan --verbose to debug

"Namespace is required" or "Directory is required" Error

Required attribute properties:

[EntityAPI(
    Namespace = "Game.Entities",  // ✅ Required
    ClassName = "GameAPI",         // ✅ Required
    Directory = "Assets/Scripts"   // ✅ Required
)]

Generated File Not Updating in Unity

• Unity auto-imports after a delay
• Force refresh: Right-click in Unity → Refresh
• Or: Assets → Reimport All

Advanced Usage

Multiple APIs in One Project

// PlayerAPI.cs
[EntityAPI(Namespace = "Game", ClassName = "PlayerAPI", Directory = "Assets/Gen")]
class PlayerAPI_Definition { /* ... */ }

// EnemyAPI.cs
[EntityAPI(Namespace = "Game", ClassName = "EnemyAPI", Directory = "Assets/Gen")]
class EnemyAPI_Definition { /* ... */ }

Custom Entity Types

[EntityAPI(
    Namespace = "Game",
    ClassName = "MyCustomAPI",
    Directory = "Assets/Gen",
    EntityType = "IMyCustomEntity"  // Custom interface
)]
class MyCustomAPI_Definition { /* ... */ }

Conditional Compilation

#if GAMEPLAY_MODULE
[EntityAPI(/* ... */)]
class GameplayEntityAPI_Definition { /* ... */ }
#endif

CI/CD Integration

GitHub Actions

- name: Generate Entity APIs
  run: |
    dotnet tool restore
    dotnet tool run atomic-codegen generate

Unity Cloud Build

Pre-build script:

#!/bin/bash
dotnet tool restore
dotnet tool run atomic-codegen generate

License

MIT License - see LICENSE file

Support

• Issues: https://github.com/your-org/atomic/issues
• Docs: https://atomic-framework.dev/codegen