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.

ItemsEngine, gömülü PacketEvents sağlayıcısıyla uyumlu olarak GPL-3.0 lisansıyla yayımlanır; üçüncü taraf bildirimleri THIRD_PARTY_NOTICES dosyasındadı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.
• Sunucuda PacketEvents varsa onun API'sini kullanır; yoksa izole edilmiş PacketEvents 2.13.0 sağlayıcısını yükler.

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. PacketEvents 2.x isteğe bağlıdır. Kuruluysa ItemsEngine sunucudaki API'yi kullanır; kurulu değilse gömülü 2.13.0 sağlayıcısı otomatik başlar.
5. ItemsAdder JAR'ını aynı sunucuya kurmayın; iki sağlayıcının birlikte çalışması desteklenmez.
6. 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-veya-emoji>%	CraftEngine font görselinin veya emoji: aliasının Unicode glifi
%img_<namespace>:<sprite>:<satır>:<sütun>%	CraftEngine sprite sheet hücresinin 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/emoji sözdizimi
:<namespace>:<sprite>:<satır>:<sütun>:	CraftEngine sprite sheet hücresinin satır içi karşılığı
: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

Chat, menü, TAB ve scoreboard satır içi desteği

ItemsEngine 1.5.0, üçüncü taraf plugin FontImageWrapper çağırmasa bile PacketEvents'in giden paket olayı üzerinden metni dönüştürür. :görsel:, :namespace:görsel:, sprite hücreleri ve :offset_N:; sistem/oyuncu sohbeti, actionbar, title/subtitle, bossbar, GUI başlığı, TAB header/footer ve oyuncu görünen adları, scoreboard score/objective ve takım prefix/suffix bileşenlerinde aynı CraftEngine assetine çözülür. <image:...> ve <shift:N> biçimleri de CraftEngine'in doğal biçimleri olarak çalışmaya devam eder.

ItemsAdder'ın belgelenmiş <noshadow metin>, <r metin>, <w metin>, <j metin>, <rw metin>, <rj metin> ve <b metin> efektleri, resmî özel HEX renk sinyallerine çevrilir. Animasyonun görünmesi için kullanılan resource pack'in ilgili ItemsAdder shaderlarını içermesi gerekir. Saf metin bileşenlerindeki <!i>/<i> ve pasif renk/dekorasyon etiketleri de işlenir; click, hover, insertion, selector ve NBT etiketleri güven sınırı nedeniyle küresel olarak yorumlanmaz.

CraftEngine'in network.intercept-packets ayarına bağımlılık yoktur. /itemsengine status çıktısında packets=external@... kurulu PacketEvents'in, packets=builtin@2.13.0 gömülü sağlayıcının seçildiğini gösterir. packets-active=true inline-surfaces=12 bütün doğrulanmış yüzeylerin etkin olduğunu; false veya 0 ise dönüşümün güvenli biçimde kapandığını belirtir.

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%. CraftEngine'de emoji: namespace:vipplus_icon_tag girdisi bir sprite hücresine işaret ediyorsa %img_vipplus_icon_tag% eski scoreboard/config değiştirilmeden aynı asseti gösterir. Kısa ad yalnızca tek bir image/emoji kaydıyla eşleşiyorsa çözümlenir; belirsiz veya bilinmeyen değerler sahte veri üretmez. Sprite koordinatları 0..4096, kaydırma -8192..8192, indekslenen hücre sayısı ve liste çıktıları ise güvenli sınırlarla kısıtlıdır.

Ekranda literal placeholder kalırsa

• /papi parse me %img_namespace:id% ile expansion zincirini sınayın; %img_*% normal sohbet komutu değildir. ItemsAdder'ın belgelenmiş görsel listeleme komutu /iaimage'dır.
• /itemsengine status çıktısında placeholders=true olmalı ve images sayısı CraftEngine image + çözümlenebilir emoji aliaslarını içermelidir.
• <t:decoration>None</t> ItemsAdder placeholder'ı değildir; Lands'in tema/çeviri etiketidir. Bu metin literal kalıyorsa Lands placeholder'ını scoreboard'a vermeden önce Lands'in kendi formatter/placeholder seçeneğini kullanın veya scoreboard pluginindeki Lands entegrasyonunu düzeltin. ItemsEngine başka pluginlerin özel <t:...> etiketlerini küresel olarak değiştirmez.

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	Gömülü + haricî PacketEvents probu geçti
Folia stable	1.21.11 build 14	21	26.7.4	Gömülü + haricî PacketEvents probu geçti
Paper stable	26.2 build 92	25	26.7.4	Gömülü + haricî PacketEvents probu geçti
Folia beta	26.2 build 1	25	26.7.4	Gömülü + haricî PacketEvents 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.

