# 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](https://www.curseforge.com/hytale/mods/alecs-animal-husbandry) or [Alec's Cats](https://www.curseforge.com/hytale/mods/alecs-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](https://wiki.hytalemodding.dev/mod/alecs-tamework/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](docs/Runtime-Activation.md) 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 - [Wiki Home](https://wiki.hytalemodding.dev/mod/alecs-tamework) - [Player Guides](https://wiki.hytalemodding.dev/mod/alecs-tamework/player-guides) - [Modder Documentation](https://wiki.hytalemodding.dev/mod/alecs-tamework/modder-documentation) - [Developer Documentation](https://wiki.hytalemodding.dev/mod/alecs-tamework/developer-documentation) - [HyDragon / API 3.0 Integration Guide](https://wiki.hytalemodding.dev/mod/alecs-tamework/hydragon-integration-guide) ## Licensing Tamework is licensed under the [GNU General Public License v3.0 with an attribution clause](LICENSE.txt). 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.