ue5coro

UE5Coro

UE5Coro mengimplementasikan dukungan coroutine C++20 untuk Unreal Engine 5 dengan fokus pada logika gameplay, kenyamanan, dan menyediakan integrasi yang lancar dengan mesin.

Catatan

Dukungan untuk C++17, kompiler lama, platform, dan versi mesin tersedia di seri UE5Coro 1.x yang lama.

Ada dukungan bawaan untuk kemudahan pembuatan UFUNCTION laten. Ubah jenis pengembalian UFUNCTION laten menjadi coroutine, dan Anda akan mendapatkan semua boilerplate FPendingLatentAction secara gratis, dengan dukungan multithreading yang aman untuk BP:

 UFUNCTION (BlueprintCallable, meta = (Latent, LatentInfo = LatentInfo))
FVoidCoroutine Example(FLatentActionInfo LatentInfo)
{
    UE_LOGFMT (LogTemp, Display, " Started " );
    co_await UE5Coro::Latent::Seconds ( 1 ); // Does not block the game thread!
    UE_LOGFMT (LogTemp, Display, " Done " );
    co_await UE5Coro::Async::MoveToThread (ENamedThreads::AnyThread);
    auto Value = HeavyComputation ();
    co_await UE5Coro::Async::MoveToGameThread ();
    UseComputedValue (Value);
}

Coroutine ini akan secara otomatis melacak UObject targetnya di seluruh thread, jadi meskipun objek miliknya dihancurkan sebelum selesai, ia tidak akan crash karena this tergantung pada thread game.

Bahkan tipe pengembalian coroutine disembunyikan dari BP agar tidak mengganggu desainer:

Tidak tertarik dengan UFUNCTION laten? Tidak masalah. Coroutine C++ mentah juga didukung, dengan rangkaian fitur yang sama persis. Implementasi pendukung dipilih pada waktu kompilasi; tindakan laten hanya dibuat jika Anda benar-benar menggunakannya.

Ubah tipe pengembalian Anda ke salah satu tipe coroutine yang disediakan oleh plugin ini, dan tugas asinkron kompleks yang sulit diterapkan sendiri menjadi satu kalimat sederhana yaitu Just Work™, sehingga menghilangkan kebutuhan akan callback dan penangan lainnya.

• Menikmati kenyamanan LoadSynchronous, namun tidak merasakan kekurangannya?
  UObject* HardPtr = co_await AsyncLoadObject(SoftPtr); memungkinkan Anda menyimpan manfaatnya saja (dan FPS Anda).
• Bagaimana dengan menyebarkan komputasi berat ke beberapa tick?
  Tambahkan co_await NextTick(); di dalam satu lingkaran, dan Anda sudah selesai. Ada kelas anggaran waktu yang memungkinkan Anda menentukan waktu pemrosesan yang diinginkan secara langsung, dan membiarkan coroutine menjadwalkan dirinya sendiri secara dinamis.
• Berbicara tentang penjadwalan dinamis, pembatasan bisa sesederhana ini:
  co_await Ticks(bCloseToCamera ? 1 : 2);
• Mengapa memotong waktu pada thread game ketika Anda memiliki banyak inti CPU yang ingin bekerja?
  Tambahkan co_await MoveToTask(); ke fungsi Anda, dan segala sesuatu setelah baris itu akan berjalan dalam sistem UE::Tasks di thread pekerja.
  
• Ingin kembali? Ini co_await MoveToGameThread(); .
  Anda bebas berpindah antar thread secara sewenang-wenang, dan coroutine UFUNCTION laten secara otomatis berpindah kembali ke thread game setelah selesai untuk melanjutkan BP.
• Masih belum yakin? Berikut cara menjalankan seluruh timeline:
  co_await Timeline(this, From, To, Duration, YourUpdateLambdaGoesHere);
• Sulit untuk menyenangkan? Inilah cara Anda menunggu delegasi DINAMIS secara asinkron tanpa menulis UFUNCTION hanya untuk AddDynamic/BindDynamic, atau berada di UCLASS, atau kelas apa pun:
  co_await YourDynamicDelegate; (itulah keseluruhan kodenya)
• Oh, Anda menginginkan parameter dengan delegasi itu?
  auto [Your, Parameters] = co_await YourDynamicDelegate;

Ini akan memberikan gambaran pengurangan signifikan dalam kode dan upaya yang mungkin dilakukan dengan plugin ini. Kode yang lebih sedikit dan sederhana untuk ditulis umumnya berarti lebih sedikit bug, dan kode asinkron yang mudah ditulis berarti tidak ada hambatan dalam melakukan sesuatu dengan cara yang benar, segera.

Ucapkan selamat tinggal pada LoadSynchronous™ yang cukup bagus untuk saat ini yang masih dalam Pengiriman, dua pembaruan nanti. Dengan tugas yang ada dikurangi dari "tulis semua boilerplate StreamableManager dan pindahkan sebagian fungsi pemanggil ke dalam panggilan balik" menjadi hanya "tempelkan co_await di depannya", Anda akan menyelesaikannya lebih cepat daripada yang seharusnya dilakukan. dengan alasan mengapa versi pemblokiran sinkron dapat diterima.

Ada banyak fitur tambahan di plugin, seperti generator yang memungkinkan Anda menghindari pengalokasian seluruh TArray hanya untuk mengembalikan sejumlah nilai variabel. Lebih mudah bagi Anda untuk menulis, lebih mudah bagi kompiler untuk mengoptimalkan, Anda hanya memerlukan penyimpanan O(1) daripada O(N) untuk N item, apa yang tidak disukai?

Daftar fitur

