EchoPlayer

EchoPlayer is a persistent virtual player mod for Minecraft 1.20.1 / Forge.

It allows you to create multiple independent player avatars, directly possess and control them, and quickly switch between your main character and different avatars without launching additional Minecraft clients.

Hold Left Alt to open the possession wheel, point at a character, and release the key to switch control. Each avatar behaves as an independent player with its own identity, inventory, equipment, status, and persistent player data.

EchoPlayer is designed for multi-character gameplay, multiplayer mechanic testing, modpack compatibility testing, scene setup, and as a foundation for external automation or AI-controlled player systems.

Features

Direct Possession and Quick Switching

EchoPlayer allows you to directly take control of a virtual player as if it were your own character.

While possessing an avatar, you can:

• Move and look around normally
• Attack entities and break blocks
• Use items and interact with blocks
• Open containers
• Craft items
• Manage the avatar's inventory and equipment
• Ride entities and interact with the world normally

Hold Left Alt to open the possession wheel. Move the cursor toward a target and release the key to switch to it.

The wheel contains your original character as well as the avatars you are allowed to manage. You can switch directly from one avatar to another without returning to your original character first.

Select your original character to return to it, move the cursor back to the center to cancel, or press Esc to close the wheel.

Press O at any time to immediately stop possessing an avatar and return to your original character.

Both key bindings can be changed in Minecraft's Controls settings.

EchoPlayer also handles character orientation, camera state, riding, sleeping, and other relevant states during transitions.

The possession wheel does not pause the game and can only be opened while no other interface, such as the inventory or chat screen, is active.

Control ownership is always validated by the server. An avatar that is currently being controlled by another player or an automation controller may not be available for possession.

Independent Character State and Persistence

Every EchoPlayer avatar has its own persistent player identity and state.

Each avatar maintains its own:

• Inventory
• Equipment
• Health and absorption
• Hunger and saturation
• Experience
• Potion effects
• Attributes
• Item cooldowns
• Action state
• Player data

When you possess an avatar, you use that avatar's state rather than your original character's state. When possession ends, your original state is restored.

Avatar information, creators, access settings, and player data are saved with the world. Persistent avatars are restored when the world is reloaded or the server restarts.

Avatars also participate in the normal death and respawn process. If an avatar dies while being possessed, EchoPlayer handles the transition and state restoration appropriately.

While you are controlling an avatar, your original character still exists in the world as a physical entity. It may still take damage or die, so you should leave it somewhere safe before switching characters.

World Interaction and Multiplayer Visibility

EchoPlayer includes additional handling to make possessed avatars behave more consistently with real players.

This includes support for:

• Attacking and taking damage
• Item and experience pickup
• Projectile damage ownership
• Boat placement
• Riding entities
• Fishing bobbers
• Leash relationships
• Command execution identity
• Player selectors
• Sleeping player counts

When switching between characters, relevant relationships and states are transferred or restored where necessary.

Other players are kept synchronized with the currently controlled character, including its orientation and riding state. Internal entities used by EchoPlayer's possession system are hidden from normal multiplayer visibility where appropriate.

Custom Skins

EchoPlayer supports custom skins for individual avatars.

A skin can be assigned using:

• A Minecraft player name
• A skin image URL
• The avatar's default skin

Skin lookup by Minecraft player name requires the server to be able to access the corresponding online services.

Skin generation from an image URL uses MineSkin, so availability may depend on network conditions, service availability, and rate limits.

Mod Compatibility

EchoPlayer contains dedicated compatibility handling for several mods and systems.

These integrations are optional and are not required for EchoPlayer's basic possession functionality.

Touhou Little Maid

EchoPlayer maps maid owner queries to the corresponding character identity while switching between the original player and avatars.

This helps preserve behaviors that depend on player ownership.

Soul Spell ownership checks are also adapted so that, while possessing an avatar, compatible Soul Spells belonging to either the original character or the currently controlled avatar can be used appropriately, including releasing stored maids while preserving the item's original ownership information.

Curios API

Curios equipment is synchronized and restored when possessing, switching between, or returning from avatars.

Each character keeps its own independent Curios inventory.

Player Collars

EchoPlayer provides compatibility handling for player ownership and collar-related behavior, including:

• Owner identity lookup and storage
• Leash interactions
• Ownership transfer
• Pulling physics
• Clicker responses
• Collar dye interfaces
• Collar thorns damage

Yes Steve Model

When switching characters, EchoPlayer copies and resynchronizes the selected YSM model data.

This allows both the controlling client and other players in the same dimension to receive the appropriate model selection for the currently active character.

Vanilla Tamed Animals

