Glymera Cats v4.0

Hytale Stable-5 Migration
All Glymera plugins updated for Hytale Server 0.5.x (Stable 5)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
​

All Glymera plugins have been updated for compatibility with Hytale Server 0.5.x (Stable 5). The previous versions targeted Hytale Server 0.4.x (Stable 4).

This document covers what changed in the Hytale Server API between Stable 4 and Stable 5, and which adjustments were required across plugins so that things keep working.

◆ Why a new major version

Stable 5 introduced a number of source-incompatible API changes. A plugin compiled against Stable 4 will either fail to load, fail silently on first use, or — in a few cases — crash the world thread. Because the surface of change is large, every plugin received a new major version number, even when the only functional behaviour change was a manifest flag.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━​

◆ What changed in Hytale Stable 5

▸ Vector math

• Internal Hytale vector types were replaced by JOML.
• com.hypixel.hytale.math.vector.Vector3d/3i/3f → org.joml.Vector3d/3i/3f
• Rotation helpers now use the Rotation3fc interface where the older API took a concrete Rotation3f.

▸ Particle / Sound API

• SpawnParticleSystem constructors gained additional arguments.
• PlaySoundEvent3D / ambient sound registration semantics tightened — long-running or looped sounds attached to a block must now use the block-state AmbientSoundEventId path; firing them with PlaySoundEvent3D from a tick handler no longer behaves correctly.

▸ Asset pack registration

• AssetModule.registerPack(...) now requires a PackSource parameter (use PackSource.MODS for plugin-installed packs).
• The IncludesAssetPack manifest flag is now strictly enforced. If a plugin both declares IncludesAssetPack: true and registers a runtime pack from its setup code, Hytale detects this as a duplicate registration and aborts boot with "Duplicate asset pack ... Remove the duplicate." For affected plugins IncludesAssetPack is now set to false; the actual asset pack is installed by the plugin at startup as before.

▸ HUD / UI system

• The HudManager API has moved to a keyed model — HUD entries now require a stable key and explicit lifecycle hooks.
• InteractiveCustomUIPage event bindings are wiped if the page is rebuilt while the client is processing a click. Plugins refreshing a HUD per tick had to throttle the rebuild rate (commonly to 1 Hz) so button presses are not lost.

▸ Player handles

• The Player component and the PlayerRef reference have been split. Plugins previously juggling one or the other now need to consider both.
• ServerPlayerListPlayer requires a worldUuid field — entries without it are silently dropped from the tab list.

▸ Entity utilities

• EntityUtils.toHolder(...) was removed. Lookups need to go through the entity store directly or via Ref<EntityStore>.

▸ Damage system

• Resistance fields on EntityEffect (damageResistanceValuesRaw, damageResistanceValues) now expect ResistanceModifier[], not StaticModifier[]. Plugins that previously injected resistances via reflection now use the ResistanceModifier(ResistanceCalculationType, float) constructor.
• The corresponding JSON CalculationType value "Multiplicative" is no longer accepted for damage resistance — it must be "Percent". Migrating large packs needed a bulk rewrite of Potion/Effect JSONs.
• Lethal-damage detection: EntityStatValue#getMin() is no longer a usable death-threshold. Lethal checks now compare the post-damage health against 0.0f directly. Plugins relying on the old behaviour would silently fail to fire and the player just died.

▸ ECS / system tick safety

• It is no longer legal to call mutating store methods (addComponent, removeEntity, …) directly from inside a system's tick handler. Doing so now throws IllegalStateException: Store is currently processing! Such calls must be deferred: either via the system's CommandBuffer, or by scheduling onto the next world tick with world.execute(...).

▸ Items, weapons and recipes

• Custom swords must declare Tags.Type: "Weapon" (not "Tool"), and they need their own complete InteractionVars block — these are no longer inherited from the parent template under Stable 5. A custom weapon without its own InteractionVars will spawn but cannot deal damage.
• Recipe bench IDs and recipe categories are now validated against the asset registry. Mistyped values cause Hytale to silently drop the recipe with no error message.

▸ Cosmetics

• CosmeticsToHide now only accepts a restricted, enumerated set of values. Custom values are rejected at asset-load time.

▸ Server authentication

After every Stable update the server's OAuth credentials must be refreshed:

1. auth logout
2. auth login device
3. Open the printed verification URL, complete the device authorisation
4. auth select <profile>

If the server is still on cached OAUTH_STORE credentials after a Stable update, every incoming player connection is rejected with serverAuthUnavailable and the client only sees "QUIC handshake failed".

