ItemsEngine

Türkçe

ItemsEngine, sunucuda ItemsAdder kuruluymuş gibi görünen ve desteklediği ItemsAdder API çağrılarını CraftEngine verilerine yönlendiren açık kaynak bir Paper/Folia uyumluluk köprüsüdür. Plugin adı ItemsEngine, ana paket adı com.siberanka.itemsengine'dir.

ItemsEngine, ItemsAdder'ın kendisi değildir; resource-pack üreticisi veya tüm özelliklerinin yeniden uygulaması da değildir. Desteklenmeyen bir çağrıda veri uydurmak yerine güvenli biçimde null, false veya boş koleksiyon döndürür.

Ne sağlar?

• Paper'ın provides: [ItemsAdder] mekanizmasıyla depend: [ItemsAdder] kullanan pluginlerin yüklenmesini ve getPlugin("ItemsAdder") çağrısının ItemsEngine'e çözülmesini sağlar.
• CraftEngine item, blok, mobilya ve görsel kayıtlarını ItemsAdder'ın güncel API adlarıyla sunar.
• Item üretme/tanıma, blok yerleştirme/kaldırma, mobilya yerleştirme/kaldırma ve font görseli metin/component erişimini köprüler.
• CraftEngine yeniden yüklemesini ItemsAdder yükleme olaylarına; temel blok ve mobilya olaylarını iptal durumu korunarak ItemsAdder olaylarına çevirir.
• CraftEngine'in eski ve güncel kararlı API şekilleri arasındaki dönüş tipi değişikliklerinden etkilenmemek için dar, doğrulanan bir reflection adaptörü kullanır.
• Güncel ItemsAdder API JAR'ındaki tüm sınıf ve public/protected method descriptor'larını build sırasında bytecode düzeyinde doğrular; davranışsal karşılığı olmayan yüzeyler açıkça tarafsız kalır.

Kurulum

1. Desteklenen sunucunuza CraftEngine kurun.
2. Son sürüm ItemsEngine-*.jar dosyasını Releases sayfasından indirip plugins/ klasörüne koyun.
3. Placeholder kullanacaksanız PlaceholderAPI 2.12.3 veya üstünü kurun. PlaceholderAPI isteğe bağlıdır; 26.2 desteği için en az 2.12.3 gerekir.
4. ItemsAdder JAR'ını aynı sunucuya kurmayın; iki sağlayıcının birlikte çalışması desteklenmez.
5. Sunucuyu tamamen yeniden başlatın ve /itemsengine status çıktısını kontrol edin.

Paper 1.21.x için Java 21; Paper 26.1 ve sonrası için Java 25 gerekir. /reload desteklenmez.

ItemsAdder placeholder uyumluluğu

ItemsEngine, belgelenmiş ItemsAdder yazımlarını korur ve değerleri CraftEngine'in gerçek kayıtlarından üretir. PlaceholderAPI eCloud'dan ayrı bir expansion indirmeniz gerekmez.

Biçim	Sonuç
%img_<görsel>%	CraftEngine font görselinin Unicode glifi
%img_offset_-16%, %img_offset_16%	CraftEngine'in ham font metriğiyle negatif/pozitif piksel kaydırma
:<görsel>:, :<namespace>:<görsel>:	ItemsAdder satır içi görsel sözdizimi
:offset_-16:, :offset_16:	ItemsAdder satır içi piksel kaydırma sözdizimi
%iaplayerstat_<ad>%	Var olan sayısal oyuncu PDC istatistiği; veri yoksa çözümlenmez
%itemsadder_newline%, %itemsadder_space%	Satır sonu ve boşluk

Bilgi placeholder'ları: %itemsadder_loaded%, %itemsadder_version%, %itemsadder_craftengine_version%, %itemsadder_items_count%, %itemsadder_blocks_count%, %itemsadder_furniture_count%, %itemsadder_images_count%; bunların *_ids listeleri ve item|block|furniture|image_exists_<namespace:id> kontrolleri. Item için item_material_, item_name_, item_max_stack_size_, item_custom_model_data_; görsel için image_unicode_, image_codepoint_, image_height_, image_ascent_, image_rows_, image_columns_, image_font_, image_file_ önekleri kullanılabilir. <namespace:id> kısmı önekin sonuna aynen eklenir. Oyuncu bağlamında %itemsadder_mainhand_id% ve %itemsadder_offhand_id% desteklenir.

