NekoX

NekoX - Cute Neko Plugin

What is this?

NekoX is a fun Minecraft plugin that makes Minecraft more interesting! It allows players to become cute neko girls with special abilities and interactive features.

Simply put: This plugin adds cute neko characters to your server!

Quick Start (3 Easy Steps)

Step 1: Download the Plugin

1. Download the NekoX-5.2-ProMax+++.jar file
2. Place this file in your server's plugins folder

Step 2: Start the Server

1. Start your Minecraft server normally
2. The plugin will automatically create configuration files

Step 3: Start Playing

1. In-game, type /nekoset playername true to turn a player into a neko
2. Neko players can now use all the fun features!

What Can Nekos Do? (Awesome Features)

🐱 Basic Abilities

• Night Vision: Nekos can see clearly in the dark
• Jump Boost: Can jump higher
• Sneak Speed: Move faster and quieter while sneaking

💬 Cute Chat

• Neko chat has special prefixes and suffixes
• Automatically converts normal words into cute neko language
• For example, "hello" might become "meow~ hello"

🍖 Special Diet

• Nekos can only eat meat! No vegetables or fruits
• Supports various meat-based foods

🐾 Claw Attacks

• Nekos have special claw attacks
• Extra damage to mobs
• Has cooldown time, cannot be used continuously

🛡️ Leather Armor Bonus

• Wearing leather armor provides speed bonuses
• Each piece of leather armor increases speed
• Multiple armor pieces stack effects
• Maximum bonus level is configurable

Simply put: Leather armor makes nekos run faster!

👑 Owner System

• Nekos can have owners
• Special interactions between owners and nekos
• Can heal and help each other
• Owner Death Effect: When an owner dies, their nekos also die (configurable)
  • Option to keep neko inventory and experience level

🌙 Night Abilities

• Neko abilities become stronger at night
• Peak power at midnight
• Automatically activates, no manual control needed

💪 Stress Response

• When neko health is very low
• Automatically gains super strength
• Lasts 1 minute, helps escape danger

⚔️ Passive Attack Boost

• Nekos deal slightly higher damage when attacking
• Stronger knockback effect against enemies
• Applies to all weapon types
• Damage and knockback multiplier configurable

Simply put: Neko attacks are more powerful and can knock enemies further!

🌿 Catnip Effects

• Nekos use catnip items (default uses wheat seeds)
• Gain temporary speed and jump boost
• Effects last for a period of time
• Can modify the items used in configuration file

🛡️ Damage Adjustment

• Fall Damage Immunity: Nekos don't take damage from falling from heights
• Other Damage Boost: Nekos take 0.8x more damage from other sources
• Can adjust damage multiplier in configuration file

Simply put: Nekos are immune to falling but more vulnerable to attacks!

🐾 Mob Repulsion

• Creeper Repulsion: Creepers won't explode when encountering nekos, but are repelled
• Phantom Repulsion: Phantoms won't attack nekos, but are repelled
• Automatically activates, no manual operation needed

Simply put: Creepers and phantoms are afraid of nekos and will automatically avoid them!

👁️ Mob Targeting Behavior

• Hostile mobs have increased detection distance for nekos
• Friendly mobs are more attracted to nekos
• Different effects on different types of mobs
• Detection parameters configurable

🔔 Player Proximity Notification

• When other players enter a 25-block radius around a neko, the neko receives a title notification
• Shows the names and distances of nearby players
• Can enable/disable the feature with the /playernotice command
• Configuration information stored in SQLite database
• Helps nekos be aware of their surroundings

Simply put: Nekos receive notifications about nearby players!

🧗‍♀️ Climbing Feature

• Wall Climbing: Nekos can climb up walls and vertical surfaces
• Usage: Use /climb command to toggle climbing feature
• Limitations: Can only climb near walls, has a limited range of use
• Auto-disable: Stops climbing automatically when leaving the wall

Simply put: Nekos can climb walls like spiders!

🐾 Tail Pull Feature

• Tail Interaction: Players can pull nekos' tails
• Usage: Use /pullthetail command to toggle tail pull feature
• Interactive Effects: Pulling tails creates fun interaction effects (damage and heal with cat sounds)
• Control: Nekos can choose whether to allow their tails to be pulled

Simply put: Players can interact with nekos by pulling their tails!

💖 Health Restore Skill

