Known Issues

Known Issues and Limitations

This page documents current known issues, limitations, and workarounds for the Atomic Plugin.

🐛 Current Issues

Critical Issues

Issue #1: First-time Generation Requirement

Description: New .atomic files require manual generation (Ctrl+Shift+G) before auto-generation works.

Status: 🔧 In Progress

Workaround:

1. Always press Ctrl+Shift+G after creating a new .atomic file
2. Auto-generation will work for subsequent changes

Planned Fix: v0.2.0 - Auto-detect new files and generate automatically

---

Issue #2: Namespace Resolution in Complex Projects

Description: Type resolution may fail in projects with duplicate type names across namespaces.

Status: 🔍 Investigating

Workaround:

• Use fully qualified type names:

values:
    Player: MyGame.Entities.Player  # Instead of just Player

Planned Fix: v0.1.5 - Improved namespace resolution algorithm

Moderate Issues

Issue #3: Large File Performance

Description: Performance degradation with .atomic files > 500 lines.

Status: 🔧 In Progress

Impact:

• Syntax highlighting delays
• Slow auto-completion
• Generation takes > 5 seconds

Workaround:

• Split large .atomic files into smaller modules
• Disable auto-generation for large files
• Use manual generation (Ctrl+Shift+G)

---

Issue #4: Rename Refactoring Limitations

Description: Renaming types in C# doesn't update .atomic files automatically.

Status: 📋 Planned

Workaround:

1. Manually update type names in .atomic files
2. Use Find & Replace in .atomic files
3. Regenerate after changes

Planned Fix: v0.2.0 - Full refactoring support

Minor Issues

Issue #5: Comments in Atomic Files

Description: Comments in .atomic files are not preserved during formatting.

Status: 📋 Planned

Current Behavior:

# This comment disappears after formatting
values:
    Health: int  # This comment also disappears

Workaround:

• Document in separate files
• Use meaningful names instead of comments

---

Issue #6: Generic Type Inference

Description: Complex generic types require full specification.

Status: 🚫 Won't Fix (by design)

Example:

# Not supported
values:
    Items: List  # Error - must specify type

# Required
values:
    Items: List<Item>

⚠️ Known Limitations

Language Limitations

1. No Nested Sections

Limitation: Cannot nest configuration sections.

Not Supported:

entities:
    Player:
        values:
            Health: int

Use Instead:

• Create separate .atomic files for each entity type
• Use naming conventions: Player.atomic, Enemy.atomic

2. No Conditional Compilation

Limitation: No support for conditional compilation directives.

Not Supported:

#if UNITY_EDITOR
values:
    DebugInfo: string
#endif

Workaround:

• Use separate .atomic files for different configurations
• Handle conditionals in generated code usage

3. Limited Expression Support

Limitation: Cannot use expressions or calculations in values.

Not Supported:

values:
    MaxHealth: 100 * 5  # Not supported

Use Instead:

• Define constants in C# code
• Set calculated values at runtime

Type System Limitations

1. No Anonymous Types

Limitation: Anonymous types are not supported.

Not Supported:

values:
    Data: var  # Not supported
    Anonymous: new { Name = "Test" }  # Not supported

2. No Dynamic Types

Limitation: dynamic keyword not supported.

Reason: Type safety and performance

Use Instead:

• Use object type with casting
• Define specific types

3. Limited Attribute Support

Limitation: Custom attributes on values not supported.

Desired but Not Supported:

values:
    [Range(0, 100)]
    Health: int  # Attributes not supported

Workaround:

• Implement validation in custom wrapper classes
• Add validation in usage code

IDE Integration Limitations

1. Limited Debugging Support

Limitation: Cannot set breakpoints in .atomic files.

Workaround:

• Debug generated C# code instead
• Use logging in generated methods

2. No IntelliSense for Custom Types

Limitation: Auto-completion doesn't show all custom types.

Status: 🔧 Improvement planned

Workaround:

• Type full type names manually
• Copy from existing code

3. Limited Quick Actions

Limitation: Fewer quick actions compared to C# files.

Available Actions:

• Add import
• Remove unused import
• Generate code

Not Available:

• Extract method
• Inline variable
• Convert to expression

Platform Limitations

1. Unity WebGL Builds

