CitizenInteraction

Static utility class that handles the full interaction pipeline — permission checks, message delivery, command execution, and animation triggers.

package com.electro.hycitizens.interactions;

Interaction Source Constants

public static final String SOURCE_LEFT_CLICK = "LEFT_CLICK";
public static final String SOURCE_F_KEY = "F_KEY";

Use these constants when calling handleInteraction to specify the interaction source.

handleInteraction

public static void handleInteraction(
    @Nonnull CitizenData citizen,
    @Nonnull PlayerRef playerRef
)

Triggers an interaction on a citizen as if the player pressed F (Use). Equivalent to calling handleInteraction(citizen, playerRef, SOURCE_F_KEY).

public static void handleInteraction(
    @Nonnull CitizenData citizen,
    @Nonnull PlayerRef playerRef,
    @Nonnull String interactionSource
)

Triggers a full interaction pipeline for the given citizen and player with the specified source. The pipeline:

1. Fires a CitizenInteractEvent — if cancelled, stops immediately
2. Checks the player's permission against citizen.getRequiredPermission()
3. Filters messages and commands by interactionTrigger matching interactionSource
4. Triggers ON_INTERACT animation behaviors
5. Delivers messages using the configured selectionMode
6. Executes command actions sequentially with their delays

// Trigger as if player used F key
CitizenInteraction.handleInteraction(citizen, playerRef);

// Trigger as a left-click
CitizenInteraction.handleInteraction(
    citizen, playerRef, CitizenInteraction.SOURCE_LEFT_CLICK
);

parseColoredMessage

@Nullable
public static Message parseColoredMessage(@Nonnull String messageContent)

Parses a message string containing color tags into a Hytale Message object. Returns null if the string is empty.

Supports two tag formats:

• Named colors: {RED}, {GOLD}, {LIGHTBLUE}, etc. (40+ colors)
• Hex colors: {#FF6B35}, {#ADD8E6}, etc.

Message msg = CitizenInteraction.parseColoredMessage(
    "{GREEN}Hello, {#FFD700}world!"
);
if (msg != null) {
    playerRef.sendMessage(msg);
}

Interaction Cooldown

The PlayerInteractionHandler enforces a 500ms cooldown between interactions per player to prevent spam. This is handled automatically — you don't need to manage it unless you're calling handleInteraction manually.

// Clear a player's cooldown manually if needed
interactionHandler.clearCooldown(playerUuid);