Forest Hue's Companion NPCs

A Hytale companion mod that lets you recruit NPC companions and control them through flexible roles and stances.

Companions can fight alongside you, farm assigned crop areas, mine tunnels or specific resources, loot items, carry their own inventory, and deposit supplies into linked chests.

They also level up through combat, mining, and farming, earn gear rewards, and can be equipped and managed directly through the companion UI.

I've created a Discord server where I'll link my personal server for testing beta builds of the mod, reporting issues, suggesting ideas, etc. Join the Companion Crew! 
https://discord.gg/gzGpS5fqg- new link 8/11/26

v0.6.0 is released! - The "Companion Possession" update (currently in review by CurseForge)

Become your companion, lead a group of companions into battle while your real body stays behind, or just scout ahead with a companion, or even use a stationed companion to quickly take control at a far location.
When switching with a companion your body inherits the companion's current stance (if the companion is set to Stay your body will stay, if set to Follow it will follow, etc.).
If you die as the companion you are sent back to your body (and the companion is fallen).
If the companion in your body gets your body killed then you instantly die (and the companion is released for its soul to return to).
You can set a cost to possess a companion in the avatar JSON settings as well as some other useful settings. Be careful straying too far from your body ("your control will fade") as you could end up not being able to return (chunk may be unloaded, tested at 250+ blocks, distance warning frequency can be set in the JSON). Max control time set = 0 in the JSON results in no time limit for the body swap.
Exiting the game as the companion may/may not cause issues, same with portals. I just wouldn't try it to be safe.

NOTE: This version of my mod (0.6.0) is intended for Hytale version 0.6.0! - As of now 0.6.0 is in Pre-release (pre 11) so this mod will only work properly for the pre-release and 0.6.0 when it releases.
IT WILL NOT WORK PROPERLY WITH THE CURRENT 0.5.7 Release!

0.6.0 Changes:

 - Added experimental companion body control / possession (please report any bugs).
  - Added Control Selected Companion / Return to Player Body UI flow.
  - Added avatar JSON settings for enabling possession, max control time, optional possession cost, and body-distance  warning.

  - Possession swaps player/companion inventory, skin, model, and position during possession/return.
  - It will block normal companion commands while you are possessing a companion.

  Map / UI

  - Added companion world map markers.
  - Added Map: ON/OFF toggle to the companion panel.
  - Moved Location under the map toggle.
  - Added Block distance from player to selected companion.
  - Added proper Last known location: display for fallen companions.

  - Patrol companions now stay committed to combat instead of being repeatedly pulled back to the patrol route by ranged enemies.

  - After combat ends, Patrol companions return to their original patrol route.

  Farming / Deposits

  - Mining deposit flow also resumes cleanly when storage cannot accept items.

  Equipment / Assets / Build

  - Updated bundled HyUI runtime to HyUI-0.9.8-all.jar (no dependency needed).
  - Added/restored HyGuns companion visual assets.
  - Added safer UI preview handling for optional HyGuns-style weapon proxy items.

v0.5.1 update is released! - Stay Bug Fix
Change - Fixed issue where companions set to Stay are still being pulled to the player (and back to their stay location) over and over

v0.5.0 update is released! - The "keeping up with the Hytale Team" update 

NOTE: This version of my mod (0.5.0) is intended for Hytale version 0.6.0! - As of now 0.6.0 is in Pre-release (pre 9.1) so this mod will only work properly for the pre-release and 0.6.0 when it releases.
IT WILL NOT WORK PROPERLY WITH THE CURRENT 0.5.7 Release!

0.5.0 Changes:

-Several bug fixes related to changes made to the game by the Hytale Team that were breaking my mod in the prerelease.

-Revised Companion Spawns!  Companions spawn in the following locations/times at a 1% chance.
All in Zone 1:
  - 00-03 VariantA1 Shores
  - 03-06 VariantB1 Plains 
  - 03-06 VariantC1 Forests 
  - 06-09 VariantA2 Azure 
  - 09-12 VariantB2 Mountains
  - 09-12 VariantC2 Autumn 
  - 12-15 VariantA3 Shores
  - 15-18 VariantB3 Swamps
  - 15-18 VariantC3 Forests 
  - 18-21 VariantA4 Azure 
  - 21-24 VariantB4 Plains
  - 21-24 VariantC4 Autumn