Issue: unsafe code not supported in WebGL builds.

Solution:

# For WebGL projects
unsafe: false  # Must be false

2. .NET Framework Support

Limitation: Requires .NET 6.0 or higher.

Not Supported:

• .NET Framework 4.x
• .NET Core 3.1 or earlier

3. Rider Version Requirements

Minimum Version: 2024.1

Not Supported:

• Rider 2023.x or earlier
• Other JetBrains IDEs

🔄 Migration Issues

From Manual Code

Issue: Existing Extension Methods Conflict

Problem: Manually written extension methods conflict with generated ones.

Solution:

1. Rename manual methods temporarily
2. Generate new methods
3. Migrate usage gradually
4. Remove old methods

From Other Generators

Issue: Different Method Naming

Problem: Other generators use different naming conventions.

Migration Path:

1. Generate with Atomic Plugin
2. Use Find & Replace for method names
3. Update gradually

Example Mapping:

// Other generator
entity.Health_Get() → entity.GetHealth()
entity.Health_Set(100) → entity.SetHealth(100)
entity.Health_Has() → entity.HasHealth()

🔧 Workarounds and Solutions

Performance Workarounds

Large Project Optimization

<!-- Directory.Build.props -->
<Project>
  <PropertyGroup>
    <!-- Exclude generated files from analysis -->
    <NoWarn>$(NoWarn);CS8019;CS0105</NoWarn>
    <GenerateDocumentationFile>false</GenerateDocumentationFile>
  </PropertyGroup>
</Project>

Generation Workarounds

Force Regeneration Script

# PowerShell script to force regenerate all
Get-ChildItem -Path . -Filter *.atomic -Recurse | ForEach-Object {
    # Touch file to trigger generation
    (Get-Item $_.FullName).LastWriteTime = Get-Date
}

Type Resolution Workarounds

Custom Type Mapping

// Create type aliases in a shared file
global using EntityId = System.Int32;
global using PlayerId = System.String;
global using Timestamp = System.Int64;

📅 Upcoming Fixes

Version 0.1.5 (Next Release)

• ✅ Fix namespace resolution issues
• ✅ Improve performance for large files
• ✅ Better error messages
• ✅ Support for more Unity types

Version 0.2.0 (Q2 2025)

• 📋 Auto-generation for new files
• 📋 Full refactoring support
• 📋 Comment preservation
• 📋 Better IntelliSense

Version 0.3.0 (Q3 2025)

• 📋 Multi-file generation
• 📋 Template support
• 📋 Custom code regions
• 📋 Debugging improvements

🐞 Reporting Issues

How to Report

1. Check Existing Issues

   • Visit GitHub Issues
   • Search for similar issues

2. Gather Information

   • Rider version
   • Plugin version
   • OS and version
   • .atomic file content
   • Error messages
   • Steps to reproduce

3. Create Issue

   **Environment:**
   - Rider: 2025.1
   - Plugin: 0.1.4
   - OS: Windows 11
   
   **Description:**
   [Clear description of the issue]
   
   **Steps to Reproduce:**
   1. Create new .atomic file
   2. Add values section
   3. Press Ctrl+Shift+G
   
   **Expected:**
   [What should happen]
   
   **Actual:**
   [What actually happens]
   
   **Workaround:**
   [If you found one]

Log Files Location

Windows:

%APPDATA%\JetBrains\Rider2025.1\logs\

macOS:

~/Library/Logs/JetBrains/Rider2025.1/

Linux:

~/.cache/JetBrains/Rider2025.1/log/

💡 Temporary Solutions

Manual Override Template

// Use when generation fails
public static class ManualExtensions
{
    public static int GetHealth(this IEntity entity)
    {
        return entity.Get<int>("Health");
    }
    
    public static void SetHealth(this IEntity entity, int value)
    {
        entity.Set("Health", value);
    }
}

Batch Processing Script

#!/bin/bash
# Process all .atomic files
find . -name "*.atomic" -exec touch {} \;
echo "All .atomic files marked for regeneration"

📞 Support Channels

• GitHub Issues: Report Bugs
• Discussions: Ask Questions
• Wiki: Documentation

---

Note: This page is updated with each release. Check back for the latest known issues and fixes.