diff --git a/src/Agents/ActionSet.cs b/src/Agents/ActionSet.cs index 7fb5f2e..b945d33 100644 --- a/src/Agents/ActionSet.cs +++ b/src/Agents/ActionSet.cs @@ -3,10 +3,21 @@ using Polonium.Resources; namespace Polonium.Agents; +/// +/// Abstract base class for managing a collection of agent actions. +/// Provides functionality to store and learn action templates. +/// public abstract partial class ActionSet : Node { - + /// + /// Gets or sets the collection of action templates available to this action set. + /// public HashSet Templates { get; set; } = new(); + + /// + /// Learns a new action template by adding it to the templates collection. + /// + /// The action template to learn. public virtual void Learn(AgentAction.Template template) => Templates.Add(template); } diff --git a/src/Agents/Agent.cs b/src/Agents/Agent.cs index 43ed975..ea5cff6 100644 --- a/src/Agents/Agent.cs +++ b/src/Agents/Agent.cs @@ -3,17 +3,34 @@ using Polonium.Resources; namespace Polonium.Agents; - +/// +/// Abstract base class for all agents in the AI system. +/// Provides knowledge management and action execution capabilities. +/// public abstract partial class Agent : Node { + /// + /// Gets or sets the knowledge component that manages the agent's information state. + /// public Knowledge Knowledge { get; set; } + + /// + /// Gets or sets the action set that defines the available actions for this agent. + /// public ActionSet ActionSet { get; set; } + /// + /// Virtual method called during agent initialization. Override to provide custom initialization logic. + /// public virtual void __Ready() { } + /// + /// Initializes the agent by setting up knowledge and action set components. + /// This method is sealed to ensure consistent initialization behavior. + /// public sealed override void _Ready() { Knowledge = GetNode("Knowledge"); @@ -22,6 +39,11 @@ public abstract partial class Agent : Node base._Ready(); } + /// + /// Executes a specific action with the given parameters. + /// + /// The type of action to execute. + /// The parameters for the action. public void Act(AgentAction.Parameter parameter) where TAction : AgentAction { @@ -33,6 +55,4 @@ public abstract partial class Agent : Node act.SetParameter(parameter); act.Execute(); } - - } diff --git a/src/Agents/AgentAction.cs b/src/Agents/AgentAction.cs index b8f70e4..9ecb635 100644 --- a/src/Agents/AgentAction.cs +++ b/src/Agents/AgentAction.cs @@ -2,33 +2,73 @@ using Godot; namespace Polonium.Agents; +/// +/// Abstract base class for all agent actions in the system. +/// Provides the foundation for executable actions that can be performed by agents. +/// public abstract partial class AgentAction : Node { + /// + /// Abstract base class for action parameters. + /// public abstract class Parameter { } + /// + /// Sets the parameter for this action. + /// + /// The parameter to set. public virtual void SetParameter(Parameter p) { } + /// + /// Executes the action logic. + /// public abstract void Execute(); + /// + /// Finishes the action execution and performs cleanup. + /// public abstract void Finish(); + /// + /// Resets the action to its initial state. + /// public abstract void Reset(); + /// + /// Abstract base class for agent action templates. + /// public abstract class Template : PoloniumTemplate { + /// + /// Gets the name of the action. + /// public abstract string ActionName { get; } + + /// + /// Gets a copy of this template. + /// public abstract Template Copy { get; } } + /// + /// Generic template class for specific agent action types. + /// + /// The type of agent action. public class Template : Template where TAction : AgentAction { + /// + /// Gets the name of the action from the registry. + /// public override string ActionName => PoloniumRegistry.Action.Name; + /// + /// Gets an instance of the action from the registry, resets it, and applies modifications. + /// public override TAction Get { get @@ -40,6 +80,10 @@ public abstract partial class AgentAction : Node } } + /// + /// Modifies the given agent action object if it's of the correct type. + /// + /// The agent action object to modify. public override void Modify(AgentAction obj) { if (obj is not TAction act) @@ -47,10 +91,21 @@ public abstract partial class AgentAction : Node Modify(act); } + /// + /// Returns the action instance to the registry for reuse. + /// + /// The action instance to return. public void Return(TAction res) => PoloniumRegistry.Asset.Return(res); + /// + /// Gets a copy of this template. + /// public override Template Copy => new Template { }; + /// + /// Virtual method to modify the action instance. Override to customize behavior. + /// + /// The action instance to modify. public virtual void Modify(TAction action) { } diff --git a/src/Attributes/AutoPatch.cs b/src/Attributes/AutoPatch.cs index e26a8ce..d20ee52 100644 --- a/src/Attributes/AutoPatch.cs +++ b/src/Attributes/AutoPatch.cs @@ -1,4 +1,10 @@ namespace Polonium.Attributes; + +/// +/// Attribute that marks an interface for automatic patch class generation. +/// When applied to an interface containing a single property marked with , +/// the source generator will create a corresponding patch class for updating implementations. +/// [AttributeUsage(AttributeTargets.Interface)] public class AutoPatch : Attribute { diff --git a/src/Attributes/RegistryEntity.cs b/src/Attributes/RegistryEntity.cs index f4791ff..a2a6b07 100644 --- a/src/Attributes/RegistryEntity.cs +++ b/src/Attributes/RegistryEntity.cs @@ -1,4 +1,10 @@ namespace Polonium.Attributes; + +/// +/// Attribute that marks a class for automatic registry property generation. +/// When applied to a class, the source generator will create a corresponding property +/// in the GlobalRegistry for easy, game-wide access to instances of this class. +/// [AttributeUsage(AttributeTargets.Class)] public class RegistryEntity : Attribute { diff --git a/src/DataStructures/TextureSet.cs b/src/DataStructures/TextureSet.cs index 5617c17..87298cc 100644 --- a/src/DataStructures/TextureSet.cs +++ b/src/DataStructures/TextureSet.cs @@ -3,8 +3,16 @@ using FileAccess = Godot.FileAccess; namespace Polonium.DataStructures; +/// +/// Represents a complete set of textures for UI button states. +/// Automatically loads textures for Normal, Pressed, Disabled, Hover, and Focused states from a directory. +/// public class TextureSet { + /// + /// Initializes a new instance of the class by loading textures from the specified path. + /// + /// The base path where texture files are located. public TextureSet(string path) { Normal = LoadTexture($"{path}/Normal"); @@ -13,12 +21,37 @@ public class TextureSet Hover = LoadTexture($"{path}/Hover"); Focused = LoadTexture($"{path}/Focused"); } + + /// + /// Gets the texture for the normal button state. + /// public Texture2D Normal { get; init; } + + /// + /// Gets the texture for the pressed button state. + /// public Texture2D Pressed { get; init; } + + /// + /// Gets the texture for the hover button state. + /// public Texture2D Hover { get; init; } + + /// + /// Gets the texture for the disabled button state. + /// public Texture2D Disabled { get; init; } + + /// + /// Gets the texture for the focused button state. + /// public Texture2D Focused { get; init; } + /// + /// Loads a texture from the specified path, supporting both static PNG files and animated texture directories. + /// + /// The path to the texture file or directory. + /// The loaded texture, or an empty texture if not found. private static Texture2D LoadTexture(string path) { Texture2D res = new(); @@ -28,6 +61,4 @@ public class TextureSet res = Utils.LoadAnimatedTextureFromDirectory($"{path}.at_dir"); return res; } - - } \ No newline at end of file diff --git a/src/Interfaces/IGlobalRegistry.cs b/src/Interfaces/IGlobalRegistry.cs index 6542a3e..9e67c85 100644 --- a/src/Interfaces/IGlobalRegistry.cs +++ b/src/Interfaces/IGlobalRegistry.cs @@ -1,8 +1,22 @@ namespace Polonium.Interfaces; +/// +/// Interface for global registry implementations that manage application-wide state and lifecycle. +/// public interface IGlobalRegistry { + /// + /// Gets or sets a value indicating whether the registry is in a paused state. + /// public bool Paused { get; set; } + + /// + /// Starts the registry and begins processing. + /// public void Start(); + + /// + /// Prepares the registry for operation, initializing necessary resources. + /// public void Prepare(); } \ No newline at end of file diff --git a/src/Interfaces/IMessageClient.cs b/src/Interfaces/IMessageClient.cs index a09c35c..0134eae 100644 --- a/src/Interfaces/IMessageClient.cs +++ b/src/Interfaces/IMessageClient.cs @@ -3,13 +3,36 @@ using Polonium.MessageManager; namespace Polonium.Interfaces; +/// +/// Interface for message clients that can send and receive messages through the message bus. +/// public interface IMessageClient { + /// + /// Gets or sets the post code used for message routing. + /// string PostCode { get; set; } + + /// + /// Receives a message from the message bus. + /// + /// The message to receive. void ReceiveMessage(PoloniumMessage msg); + /// + /// Delegate for message sent events. + /// + /// The message that was sent. delegate void MessageSentEventHandler(PoloniumMessage msg); + + /// + /// Event raised when a message is sent by this client. + /// event MessageSentEventHandler MessageSent; + /// + /// Sends a message through the message bus. + /// + /// The message to send. public void SendMessage(PoloniumMessage msg); } diff --git a/src/MessageManager/MessageBus.cs b/src/MessageManager/MessageBus.cs index e98a189..9f4e303 100644 --- a/src/MessageManager/MessageBus.cs +++ b/src/MessageManager/MessageBus.cs @@ -3,12 +3,27 @@ using Polonium.Interfaces; namespace Polonium.MessageManager; +/// +/// Abstract base class for message bus implementations that handle publish-subscribe communication. +/// Manages message clients, routes messages, and handles delivery failures with retry logic. +/// public abstract partial class MessageBus : Node { + /// + /// Dictionary mapping post codes to sets of message clients. + /// public Dictionary> Clients { get; } = new(); + /// + /// Generates a new unique post code for message routing. + /// + /// A unique post code string. public abstract string NewPostCode(); + /// + /// Registers a message client with the bus and subscribes to its message events. + /// + /// The message client to register. public void Register(IMessageClient client) { if(!Clients.ContainsKey(client.PostCode)) @@ -16,16 +31,37 @@ public abstract partial class MessageBus : Node Clients[client.PostCode].Add(client); client.MessageSent += Collect; } + + /// + /// Queue of messages waiting to be processed. + /// public Queue Messages { get; } = new(); + + /// + /// Queue of messages that failed delivery and need to be retried. + /// public Queue DeadMessages { get; } = new(); + + /// + /// Collects a message into the processing queue. + /// + /// The message to collect. public void Collect(PoloniumMessage message) => Messages.Enqueue(message); + /// + /// Initializes the message bus and registers it with the PoloniumRegistry. + /// public override void _Ready() { PoloniumRegistry.Instance.MessageBus = this; base._Ready(); } + /// + /// Processes messages from the queue, delivering them to registered clients. + /// Handles delivery failures and implements retry logic. + /// + /// The time elapsed since the last frame. public override void _Process(double delta) { if(DeadMessages.Count > 0) diff --git a/src/PoloniumRegistry.cs b/src/PoloniumRegistry.cs index 7f4a1e2..58b49a4 100644 --- a/src/PoloniumRegistry.cs +++ b/src/PoloniumRegistry.cs @@ -7,60 +7,140 @@ using Polonium.Resources; namespace Polonium; +/// +/// Central registry for managing global state, resources, and shared objects in the Polonium framework. +/// Provides singleton access to configuration, saves, agents, and asset management systems. +/// public class PoloniumRegistry { + /// + /// Internal singleton instance holder. + /// private static PoloniumRegistry InternalInstance { get; set; } + + /// + /// Gets the singleton instance of the PoloniumRegistry. + /// public static PoloniumRegistry Instance => InternalInstance ??= new PoloniumRegistry(); + + /// + /// Global configuration settings for the application. + /// [RegistryPassThrough] public Config Config { get; set; } + + /// + /// Global save data for the application. + /// [RegistryPassThrough] public Save Save { get; set; } + + /// + /// The currently active world in the agent system. + /// [RegistryPassThrough] public World CurrentWorld { get; set; } + /// + /// Factory for creating Polonium-specific objects. + /// [RegistryPassThrough] public IPoloniumFactory PoloniumFactory { get; set; } + + /// + /// Message bus for pub-sub communication between components. + /// [RegistryPassThrough] public MessageBus MessageBus { get; set; } - + /// + /// Prepares the registry by creating necessary directories and initializing resources. + /// public static void Prepare() { DirAccess.MakeDirAbsolute("user://saves"); } + + /// + /// Collection of all registered agents in the system. + /// // ReSharper disable once CollectionNeverQueried.Global [RegistryPassThrough(true)] public Dictionary Agents { get; } = new(); + /// + /// Collection of all objects that consume time in the system. + /// // ReSharper disable once CollectionNeverQueried.Global [RegistryPassThrough(true)] public HashSet TimeConsumers { get; } = new(); + /// + /// Generic registry for agent actions, providing type-safe access to action names. + /// + /// The type of agent action. public static class Action where TAction : AgentAction { + /// + /// Gets or sets the name of the action type. + /// // ReSharper disable once StaticMemberInGenericType public static string Name { get; set; } } - + /// + /// Generic registry for skin palette management, providing color mapping and palette roots. + /// + /// The type of skin. public static class SkinRegistry where TSkin : Polonium.SkinManagers.Skin { + /// + /// Gets or sets the root colors for the palette. + /// // ReSharper disable once StaticMemberInGenericType public static Color[] PaletteRoots { get; set; } + + /// + /// Gets or sets the color mapping dictionary for palette transformations. + /// // ReSharper disable once StaticMemberInGenericType public static Dictionary PaletteMap { get; set; } } + /// + /// Generic asset registry providing pooled instantiation and management of Godot nodes. + /// + /// The type of node asset. public static class Asset where TAsset : Node { + /// + /// Object pool for reusing instances to improve performance. + /// private static readonly Queue Pool = new(); + + /// + /// Gets or sets the packed scene for instantiation. + /// public static PackedScene Scene { get; set; } + + /// + /// Creates a new instance of the asset from the scene. + /// private static TAsset Instance => Scene.Instantiate(); + + /// + /// Gets an instance from the pool or creates a new one if the pool is empty. + /// + /// An instance of the asset. public static TAsset Get() => Pool.Count > 0 ? Pool.Dequeue() : Instance; + /// + /// Returns an asset instance to the pool for reuse or frees it if the pool is full. + /// + /// The asset instance to return. public static void Return(TAsset asset) { if (Pool.Count < 10) diff --git a/src/SkinManagers/SkinPacker.cs b/src/SkinManagers/SkinPacker.cs index 583022b..5a57f39 100644 --- a/src/SkinManagers/SkinPacker.cs +++ b/src/SkinManagers/SkinPacker.cs @@ -38,6 +38,4 @@ public abstract partial class SkinPacker : Node2D SyncPlayer = GetNode("AnimationPlayer"); SkinCollector = GetNode("SkinCollector"); } - - } \ No newline at end of file