-Added some support for Hyguns (companion use). Hyguns is currently out of date and causes problems but I've added support for the companions to use their guns (no gun effects and flamethrowers and grenades do not work as intended). If Hyguns is updated I'll work on this more.
- Fixed gun animations, they will now shoot as expected (and damage correctly).
- Addded gun kiting behaviour. 
- Miners can now "sweet pick" some items like berry bushes.
- Much better optimization for multiple farmers working at once.
- Reduced  or removed impact of portals to companions.
- Companions now do not keep poison effect forever (or until resummoned).
- Improved json settings for more customization.
- Added a re-roll appearance button to the UI.
- Worked on more stability and optimization overall (tested with about 300 wild companions and 15 farmers, although I recommend keeping it lower)
- Tons more tweaks and fixes I stumbled upon while working.
-Special Note for Recipe Overrides: It will create a mod (Recipe Override Mod) that you will see in your mod list. Do NOT activate it, it is not needed. Leave it unchecked.

v0.4.0 update is released! - The beacon/bug fix update
Note: this build is meant for Hytale 0.5.4 and will have issues in other builds.
- Several bug fixes
- New spawn system
- New Item Companion Beacon
- Toggle to allow auto equip of gear rewards for each companion in the UI
- Keyboard added to the UI for controller support
- Companions now block
- Revamped Max Defend, it will now try to block about 1/3 of the time and protect itself much more than Fight.
- Fix for issues going through portals

New Demo coming soon! - Note there are some issues when playing in the pre-release that will be addressed in the next update.

v0.3.0 update is released! - The Teams Update



Changes include:

• Default wild companion spawns have been dramatically reduced down to a 1-3% chance to spawn (while still keeping all 12 types!), only in certain zones and only at certain times (zone times are offset to prevent overlap). Measures are in place to prevent farming of companions in an area.
• Added a Wild Spawn Settings json, which can add more supplemental spawns if desired and set other settings for the spawns. Example of json:
  {
    "enabled": true,
    "radiusBlocks": 120,
    "maxWildCompanionsPerPlayer": 12,
    "despawnExtraWildCompanions": false,
    "supplementalPluginSpawnsEnabled": true,
    "minSpawnDistanceFromPlayerBlocks": 25,
    "maxSpawnDistanceFromPlayerBlocks": 120,
    "minWildCompanionSpacingBlocks": 20,
    "_note": "Wild recruitables use the world spawn tables by default. Set supplementalPluginSpawnsEnabled=true only if you want extra plugin-driven recruitable spawns."
  }
• Teams have been added. Now a player can select a team (red, blue, green, or gold) and battle other teams. Team settings are accessable from the team_settings.json that will allow to set a cooldown time for switching teams if needed (-1 = switch disabled, 0 switch at anytime, any positive number will be the seconds before you can switch teams) Also a setting to remove team color from companion nametag.
• Bonus: Orange Team - the orange team is an NPC team that will attack a random player in waves. The team can be turned on in the orange_team_settings.json and configured as needed. Note 1/3 of orange team forces will be ranged attackers starting a level 5.
• Changed the 'Mine For' functionality to more align with the GlymeraWorker mod (only in mining functionality not in box setting or setting what to mine for) Note: regular 'Mine' functionality is for digging straight tunnels/squares. Also note: Miners set to Free will mine anything in their path, be careful with this.
• Several bug fixes and improvements including but not limited to: a bug that caused working companions to be pulled to the player, issue with companions getting duplicated upon reloading, added an autonomous_worker.json setting to allow working companions to be suspended when out of range and return to work when getting back in range (can be set as needed, prevents despawning issues) Note: depending on how this is setup it can cause companions to be [STORED] when leaving range, this is up to you and depending on the number of companions working/entities in the loaded area could respond differently (this is needed for users trying to get better performance with larger numbers of companions), crashing bug found by a user related to companion updates, auto-restart of workers when reloading, added a mining_settings.json to allow miners to deposit at a set mined block number, combat settings that allow user to set distance ranged attacks will work (max may be limited by the game engine), added ranged weapon preview stability in the UI, improved follow recovery and reduced repeated leash teleports in some vertical-distance cases.
  
  Important notes:
  - normal wild recruitables use the world spawn tables by default
  - `supplementalPluginSpawnsEnabled` is optional and only adds extra plugin-driven recruitable spawns
  - if you want the default world-only behavior, leave `supplementalPluginSpawnsEnabled` set to `false`
  
  I'll be adding a new demo video for 0.3.0 soon (possibly today if I can finish). It will cover all old and new functionality and explain all json settings.
  
  0.3.0 NOTE - I still need a lot of testing from players to make sure there are no more bugs (especially with the new Teams functionality). Please report any bugs encountered either here or in the discord. Please make sure that you are not seeing results of setting up the json config files in a certain way before reporting. 
  
  If curious the spawn locations and times are as follows:

   - Zone 1:
        - Env_Zone1_Azure
        - Env_Zone1_Autumn
        - Env_Zone1_Mountains
    - Zone 2:
        - Env_Zone2_Plateaus
        - Env_Zone2_Oasis
    - Zone 3:
        - Env_Zone3_Forests
        - Env_Zone3_Shores
        - Env_Zone3_Tundra
    - Zone 4:
        - Env_Zone4_Jungles
        - Env_Zone4_Villages_Forests
        - Env_Zone4_Volcanoes

    Current time windows:

    - 10-12
        - Env_Zone1_Azure
        - Env_Zone2_Plateaus
        - Env_Zone3_Shores
        - Env_Zone4_Jungles
    - 12-14
        - Env_Zone1_Autumn
        - Env_Zone2_Plateaus
        - Env_Zone3_Forests
        - Env_Zone4_Villages_Forests
    - 14-16
        - Env_Zone1_Mountains
        - Env_Zone2_Oasis
        - Env_Zone3_Tundra
        - Env_Zone4_Volcanoes

    Matching despawn windows are the inverse:

    - 10-12 -> 12-10
    - 12-14 -> 14-12
    - 14-16 -> 16-14
  
  Note that managed companions start at 200 health, whereas wild companions can range from 140-170.

  v0.2.0 update is released!
  
  Changes include:

