add: README

README.md

@@ -0,0 +1,70 @@
+# 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).
+