# Polonium

**Project Description**  
Polonium is a C# library distilled from numerous personal Godot development experiences. By generalizing common patterns across projects, Polonium aims to streamline game development workflows and reduce repetitive boilerplate code. From agent-based AI to automated texture configuration, it offers a cohesive set of features that integrate smoothly with Godot’s C# environment.

---

## Key Features

1. **Agent-Based AI Framework**  
   Polonium provides an `Agent / Action / World` system that supports building complex AI behaviors in a structured manner. Agents can execute actions defined in `ActionSet`s, and the `World` manages overarching states and knowledge.

2. **Global Registry**  
   Centralizes data such as configs, saves, and references to nodes or scenes. `GlobalRegistry` provides an entry point for everything from your game’s assets to the paused state.

3. **Message Bus & Patch System**
   - **Message Bus**: Enables publish-subscribe communication among different parts of your game. This decouples your components and improves maintainability.
   - **PatchableItem**: Allows sending patches (e.g., `FramePatch`) to `Knowledge` nodes, updating game state without direct references. This pattern is extensible and can be applied to various synchronous or asynchronous data updates.

4. **PoloniumTextureButton** & Automatic Textures
   - **PoloniumTextureButton**: A specialized `TextureButton` that automatically loads **Normal**, **Hover**, **Pressed**, **Disabled**, and **Focused** textures from a predefined directory structure.
   - **AnimatedTexture Builder**: Automatically converts folders ending in `.at_dir` under `Resources` into `AnimatedTexture` resources, speeding up the creation of animated UI elements or sprites.

5. **Asset Management & Resource Pool**
   - **Instance by Class**: You can instantiate scenes purely by type (`GlobalRegistry.Asset<TAsset>.Get()`), bypassing manual path references. Scenes and scripts must align under `Assets` for this to work.
   - **Reusable Pool**: The same system offers an object pool for frequently used scenes, improving performance by reducing repeated instantiation.

6. **Skins & Recoloring**  
   Provides an easy-to-use skin system with dynamic color palettes (roots and maps), plus the ability to `Dye` or glow specific palette entries in real-time.

7. **Attribute-Driven Code Generation**
   - **[AutoRegister]**, **[ProxyNode]**, **[RegistryPassThrough]**: Primarily used in Polonium’s embedded code. They automate tasks like bridging registry properties, generating proxy classes, etc.
   - **[AutoPatch] + [PatchableProperty]**: If an interface is marked with `[AutoPatch]` and contains at most one property marked `[PatchableProperty]` (with getter and setter), Polonium.Generators will automatically create a matching `Patch` class for updating classes that implement this interface.
   - **[RegistryEntity]**: Automatically generates a matching property in `GlobalRegistry` for the annotated class, providing easy, game-wide access.
   - **[SkinInfo]**: When applied to a `Skin` subclass, Polonium can automatically extract a color palette from a PNG file, generating code to handle recoloring logic.

---

## Installation
1. Clone or download this repository.
2. Reference `Polonium.dll` in your Godot C# or other .NET project.
3. Run `dotnet restore` to resolve dependencies.

---

## Quick Start Example
```csharp
public partial class Root : Node
{
    public override void _Ready()
    {
        GlobalRegistry.Prepare();
        GlobalRegistry.Start();
    }
}
```
This initializes Polonium’s registry and automatically registers classes marked with `[AutoRegister]`. Alternatively, inherit from `RootScene` and set it as your main scene in the Godot editor.

---

## Usage Notes
- **Attributes for Polonium-Embedded Code**: `[ProxyNode]` and `[RegistryPassThrough]` are primarily used in Polonium’s own code generation for its embedded templates; end users typically don’t apply these in their own scripts.
- **AutoPatch & PatchableProperty**: The generator can create specialized Patch classes that help automatically update the data in classes implementing `[AutoPatch]` interfaces.
- **RegistryEntity**: Declaring a class with `[RegistryEntity]` ensures a globally accessible property is created in `GlobalRegistry`.

---

## License
This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).