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. Feel free to join if you'd like. The server will have limited slots of course and will be mostly for testing purposes (companion saves will probably be removed periodically).
https://discord.gg/xk3r8jpT - new link 6/9/26

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:

Planned for 0.4.0:
-Companion beacon item to attract companions with a configurable cost
-New companion types (Hero? Skeleton? Legend? who knows?)
-Remaining known bug fixes
- Suggestions???

Planned for 0.5.0:
-SoulSwitch Medallion item/functionality to switch control with any companion
-More crop support
-Fertilizer support in farming loop
-Cross-mod support for companion hostility against modded NPCs
- Bug Fixes

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.