▸ Manifest / ServerVersion

• Stable 5 enforces a recognisable ServerVersion declaration in each plugin's manifest.json. A malformed value prevents the server from booting. Glymera plugins declare "ServerVersion": "*" to remain agnostic across patch versions.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━​

◆ Plugin-data path

The plugin-data directory used by all Glymera plugins is now:

mods/de.glymera_<PluginName>/

(Previously it was plugins/<PluginName>/.) Existing configuration files are not migrated automatically — if you want to keep custom configuration from an older install, move the relevant files from the old plugins/ location into the new one before first launch.

GlymeraCats - Changelog

v2.0.0 (2026-04-22)

New Features

• Real cat sounds (replaces Leopard-Snow placeholders): 4 meow, 2 hiss, 1 purr variants (CC0 from BigSoundBank) shipped as OGGs in the asset pack. Three new SoundEvents: SFX_GlymeraCat_Meow, SFX_GlymeraCat_Hiss, SFX_GlymeraCat_Purr.
• Pet and feed via F-key (Interact): empty hand = hearts + purr. Raw meat = heal +200HP, item consumed, hearts + purr. Only works on cats the player owns.
• No more hit damage on own cats: DisableDamageGroups fully blocks player damage — no HP loss, no knockback, no hit particles. Client-side swing animation and click sound remain visible (not preventable server-side).

Changes

• Idle sounds are now per-cat and independent: random 90-150s cooldown per cat instead of a 20s global tick firing all cats in sync (prevents chorus effect). Owner now counts as a listener.
• Range for idle sounds raised from 8 to 16 blocks.
• Combat hiss: plays once on combat entry plus every 8-12s during active combat (was every 20s).
• Bite-meow removed — combat audio now runs only through the combat hiss scheduler.
• Low-HP distress call (<20% HP) is now a meow instead of a purr (more appropriate).
• Hearts particle fixed: uses "Hearts" instead of the missing "Merchant_Sold".

Technical Details

• Custom NPC action GlymeraCatsPetOrFeed registered via NPCPlugin.registerCoreComponentType() (analogous to GlymeraMerchant's OpenMerchantShop). Role JSONs extended with InteractionInstruction using sensor HasInteracted and actions LockOnInteractionTarget + GlymeraCatsPetOrFeed.
• PlayerInteractEvent does NOT fire for NPCs — the correct path is custom action + state machine in the role. Useful finding for future pet plugins.
• Static singleton GlymeraCats.INSTANCE so the static action class can reach plugin state.
• Per-cat cooldowns via ConcurrentHashMap (nextMeowAt, nextCombatHissAt) — no more global scheduler interval; tick checks cooldowns individually.
• Gson config backfill for new fields (meowIntervalMinMs/MaxMs, combatHissIntervalMinMs/MaxMs) — old v1.0.0 configs get defaults populated on load.
• Legacy CatInteractSystem (damage-based) is still in the code but never fires due to DisableDamageGroups — effectively dead code.

v1.0.0 (2026-04-18)

New Features

• Initial release: 1:1 clone of GlymeraDogs with Cat + Kitten instead of Dog + Corgi.
• Two types: adult Cat, juvenile Kitten. Both use previously dormant Hytale assets from Common/NPC/Pets/.
• 20 color variants: 10 cat coats (Brown, Chestnut, Amber, Rusty, ...) + 10 kitten variants.
• Command /gcat with sub-commands: spawn, list, come, call, dismiss, name, remove, status, preview, spawnpick, variants.
• Spawner block with fish recipe (Food_Fish_Raw + Life Essence) on the Alchemybench.
• UI page CatPage.ui with CatCard.ui, interactive (Call/Dismiss/Release via buttons).
• Call/Dismiss, follow logic, combat systems (Defend, SelfDefense), 100 cat + 100 kitten names.

Technical Details

• Package de.glymera.cats, main class GlymeraCats.
• 4 ECS systems: CatDefendSystem, CatSelfDefenseSystem, CatInteractSystem, CatSpawnerPlaceSystem.
• Color variant solution: multi-appearance with 22 model JSONs plus per-variant textures generated from a grayscale template (target color x pixel brightness with feature-preserve for eyes/nose/white areas). RandomAttachmentSets and GradientId do not work for Cat/Kitten models.
• Placeholder sounds: SFX_Leopard_Snow_Alerted and SFX_Leopard_Snow_Hurt (replaced in v2).