Imitation Core API

Imitation Core API is a reusable NeoForge 1.21.1 API for mods that need entity recording, transformations, disguises, replicas, copied identities, custom chat, animations, and compatibility with other gameplay systems.

This mod is currently in Beta testing! For reporting bugs or things that don't work with the mod, please go to the Discord linked and report a bug. Thanks!

The mod provides the underlying systems used by imitation-based skills and addons. It does not add a standalone transformation skill by itself.

Main Features

• Record living entities and players.
• Store recorded forms permanently.
• Select, replace, and manage forms through a dedicated menu.
• Transform players into copied mobs or players.
• Preserve recorded player skins after the original player disconnects.
• Display copied armor and held equipment without creating real items.
• Adjust camera and eye height to match the copied form.
• Synchronize transformations between players.
• Restore the player’s original appearance and state after reverting.
• Recover interrupted transformation sessions.
• Provide clear diagnostics when a form cannot be copied correctly.

Recorded Forms

Recorded forms can contain supported information such as:

• Entity type.
• Display name.
• Player profile and skin.
• Model and renderer information.
• Visual equipment.
• Camera height.
• Physical attributes.
• Movement attributes.
• Animation information.
• Faction information.
• Form abilities.
• Appraisal information.
• Optional mod-specific data.

Recorded combat targets, temporary movement, active attacks, passengers, leash data, and other unsafe temporary information are removed before the form is stored.

Transformations

• Supports appearance-only transformations.
• Supports deeper gameplay transformations when enabled by the skill using the API.
• Tracks each transformation as a server-controlled session.
• Prevents clients from creating unauthorized transformations.
• Saves active transformation state.
• Synchronizes active disguises to nearby players.
• Restores the original player when the transformation ends.
• Supports configurable transformation durations.
• A duration of 0 allows an unlimited transformation.
• Attempts to safely revert a transformed player before lethal damage kills them.
• Tracks temporary transformation data and removes it during reversion.

Physical Form Copying

Compatible transformations can reproduce supported attributes such as:

• Maximum health.
• Armor.
• Armor toughness.
• Attack damage.
• Attack speed.
• Attack knockback.
• Movement speed.
• Flying speed.
• Jump strength.
• Gravity.
• Knockback resistance.
• Scale.
• Step height.
• Safe fall distance.
• Block-breaking speed.
• Sneaking speed.
• Water movement.
• Interaction range.
• Oxygen bonuses.

The player’s original attributes and health are restored after reverting.

Appearance and Rendering

• Vanilla living-entity rendering.
• Recorded player skin rendering.
• Visual armor and held equipment.
• First-person camera adjustment.
• Eye-height adjustment.
• Position synchronization.
• Body rotation.
• Head rotation.
• Looking direction.
• Safe fallback rendering for unsupported entities.
• Client disguise-cache cleanup after reverting or disconnecting.

Copied equipment is visual-only and cannot be dropped, stored, traded, crafted, or duplicated.

Animation Support

• Idle animations.
• Walking animations.
• Sprinting animations.
• Crouching animations.
• Swimming animations.
• Attack animations.
• Hurt animations.
• Death animation intents.
• Head and body rotation.
• Protection against recorded one-time animations becoming permanently stuck.
• Support for addon-provided animation adapters.

Form Abilities

The API allows recorded forms to provide passive and activated abilities.

Built-in examples include:

• Spiders and cave spiders climbing walls.
• Skeleton variants shooting arrows.
• Endermen teleporting to a random safe location.
• Sun-sensitive undead burning in daylight.
• Helmets, water, rain, and fire immunity preventing sunlight burning.
• Support for addon-created attacks, movement abilities, passive effects, and special actions.

Skill and Ability Copying

Dependent mods can configure how copied skills and abilities work.

Supported rules include:

• Suppressing the player’s original abilities while transformed.
• Temporarily granting skills belonging to the recorded form.
• Comparing the player’s power with the recorded target’s power.
• Allowing stronger players to access additional copied abilities.
• Preventing weaker players from copying restricted skill categories.
• Configurable Common, Extra, Resistance, Intrinsic, Unique, and Ultimate copying.
• Configurable copied-skill mastery.
• Configurable denied-skill lists.
• Automatic removal of copied skills after reverting.
• Protection against removing skills the player legitimately owned before transforming.

Form Progression

• Tracks progression earned while transformed.
• Preserves progression earned by the original player.
• Applies matching progression to the active recorded form.
• Updates the form’s stored statistics.
• Updates supported appraisal information.
• Allows repeated transformations to improve form precision.
• Supports configurable precision, mastery, and progression rules.

Appraisal and Identity Masking

• Presents supported information from the copied form.
• Masks the player’s visible identity as the recorded entity.
• Supports copied health and armor information.
• Supports optional mod-specific statistics.
• Updates displayed information when the stored form progresses.
• Keeps the real player identity for permissions, ownership, logs, and moderation.
• Never replaces another player’s authenticated account.