Ownership checks for vanilla tameable animals are adapted so that owner relationships remain consistent while switching between the original player and avatars.

Compatibility support reflects the currently implemented integration scope and does not guarantee support for every version or feature of these mods.

Other mods that store custom inventories, capabilities, ownership information, or special player identity data may require additional compatibility handling.

Installation

EchoPlayer currently targets:

• Minecraft Java Edition: 1.20.1
• Mod Loader: Forge
• Java: 17

EchoPlayer must be installed on both the client and server in multiplayer.

For single-player worlds, installing the mod in the client instance's mods folder is sufficient.

In multiplayer, the server and participating clients should use the same EchoPlayer version.

Getting Started

After entering a world, create your first avatar:

/echoplayer spawn EchoOne

Then take control of it:

/echoplayer control EchoOne

The first command creates a persistent avatar at your current position and orientation. The second command possesses it.

Once possessed, you can move, interact with blocks, use items, fight, and play normally through that avatar.

Create another avatar:

/echoplayer spawn EchoTwo

Then hold Left Alt, point toward EchoTwo on the possession wheel, and release the key to switch directly to it.

To return to your original character, select it on the possession wheel, press O, or run:

/echoplayer unpossess

Avatar names cannot contain spaces and may contain up to 16 characters. EchoPlayer checks for name and identity conflicts when creating new avatars.

Commands and Permissions

The root command is:

/echoplayer

Commands that operate on existing avatars provide name completion based on the avatars you are currently allowed to manage.

Create an Avatar

/echoplayer spawn <name>

Creates a persistent avatar at your current position and records you as its creator.

Possess an Avatar

/echoplayer control <name>

Takes control of the specified avatar.

If you are already possessing another avatar, this command switches directly to the new target.

Stop Possessing

/echoplayer unpossess

Returns control to your original character while keeping the avatar and its data.

Remove an Avatar

/echoplayer remove <name>

Permanently removes the specified avatar and deletes its persistent player data.

Use unpossess instead if you only want to stop controlling an avatar without deleting it.

Set a Skin by Player Name

/echoplayer skin set <name> <skin_name>

Sets the avatar's skin using the skin associated with the specified Minecraft player name.

Set a Skin from a URL

/echoplayer skin url <name> <url>

Sets the avatar's skin using a skin image URL.

Clear a Custom Skin

/echoplayer skin clear <name>

Removes the avatar's custom skin.

Public Avatar Control

Check the current public-control setting:

/echoplayer config allow_other_players_control

Enable or disable it:

/echoplayer config allow_other_players_control <true|false>

Changing this setting requires permission level 2, normally an operator.

By default, only an avatar's creator can control it, remove it, or modify its skin.

When allow_other_players_control is enabled, other players are also allowed to perform these management operations.

This setting is saved with the world and is disabled by default.

Only one real player can directly possess a particular avatar at a time.

If an external automation controller currently owns the avatar's control input, whether a player can temporarily take over depends on the automation controller's possession-preemption policy.

Automation and AI Extension Interface

EchoPlayer is also designed to act as a foundation for external automation and AI control systems.

It exposes a control arbitration API that allows addon mods to acquire control of EchoPlayer avatars and provide their own automated behavior.

Possible extensions can implement features such as:

• Pathfinding
• Navigation to a target location
• Mining tasks
• Building from schematics
• Item collection
• Farming
• Combat behavior
• Task scheduling
• AI-driven decision making
• Integration with external control systems

EchoPlayer itself provides the persistent player entities, player-state handling, possession system, and control-ownership arbitration.

It does not automatically make avatars perform tasks on its own. Pathfinding, planning, automation logic, and AI behavior are provided by external extensions.

The main integration entry point is EchoPlayerControlApi.

Automation controllers acquire an exclusive control lease before writing input to an avatar. This prevents multiple systems from attempting to control the same character at the same time.

Automation controllers can choose how player possession should interact with their control lease.

With possession preemption disabled, players cannot possess an avatar while it is under automation control.

With possession preemption enabled, an authorized player may temporarily take control. EchoPlayer asks the automation controller to release its writable inputs, pauses the automation lease while the player is possessing the avatar, and restores automation control after the player leaves.

The API also provides lifecycle notifications for events such as:

• Player possession taking control from automation
• Player possession ending
• Automation control being restored
• Control leases being revoked
• Avatar removal or unloading
• Server shutdown

Automation leases can survive the normal death and respawn process and transfer to the replacement avatar instance with the same UUID.

This makes EchoPlayer suitable not only for manual multi-character gameplay, but also as a common virtual-player layer for more advanced automation, AI agents, and externally controlled Minecraft characters.