- There are now 4 different skin tones for companions

- There are now several more clothing options and combinations. There are now thousands of potential companion combinations (skin tone, clothing, hair) 

- Added an auto-revive option. (Note: you must run the mod one time create the json or to update the existing revive-config).
Example usage:                             

- Improved 'Mine For' (miner will now stop running in place when searching wider area or when cannot find block in area)

- Improved Mining (miner has better repositioning when moving into a new lane)
- Default companion weapons have been changed from iron to stone (or a club)
- Slightly changed companion spawning rate for balance



Base Features include:

  - Recruitable companion NPCs found in the world (use F to recurit. Companions are found in Zone 1 - Drifting Plains, Seedling Woods, The Fens, Autumn Forest, Azure Forest, and Rocky Terrain/Swamps)
  - Summon and dismiss owned companions
  - Role system:
      - Fighter
      - Farmer
      - Miner
Note: a companion's role can be changed at any time and progress is saved for each role
  - Stance system:
      - Follow
      - Stay
      - Free
      - Patrol
  - Companion combat assistance
  - Reactive defense when enemies attack you or the companion
  - Melee and ranged weapon support
  - Companion equipment system:
      - weapons
      - armor
      - offhand items

  - Companion Radio craftable item (in the Workbench > Tinkering tab) that can control companions remotely
  - Companion inventory management
  - Item transfer between player and companion - with click-slot-to-move functionality
  - Loot pickup support
  - Farming system with assignable farm area (use TL - top left corner and BR - bottom right corner buttons to set farm area) Note: UI buttons change depending on the companion's role
  - Mining system:
      - directional mining
      - mine-for specific resource mining
  - Linked chest storage and deposit behavior (auto-deposits occur in farming loop and mining when full or deposit on command)
  - Combat, mining, and farming progression
  - Level-up reward gear and items (level up gear is auto-equipped)
  - External config support for changing level-up rewards outside the game (located in AppData\Roaming\Hytale\UserData\Saves\Your_Save_Name\mods\ForestHue_CompanionNPCs\progression-config) Note: incorrect asset names WILL cause a crash
  - External config support for changing revive costs outside the game (located in AppData\Roaming\Hytale\UserData\Saves\Your_Save_Name\mods\ForestHue_CompanionNPCs\revive-config) Note: incorrect asset names WILL cause a crash
Example:

{

Note: You'll need to run the mod once for the json files to be created.

  - Companion UI for status, equipment, inventory, commands, and live updates
  - Appearance persistence and managed companion restoration
  - Revive support for fallen companions

Note: UI Command buttons change depending on the companion's role

Demo Video

Note: some functionality does not work in Creative Mode.

Server Usage  - so far I've not had any issues using the mod on a server with multiple players, but this has been very limited in testing, I need feedback on issues using it on a server. Tested using Apex Hosting server.

Farming Note: The current supported crops are: Wheat, Lettuce, Carrots, Corn, Cauliflower, Turnip, Aubergine, Pumpkin, Tomato, Chili, Rice, Cotton, Onion, and Potato. Others may be added in a future update if there are users wanting it.

Commands for testing purposes - set self to OP then you can use:

- Open the UI quick command: /fhc (note there is a "fallback UI" with less functionality that may appear if something fails, but you'll likely never see it unless you explicitly call it using a command)

  Roster

  - /companion create [name]
    Create a new companion.
  - /companion list
    Show your full roster.
  - /companion select <name|number>
    Select which companion later commands target.
  - /companion rename <new name>
    Rename the selected companion.

  Summon / Dismiss

  - /companion summon [name|all]
    Summon one companion or all companions.
  - /companion dismiss [name|all]
    Dismiss one companion or all companions.

  Role

  - /companion fighter [name]
    Set role to Fighter.
  - /companion farmer [name]
    Set role to Farmer.
  - /companion miner [name]
    Set role to Miner.

  Aliases:

  - fight, defend -> fighter
  - farm -> farmer
  - mine -> miner

  Stance

  - /companion follow [name]
    Companion follows you.
  - /companion stay [name]
    Companion stays in place.
  - /companion patrol [name]
    Companion patrols around its anchor area.
  - /companion free [name]
    Companion acts with no movement restrictions.

  Inventory / Equipment

  - /companion givehand [name]
    Give your held item to the companion.
  - /companion takehand [name]
    Take an item from the companion.
  - /companion giveall [name]
    Give all possible items to the companion.
  - /companion takeall [name]
    Take all items from the companion.
  - /companion equip [name]
    Equip your held armor or weapon onto the companion.

  Storage

  - /companion chestlink
    Link the chest you are looking at.
  - /companion chestunlink
    Unlink the chest you are looking at.
  - /companion deposit
    Force active companions to deposit items.

  Appearance

  - /companion appearance <modelId>
    Set a specific appearance model.
  - /companion appearancerandom
    Clear the appearance override.
  - /companion rerollappearance [name]
    Reroll the companion’s appearance.

  Status / UI

  - /companion status [name]
    Show companion status.
  - /companion debug [name]
    Show debug information.
  - /companion progression [name]
    Show progression details.
  - /companion menu
    Open the text menu.
  - /companion uimenu
    Open the graphical UI.

  Aliases:

  - levels -> progression
  - menuui -> uimenu

  Recovery

  - /companion fallen
    List fallen companions.
  - /companion revive <name|number>
    Revive a fallen companion.

  Utility

  - /companion roles
    Show role info.
  - /companion rolesall
    Show all role-related info.
  - /companion models
    List available appearance models.
  - /companion farmtest
    Farm-related test command.
  - /companion help
    Show help.

The new 0.3.0 command additions are:

  - /companion team <red|blue|green|gold|clear>
      - set or clear your player team
  - /companion clearteam
      - clear your current team directly
  - /companion orangestatus
      - show the Orange Team NPC team wave/scheduler status
  - /companion orangereset
      - reset Orange Team NPC team progression back to wave 1
  - /companion testspawn <none|red|blue|green|gold|orange> [fighter|farmer|miner|ranged] [slot 1-4]
      - spawn a synthetic team test companion
  - /companion testclear
      - clear your synthetic team test companions

Note: This is my take on a companion mod. I took a lot of inspiration from other companion mods. I encourage everyone to check them out.
Special thank you to the creators for the inspiration and the awesome mods!

- Cubia's Companions
- RPG Companions
- AmigoNPC
- My Friends
- Alec's Animal Husbandry!

Future enhancements include:

-New companion types (Hero? Skeleton? Legend? who knows?)
-item/functionality to switch control with any companion (planned for 0.6.0)
-More crop support
-Fertilizer support in farming loop
-Cross-mod support for companion hostility against modded NPCs

Other planned enhancements:

- More Companion variants with skin tone variations - added in 0.2.0
- Selectable teams for "companion battles" between players or player groups - added in 0.3.0
- Attempting to use and incorporate the Combat Action Evaluator as much as I can
- Remaining bug fixes (please report any bugs found) - updated each release
- Companion swimming - limited by game engine
- Proper companion animations when mining, farming, etc.
- P vs C damage switch
- Smarter pathing to target (mining, farming) - added in 0.2.0
- Better Mine For functionality - updated in 0.3.0
- Selected companion image in UI (right side of gear section)
- Reduce java-driven behavior as much as possible and rely more on asset/role-driven scaffolding

Suggestions are welcome! I have not had much in the way of feedback when testing so I would appreciate any suggessions and all suggestions will be considered. Features that should be added? Please feel free to suggest anything.