Adyeshach Virtual Entity Solution

An EntityRefSet is a specialized collection designed to manage sets of EntityInstance objects using a lazy-resolution pattern. This is particularly useful for handling entity references that may not be immediately available (e.g., after deserialization).

Key Behaviors:

• Lazy Resolution: When entities are not yet loaded, their UUIDs are stored in pendingUuids. You must call resolve(manager) to attempt to convert these UUIDs into actual EntityInstance objects using a provided Manager.
• Serialization Logic: When calling getUuids(), the set prioritizes instances. However, to ensure data integrity, it only returns UUIDs for entities that belong to the same Manager as the owner. References to entities in different managers are kept in memory during runtime but are not persisted during serialization.
• Lifecycle Management: Use verify() to clean up the set by removing any EntityInstance that has been marked as removed (isRemoved).

// Example workflow for EntityRefSet
val entitySet = EntityRefSet(owner = myEntityInstance)

// 1. Adding an entity
entitySet.add(someEntityInstance)

// 2. Resolving pending UUIDs (e.g., after loading from disk)
entitySet.resolve(entityManager)

// 3. Checking contents
if (entitySet.containsUuid("some-uuid-string")) {
    // ...
}

// 4. Cleaning up invalid/removed entities
entitySet.verify()

The npc edit command allows you to modify existing entities (such as NPCs) using various modes: GUI-based panels, specialized editors, or direct value injection via CLI arguments.

Usage Patterns

1. GUI-based Editing (Panels)

To open a visual editing interface, use the following action types:

• main: Opens the basic entity panel.
• traits: Opens the traits management panel.
• public-meta: Opens the public metadata panel.
• private-meta: Opens the private metadata panel.
• move: Opens the movement/positioning panel.
• controller: Opens the PresetController interface.

Syntax: npc edit <id> <action>:<page> Example: npc edit e:123 main:1 (Opens page 1 of the main panel for entity ID e:123)

2. Visual Meta Editing (e action)

Opens a specific MetaEditor for a metadata key. This supports automatic detection of the editor type.

Syntax: npc edit <id> e:<key>-><default_value> <EditType>

• <key>: The metadata key to edit.
• <default_value>: The value to use as a default.
• <EditType>: (Optional) The specific editor class to use (e.g., AUTO). Example: npc edit e:123 e:skin->default

3. Quick Value Modification (m action)

Directly sets a metadata value without opening a GUI. Use @RESET to revert a value to its default.

Syntax: npc edit <id> m:<key>-><value>

• <key>: The metadata key.
• <value>: The new value. Use @RESET to reset. Example: npc edit e:123 m:hand->RESET (Resets the 'hand' metadata)

4. Trait Editing (t action)

Modifies specific entity traits.

Syntax: npc edit <id> t:<trait_id>

• sit, title, command, view-condition: Opens the respective trait editor.
• title-height: Prompts for a new title height via sign input.
• patrols: Opens the patrol trait editor.
• patrols-wait-time: Prompts for a new patrol wait time via sign input.
• patrols-update: Refreshes the patrol nodes.

5. Contextual Editing

• Nearest Entity: Running npc edit without an ID targets the nearest entity that passes the filter.
• Targeted Entity: Running npc edit <id> opens the default EditPanel for that specific entity.

# Open main panel for NPC with ID 123, page 1
npc edit 123 main:1

# Quick reset of metadata
npc edit 123 m:hand->RESET

# Edit a trait
npc edit 123 t:sit

The MigrateCitizens utility allows for the conversion of existing Citizens NPCs into Adyeshach persistent entities.

How it works:

1. It scans all currently spawned Citizens NPCs.
2. For each NPC, it creates a corresponding Adyeshach entity using the PERSISTENT manager type.
3. It maps basic metadata (Name, Custom Name Visibility, Glowing state, Pose, and Swimming state).
4. It performs type-specific attribute mapping (e.g., Age, ArmorStand properties, Bee states, Cat colors, Fox behaviors, Horse styles, etc.).
5. It attempts to migrate equipment (Helmet, Chestplate, Leggings, Boots, Main Hand, and Off Hand) for living entities.
6. For Human/Player NPCs, it attempts to migrate skin textures.
7. Finally, it despawns the original Citizens NPC.

