Alec's Tamework!

Alec's Tamework is a modular NPC framework for Hytale built to let modders add rich NPC features through assets, templates, and config-driven systems instead of writing custom Java code. It embeds Patchwork for non-destructive asset patching, so artists, designers, and less technical modders can build advanced optional integrations without first creating their own plugin.

Tamework also aims to establish a shared standard for tameable NPCs in Hytale so different mods can work on top of similar ownership, naming, command, progression, and companion-management systems instead of forcing players to learn a different workflow for every mod.

This Is a Library

Tamework is a framework dependency for other mods. It does not add a standalone gameplay expansion by itself.

If you are a player looking for gameplay built on Tamework, start with Alec's Animal Husbandry or Alec's Cats, or see the wiki for the specific mod you are using.

Why Tamework

No Java required for most integrations: the main integration path is built around JSON assets, templates, role wiring, and Tw*Config files rather than custom Java systems.
Non-destructive asset patching: Embedded Patchwork can add, merge, and insert JSON into one or many Hytale assets with composable conditions. It regenerates at startup, on an administrator reload, and after relevant directory-pack edits, and it reports which changes require a restart.
A shared standard for tameable NPCs: mods built on Tamework can present familiar ownership, naming, command, linked-panel, breeding, and progression behavior instead of inventing incompatible one-off systems.
Optimized interactions: build taming, feeding, mounting, harvesting, breeding, and custom interactions with TwInteractionConfig and TameworkInteract.
Boss and combat tools: author sweeping beams, targeted leaps, native boss health bars, projectile landing markers, and hatching NPCs through assets. Targeted leaps require Hytale 0.6.7 or later.
Ownership and tame-state systems: use reusable builders and role-scoped policy for owner checks, protection rules, and companion behavior.
Spawner, naming, and command items: capture and respawn NPCs with metadata, name companions with custom items, and build command tools with radial and linked-panel support.
Linked companion runtime: manage loaded, unloaded, dead, and lost companions through a linked panel with recall, home, revive, and related flows.
Progression systems: add happiness, needs, breeding, life stage, and trait-driven variation through config-driven systems.
Coop integration: configured coops can accept eligible live companions or canonical filled capture items and release the same saved companion again; other coops retain their normal behavior.
Durable population controls: separate per-player limits for companions out in the world and companions owned, plus role-defined group limits, count every saved companion across unloads, capture items, rosters, coops, death, travel, and restarts. Direct SimpleClaims checks can still limit breeding by claim and apply its native tamed-companion damage rules.
Advanced extension points when needed: bridge into custom logic through hooks and optional integrations without giving up the higher-level framework.
Stable integration data: Public API 3.0 exposes companion profiles, bonded companions, population groups, admission providers, and namespaced profile extension data, including revision-fenced compare-and-set writes for integrations that need restart-safe custom state. Command rosters, timed summons, provisioning, and paid revival are configured through Tw*Config assets instead of public APIs.
Companion data in the world folder: Tamework 5.0 saves companions as plain files under universe/Tamework/Companions, so normal Hytale world backups include them. There is no database.

Requirements and Upgrades

Tamework 5.0 requires Hytale server 0.6.0 or later.
Back up the world's universe folder before updating.
The first start on a 3.x or 4.x world imports all companion data automatically before worlds load. The old database files are only read and stay unchanged. A later release removes this importer, so 3.x and 4.x worlds must run a 5.0.x release once before they update further.
2.x worlds are not imported. Run Tamework 4.3.x once first, or start fresh with /tw persistence start-fresh.
Mods that call the Tamework Java API need a version built for Public API 3.0.
See World Migration for Server Admins for the full upgrade guide.

What Integration Looks Like

Integrating Tamework is usually a content-authoring workflow, not a programming workflow. Mods can use it in two ways:

Required Dependency

Wire your desired Tamework behavior directly into your NPC, item, config, and other server-side assets.
Add configs for the Tamework systems you want to support.
Add Alec's Tamework as a required dependency when deploying to CurseForge.

Optional Dependency

Keep your base assets clean of any references to Tamework functionality.
Create asset patches under Server/Patchwork/Patches that add Tamework actions, interactions, configs, and other JSON-based behavior only when Tamework is installed. Use Targets for shared operations across several assets and When.ModInstalled for optional cross-mod gates. The legacy Server/Tamework/Patches root remains readable while Tamework is installed, but new integrations should use the neutral Patchwork root.
Add configs for the Tamework systems you want to support.
Declare Patchwork as a dependency for asset-only patch packs. Declare Alec's Tamework too when the patch uses Tamework macros or behavior.

Optional example asset pack

The Tamework plugin jar does not include sample NPCs, sample items, or sample progression configs. This keeps a library-only installation dormant until a downstream mod supplies matching assets. Reusable framework media, including the Nametag and Soul Lantern asset closures, remain in the main jar so dependent mods can reference them without installing the examples pack.

Build the optional examples with ./gradlew exampleAssetPack. Install the generated Alec's Tamework! Examples v.zip beside the Tamework jar and explicitly enable it only when you need the sample graph. The pack is disabled by default, declares Tamework as a dependency, and can be omitted from production servers.

In both cases, no Java is required: install the optional example pack when you need a starting point, then copy and adapt its assets. Enable the systems you want through comprehensive configs, and polish. The full setup and implementation details can be found in the wiki.

Advanced integrations should use the Public API for canonical profiles and namespaced profile extension data instead of writing Tamework metadata or companion store files directly. Always check the relevant capability before using an optional API surface.

Tamework also builds one immutable runtime activation plan at startup. It installs no systems, feature listeners, or workers for an unused module. See Runtime Activation for automatic evidence, restart-bound reloads, /tw runtime status, and the Runeteria/RuneProfessions activation contract.

Player-facing Tamework config strings support server.lang keys. Built-in talents, traits, command labels, interaction messages, happiness labels, and major UI labels use language keys so translation packs can override copy without changing behavior assets.

Documentation

Licensing

Tamework is licensed under the GNU General Public License v3.0 with an attribution clause. You may use, modify, and redistribute Tamework under GPLv3.

Distributed versions and derivative works must credit "Alec's Tamework!" by Alechilles in their listing, description, or documentation.

Issue Reporting

If you run into a bug, integration issue, or behavior problem, report it in the Discord server:

https://discord.gg/E8n8RgTTdq

Telemetry

Alec's Tamework uses Beacon for its own crash, error, lifecycle, performance, and usage telemetry. The Patchwork runtime embedded in Tamework reports Patchwork operations through a separate hosted-only project.

Tamework 5.0 no longer sends automatic persistence diagnostics or database attachments. Automatic events never attach save data or companion store files. Set telemetry.enabled to false in Tamework's global settings, or change Tamework's entry in /beacon consent, to opt out.

Automatic aggregate Tamework and Patchwork telemetry does not include personally identifiable information and is used to diagnose issues and improve the mods. Reports you submit manually can include the contact text and server-log attachments you choose to send; review those fields and files before submitting.

Tamework and Patchwork have independent consent entries, so disabling Tamework telemetry does not implicitly disable Patchwork telemetry. You may change either entry at any time in the `/beacon consent` menu.

Alec's Tamework also reports anonymized active user numbers to HStats to track active user count summaries.