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 ActionSets, 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

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.