Note: The resulting Adyeshach entity ID will be prefixed with citizens_ followed by the original NPC ID (e.g., citizens_123).

// This is a programmatic migration utility. 
// It is typically invoked via a command handler calling:
MigrateCitizens.migrate(sender)

The npc create subcommand allows you to spawn new entities (NPCs) with specific types and IDs. You can optionally specify an action to determine where the entity spawns or if an editor panel should open immediately.

Syntax

npc create <type> <id> [action]

Arguments

• <type>: The type of entity to create. This must be a valid value from EntityTypes (e.g., ZOMBIE).
• <id>: A unique identifier for the new entity.
• [action]: (Optional) An action to perform after creation:
  • t or target: Spawns the entity at the block you are currently looking at (offset to the top of the block). If looking at air, it spawns at your location.
  • e or edit: Spawns the entity at your current location and immediately opens the EditPanel for configuration.

If no action is provided, the entity spawns at your current location.

# Basic creation at player location
npc create ZOMBIE my_npc_id

# Create at the target block you are looking at
npc create ZOMBIE my_npc_id target

# Create and immediately open the editor panel
npc create ZOMBIE my_npc_id edit

The npc look subcommand allows you to change the looking direction of an entity (NPC) using several modes: looking at a specific location, looking at the player, or mimicking the player's current rotation.

Syntax

npc look <id> <mode>

Modes

1. Looking at the player's current position

Use these to make the NPC look at where the player is currently looking.

• npc look <id> here: Makes the NPC look at the player's eye location (Head only).
• npc look <id> here-a: Makes the NPC look at the player's eye location (Head and Body).
• npc look <id> here-c: Uses controller-based looking (smooth movement) to look at the player's eye location.

2. Mimicking the player's rotation

Use these to make the NPC match the player's exact yaw and pitch.

• npc look <id> like: Matches the player's rotation (Head only).
• npc look <id> like-a: Matches the player's rotation (Head and Body).
• npc look <id> like-c: Uses controller-based looking to match the player's direction.

3. Looking at specific coordinates

• By Euler Angles (Yaw/Pitch): npc look <id> with <yaw> <pitch> Sets the entity's head rotation to the specified yaw and pitch.
• By XYZ Coordinates: npc look <id> to <x> <y> <z> Sets the entity's head rotation to face the specified world coordinates.

Note: The entity must be in the same world as the player for these commands to work.

# Examples
npc look 1 here
npc look 1 here-a
npc look 1 like-a
npc look 1 with 90 0
npc look 1 to 100 64 200

The GameProfile class is a data structure used to represent player or entity profiles, specifically for managing names, pings, textures (skins), and visibility status. It can be converted to a Mojang GameProfile for compatibility with authlib.

Key Properties

• name: The profile name. It is automatically truncated to a maximum of 16 characters.
• ping: An integer representing the connection latency.
  • Negative values result in a 'no connection' icon.
  • Values follow a bar-based logic: <150ms (5 bars), <300ms (4 bars), <600ms (3 bars), <1000ms (2 bars), >=1000ms (1 bar).
• texture: An array of strings used for skin data. For Mojang compatibility, it expects [0] = texture_value and [1] = signature.
• textureName: A string representing the player's skin.
• spectator: Boolean indicating if the entity is in spectator mode.
• listed: Boolean indicating if the player is visible in the player list (supported in Minecraft versions where MinecraftVersion.majorLegacy >= 11903).
• showHat: Boolean indicating whether to show the hat layer (supported starting from version 1.21.4).

val profile = GameProfile().apply {
    name = "PlayerName"
    ping = 100
    texture = arrayOf("texture_value", "signature_value")
    spectator = false
}