From 4362e88eabb7760cf5886259dff969bb1ec952c4 Mon Sep 17 00:00:00 2001
From: dnesov <contact.dnesov@gmail.com>
Date: Tue, 24 Jun 2025 22:25:26 +0200
Subject: [PATCH] Add more methods to retrieve resources in ResourceRef, and
 document existing ones.

---
 Voile/Source/Resources/Resource.cs | 32 ++++++++++++++++++++++++++----
 1 file changed, 28 insertions(+), 4 deletions(-)

diff --git a/Voile/Source/Resources/Resource.cs b/Voile/Source/Resources/Resource.cs
index b85b6c6..6b41c7b 100644
--- a/Voile/Source/Resources/Resource.cs
+++ b/Voile/Source/Resources/Resource.cs
@@ -13,11 +13,35 @@ namespace Voile
         /// </summary>
         public readonly Guid Guid = Guid.Empty;
         public bool HasValue => Guid != Guid.Empty;
-        /// <summary>
-        /// Retrieve a reference.
-        /// </summary>
-        public T Value => ResourceManager.GetResource<T>(Guid);
 
+        /// <summary>
+        /// Retrieves a <see cref="Resource"/>.<br />
+        /// This will throw an <see cref="InvalidOperationException"/> if the resource wasn't loaded or is invalid. <br />
+        /// You can check if resource was loaded with <see cref="HasValue"/>, or consider using <see cref="TryGetValue"/>.
+        /// </summary> 
+        public T Value => ResourceManager.GetResource<T>(Guid)
+            ?? throw new InvalidOperationException($"Resource with GUID {Guid} is not loaded or invalid.");
+
+        /// <summary>
+        /// Retrieves a resource or <c>null</c> if the resource wasn't loaded or is invalid.
+        /// </summary>
+        public T? ValueOrNull => ResourceManager.GetResource<T>(Guid);
+
+        /// <summary>
+        /// Tries to retrieve a <see cref="Resource"/>.
+        /// </summary>
+        /// <param name="value">An instance of a retrieved <see cref="Resource"/>.</param>
+        /// <returns><c>true</c> if the resource was successfully retrieved, otherwise <c>false</c>.</returns>
+        public bool TryGetValue(out T? value)
+        {
+            value = ResourceManager.GetResource<T>(Guid);
+            return value != null;
+        }
+
+        /// <summary>
+        /// Create an empty <see cref="ResourceRef"/>.
+        /// </summary>
+        /// <returns></returns>
         public static ResourceRef<T> Empty()
         {
             return new ResourceRef<T>(Guid.Empty);