Tam ad her zaman önerilir: %img_namespace:görsel%. Kısa ad yalnızca tek bir kayıtla eşleşiyorsa çözümlenir; belirsiz veya bilinmeyen değerler sahte veri üretmez. Kaydırma -8192..8192, liste çıktıları ise güvenli boyutlarla sınırlıdır.

Anti-xray ve anti-cheat bağlantısı

ItemsEngine, ItemsAdder bağlantısı kullanan anti-xray/anti-cheat eklentilerinin yaygın açık API yolunu taklit eder: ItemsAdder sağlayıcı adı, yükleme olayları, CustomBlock.byAlreadyPlaced(Block), ItemsAdder.isCustomBlock(Block), CustomStack.byItemStack(ItemStack) ve özel blok yerleştirme/kırma olayları CraftEngine verisine bağlanır. CustomStack.getInstance, CustomBlock.getInstance ve mobilya yerleştirme girişleri hem namespace:id hem de benzersiz kısa id kabul eder; kısa ad çakışırsa güvenli biçimde başarısız olur.

Bu sözleşme gerçek Paper/Folia sunucusunda bir CraftEngine özel bloğunu yerleştirip ItemsAdder API'siyle aynı kimlikte geri okuyarak ve ardından test bloğunu kaldırıp önceki blok verisini geri yükleyerek doğrulanır. Açık kaynak RayTraceAntiXray sürümleri doğrudan ItemsAdder çağrısı içermediğinden, özel/ücretli bir sürümün yayımlanmamış iç sınıflarına uyumluluk iddia edilmez. Public ItemsAdder API kullanan bağlantılar hedeflenir.

Doğrulanmış uyumluluk

Platform	Minecraft	Java	CraftEngine	Sonuç
Paper stable	1.21.11 build 132	21	26.7.4	Placeholder + özel blok tüketici probu geçti
Folia stable	1.21.11 build 14	21	26.7.4	Placeholder + özel blok tüketici probu geçti
Paper stable	26.2 build 92	25	26.7.4	Placeholder + özel blok tüketici probu geçti
Folia beta	26.2 build 1	25	26.7.4	Placeholder + özel blok tüketici probu geçti

Kaynak kod Java 21 bytecode üretir. Böylece 1.21.x alt sınırı korunurken Java 25 üzerinde çalışan 26.x sunucularında da aynı JAR kullanılabilir. Ayrıntılı ve dürüst özellik matrisi için Uyumluluk belgesine bakın.

Geliştiriciler için

ItemsAdder API bağımlılığınızı değiştirmek zorunda değilsiniz. Plugininiz normal şekilde depend, softdepend veya loadbefore ile ItemsAdder adını kullanabilir. Verilerin hazır olduğunu anlamak için ItemsAdder yükleme olayını dinlemeye devam edin; onEnable sırasında kayıtların hazır olduğunu varsaymayın.

CustomStack stack = CustomStack.getInstance("namespace:item");
if (stack != null) {
    player.getInventory().addItem(stack.getItemStack());
}

Yerel doğrulama:

./gradlew clean build cyclonedxBom integrationProbeJar

Mimari, tehdit modeli ve kaynak kayıtları sırasıyla ARCHITECTURE, SECURITY ve RESEARCH belgelerindedir. Hata bildirirken issue formlarını kullanın.

---

English

ItemsEngine is an open-source Paper/Folia compatibility bridge that presents itself as an ItemsAdder provider and routes supported ItemsAdder API calls to CraftEngine data. Its plugin name is ItemsEngine and its root package is com.siberanka.itemsengine.

ItemsEngine is not ItemsAdder, a resource-pack generator, or a reimplementation of every ItemsAdder feature. Unsupported calls fail closed with null, false, or an empty collection instead of fabricated data.

What does it provide?

• Uses Paper's provides: [ItemsAdder] mechanism so plugins declaring depend: [ItemsAdder] load and getPlugin("ItemsAdder") resolves to ItemsEngine.
• Exposes CraftEngine item, block, furniture, and image registries through current ItemsAdder API names.
• Bridges item building/identification, block placement/removal, furniture placement/removal, and font-image text/components.
• Translates CraftEngine reloads into ItemsAdder load events and maps core block/furniture events while propagating cancellation back to CraftEngine.
• Uses a narrow, validated reflection adapter to survive return-type changes between older and current stable CraftEngine API generations.
• Bytecode-checks every class and public/protected method descriptor in the current ItemsAdder API JAR; surfaces without a behavioral equivalent remain explicitly neutral.