Tautan berikut akan membawa Anda ke halaman dokumentasi yang relevan. Tandai bagian ini jika Anda lebih suka membaca dokumentasi terbaru di browser Anda, atau membacanya langsung dari IDE Anda. Setiap fungsi API didokumentasikan dalam header C++, dan rilisnya berisi sumber Markdown dari dokumentasi yang sedang Anda baca saat ini.

Penulisan coroutine

Fitur-fitur ini berfokus pada mengekspos coroutine ke seluruh mesin.

• Coroutine (tentu saja)
  • Dukungan pembatalan memiliki halamannya sendiri.
• Generator
• Integrasi Sistem Kemampuan Gameplay bekerja sedikit berbeda.

Integrasi yang tidak nyata

Wrapper ini memberikan cara mudah untuk menggunakan fitur mesin dari coroutine Anda.

• Integrasi AI (MoveTo, pencarian jalan...)
• Penunggu animasi (montase, pemberitahuan...)
• Penunggu async (multithreading, sinkronisasi...)
• HTTP (permintaan HTTP asinkron)
• Penunggu implisit (tipe mesin tertentu langsung co_awaitable, tanpa pembungkus)
• Penunggu laten (interaksi thread game, Penundaan...)
  • Pemuatan aset (pemuatan async soft pointer, bundel...)
  • Kueri tabrakan asinkron (pelacakan garis, pemeriksaan tumpang tindih...)
  • Rantai laten (pembungkus tindakan laten universal)
  • Anggaran waktu centang (dijalankan selama x ms per frame)
• Callback laten (interaksi dengan manajer tindakan laten)

Catatan

Sebagian besar fungsi ini mengembalikan tipe internal yang tidak terdokumentasi dari namespace UE5Coro::Private . Kode klien tidak boleh merujuk ke apa pun dari namespace ini secara langsung, karena semua yang ada di dalamnya dapat berubah di versi mendatang, tanpa penghentian sebelumnya.

Seringkali, hal ini tidak menjadi masalah: misalnya, objek sementara yang tidak disebutkan namanya di co_await Something() tidak muncul dalam kode sumber. Jika nilai pengembalian Private perlu disimpan, gunakan auto (atau TAwaitable auto yang dibatasi) untuk menghindari penulisan nama tipe.

Memanggil secara langsung fungsi-fungsi C++ yang dapat ditunggu oleh publik await_suspend await_ready dan await_resume tidak didukung pada penunggu mana pun.

Fitur tambahan

• Penunggu agregat (WhenAny, WhenAll, Race...)
• Garis waktu laten (interpolasi halus saat centang)
• Threading primitif (semafor, peristiwa...)

Instalasi

Hanya rilis bernomor yang didukung. Jangan gunakan cabang Git secara langsung.

Unduh rilis yang Anda pilih, dan ekstrak ke dalam folder Plugin proyek Anda. Ganti nama folder menjadi UE5Coro saja, tanpa nomor versi. Jika dilakukan dengan benar, Anda akan mendapatkan YourProjectPluginsUE5CoroUE5Coro.uplugin .

Catatan

Silakan lihat README rilisnya sendiri jika Anda menggunakan 1.x. Itu memiliki metode instalasi berbeda yang melibatkan banyak plugin.

Pengaturan proyek

Proyek Anda mungkin menggunakan beberapa pengaturan lama yang perlu dihapus untuk membuka dukungan C++20, yang sebaliknya menjadi standar dalam proyek baru yang dibuat di Unreal Engine 5.3 atau lebih baru.

Di file Target.cs Anda (semuanya), pastikan Anda menggunakan pengaturan terbaru dan menyertakan versi pesanan:

 DefaultBuildSettings = BuildSettingsVersion . Latest ;
IncludeOrderVersion = EngineIncludeOrderVersion . Latest ;

Jika Anda menggunakan tanda bEnableCppCoroutinesForEvaluation yang lama, hal itu tidak diperlukan lagi, dan tidak lagi harus diaktifkan secara eksplisit; melakukan hal tersebut dapat menimbulkan masalah. Disarankan untuk menghapus semua referensi dari file build Anda.

Jika Anda menyetel CppStandard ke CppStandardVersion.Cpp17 di file Build.cs... jangan :)

Penggunaan

Referensikan modul "UE5Coro" dari Build.cs Anda seperti yang Anda lakukan pada modul C++ lainnya, dan gunakan #include "UE5Coro.h" . Plugin itu sendiri tidak perlu diaktifkan.

Beberapa fungsi ada dalam modul opsional yang perlu direferensikan secara terpisah. Misalnya, dukungan Sistem Kemampuan Gameplay memerlukan "UE5CoroGAS" di Build.cs, dan #include "UE5CoroGAS.h" . Modul inti UE5Coro hanya bergantung pada modul mesin yang diaktifkan secara default.

Penting

Jangan langsung #sertakan header lainnya, hanya header yang cocok dengan nama modul. IDE utama yang digunakan dengan Unreal Engine diketahui memberikan saran header yang salah. Jika Anda menambahkan UE5Coro.h ke PCH Anda, Anda dapat membuatnya tersedia di mana saja.

Pembaruan

Untuk memperbarui, hapus UE5Coro dari folder Plugin proyek Anda, dan instal versi baru menggunakan petunjuk di atas.

Kemasan

Mengemas UE5Coro secara terpisah (dari jendela Plugins) tidak diperlukan, dan tidak didukung.

Pemindahan

Untuk menghapus plugin dari proyek Anda, terapkan kembali semua coroutine Anda tanpa fungsinya, hapus semua referensi ke plugin dan modulnya, dan tambahkan pengalihan inti dari /Script/UE5CoroK2.K2Node_UE5CoroCallCoroutine ke /Script/BlueprintGraph.K2Node_CallFunction .