API

Other plugins are able to interact with PandaKnockback in order to provide more customization than would normally be possible. To start, you'll first need to depend on the plugin JAR. It is recommended you use a build system such as Gradle or Maven for this:

Maven

<repositories>
    <repository>
        <id>hpfxd-repo</id>
        <url>https://repo.hpfxd.com/releases/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.hpfxd</groupId>
        <artifactId>PandaKnockback</artifactId>
        <version>YOUR VERSION HERE</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Gradle (kts)

repositories {
    mavenCentral()
    maven("https://repo.hpfxd.com/releases/")
}

dependencies {
    compileOnly("com.hpfxd:PandaKnockback:YOUR VERSION HERE")
}

Concepts

• ValueSource: This is an interface which provides the actual double number for a knockback setting.
  • ConstantValue: This implementation of ValueSource simply provides a constant value which was provided during construction.
  • UniformRandomValue: This implementation of ValueSource provides a uniformly distributed random number between a specified minimum and maximum.
• KnockbackSettings: This class holds ValueSources for all the different settings the plugin provides for changing knockback for an attack.
• KnockbackProfile: This is an interface with a single method to retrieve the KnockbackSettings based on the attacking entity.
  • PersistedProfile: This is the default provided implementation of KnockbackProfile. It includes a name, the base KnockbackSettings, as well as additional KnockbackSettings for different entity types.
• KnockbackProfileService: This is an interface which is responsible for retrieving and setting the knockback profile of online players.
  • PersistedProfileService: This is the default provided implementation of KnockbackProfileService. This implementation provides additional methods for retrieving the loaded knockback profiles from profiles.yml.

Applying a knockback profile to a player

Player player = ...;
String profileName = ...;

// Retrieve the KnockbackProfileService from the Bukkit service registry
KnockbackProfileService service = Bukkit.getServicesManager().load(KnockbackProfileService.class);

// We need to check if the service is an instance of the built-in PersistedProfileService. This implementation is what
// provides the methods for retrieving loaded stored profiles. It is possible for other plugins to replace this service
// in order to load profiles from a different source or to implement the profile system in their own way.
if (service instanceof PersistedProfileService) {
    PersistedProfileService profileService = (PersistedProfileService) service;

    // Retrieve the profile from the PersistedProfileService using the name of the profile. If a profile with the
    // specified name doesn't exist, the result will be null and it's recommended to check the result before using it
    PersistedProfile profile = profileService.getLoadedProfile(profileName);
    
    // Apply the profile to the player
    profileService.setProfile(player, profile);
}

Creating a knockback profile

// First, construct an instance of KnockbackSettings which the profile will use
KnockbackSettings settings = new KnockbackSettings(
        // You'll need to provide instances of ValueSource for all settings this constructor needs. To create a
        // ValueSource for a constant value (in this example, 1), you can use new ConstantValue(1)
);

// Then, create a KnockbackProfile which will supply your settings. This example uses the "KnockbackProfile.constant"
// utility method to create a KnockbackProfile which always supplies the same settings regardless of the attacker. If
// you'd like to provide different settings in different situations, you can instead opt to create your own
// implementation of KnockbackProfile.
KnockbackProfile profile = KnockbackProfile.constant(settings);

// You can then apply the profile to a player using the setProfile method of KnockbackProfileService.

Setting values for individual attacks

If your use case requires different knockback settings for each attack, you can bypass the profile system entirely and listen to the below events instead.

• PlayerKnockbackByEntityEvent: This event is called when calculating the knockback values for an attack
• PlayerKnockbackByEntityApplyEvent: This event is called when the plugin is about to apply the velocity to the victim. It can be used to apply any final calculations on the result such as limiting or friction.

To see how the plugin uses these events to apply profiles, see ProfileApplicationListener

Implementing knockback yourself

If the plugin doesn't provide enough flexibility or settings for your use case, it's possible to implement knockback handling in your own plugin instead! See AttackListener to learn how the plugin uses EntityDamageByEntityEvent and PlayerVelocityEvent to apply knockback and replaces the server's built-in calculations.