Merge pull request #86 from AristurtleDev/develop

5.1.0 Release

Author: AristurtleDev

.github/release-notes.txt

@@ -41,4 +41,8 @@
 - Resolved issue where MonoGame.Aseprite.dll assembly reference was required for the MonoGame.Aseprite.Content.Pipeline.dll assembly in the mgcb-editor (Closes #76)
 - `TextureRegion.TryGetSlice` and `TextureRegion.TryGetSlice<T>` methods added (credit: @fdrobidoux)
 
+ ## 5.1.0
+- `AsepriteCel` properties were made public (thanks @SephDB)
+- `AnimatedSprite` now supports setting frame both on initial play and during playback.
+
 

.nuget/README.md

@@ -3,7 +3,7 @@
 A Cross Platform C# Library That Adds Support For Aseprite Files in MonoGame Projects.
 
 [![build-and-test](https://github.com/AristurtleDev/monogame-aseprite/actions/workflows/buildandtest.yml/badge.svg)](https://github.com/AristurtleDev/monogame-aseprite/actions/workflows/buildandtest.yml)
-[![Nuget 5.0.1](https://img.shields.io/nuget/v/MonoGame.Aseprite?color=blue&style=flat-square)](https://www.nuget.org/packages/MonoGame.Aseprite/5.0.1)
+[![Nuget 5.1.0](https://img.shields.io/nuget/v/MonoGame.Aseprite?color=blue&style=flat-square)](https://www.nuget.org/packages/MonoGame.Aseprite/5.1.0)
 [![License: MIT](https://img.shields.io/badge/📃%20license-MIT-blue?style=flat)](LICENSE)
 [![Twitter](https://img.shields.io/badge/%20-Share%20On%20Twitter-555?style=flat&logo=twitter)](https://twitter.com/intent/tweet?text=MonoGame.Aseprite%20by%20%40aristurtledev%0A%0AA%20cross-platform%20C%23%20library%20that%20adds%20support%20for%20Aseprite%20files%20in%20MonoGame%20projects.%20https%3A%2F%2Fgithub.com%2FAristurtleDev%2Fmonogame-aseprite%0A%0A%23monogame%20%23aseprite%20%23dotnet%20%23csharp%20%23oss%0A)
 

README.md

@@ -4,7 +4,7 @@
 A Cross Platform C# Library That Adds Support For Aseprite Files in MonoGame Projects.
 
 [![build-and-test](https://github.com/AristurtleDev/monogame-aseprite/actions/workflows/buildandtest.yml/badge.svg)](https://github.com/AristurtleDev/monogame-aseprite/actions/workflows/buildandtest.yml)
-[![Nuget 5.0.1](https://img.shields.io/nuget/v/MonoGame.Aseprite?color=blue&style=flat-square)](https://www.nuget.org/packages/MonoGame.Aseprite/5.0.1)
+[![Nuget 5.1.0](https://img.shields.io/nuget/v/MonoGame.Aseprite?color=blue&style=flat-square)](https://www.nuget.org/packages/MonoGame.Aseprite/5.1.0)
 [![License: MIT](https://img.shields.io/badge/📃%20license-MIT-blue?style=flat)](LICENSE)
 [![Twitter](https://img.shields.io/badge/%20-Share%20On%20Twitter-555?style=flat&logo=twitter)](https://twitter.com/intent/tweet?text=MonoGame.Aseprite%20by%20%40aristurtledev%0A%0AA%20cross-platform%20C%23%20library%20that%20adds%20support%20for%20Aseprite%20files%20in%20MonoGame%20projects.%20https%3A%2F%2Fgithub.com%2FAristurtleDev%2Fmonogame-aseprite%0A%0A%23monogame%20%23aseprite%20%23dotnet%20%23csharp%20%23oss%0A)
 

source/MonoGame.Aseprite.Content.Pipeline/MonoGame.Aseprite.Content.Pipeline.csproj

@@ -4,7 +4,7 @@
         <ImplicitUsings>enable</ImplicitUsings>
         <Nullable>enable</Nullable>
         <GenerateDocumentationFile>False</GenerateDocumentationFile>
-        <Version>5.0.1</Version>
+        <Version>5.1.0</Version>
     </PropertyGroup>
 
     <PropertyGroup>
@@ -21,9 +21,9 @@
     <!-- dotnet pack Nuget Config stuff -->
     <PropertyGroup>
         <PackageId>MonoGame.Aseprite.Content.Pipeline</PackageId>
-        <Version>5.0.1</Version>
-        <AssemblyVersion>5.0.1</AssemblyVersion>
-        <FileVersion>5.0.1</FileVersion>
+        <Version>5.1.0</Version>
+        <AssemblyVersion>5.1.0</AssemblyVersion>
+        <FileVersion>5.1.0</FileVersion>
         <Authors>Christopher Whitley</Authors>
         <Company>Aristurtle</Company>
         <PackageLicenseExpression>MIT</PackageLicenseExpression>
@@ -38,10 +38,10 @@
             MonoGame;Aseprite;import;processes;read;write;sprite;animation;tileset;tilemap;spritesheet;pipeline;mgcb
         </PackageTags>
         <PackageReleaseNotes>
-            Version 5.0.1
+            Version 5.1.0
             The following changes were implemented:
-                - Resolved issue where MonoGame.Aseprite.dll assembly reference was required for the MonoGame.Aseprite.Content.Pipeline.dll assembly in the mgcb-editor (Closes #76)
-                - `TextureRegion.TryGetSlice` and `TextureRegion.TryGetSlice&lt;T&gt;` methods added (credit: @fdrobidoux)
+                - `AsepriteCel` properties were made public (thanks @SephDB)
+                - `AnimatedSprite` now supports setting frame both on initial play and during playback.
         </PackageReleaseNotes>
         <Description>
             MonoGame.Aseprite.Content.Pipeline is a cross-platform C# library that adds an extension to the MonoGame

source/MonoGame.Aseprite.Shared/AsepriteTypes/AsepriteCel.cs

@@ -40,17 +40,17 @@ public abstract class AsepriteCel
     ///     Gets the x- and y-coordinate location of this <see cref="AsepriteCel"/> relative to the bounds of the 
     ///     <see cref="AsepriteFrame"/> it is in.
     /// </summary>
-    internal Point Position { get; }
+    public Point Position { get; }
 
     /// <summary>
     ///     Gets the opacity level of this <see cref="AsepriteCel"/>.
     /// </summary>
-    internal int Opacity { get; }
+    public int Opacity { get; }
 
     /// <summary>
     ///     Gets the custom <see cref="AsepriteUserData"/> that was set for this <see cref="AsepriteCel"/> in aseprite.
     /// </summary>
-    internal AsepriteUserData UserData { get; } = new();
+    public AsepriteUserData UserData { get; } = new();
 
     internal AsepriteCel(AsepriteLayer layer, Point position, int opacity) =>
         (Layer, Position, Opacity) = (layer, position, opacity);

source/MonoGame.Aseprite/MonoGame.Aseprite.csproj

@@ -4,7 +4,7 @@
         <ImplicitUsings>enable</ImplicitUsings>
         <Nullable>enable</Nullable>
         <GenerateDocumentationFile>False</GenerateDocumentationFile>
-        <Version>5.0.1</Version>
+        <Version>5.1.0</Version>
     </PropertyGroup>
 
     <PropertyGroup>
@@ -29,10 +29,10 @@
         </PackageTags>
         <PackageReadmeFile>README.md</PackageReadmeFile>
         <PackageReleaseNotes>
-            Version 5.0.1
+            Version 5.1.0
             The following changes were implemented:
-                - Resolved issue where MonoGame.Aseprite.dll assembly reference was required for the MonoGame.Aseprite.Content.Pipeline.dll assembly in the mgcb-editor (Closes #76)
-                - `TextureRegion.TryGetSlice` and `TextureRegion.TryGetSlice&lt;T&gt;` methods added (credit: @fdrobidoux)
+                - `AsepriteCel` properties were made public (thanks @SephDB)
+                - `AnimatedSprite` now supports setting frame both on initial play and during playback.
         </PackageReleaseNotes>
         <Description>
             MonoGame.Aseprite is a cross-platofrm C# library that adds support to MonoGame projects for

source/MonoGame.Aseprite/Sprites/AnimatedSprite.cs

@@ -97,6 +97,11 @@ public double Speed
         }
     }
 
+    /// <summary>
+    ///     Gets the total number of frames in this <see cref="AnimatedSprite"/>
+    /// </summary>
+    public int FrameCount => _animationTag.FrameCount;
+
     /// <summary>
     ///     Gets the source <see cref="AnimationFrame"/> of the current frame of animation for this 
     ///     <see cref="AnimatedSprite"/>.
@@ -202,6 +207,29 @@ public void Update(GameTime gameTime)
         }
     }
 
+    /// <summary>
+    ///     Sets the current frame of animation for this <see cref="AnimatedSprite"/>.
+    /// </summary>
+    /// <param name="frameIndex">
+    ///     The index of the frame to set. Value must be greater than zero and less than the total count of frames. You 
+    ///     can use <see cref="AnimatedSprite.FrameCount"/> to determine the total number of frames.
+    /// </param>
+    /// <exception cref="ArgumentOutOfRangeException">
+    ///     Thrown if the <paramref name="frameIndex"/> value provided is less than zero or is greater than or equal to
+    ///     the total number of frames in this <see cref="AnimatedSprite"/>.
+    /// </exception>
+    public void SetFrame(int frameIndex)
+    {
+        if(frameIndex < 0 || frameIndex >= FrameCount)
+        {
+            throw new ArgumentOutOfRangeException(nameof(frameIndex), $"{nameof(frameIndex)} must be greater than zero and less than the total number of frames in this AnimatedSprite");
+        }
+
+        _currentIndex = frameIndex;
+        TextureRegion = CurrentFrame.TextureRegion;
+        CurrentFrameTimeRemaining = CurrentFrame.Duration;
+    }
+
     private void AdvanceFrame()
     {
         OnFrameEnd?.Invoke(this);
@@ -267,13 +295,30 @@ private void ReduceLoopsRemaining()
     ///         ping-pong will count as a loop.  
     ///     </para>
     /// </param>
+    /// <param name="startingFrame">
+    ///     <para>
+    ///         When this value is provided, specifies the frame to start the animation at
+    ///     </para>
+    ///     <para>
+    ///         When <see langword="null"/> is provided, play will start at frame 0 of the animation.
+    ///     </para>
+    /// </param>
     /// <returns>
     ///     <see langword="true"/> if animation play was successfully started for this <see cref="AnimatedSprite"/>;
     ///     otherwise, <see langword="false"/>.  This method returns <see langword="false"/> if the animation is already
     ///     playing (when <see cref="AnimatedSprite.IsAnimating"/> equals <see langword="true"/>).
     /// </returns>
-    public bool Play(int? loopCount = default)
+    /// <exception cref="ArgumentOutOfRangeException">
+    ///     Thrown if the <paramref name="startingFrame"/> value provided is less than zero or is greater than or equal to
+    ///     the total number of frames in this <see cref="AnimatedSprite"/>.
+    /// </exception>
+    public bool Play(int? loopCount = default, int? startingFrame = 0)
     {
+        if(startingFrame < 0 || startingFrame >= FrameCount)
+        {
+            throw new ArgumentOutOfRangeException(nameof(startingFrame), $"{nameof(startingFrame)} must be greater than zero and less than the total number of frames in this AnimatedSprite");
+        }
+
         //  Cannot play something that's already playing
         if (IsAnimating)
         {
@@ -291,14 +336,15 @@ public bool Play(int? loopCount = default)
         IsAnimating = true;
         IsPaused = false;
 
-        _currentIndex = 0;
+        _currentIndex = startingFrame ?? 0;
 
         if (IsReversed)
         {
             _currentIndex = _animationTag.Frames.Length - 1;
         }
 
         TextureRegion = CurrentFrame.TextureRegion;
+        CurrentFrameTimeRemaining = CurrentFrame.Duration;
         _hasBegun = false;
 
         return true;
@@ -398,8 +444,8 @@ public bool Stop()
 
     /// <summary>
     ///     Resets this <see cref="AnimatedSprite"/> back to its initial state as defined by the 
-    ///     <see cref="AnimationTag"/> used to create it.  You will need to call <see cref="AnimatedSprite.Play(int?)"/>
-    ///     after resetting to start the playback of the animation.s
+    ///     <see cref="AnimationTag"/> used to create it.  You will need to call <see cref="AnimatedSprite.Play(int?, int?)"/>
+    ///     after resetting to start the playback of the animation.
     /// </summary>
     /// <remarks>
     ///     <para>