Penyebab acara

Peristiwa sangat bagus untuk menggunakan tambahan logika dalam permainan, namun ada kekurangan dalam menyediakan konteks tanpa ada penyebabnya ** kejadian itu terjadi. The: javadoc:`Penyebab objek memungkinkan menyediakan dan menerima informasi kontekstual tambahan tentang acara tersebut. Informasi kontekstual ini kemudian dapat digunakan untuk mengubah perilaku pendengar acara Anda.

Misalnya, plugin perlindungan dunia memerlukan informasi tentang pemutar yang menyebabkan: javadoc: ChangeBlockEvent terjadi sebelum mereka dapat memutuskan apakah acara tersebut harus dibatalkan atau tidak. Alih-alih pergi dengan rute tradisional untuk menciptakan banyak sumber daya untuk kondisi sumber yang berbeda, informasi ini diberikan di `` Penyebab'` dari acara tersebut.

Setiap acara penyediaan objek `` Cause`` yang dapat diinterogasi untuk informasi yang berkaitan dengan mengapa acara dibatalkan. Objek Penyebab dapat diambil dari sebuah acara dengan hanya menelepon Event#getCause().

Mengambil benda dari sebuah penyebab

Secara struktural, sebuah objek `` Cause`` berisi daftar objek yang berurutan. Ada beberapa metode untuk mengambil informasi dari objek Penyebab yang akan kita bahas di sini, untuk daftar yang lebih lengkap, silakan lihat Javadocs <https://jd.spongepowered.org> _.

Catatan

Objek di dalam suatu benda diperintahkan sedemikian rupa sehingga objek pertama adalah penyebab kejadian yang paling langsung, dan objek selanjutnya kurang penting dan / atau mungkin hanya menyediakan informasi kontekstual.

Cause#root() returns the first object within the cause. This object is the most immediate or direct cause of the event. Since a Cause may not be empty, it is guaranteed to have a root.

Cause#first(Class) returns the first object in the cause chain whose type is either the same as or is a subtype of the given class. For example given a cause which contained a player followed by an entity [Player, Entity, ...]

@Listener
public void onEvent(ExampleCauseEvent event) {
    Cause cause = event.getCause(); // [Player, Entity]
    Optional<Player> firstPlayer = cause.first(Player.class); // 1
    Optional<Entity> firstEntity = cause.first(Entity.class); // 2
}

Pilihan kedua akan berisi objek pemutar karena jenisnya sesuai permintaan untuk jenis Pemain dan sesuai dengan permintaan jenis Entitas karena Player adalah subtipe Entitas.

Cause#last(Class) hampir sama Cause#first(Class) kecuali mengembalikan nilai terakhir pada rantai penyebab yang sesuai dengan jenisnya.

Melanjutkan dari contoh di atas, jika kita mengubah itu untuk memanggil '' Cause#last(Class)'' opsional pertama masih akan berisi objek pemain, tetapi kedua opsional sekarang akan berisi entitas yang kami melewati di posisi kedua penyebab.

:javadoc:'Cause#containsType(class)' nilai boolean dan dapat digunakan untuk memeriksa jika penyebab jaringan berisi objek pencocokan tipe disediakan.

Cause#all() mengembalikan semua objek dalam penyebabnya sehingga penanganan lebih maju.

Penyebab yang dinamakan

Kadang-kadang pemesanan objek di dalam penyebab tidak cukup untuk mendapatkan gagasan yang tepat tentang apa yang mewakili suatu objek dalam kaitannya dengan acara tersebut. Di sinilah: javadoc: NamedCause masuk ke dalam. Penyebab yang dinamakan menyediakan metode untuk menandai objek dalam sebab dengan nama unik yang memungkinkannya diidentifikasi dan diminta dengan mudah. Beberapa contoh kasus penggunaan untuk penyebab bernama adalah Notifier dari :javadoc:` ChangeBlockEvent.Grow` atau Source dari a :javadoc:` DamageEntityEvent`.

Retrieving a named entry from a cause

@Listener
public void onGrow(ChangeBlockEvent.Grow event) {
    Optional<Player> notifier = event.getCause().get(NamedCause.NOTIFIER, Player.class);
}

Ini contoh penggunaan Cause#get(String, Class<T>) yang dapat digunakan untuk mengambil objek yang diharapkan terkait dengan nama jika hadir dalam rantai penyebab. Selain itu Cause#getNamedCauses() provides a Map<String, Object> yang dapat digunakan untuk menemukan semua nama yang hadir dan objek yang diharapkan.

Catatan

Beberapa nama identifikasi umum untuk NamedCauses ada sebagai field statis dalam kelas NamedCause. Pengidentifikasi yang spesifik pada event tertentu dapat sering ditemukan sebagai field statis pada kelas event, contohnya DamageEntityEvent#SOURCE.

Membuat penyebab kebiasaan

Menciptakan penyebab untuk digunakan saat menembaki sebuah acara sangat mudah dilakukan. Bagian tersulit adalah menentukan informasi apa yang harus disertakan dalam penyebabnya. Jika Anda menembaki sebuah acara dari plugin Anda yang biasanya dipicu dengan cara lain mungkin Anda ingin memasukkan wadah plugin Anda sehingga plugin lain tahu bahwa acara tersebut berasal dari plugin Anda. Atau jika Anda menembaki acara tersebut atas nama pemain karena beberapa tindakan, biasanya ada baiknya menyertakan pemain itu penyebabnya.

Catatan

Sebab benda tidak berubah sehingga tidak bisa dimodifikasi begitu dibuat.

Menggunakan : javadoc: Cause # of (NamedCause), Anda dapat membuat penyebab dari serangkaian objek. Objek akan ditambahkan ke rantai penyebab dalam urutan yang dilewatkan ke metode, sehingga parameter objek pertama akan menjadi akar penyebabnya. Ingat bahwa `` Penyebab`` mungkin tidak kosong, jadi setidaknya satu parameter non-nol selalu diperlukan.

Jika Anda sudah memiliki objek penyebab dan ingin menambahkan beberapa objek ke rantai yang dapat Anda gunakan : javadoc: Cause # with (NamedCause, NamedCause ...). Ini mengkonstruksi objek Penyebab baru yang berisi objek pertama yang sudah ada pada penyebab aslinya, kemudian diikuti oleh objek tambahan yang Anda berikan.

Akhirnya jika Anda ingin menambahkan objek ke penyebab dengan panggilan pertama yang didefinisikan : javadoc: NamedCause # of (String, Object) dan kemudian lewati instance NamedCause` yang dikembalikan ke rantai penyebab seperti yang biasa Anda lakukan. obyek.