ItemsEngine is distributed under GPL-3.0 to remain compatible with its bundled PacketEvents provider; attribution is recorded in THIRD_PARTY_NOTICES.

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.
• Uses a server-installed PacketEvents API when present; otherwise loads an isolated PacketEvents 2.13.0 provider.

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. PacketEvents 2.x is optional. ItemsEngine uses the server plugin when installed and starts its built-in 2.13.0 provider otherwise.
5. Do not install the ItemsAdder JAR on the same server; dual providers are unsupported.
6. 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-or-emoji>%	Unicode glyph of a CraftEngine font image or emoji: alias
%img_<namespace>:<sprite>:<row>:<column>%	Unicode glyph of a CraftEngine sprite-sheet cell
%img_offset_-16%, %img_offset_16%	Negative/positive pixel shift generated by CraftEngine's raw font metrics
:<image>:, :<namespace>:<image>:	ItemsAdder inline image/emoji syntax
:<namespace>:<sprite>:<row>:<column>:	Inline CraftEngine sprite-sheet cell
: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

Inline chat, menu, TAB, and scoreboard support

ItemsEngine 1.5.0 transforms outbound text through PacketEvents send events even when a third-party plugin never calls FontImageWrapper. :image:, :namespace:image:, sprite cells, and :offset_N: resolve to the same CraftEngine asset in system/player chat, actionbar, title/subtitle, bossbar, GUI titles, TAB header/footer and player display names, scoreboard score/objective, and team prefix/suffix components. CraftEngine's native <image:...> and <shift:N> forms continue to work unchanged.

The documented ItemsAdder <noshadow text>, <r text>, <w text>, <j text>, <rw text>, <rj text>, and <b text> effects are mapped to their official special HEX shader signals. The resource pack must still contain the corresponding ItemsAdder shaders for animation to appear. Pure text components also accept <!i>/<i> and passive color/decoration tags; click, hover, insertion, selector, and NBT tags are not globally interpreted across the trust boundary.

CraftEngine's network.intercept-packets setting is not required. In /itemsengine status, packets=external@... identifies the installed PacketEvents provider and packets=builtin@2.13.0 the embedded provider. packets-active=true inline-surfaces=12 proves all verified surfaces are active; false or 0 means conversion failed closed.

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%. If a CraftEngine emoji: namespace:vipplus_icon_tag entry targets a sprite cell, the unchanged %img_vipplus_icon_tag% form renders that same asset. A short name resolves only when unique across image and emoji entries; ambiguous and unknown values fail closed. Sprite coordinates are bounded to 0..4096, offsets to -8192..8192, and indexed cells/list output are safely bounded.

If a literal placeholder remains on screen

• Test the expansion chain with /papi parse me %img_namespace:id%; %img_*% is not a normal chat command. ItemsAdder's documented image-list command is /iaimage.
• /itemsengine status must report placeholders=true; its images count includes CraftEngine images plus resolvable emoji aliases.
• <t:decoration>None</t> is not an ItemsAdder placeholder. It is a Lands theme/translation tag. If it remains literal, use the Lands-formatted placeholder/output or fix the scoreboard plugin's Lands integration. ItemsEngine intentionally does not rewrite another plugin's private <t:...> tags globally.

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	Built-in + external PacketEvents probes passed
Folia stable	1.21.11 build 14	21	26.7.4	Built-in + external PacketEvents probes passed
Paper stable	26.2 build 92	25	26.7.4	Built-in + external PacketEvents probes passed
Folia beta	26.2 build 1	25	26.7.4	Built-in + external PacketEvents probes 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.