Installation

1. Install CraftEngine on a supported server.
2. Download the latest ItemsEngine-*.jar from Releases and place it in plugins/.
3. If you need placeholders, install PlaceholderAPI 2.12.3 or newer. PlaceholderAPI is optional; 26.2 requires at least 2.12.3.
4. Do not install the ItemsAdder JAR on the same server; dual providers are unsupported.
5. Fully restart the server and inspect /itemsengine status.

Paper 1.21.x requires Java 21; Paper 26.1+ requires Java 25. /reload is unsupported.

ItemsAdder placeholder compatibility

ItemsEngine preserves the documented ItemsAdder spellings and produces values from the real CraftEngine registries. No separate eCloud expansion is required.

Syntax	Result
%img_<image>%	Unicode glyph of a CraftEngine font image
%img_offset_-16%, %img_offset_16%	Negative/positive pixel shift generated by CraftEngine's raw font metrics
:<image>:, :<namespace>:<image>:	ItemsAdder inline image syntax
:offset_-16:, :offset_16:	ItemsAdder inline pixel-offset syntax
%iaplayerstat_<name>%	Existing numeric player PDC statistic; remains unresolved when no data exists
%itemsadder_newline%, %itemsadder_space%	Newline and space

Information placeholders include %itemsadder_loaded%, %itemsadder_version%, %itemsadder_craftengine_version%, registry *_count/*_ids values, and item|block|furniture|image_exists_<namespace:id>. Item metadata uses item_material_, item_name_, item_max_stack_size_, and item_custom_model_data_; image metadata uses image_unicode_, image_codepoint_, image_height_, image_ascent_, image_rows_, image_columns_, image_font_, and image_file_. Append the exact <namespace:id> after the prefix. %itemsadder_mainhand_id% and %itemsadder_offhand_id% are available with a player context.

Prefer fully qualified IDs such as %img_namespace:image%. A short name resolves only when unique; ambiguous and unknown values fail closed. Offsets are bounded to -8192..8192, and registry list output is safely bounded.

Anti-xray and anti-cheat hooks

ItemsEngine emulates the common public API path used by anti-xray/anti-cheat plugins with an ItemsAdder hook: the ItemsAdder provider identity, load events, CustomBlock.byAlreadyPlaced(Block), ItemsAdder.isCustomBlock(Block), CustomStack.byItemStack(ItemStack), and custom block place/break events are backed by CraftEngine data. CustomStack.getInstance, CustomBlock.getInstance, and furniture placement entry points accept either namespace:id or a unique bare id; an ambiguous bare name fails closed.

The contract is verified on real Paper/Folia servers by placing a CraftEngine custom block, reading back the identical ID through the ItemsAdder API, removing it, and restoring the original test block data. The public RayTraceAntiXray editions contain no direct ItemsAdder calls, so ItemsEngine does not claim compatibility with unpublished internals of a private/paid build. Integrations using the public ItemsAdder API are the supported target.

Verified compatibility

Platform	Minecraft	Java	CraftEngine	Result
Paper stable	1.21.11 build 132	21	26.7.4	Placeholder + placed-block consumer probe passed
Folia stable	1.21.11 build 14	21	26.7.4	Placeholder + placed-block consumer probe passed
Paper stable	26.2 build 92	25	26.7.4	Placeholder + placed-block consumer probe passed
Folia beta	26.2 build 1	25	26.7.4	Placeholder + placed-block consumer probe passed

The project emits Java 21 bytecode, preserving the 1.21.x lower bound while allowing the same JAR to run on Java 25-based 26.x servers. See Compatibility for the detailed, conservative feature matrix.

For plugin developers

You do not need to change your ItemsAdder API dependency. Continue declaring ItemsAdder in depend, softdepend, or loadbefore. Continue listening for the ItemsAdder load event; do not assume registry data is ready during onEnable.

CustomStack stack = CustomStack.getInstance("namespace:item");
if (stack != null) {
    player.getInventory().addItem(stack.getItemStack());
}

Local verification:

./gradlew clean build cyclonedxBom integrationProbeJar

See Architecture, Security, and Research. Please use the structured issue forms when reporting a problem.