From f7d1c5a66bedc6453f5dfb9fb5d39fbafd2d4e0c Mon Sep 17 00:00:00 2001 From: hzhang Date: Fri, 7 Mar 2025 16:31:40 +0000 Subject: [PATCH] add: README --- Polonium.csproj | 1 + README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 README.md diff --git a/Polonium.csproj b/Polonium.csproj index fcaf97d..7b5a612 100644 --- a/Polonium.csproj +++ b/Polonium.csproj @@ -37,6 +37,7 @@ + diff --git a/README.md b/README.md new file mode 100644 index 0000000..4d39eea --- /dev/null +++ b/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.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). +