同步

Packages/dev.yarnspinner.unity/Runtime/LineProviders/LineProviderBase.cs

@@ -0,0 +1,132 @@
+/*
+Yarn Spinner is licensed to you under the terms found in the file LICENSE.md.
+*/
+
+using System.Collections.Generic;
+using System.Threading;
+using UnityEngine;
+using Yarn.Markup;
+
+#nullable enable
+
+namespace Yarn.Unity
+{
+    /// <summary>
+    /// Contains methods for retrieving user-facing localized content, given
+    /// non-localized line IDs.
+    /// </summary>
+    public interface ILineProvider
+    {
+        /// <summary>
+        /// The <see cref="YarnProject"/> that contains the localized data for
+        /// lines.
+        /// </summary>
+        /// <remarks>
+        /// This property is set at run-time by the object that will be requesting
+        /// content (typically a <see cref="DialogueRunner"/>).
+        /// </remarks>
+        public YarnProject? YarnProject { get; set; }
+
+        /// <summary>
+        /// Gets the line provider's current locale identifier, as a BCP-47 code.
+        /// </summary>
+        public string LocaleCode { get; }
+
+        /// <summary>
+        /// Prepares and returns a <see cref="LocalizedLine"/> from the specified
+        /// <see cref="Yarn.Line"/>.
+        /// </summary>
+        /// <param name="line">The <see cref="Yarn.Line"/> to produce the <see
+        /// cref="LocalizedLine"/> from.</param>
+        /// <param name="cancellationToken">A cancellation token that indicates
+        /// whether the process of fetching the localised version of <paramref
+        /// name="line"/> should be cancelled.</param>
+        /// <returns>A localized line, ready to be presented to the
+        /// player.</returns>
+        public YarnTask<LocalizedLine> GetLocalizedLineAsync(Line line, CancellationToken cancellationToken);
+
+        /// <summary>
+        /// Signals to the line provider that lines with the provided line IDs may
+        /// be presented shortly.        
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// This method allows implementing classes a chance to prepare any
+        /// neccessary resources needed to present these lines, like pre-loading
+        /// voice-over audio. The default implementation does nothing.
+        /// </para>
+        /// <para style="info">
+        /// Not every line may run; this method serves as a way to give the line
+        /// provider advance notice that a line <i>may</i> run, not <i>will</i> run.
+        /// </para>
+        /// </remarks>
+        /// <param name="lineIDs">A collection of line IDs that the line provider
+        /// should prepare for.</param>
+        /// <param name="cancellationToken">A cancellation token that indicates
+        /// whether the operation should be cancelled.</param>
+        public YarnTask PrepareForLinesAsync(IEnumerable<string> lineIDs, CancellationToken cancellationToken);
+
+        /// <summary>
+        /// Adds a new marker processor to the line provider.
+        /// </summary>
+        /// <param name="attributeName">The name of the markers to use <paramref
+        /// name="markerProcessor"/> for.</param>
+        /// <param name="markerProcessor">The marker processor to add.</param>
+        public void RegisterMarkerProcessor(string attributeName, Yarn.Markup.IAttributeMarkerProcessor markerProcessor);
+
+        /// <summary>
+        /// Removes all marker processors that handle markers named <paramref
+        /// name="attributeName"/>.
+        /// </summary>
+        /// <param name="attributeName">The name of the marker to remove processors
+        /// for.</param>
+        public void DeregisterMarkerProcessor(string attributeName);
+    }
+
+    /// <summary>
+    /// A <see cref="MonoBehaviour"/> that produces <see
+    /// cref="LocalizedLine"/>s, for use in Dialogue Presenters.
+    /// </summary>
+    /// <remarks>
+    /// <see cref="DialogueRunner"/>s use a <see cref="LineProviderBehaviour"/>
+    /// to get <see cref="LocalizedLine"/>s, which contain the localized
+    /// information that is presented to the player through dialogue presenters.
+    /// </remarks>
+    public abstract class LineProviderBehaviour : MonoBehaviour, ILineProvider
+    {
+        /// <inheritdoc/>
+        public abstract YarnTask<LocalizedLine> GetLocalizedLineAsync(Line line, CancellationToken cancellationToken);
+
+        /// <inheritdoc/>
+        public YarnProject? YarnProject { get; set; }
+
+        /// <inheritdoc/>
+        public virtual YarnTask PrepareForLinesAsync(IEnumerable<string> lineIDs, CancellationToken cancellationToken)
+        {
+            // No-op by default.
+            return YarnTask.CompletedTask;
+        }
+
+        /// <inheritdoc/>
+        public abstract string LocaleCode { get; set; }
+
+        /// <summary>
+        /// Called by Unity when the <see cref="LineProviderBehaviour"/> has
+        /// first appeared in the scene.
+        /// </summary>
+        /// <remarks>
+        /// This method is <see langword="public"/> <see langword="virtual"/> to
+        /// allow subclasses to override it.
+        /// </remarks>
+        public virtual void Start()
+        {
+        }
+
+        /// <inheritdoc/>
+        public abstract void RegisterMarkerProcessor(string attributeName, IAttributeMarkerProcessor markerProcessor);
+
+        /// <inheritdoc/>
+        public abstract void DeregisterMarkerProcessor(string attributeName);
+    }
+
+}