71 lines
4.4 KiB
Markdown
71 lines
4.4 KiB
Markdown
# 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).
|
||
|