• Active Skill: Nekos can use /health command to restore health for themselves and their owners
• Cost: Consumes hunger points to use
• Cooldown: Has a cooldown period between uses
• Scaling Effect: The lower the health, the stronger the restoration effect

Simply put: Nekos can heal themselves and their owners with this skill!

📋 Skills List

• Command: /myskills - Shows all available skills for nekos
• Active Skills: Displays cooldown status and usage information
• Passive Skills: Shows status and description
• Clear Format: Easy to understand skill information

Simply put: Nekos can view all their skills and cooldowns with this command!

📋 Placeholder System

• New Command: /nekox placeholders - Lists all available NekoX placeholders
• Enhanced Compatibility: Works correctly even without PlaceholderAPI installed
• Better Error Handling: Clear error messages when PlaceholderAPI is unavailable
• Status Display: Shows registration status for each placeholder

Simply put: More reliable placeholder system with improved user experience!

🔧 Command System Enhancements

• Message Localization: Ensures proper message display in Chinese
• Improved Stability: Optimized command execution flow for better code reliability
• Crash Prevention: Enhanced error handling mechanisms
• Language Support: Better default message fallback system

Simply put: More stable commands with correct message display!

🌐 Language System Improvements

• Safe Message Access: Using SafeMessageUtils for secure message retrieval
• Fallback System: Better default messages when translations are missing
• Consistent Display: Ensured all command messages show correctly in different language environments

Simply put: Enhanced language support with more reliable message handling!

🌿 Catnip Detailed Usage Guide

What is Catnip?

Catnip is a special feature in the NekoX plugin that allows neko players to use specific items to gain temporary buff effects.

🎯 Usage Method

Basic Operation:

1. Must be a Neko Player - Only players set as nekos can use catnip
2. Hold Catnip Item - Default uses wheat seeds (WHEAT_SEEDS)
3. Right-Click to Use - Hold the catnip item and right-click to activate the effect

Specific Steps:

1. Ensure you are a neko (admin uses /nekoset yourname true to set)
2. Obtain wheat seeds (or other configured catnip items)
3. Hold wheat seeds and right-click
4. Immediately gain speed and jump boost effects

⚡ Effect Details

Catnip provides the following buff effects:

• Speed Boost (Speed II) - Significantly increased movement speed
• Jump Boost (Jump Boost II) - Greatly enhanced jump height
• Duration - Default 60 seconds (can be modified in configuration)

Effect Characteristics:

• Effects activate immediately
• Consumes one catnip item
• Has cooldown time, cannot be used continuously
• Only effective for neko players

⚙️ Configuration Options

Customize catnip settings in config.yml:

cat-nip:
  enabled: true           # Enable/disable catnip feature
  item: "WHEAT_SEEDS"     # Catnip item ID (can be changed to other items)
  duration: 60            # Effect duration (seconds)

Modifiable Item Options:

• Default: WHEAT_SEEDS (wheat seeds)
• Can be changed to: GRASS (grass), FERN (fern), VINE (vine), etc.
• Supports any Minecraft item ID

💡 Usage Tips

1. Combat Assistance - Use during PVP or mob fighting to gain speed and jump advantage
2. Escape Tool - Use catnip to quickly escape danger when being chased
3. Exploration Boost - Use during long-distance travel to improve movement efficiency
4. Building Aid - Jump boost helps with building at heights
5. Armor Selection - Wear leather armor to get maximum speed bonus

🚫 Limitations

• Only neko players can use
• Requires consumption of catnip items
• Has usage cooldown
• Cannot be used with off-hand items (must be held in main hand)

🔄 Synergy with Other Features

• Night Effects - Catnip effects work better at night
• Stress Response - Better effect when combining with catnip when health is low
• Armor Bonus - Speed bonus stacks with leather armor effects

Important Note: Right-clicking with catnip in main hand consumes 1 catnip item, off-hand items won't trigger the effect.

Common Commands (In-Game Usage)

Interaction Commands (Everyone can use)

• /pat player - Gently pat someone
• /lovebite player - Give a cute love bite
• /earscratch player - Scratch someone's ears
• /purr - Make purring sounds
• /hiss player - Hiss at someone
• /scratch player - Scratch someone with claws
• /attention player - Attract other players' attention
• /pullthetail - Toggle tail pull feature

Ability Commands (Nekos only)

