Skip to content

Commit

Permalink
Merge pull request #5 from mewlist/update-docs
Browse files Browse the repository at this point in the history 
Update documents
  • Loading branch information
@mewlist
mewlist authored Nov 30, 2023
2 parents 75a16b0 + 1f26577 commit 99ed452
Show file tree
Hide file tree
Showing 12 changed files with 494 additions and 172 deletions.
69 changes: 39 additions & 30 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,18 @@ Core Game Libraries for Unity
![](https://img.shields.io/badge/unity-2022.3%20or%20later-green?logo=unity)
[![](https://img.shields.io/badge/license-MIT-blue)](https://github.com/mewlist/MewCore/blob/main/LICENSE)

## Readme (日本語)

[Readme_ja.md](./README_ja.md)

## Documents

https://mewlist.github.io/MewCore/

## Readme (日本語)
## Features

[Readme_ja.md](./README_ja.md)
* TaskQueue: a library for executing asynchronous functions in series
* TaskInterval: a library for running asynchronous functions at regular intervals

## Installation

Expand All @@ -22,16 +27,16 @@ git@github.com:mewlist/MewCore.git

## TaskQueue

TaskQueue is a library that simplifies and efficiently handles asynchronous processes in Unity development. This library enables the management of dynamically changing asynchronous functions and the determination of execution order based on priority.
TaskQueue is a library for handling serial processing of asynchronous functions in Unity development.
Asynchronous functions are executed in the order they are input into the queue.
It also has the feature of a priority queue, which allows you to prioritize important tasks.

### Main Features
Dynamic Function Addition: Allows adding asynchronous functions to the task queue at runtime. This enables flexible response to changing requirements and situations.

Priority-Based Execution Management: Sets priorities for each asynchronous function and processes important tasks preferentially. This prevents delays in critical processes.

Serial Processing and Safety: Executes multiple asynchronous functions in order, waiting for one function to complete before starting the next. This improves safety in UI updates and game sequencing.

Simple Description: TaskQueue is designed to simplify the description of executing asynchronous functions.
* ***Dynamic Function Addition***: You can add asynchronous functions to the task queue at runtime. This allows you to flexibly respond to changing requirements and situations.
* ***Execution management based on priority***: You can set a priority for each asynchronous function and process important tasks preferentially. This prevents delays in important processing.
* ***Serial processing and safety***: Multiple asynchronous functions are executed in order and wait for the completion of one function before starting the execution of the next. This improves the safety of UI updates and game sequences.
* ***Maximum size of the queue***: You can set the maximum number of tasks that can be input into the queue. This allows you to prevent tasks from building up in the queue.

### Use Scenarios

Expand All @@ -50,13 +55,11 @@ class Sample : Monobehaviour
{
void Start()
{
// Create an instance of TaskQueue.
var taskQueue = new TaskQueue();
// Start executing TaskQueue.
// Passing destroyCancellationToken will automatically stop the process and dispose of it when the MonoBehaviour is destroyed.
// By passing the destroyCancellationToken, processing is automatically stoppped and disposed when MonoBehaviour is destroyed.
taskQueue.Start(destroyCancellationToken);

// Add asynchronous functions to TaskQueue.
// Add an asynchronous function to TaskQueue.
taskQueue.Enqueue(async cancellationToken =>
{
Debug.Log("Hello");
Expand All @@ -81,34 +84,40 @@ Bye

### Executing Priority Tasks

You can execute priority tasks by specifying the priority as the second argument in Enqueue.
The lower the number, the more prioritized the processing. The default value is 0.
You can execute priority tasks by specifying the priority as the second argument to Enqueue.
The processing with a smaller ```priority``` value is prioritized. The default value is 0.

```csharp
taskQueue.Enqueue(async ct => { ... }, priority: 1);
taskQueue.Enqueue(async ct => { ... }, priority: 0); // This task is processed first
```

### Specifying PlayerLoop

You can specify the PlayerLoop timing for processing the queue.
The following timing types are defined.
### Setting the Maximum Queue Size

| Timing | Description |
|-------------------------|------|
| `MewUnityEarlyUpdate` | Called at the beginning of Unity's frame update. At this stage, initial event processing and input updates occur. |
| `MewUnityFixedUpdate` | The timing for physics updates. Corresponds to fixed-frame-rate processing in Unity Engine. |
| `MewUnityPreUpdate` | Processing executed before the Update method. Includes scene state updates and animation updates. |
| `MewUnityUpdate` | The normal Update method timing, mainly used for updating game logic. |
| `MewUnityPreLateUpdate` | Processing executed before LateUpdate. Some post-processing for cameras and animations may occur. |
| `MewUnityPostLateUpdate` | Processing at the end of the frame, including rendering preparation and final camera updates. |
#### TaskQueueLimitType.Discard

To specify PlayerLoop timing, specify the timing type in the constructor.
For example, specifying MewUnityFixedUpdate can prevent queue processing delays in case of frame skips.
If you add tasks to a queue with a maximum size of 2 as follows,
and exceed the maximum number, the last added task is discarded.

```csharp
var fixedUpdateTaskQueue = new TaskQueue<MewUnityFixedUpdate>();
taskQueue = new TaskQueue(TaskQueueLimitType.Discard, maxSize: 2);
taskQueue.Enqueue(async ct => { ... });
taskQueue.Enqueue(async ct => { ... });
taskQueue.Enqueue(async ct => { ... }); // This task is discarded
```

#### TaskQueueLimitType.SwapLat

If you add tasks to a queue with a maximum size of 2 as follows,
and exceed the maximum number, the last task is replaced.
If the queue is made up of tasks that have a higher priority than the task to be added, no replacement will be made.

```csharp
taskQueue = new TaskQueue(TaskQueueLimitType.Discard, maxSize: 2);
taskQueue.Enqueue(async ct => { ... });
taskQueue.Enqueue(async ct => { ... }); // This task is discarded
taskQueue.Enqueue(async ct => { ... });
```

## TaskInterval

Expand Down
111 changes: 48 additions & 63 deletions README_ja.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,15 @@ Core Game Libraries for Unity
![](https://img.shields.io/badge/unity-2022.3%20or%20later-green?logo=unity)
[![](https://img.shields.io/badge/license-MIT-blue)](https://github.com/mewlist/MewCore/blob/main/LICENSE)

## ドキュメント

https://mewlist.github.io/MewCore/

## 機能

* TaskQueue: 非同期関数を直列実行するためのライブラリ
* TaskInterval: 非同期関数を一定間隔で実行するためのライブラリ

## インストール

UPM 経由でインストールすることができます。
Expand All @@ -14,29 +23,25 @@ git@github.com:mewlist/MewCore.git

## TaskQueue

TaskQueue は、Unity 開発における非同期処理を簡素化し、効率的に扱うためのライブラリです。このライブラリは、動的に変化する非同期関数の管理と、優先度に基づいた実行順序の決定を可能にします。
TaskQueue は Unity 開発における**非同期関数の直列処理**を行うためのライブラリです。
キューに入力した順で非同期関数が実行されます。
また、優先度付きキューの機能も備えており、重要なタスクを優先的に実行することができます。

### 主な特徴

動的な関数追加: ランタイムで非同期関数をタスクキューに追加することができます。これにより、変化する要件や状況に柔軟に対応可能です。

優先度に基づく実行管理: 各非同期関数に優先度を設定し、重要なタスクを優先的に処理します。これにより、重要な処理の遅延を防ぎます。

直列処理と安全性: 複数の非同期関数を順序立てて実行し、一つの関数が完了するまで次の関数の実行を待機します。これにより、UI 更新やゲームシーケンスの安全性が向上します。

シンプルな記述: TaskQueue は、非同期関数の実行を簡単に記述できるように設計されています。
* ***動的な関数追加***: ランタイムで非同期関数をタスクキューに追加することができます。これにより、変化する要件や状況に柔軟に対応可能です。
* ***優先度に基づく実行管理***: 各非同期関数に優先度を設定し、重要なタスクを優先的に処理します。これにより、重要な処理の遅延を防ぎます。
* ***直列処理と安全性***: 複数の非同期関数を順序立てて実行し、一つの関数が完了するまで次の関数の実行を待機します。これにより、UI 更新やゲームシーケンスの安全性が向上します。
* ***キューの最大サイズ***: キューに入力できるタスクの最大数を設定できます。これにより、キューにタスクが溜まりすぎることを防ぐことができます。
* ***シンプルな記述***: シンプルに記述できるように設計されています。

### 使用シナリオ

UIの動的更新: ゲーム内でのダイアログボックスやメニューの動的な表示・非表示をスムーズに制御する際に使用します。

ゲームイベントのシーケンシング: 物語進行やチュートリアルなど、順序立てられたイベントの管理に適しています。

TaskQueue を使用することで、Unity 開発における非同期処理の複雑さを軽減し、より効果的かつ効率的なコード記述を可能にします。

コマンドパターンへの適応: 非同期処理を含めたコマンドパターンの実装に適しています。

UI イベントのハンドリング: クリックなど UI の非同期イベントに対して並列実行を防ぐために使用します。
* ***UIの動的更新***: ゲーム内でのダイアログボックスやメニューの動的な表示・非表示をスムーズに制御する際に使用します。
* ***ゲームイベントのシーケンシング***: 物語進行やチュートリアルなど、順序立てられたイベントの管理に適しています。
* ***TaskQueue*** を使用することで、Unity 開発における非同期処理の複雑さを軽減し、より効果的かつ効率的なコード記述を可能にします。
* ***コマンドパターンへの適応***: 非同期処理を含めたコマンドパターンの実装に適しています。
* ***UI*** イベントのハンドリング: クリックなど UI の非同期イベントに対して並列実行を防ぐために使用します。

### サンプルコード

Expand All @@ -45,9 +50,7 @@ class Sample : Monobehaviour
{
void Start()
{
// TaskQueue のインスタンスを生成します。
var taskQueue = new TaskQueue();
// TaskQueue の実行を開始します。
// destroyCancellationToken を渡すことで
// MonoBehaviour が破棄されたタイミングで自動的に処理を停止し Dispose されます。
taskQueue.Start(destroyCancellationToken);
Expand Down Expand Up @@ -78,31 +81,36 @@ Bye
### 優先度付きタスクの実行

Enqueue の第二引数に優先度を指定することで、優先度付きタスクを実行することができます。
```priotiry'''値が小さい処理が優先されます。既定値は 0 です。
```priotiry```値が小さい処理が優先されます。既定値は 0 です。

```csharp
taskQueue.Enqueue(async ct => { ... }, priority: 1);
taskQueue.Enqueue(async ct => { ... }, priority: 0); // このタスクが優先して処理される
```

### PlayerLoop の指定
### キュー最大サイズの設定

Queue を処理する PlayerLoop のタイミングを指定することができます。
以下のタイミング型が定義されています。
#### TaskQueueLimitType.Discard

| タイミング | 説明 |
|-------------------------|------|
| `MewUnityEarlyUpdate` | Unityのフレーム更新の最初の段階で呼ばれます。この時点で、最初のイベント処理や入力の更新が行われます。 |
| `MewUnityFixedUpdate` | 物理演算の更新が行われるタイミングです。Unityエンジンにおける固定フレームレートでの処理に対応します。 |
| `MewUnityPreUpdate` | `Update` メソッドの前に実行される処理です。シーンの状態更新やアニメーションの更新などが含まれます。 |
| `MewUnityUpdate` | 主にゲームロジックの更新に使用される、通常の `Update` メソッドのタイミングです。 |
| `MewUnityPreLateUpdate` | `LateUpdate` の前に実行される処理です。一部のカメラやアニメーションの後処理が行われる可能性があります。 |
| `MewUnityPostLateUpdate` | フレームの最後に実行される処理で、レンダリングの前準備やカメラの最終更新が含まれます。 |
最大サイズ 2 のキューに対して以下のようにタスクを追加し、最大数を超えた場合、最後に追加されたタスクが破棄されます。

PlayerLoop のタイミングを指定するには、コンストラクタにタイミング型を指定します。
例えば MewUnityFixedUpdate を指定ることで、フレームスキップが発生した場合にキューの処理が遅延することを防くことができます。
```csharp
taskQueue = new TaskQueue(TaskQueueLimitType.Discard, maxSize: 2);
taskQueue.Enqueue(async ct => { ... });
taskQueue.Enqueue(async ct => { ... });
taskQueue.Enqueue(async ct => { ... });　// このタスクが破棄される
```

#### TaskQueueLimitType.SwapLat

最大サイズ 2 のキューに対して以下のようにタスクを追加し、最大数を超えた場合、最後のタスクを入れ替えます。
追加されるタスクより優先度が高いタスクでキューが構成される場合は、入れ替えは行われません。

```csharp
var fixedUpdateTaskQueue = new TaskQueue<MewUnityFixedUpdate>();
taskQueue = new TaskQueue(TaskQueueLimitType.Discard, maxSize: 2);
taskQueue.Enqueue(async ct => { ... });
taskQueue.Enqueue(async ct => { ... });　// このタスクが破棄される
taskQueue.Enqueue(async ct => { ... });　
```

## TaskInterval
Expand Down Expand Up @@ -170,12 +178,13 @@ public class Sample : MonoBahaviour
### 使用する Timer の指定

Create の第３引数に Timer の種類を指定することで、使用する Timer を変更することができます。
Unity の Time.timeScale の影響を受けないようにしたい場合は、```IntervalTimerType.UnityTime``` 以外の値を指定するとよいでしょう。

| Timer の種類 | 説明 |
|--------------|---------------------------|
| `IntervalTimerType.SystemTime` | システム時間を使用します。 |
| `IntervalTimerType.UnityTime` | Unity の Time.time を使用します。 |
| `IntervalTimerType.UnityUnscaledTime` | Time.unscaledTime を使用します。|
| Timer の種類 | 説明 |
|--------------|-----------------------------|
| `IntervalTimerType.SystemTime` | システム時間を使用します。 |
| `IntervalTimerType.UnityTime` | Unity の Time.time を使用します。(***規定値***) |
| `IntervalTimerType.UnityUnscaledTime` | Time.unscaledTime を使用します。 |

Time.timeScale の影響を受けずに処理を実行する例。

Expand All @@ -184,27 +193,3 @@ TaskInterval
.Create(1000 /* ms */, TestTaskAsync, IntervalTimerType.UnityUnscaledTime)
.Start(destroyCancellationToken);
```

### PlayerLoop の指定

タスクを処理する PlayerLoop のタイミングを指定することができます。
以下のタイミング型が定義されています。

| タイミング | 説明 |
|-------------------------|------|
| `MewUnityEarlyUpdate` | Unityのフレーム更新の最初の段階で呼ばれます。この時点で、最初のイベント処理や入力の更新が行われます。 |
| `MewUnityFixedUpdate` | 物理演算の更新が行われるタイミングです。Unityエンジンにおける固定フレームレートでの処理に対応します。 |
| `MewUnityPreUpdate` | `Update` メソッドの前に実行される処理です。シーンの状態更新やアニメーションの更新などが含まれます。 |
| `MewUnityUpdate` | 主にゲームロジックの更新に使用される、通常の `Update` メソッドのタイミングです。 |
| `MewUnityPreLateUpdate` | `LateUpdate` の前に実行される処理です。一部のカメラやアニメーションの後処理が行われる可能性があります。 |
| `MewUnityPostLateUpdate` | フレームの最後に実行される処理で、レンダリングの前準備やカメラの最終更新が含まれます。 |

PlayerLoop のタイミングを指定するには、TaskIntervalに対してタイミング型を指定します。
例えば MewUnityFixedUpdate を指定ることで、フレームスキップが発生した場合にも安定したゲーム時間でのタスク実行を行い遅延することを防くことができます。

```csharp
TaskInterval<MewUnityFixedUpdate>
.Create(1000 /* ms */, TestTaskAsync, IntervalTimerType.UnityUnscaledTime)
.Start(destroyCancellationToken);
```

8 changes: 4 additions & 4 deletions docs/api/Mew.Core.Tasks.TaskQueue-1.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ <h5 class="offcanvas-title" id="tocOffcanvasLabel">Table of Contents</h5>

<h1 id="Mew_Core_Tasks_TaskQueue_1" data-uid="Mew.Core.Tasks.TaskQueue`1" class="text-break">
Class TaskQueue&lt;T&gt;
<a class="header-action link-secondary" title="View source" href="https://github.com/mewlist/MewDev/blob/main/Assets\MewCore\Runtime\TaskQueue\TaskQueue.cs/#L208"><i class="bi bi-code-slash"></i></a>
<a class="header-action link-secondary" title="View source" href="https://github.com/mewlist/MewDev/blob/main/Assets\MewCore\Runtime\TaskQueue\TaskQueue.cs/#L230"><i class="bi bi-code-slash"></i></a>
</h1>

<div class="facts text-secondary">
Expand Down Expand Up @@ -205,7 +205,7 @@ <h2 class="section" id="constructors">Constructors

<h3 id="Mew_Core_Tasks_TaskQueue_1__ctor" data-uid="Mew.Core.Tasks.TaskQueue`1.#ctor">
TaskQueue()
<a class="header-action link-secondary" title="View source" href="https://github.com/mewlist/MewDev/blob/main/Assets\MewCore\Runtime\TaskQueue\TaskQueue.cs/#L213"><i class="bi bi-code-slash"></i></a>
<a class="header-action link-secondary" title="View source" href="https://github.com/mewlist/MewDev/blob/main/Assets\MewCore\Runtime\TaskQueue\TaskQueue.cs/#L235"><i class="bi bi-code-slash"></i></a>
</h3>

<div class="markdown level1 summary"><p><inheritdoc></inheritdoc></p>
Expand All @@ -232,7 +232,7 @@ <h3 id="Mew_Core_Tasks_TaskQueue_1__ctor" data-uid="Mew.Core.Tasks.TaskQueue`1.#

<h3 id="Mew_Core_Tasks_TaskQueue_1__ctor_Mew_Core_Tasks_TaskQueueLimitType_System_Int32_" data-uid="Mew.Core.Tasks.TaskQueue`1.#ctor(Mew.Core.Tasks.TaskQueueLimitType,System.Int32)">
TaskQueue(TaskQueueLimitType, int)
<a class="header-action link-secondary" title="View source" href="https://github.com/mewlist/MewDev/blob/main/Assets\MewCore\Runtime\TaskQueue\TaskQueue.cs/#L221"><i class="bi bi-code-slash"></i></a>
<a class="header-action link-secondary" title="View source" href="https://github.com/mewlist/MewDev/blob/main/Assets\MewCore\Runtime\TaskQueue\TaskQueue.cs/#L243"><i class="bi bi-code-slash"></i></a>
</h3>

<div class="markdown level1 summary"></div>
Expand Down Expand Up @@ -265,7 +265,7 @@ <h4 class="section">Parameters</h4>
</article>

<div class="contribution d-print-none">
<a href="https://github.com/mewlist/MewDev/blob/main/Assets\MewCore\Runtime\TaskQueue\TaskQueue.cs/#L208" class="edit-link">Edit this page</a>
<a href="https://github.com/mewlist/MewDev/blob/main/Assets\MewCore\Runtime\TaskQueue\TaskQueue.cs/#L230" class="edit-link">Edit this page</a>
</div>


Expand Down
Loading

0 comments on commit 99ed452

Please sign in to comment.