Ziggfreed's CommonLib

Ziggfreed's CommonLib

The shared library behind Ziggfreed's Hytale mods. A required dependency for some of them, and a toolkit for modders who want to build their own.

CommonLib is the battle-tested plumbing that Ziggfreed's mods stand on: 3D sound, camera effects, notifications and HUD helpers, a branching NPC dialogue engine, and a full co-op instance framework (parties, queues, leaderboards, rewards). Shipping it once means every mod that uses it behaves the same way and gets fixed in one place.

Do I need this?

If a mod's page lists Ziggfreed's CommonLib as a required dependency, yes: install it alongside that mod and you are done. If nothing you run asks for it, you do not need it.

There is nothing to set up. CommonLib adds no commands, no config files, no items, and no gameplay of its own. It loads quietly, the mods that depend on it do the rest, and it stays out of the way otherwise.

Install

1. Download ZiggfreedCommon-<version>.jar from the Versions tab.
2. Drop it into your server's Mods/ folder, next to the mod that needs it.
3. Make sure your Hytale server is in the Update 5 range (0.5.x).

Load CommonLib before the mods that depend on it (Hytale handles this automatically when a mod declares the dependency).

---

For modders

CommonLib is a mod-agnostic primitive library. Its only dependency is the Hytale server jar (zero coupling to any other mod), every utility is a static call, and it is reusable as-is. Add it as a compileOnly dependency, list it in your manifest.json dependencies so the server loads it first, and call what you need.

It is the foundation under Kweebec Nightmare, and is built to back any future Ziggfreed minigame, dungeon, or raid.

What's inside

• 3D sound - play any SoundEvent at a position or on an entity, with category and per-listener filtering.
• Camera - one-shot screen-shake effects and a top-down server camera apply/reset.
• Notifications and titles - styled toast notifications (Default / Danger / Warning / Success) and centered event banners.
• HUD and in-page toasts - install a custom HUD with strip/restore of the native one, plus a transport-agnostic in-page toast engine.
• Branching NPC dialogue engine - a generic conversation system (nodes, options, conditions, actions) with its own UI, a template DSL, and a structural validator. Ships its UI asset pack.
• Co-op instance framework - a searchable-invite party system, a Public / Party / Solo play-and-queue screen with a live launch timer, an end-game results screen, a bucketed leaderboard, and an asset-driven reward model with a no-loss inventory-full guard.
• Encounter framework - timed and banded per-entity effects (on-hit slows, debuffs, escalation bands), weighted spawn rosters with a wave director, a co-op zone-hold objective timer (extraction pads, capture points, king-of-the-hill), and floor-snapped runtime spawn placement.
• World helpers - a surface probe that floor-snaps placements onto procedural terrain, world-map and compass POI markers (global and per-player), and a hidden-until-discovered POI tracker.
• Utilities - asset-index cache, number formatter, command execution, hostility checks, entity identifiers, and a memoized damage-cause index, plus inventory helpers for custom resource items.

Author your own content, no Java required

Where it makes sense, CommonLib is driven by asset-pack JSON under Server/ZiggfreedCommon/ (dialogues and dialogue templates, instance presets, multi-phase bosses, banded effects, encounter rules, prefab placements, leaderboard layouts, and party settings), resolved defaults < pack < owner. A content pack can tune the framework without touching code.

---

Versions

Version	Notes
1.0.0	First stable release. The primitives, the dialogue engine, and the co-op instance + encounter framework are feature-complete for the 1.0 consumer surface. Adds runtime boss health scaling, boss world-map marker knobs, and same-identity reward merging.
0.3.2	Adds a reusable co-op "hold this zone" objective timer (extraction pads, capture points, king-of-the-hill) and per-phase helper-throwable cluster knobs on the multi-phase boss primitive.
0.3.1	Adds a shared segmented-tab / filter button style for consumer pages (party-size tabs, category chips).
0.3.0 and earlier	The core primitives (3D sound, camera, asset-index cache, command exec, inventory, notifications, HUD helper, surface probe) plus the branching NPC dialogue engine and its UI asset pack.

Made by Ziggfreed / Wintergreen Solutions.