Mob Factions

• Records the copied entity’s faction information.
• Makes mobs evaluate transformed players as the copied form.
• Works independently from deeper gameplay-state copying.
• Supports vanilla faction relationships.
• Supports tag-based modded factions.
• Allows other mods to register custom faction resolvers.
• Regularly clears invalid hostile targets.
• Allows servers to configure targeting range and update frequency.
• Allows faction-based targeting changes to be disabled.

Replica System

The API can create temporary living replicas from recorded forms.

Replica support includes:

• Mob forms.
• Fallback handling for player forms.
• Configurable replica lifetime.
• Configurable spawn distance.
• Configurable cleanup distance.
• Replica ownership tracking.
• Optional entity-state copying.
• Optional mod-specific state copying.
• Custom replica names.
• Automatic cleanup.
• Suppressed item drops.
• Suppressed experience drops.
• Protection against copied-equipment duplication.

Chat Replacement

Imitation Core API includes a server-controlled chat-routing system.

Chat Channels

• Global chat.
• Local chat within 128 blocks and the same dimension.
• Direct messages.
• Persistent global or local channel selection.
• A server-configurable default channel.
• Support for addon-created channels.

Chat Commands

• /imitchat global
• /imitchat local
• /imitchat global <message>
• /imitchat local <message>
• /imitchat direct <player> <message>
• /imitationchat as an alternative command name.

Using /imitchat global or /imitchat local without a message changes where normal chat messages are sent.

Chat Safety

• Server-controlled message routing.
• Real sender information preserved for logs and moderation.
• Optional copied-persona names.
• Message-size limits.
• Rate limiting.
• Protocol negotiation between clients and servers.
• Safe handling for clients without the complete chat protocol.
• Extension points for moderation, auditing, filtering, formatting, and custom personas.
• Copied identities are never presented as cryptographically signed messages from another player.

Discord Chat Relay

Servers can configure Discord integration through:

config/imitationcoreapi-discord.properties

The bridge supports:

• Minecraft-to-Discord chat through a webhook.
• Discord-to-Minecraft chat through a Discord bot.
• Global chat relaying.
• Optional local-message relaying.
• Optional direct-message relaying.
• Optional system-message relaying.
• Message sanitization.
• Message-length limits.
• Relay-loop prevention.
• Discord rate-limit handling.
• Configurable polling frequency.

A webhook is sufficient for Minecraft-to-Discord messages. A bot token and channel ID are required for Discord-to-Minecraft messages.

For Addon Developers

Other mods can use Imitation Core API to create custom transformation and imitation-based skills.

The public API provides systems for:

• Recording entities.
• Persistent form libraries.
• Form-selection menus.
• Transformations and reversion.
• Replicas.
• Costs, cooldowns, and mastery.
• Precision and progression.
• Transformation duration.
• Skill-category rules.
• Unique and Ultimate copying.
• Form abilities.
• Physical attributes.
• Faction recognition.
• Appraisal masking.
• Rendering and animations.
• Persona chat.
• Custom chat channels.
• Moderation and auditing.
• Transformation events.
• Diagnostics.
• Temporary-state cleanup.
• Optional compatibility adapters.

Requirements

• Minecraft: 1.21.1
• Mod Loader: NeoForge 21.1.150 or newer
• Java: 21
• Required Side: Client and server for complete functionality

Beta Notice

Imitation Core API is currently in beta.

Automated tests and builds pass, but unusual modded entities, complex animations, custom mob AI, gameplay-state copying, multiplayer synchronization, replicas, lifecycle recovery, and live Discord connections still require wider gameplay testing.

Please include the following when reporting a problem:

• The latest game log.
• Installed mod versions.
• The entity or player being copied.
• The type of transformation being used.
• Whether the issue occurred in singleplayer or multiplayer.

GeckoLib Compatibility

GeckoLib is optional.

When GeckoLib is installed, Imitation Core API can:

• Detect compatible GeckoLib entities.
• Record available animation controllers.
• Map live player actions onto copied entity animations.
• Support custom GeckoLib adapters from other mods.
• Fall back safely when an animation cannot be reproduced.

Compatibility may vary for entities with custom controller logic, multipart models, or unusual rendering systems.

Tensura and ManasCore Compatibility

Tensura and ManasCore are optional.

When installed, Imitation Core API provides support for:

• Race information.
• EP.
• MP and magicules.
• Aura.
• Spiritual health.
• Player state.
• Spirit state.
• Attributes.
• Ability information.
• Skill recording.
• Temporary copied skills.
• Skill classification rules.
• Unique and Ultimate skill-copy policies.
• Original-skill suppression.
• Safe restoration after reverting.
• Appraisal masking.
• EP-based transformation rules.
• Configurable race statistics, functions, and evolution lines.

The API can load without Tensura or ManasCore.