Atomic File Syntax

Atomic File Syntax Reference

Complete syntax reference for .atomic configuration files using YAML-style format.

File Structure

An atomic file consists of:

1. Configuration properties (required & optional)
2. Imports section (optional) - list format
3. Tags section (optional) - list format
4. Values section (optional) - list format with type mappings

# Configuration Properties
namespace: Game.Components
className: EntityExtensions
entityType: IEntity

# Optional Properties
directory: Generated
aggressiveInlining: true
unsafe: false

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

tags:
  - Player
  - Enemy
  - Dead

values:
  - Health: int
  - Position: Vector3
  - Inventory: List<Item>

Configuration Properties

Required Properties

Property	Type	Description	Example
namespace	string	Target C# namespace	Game.Components
className	string	Generated class name	EntityExtensions
entityType	string	Base entity type	IEntity, GameObject

Optional Properties

Property	Type	Default	Description	Example
directory	string	same as source	Output directory	Generated, Assets/Scripts
solution	string	current	Target solution	MyGame.sln
aggressiveInlining	bool	false	Enable aggressive inlining	true, false
unsafe	bool	false	Enable unsafe code	true, false

Note: The header property was removed in v0.1.4. Generated files now include a standard header automatically.

Property Syntax

# String values - quotes optional for single words
namespace: MyGame.Components
namespace: "MyGame.Components"
namespace: 'Complex Name With Spaces'

# Boolean values
aggressiveInlining: true
unsafe: false

# Paths - relative or absolute
directory: Generated
directory: "Assets/Scripts/Generated"
directory: "../Shared/Generated"

Imports Section

Defines C# namespaces to import in the generated file.

Syntax

imports:
  - System
  - System.Collections.Generic
  - UnityEngine
  - MyGame.Core
  - Atomic.Entities  # Always included by default

Rules

• List format with - prefix
• One namespace per line
• Proper indentation required (2 spaces recommended)
• No semicolons or import keywords needed
• Atomic.Entities is always included automatically
• using static Atomic.Entities.EntityNames is always added

Tags Section

Defines boolean flags for entities.

Syntax

tags:
  - Player
  - Enemy
  - Projectile
  - Dead
  - Invincible

Rules

• List format with - prefix
• One tag per line
• PascalCase recommended
• No spaces in tag names
• Generates methods: Has{Tag}Tag(), Add{Tag}Tag(), Del{Tag}Tag()

Generated Code for Tags

public static readonly int Player;

static ClassName()
{
    Player = NameToId(nameof(Player));
}

public static bool HasPlayerTag(this IEntity entity) => entity.HasTag(Player);
public static bool AddPlayerTag(this IEntity entity) => entity.AddTag(Player);
public static bool DelPlayerTag(this IEntity entity) => entity.DelTag(Player);

Values Section

Defines typed properties for entities.

Syntax

values:
  - Health: int
  - MaxHealth: int
  - Position: Vector3
  - Velocity: Vector3
  - Name: string
  - Items: List<Item>
  - Attributes: Dictionary<string, float>

Rules

• List format with - prefix
• Format: - PropertyName: Type
• PascalCase for property names
• Any C# type can be used
• Generic types supported

Type Examples

values:
  # Primitive types
  - Count: int
  - Price: float
  - IsActive: bool
  - Name: string
  
  # Unity types
  - Position: Vector3
  - Rotation: Quaternion
  - Transform: Transform
  - Sprite: Sprite
  
  # Collections
  - Items: List<Item>
  - Waypoints: Vector3[]
  - Stats: Dictionary<string, int>
  - UniqueIds: HashSet<Guid>
  
  # Custom types
  - Player: PlayerData
  - Config: GameConfiguration

Generated Code for Values

public static readonly int Health; // int

static ClassName()
{
    Health = NameToId(nameof(Health));
}

public static int GetHealth(this IEntity entity) => entity.GetValue<int>(Health);
public static void SetHealth(this IEntity entity, int value) => entity.SetValue(Health, value);
public static bool HasHealth(this IEntity entity) => entity.HasValue(Health);
public static void AddHealth(this IEntity entity, int value) => entity.AddValue(Health, value);
public static bool DelHealth(this IEntity entity) => entity.DelValue(Health);
public static bool TryGetHealth(this IEntity entity, out int value) => entity.TryGetValue(Health, out value);
// If unsafe: true
public static ref int RefHealth(this IEntity entity) => ref entity.GetRef<int>(Health);

Complete Examples

Minimal Example

namespace: Game
className: BasicExtensions
entityType: IEntity

tags:
  - Active

values:
  - Health: int

Advanced Example

namespace: Game.Components
className: EntityComponents
entityType: IEntity
directory: "Generated/Components"
aggressiveInlining: true
unsafe: true

imports:
  - System
  - System.Collections.Generic
  - UnityEngine
  - Game.Core
  - Game.Items

tags:
  # Flags
  - Player
  - Enemy
  - Dead
  - Invincible
  
  # States
  - Moving
  - Attacking
  - Defending

values:
  # Basic stats
  - Health: int
  - MaxHealth: int
  - Mana: float
  - MaxMana: float
  
  # Movement
  - Position: Vector3
  - Velocity: Vector3
  - Speed: float
  
  # Combat
  - Damage: float
  - Defense: float
  - CritChance: float
  
  # Inventory
  - Items: List<Item>
  - Equipment: Dictionary<SlotType, Item>
  
  # References
  - Transform: Transform
  - Animator: Animator

Comments

Comments are supported using #:

# This is a comment
namespace: Game  # Inline comment

# Section comments
tags:
  - Player  # Player tag
  - Enemy   # Enemy tag

values:
  # Health system
  - Health: int
  - MaxHealth: int
  
  # Movement system
  - Position: Vector3
  - Velocity: Vector3

Validation Rules

The plugin validates:

Required Fields

• namespace must be present
• className must be present
• entityType must be present

Naming Rules

• Tag/value names must be valid C# identifiers
• No duplicate tag names
• No duplicate value names
• Tags and values cannot share names

Type Validation

• Value types must be valid C# types
• Types must be resolvable from imports
• Generic types must have type arguments

Example Validation Errors

# ERROR: Missing required field
className: Test
# Missing namespace and entityType

# ERROR: Duplicate names
tags:
  - Player
  - Player  # Duplicate!

# ERROR: Invalid type
values:
  - Health: NotAType  # Type not found

# ERROR: Invalid identifier
tags:
  - 123Invalid  # Cannot start with number
  - Has-Dash    # Invalid character

Best Practices

1. Organization

   • Group related tags and values with comments
   • Use consistent naming conventions
   • Keep files focused on one system

2. Performance

   • Enable aggressiveInlining for hot paths
   • Use unsafe only when profiling shows benefit
   • Keep imports minimal

3. Naming

   • Use PascalCase for tags and values
   • Use descriptive names
   • Avoid abbreviations

4. Types

   • Prefer simple types when possible
   • Use Unity types for Unity projects
   • Document complex types with comments

Migration from Old Format

Old Format (pre-v0.1.6)

entityType: Entity
namespace: Game
className: Extensions

tags:
    Player
    Enemy

values:
    Health: int
    Position: Vector3

New Format (v0.1.6+)

namespace: Game
className: Extensions
entityType: IEntity

tags:
  - Player
  - Enemy

values:
  - Health: int
  - Position: Vector3

Key Changes

• Properties can be in any order
• imports, tags, and values use list format with -
• entityType typically uses IEntity interface
• Consistent YAML-style formatting

---

Note: The syntax follows YAML conventions for better readability and consistency.