Polonium.Generators/README.md

Polonium.Generators

Project Description
Polonium.Generators is a C# source generator suite specifically built for the Polonium ecosystem. By analyzing attributes like [ProxyNode], [AutoPatch], [RegistryEntity], and [RegistryPassThrough], it generates boilerplate code that ties together key features in Polonium, reducing repetitive tasks and ensuring consistency.

---

Code Generation Highlights

1. [ProxyNode]
   When a class is annotated with [ProxyNode] (and optionally [ProxyProperty] for properties or [ProxyMethod] for methods), Polonium.Generators automatically creates partial classes or methods, simplifying script bridging and property handling. This is primarily used in Polonium’s embedded classes, but it can also be extended.

2. [AutoPatch] & [PatchableProperty]
   If an interface is marked with [AutoPatch] and contains at most one [PatchableProperty] (with a getter and setter), Polonium.Generators will create a corresponding Patch class. This allows you to apply changes ("patches") to classes implementing that interface without direct references, greatly simplifying state synchronization.

3. [RegistryEntity]
   Classes annotated with [RegistryEntity] trigger a code generation step that adds a property for that class in GlobalRegistry, enabling you to easily access and manage instances across your entire project.

4. [RegistryPassThrough]
   Properties marked with [RegistryPassThrough] are automatically bridged so that getting or setting them references the central PoloniumRegistry. While primarily used by Polonium’s own embedded classes, it can be adapted for larger multi-module scenarios.

---

Installation

1. Ensure you’re targeting .NET 6 or higher (or the same version Polonium requires).
2. Install via NuGet:

   dotnet add package Polonium.Generators
   

3. Add <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles> in your .csproj if you want to inspect the generated sources.

---

License

This project is licensed under the MIT License.