• /nightvision - Enable night vision
• /jumpboost - Jump boost
• /swiftsneak - Sneak speed
• /health - Heal yourself and owner
• /myskills - View all skills and cooldowns
• /playernotice [on|off] - Enable/disable player proximity notification
• /climb - Toggle climbing feature

Owner System Commands

• /owner add player - Request to become someone's owner
• /owner accept player - Accept owner request
• /owner deny player - Deny owner request
• /owner remove player - Remove owner relationship
• /owner list - View your owners
• /owner mylist - View your nekos

Admin Commands

• /nekox reload - Reload plugin settings
• /nekoset player true/false - Set player as neko
• /nekox language language - Switch plugin language
• /nekox placeholders - Display all available NekoX placeholders

New Features in Emergency-fix Version

📋 Placeholder System Improvements

• New Command: /nekox placeholders - Lists all available NekoX placeholders
• Enhanced Compatibility: Works correctly even when PlaceholderAPI is not installed
• Better Error Handling: Clear error messages when PlaceholderAPI is unavailable
• Status Display: Shows registration status for each placeholder

Simple Description: More reliable placeholder system with improved user experience!

🔧 Command System Enhancements

• Message Localization: Fixed issues to ensure proper message display in Chinese
• Improved Stability: Optimized command execution flow for better code reliability
• Crash Prevention: Enhanced error handling mechanisms
• Language Support: Better default message fallback system

Simple Description: More stable commands with correct message display!

🌐 Language System Improvements

• Safe Message Access: Using SafeMessageUtils for secure message retrieval
• Fallback System: Better default messages when translations are missing
• Consistent Display: Ensured all command messages show correctly in different language environments

Simple Description: Enhanced language support with more reliable message handling!

Configuration (Optional Settings)

The plugin creates a config.yml file on first run, which you can open and modify with a text editor:

Basic Settings

• neko-chat: Enable/disable neko chat effects
• meat-only: Whether nekos can only eat meat
• owner-system: Enable/disable owner system

Ability Adjustments

• claws: Claw attack damage and cooldown time
• armor-bonus: Speed bonus from leather armor
• night-effects: Night ability start and end times
• health-skill: Healing skill cooldown and cost

Special Effects

• cat-nip: Catnip effects and duration
• stress-effect: Stress response trigger conditions
• passive-attack-boost: Attack damage bonus
• armor-bonus: Leather armor bonus settings
  • enabled: Enable/disable armor bonus
  • leather-bonus: Leather armor type list
  • speed-bonus-per-piece: Speed bonus per armor piece
• neko-damage-modification: Neko damage adjustment settings
  • enabled: Enable/disable damage adjustment feature
  • fall-damage-immunity: Fall damage immunity
  • other-damage-multiplier: Other damage increase multiplier
  • debug: Debug mode
• neko-mob-behavior: Neko mob behavior settings
  • enabled: Enable/disable mob behavior feature
  • creeper-repulsion: Creeper repulsion feature
  • phantom-repulsion: Phantom repulsion feature
  • debug: Debug mode
• mob-targeting: Mob targeting behavior settings
  • enabled: Enable/disable targeting behavior adjustment
  • distance-increase: Detection distance increase multiplier
  • friendly-attraction: Enable/disable friendly mob attraction
• owner-death: Owner death effect settings
  • feature.enabled: Enable/disable owner death effect
  • keep-inventory: Keep neko inventory
  • keep-level: Keep neko experience level

Developer API

NekoX provides a comprehensive API for other plugins to integrate neko functionality.

API Access

Using NekoX API in your plugin:

1. Add dependency in plugin.yml:

depend: [NekoX]

2. Get API instance in your plugin:

import org.cneko.nekox.api.NekoXAPI;

public class YourPlugin extends JavaPlugin {
    private NekoXAPI nekoXAPI;
    
    @Override
    public void onEnable() {
        nekoXAPI = NekoXAPI.getInstance(this);
        if (nekoXAPI == null) {
            getLogger().warning("NekoX plugin not found!");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }
    }
}

Development Environment Setup

Since NekoX is not published to JitPack or other public repositories, you need to manually add it to your project:

1. Maven Project Setup:

   • Create a libs folder in your project directory
   • Copy the NekoX-5.2-ProMax+++.jar file from this plugin's target folder to your libs folder
   • Add the following dependency to your pom.xml:

   <dependency>
       <groupId>org.cneko</groupId>
       <artifactId>NekoX</artifactId>
       <version>5.2-ProMax+++</version>
       <scope>system</scope>
       <systemPath>${project.basedir}/libs/NekoX-5.2-ProMax+++.jar</systemPath>
   </dependency>
   

2. Gradle Project Setup:

   • Create a libs folder in your project directory
   • Copy the NekoX-5.2-ProMax+++.jar file to your libs folder
   • Add the following dependency to your build.gradle:

   implementation files('libs/NekoX-5.2-ProMax+++.jar')
   

3. Manual Setup (IDE):

   • Create a libs folder in your project directory
   • Copy the NekoX-5.2-ProMax+++.jar file to your libs folder
   • Add the jar file to your project's build path in your IDE

API Methods

Neko Status Check

• boolean isNeko(Player player) - Check if player is a neko
• boolean isNeko(String playerName) - Check if player (by name) is a neko

Player Retrieval

• Set<String> getAllNekoNames() - Get all neko player names (including offline)

Owner Relationship Management

• Set<String> getOwnerNames(String nekoName) - Get all owners of a neko
• boolean isOwnerOf(String ownerName, String nekoName) - Check if player is owner of a neko
• boolean hasOwner(String playerName) - Check if player has an owner

Events

NekoX provides custom events for other plugins to listen to:

NekoStatusChangeEvent

Triggered when a player's neko status changes:

@EventHandler
public void onNekoStatusChange(NekoStatusChangeEvent event) {
    Player player = event.getPlayer();
    boolean isNeko = event.isNeko();
    boolean isOnline = event.isOnline();
    // Handle status change
}

OwnerRelationshipEvent

Triggered when owner relationships are added, removed, or requested:

@EventHandler
public void onOwnerRelationshipChange(OwnerRelationshipEvent event) {
    String nekoName = event.getNekoName();
    String ownerName = event.getOwnerName();
    OwnerRelationshipEvent.RelationshipAction action = event.getAction();
    
    switch (action) {
        case ADD:
            // Handle relationship addition
            break;
        case REMOVE:
            // Handle relationship removal
            break;
        case REQUEST:
            // Handle relationship request
            break;
    }
}

🔧 Developer Documentation

💡 Friendly Reminder: If you're just a regular user without programming knowledge, you can skip this section!

Maven Configuration

If you want to develop plugins that integrate with NekoX, here's the Maven configuration you need:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    
    <groupId>your.group.id</groupId>
    <artifactId>YourPlugin</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>
    
    <name>YourPlugin</name>
    
    <properties>
        <java.version>17</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>
    
    <repositories>
        <!-- PaperMC Repository -->
        <repository>
            <id>papermc-repo</id>
            <url>https://repo.papermc.io/repository/maven-public/</url>
        </repository>
    </repositories>
    
    <dependencies>
        <!-- Paper API -->
        <dependency>
            <groupId>io.papermc.paper</groupId>
            <artifactId>paper-api</artifactId>
            <version>1.20.4-R0.1-SNAPSHOT</version>
            <scope>provided</scope>
        </dependency>
        
        <!-- NekoX API -->
        <!-- Place the NekoX plugin jar file in your project's libs folder -->
        <dependency>
            <groupId>org.cneko</groupId>
            <artifactId>NekoX</artifactId>
            <version>5.2-ProMax+++</version>
            <scope>system</scope>
            <systemPath>${project.basedir}/libs/NekoX-5.2-ProMax+++.jar</systemPath>
        </dependency>
    </dependencies>
    
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.11.0</version>
                <configuration>
                    <source>${java.version}</source>
                    <target>${java.version}</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

How to Compile the Plugin (For Developers Who Want to Build the Plugin)

If you want to compile the plugin file yourself, you can follow these steps:

For Minecraft 1.20.4 (Default Version)

Open command line and enter:

mvn clean install

For Minecraft 1.21.4

Important Note: You need to install Java 21 on your computer first
Open command line and enter:

mvn clean install -Ppaper-1.21.4

Current Limitations

• If your computer uses Java 17, you can only compile the 1.20.4 version
• To compile the 1.21.4 version, you need to install Java 21 first

PlaceholderAPI Support

NekoX integrates with PlaceholderAPI and provides the following placeholders (requires PlaceholderAPI plugin to be installed):

| Placeholder | Description |
|