Welcome, server owner! This guide contains everything you need to install, configure, and manage the ForcePlugin on your server.


Getting started is simple:

1. Download the ForcePlugin.jar file from the main page.
2. Place the jar in your server's /plugins/ folder.
3. (<Optional but Highly Recommended>) Install the latest version of PlaceholderAPI. This is required to use the custom placeholders.
4. Start or restart your server.
5. The plugin will generate a config.yml, a ranks.yml, and a passives.yml file in the /plugins/ForcePlugin/ folder. You are now ready to configure the plugin!

This is the core experience for your players.

The First Choice:
A player's journey begins by executing /force choose. This opens the Choose Side GUI, where they can select either the Light Side (White Wool) or the Dark Side (Black Wool). This is a permanent choice that grants them their unique Holocron and sets them on their path.

The Holocron:
The Holocron is the key to everything. It is a custom-textured head that cannot be dropped or stored in chests.

• Right-Click: Opens the Skill Tree GUI to unlock or manage abilities. Inside the Skill Tree, you can click the Passive Skills button (Beacon) to open the Passives GUI and unlock/upgrade passive skills.
• Hold SHIFT + Scroll: Cycles through all unlocked abilities. The selected power is shown on the action bar.
• Left-Click: Uses the currently selected Force power.

Force Enchanting (Requires Specialization):
Once players reach level 31 and choose a specialization path, they can use /forceenchant (or /fe). Holding any enchantable item in their main hand and running this command opens a GUI to temporarily infuse it with enchantments using Force Energy. Applying these enchantments deducts Force Energy and applies temporary side effects:

• A Force Energy regeneration slowdown (scales with the total energy cost).
• A temporary Hunger effect.
• A temporary Mining Fatigue effect.

Progression:
Players gain Force XP by using abilities and killing mobs. When they level up (up to the max level of 100), they earn Force Points, which are spent in the Skill Tree and Passives GUIs to unlock and upgrade abilities and passive skills. Players can check their progress at any time with /forcestats.


Player Commands:

• /force choose - Opens the alignment selection GUI.
  Permission: forceplugin.use | Default: All Players
• /forcestats [player] (Alias: /fs) - Displays current stats and progression.
  Permission: forceplugin.use (for self), forceplugin.admin (for others) | Default: All Players (for self)
• /forceenchant (Alias: /fe) - Opens the Force Enchanting GUI.
  Permission: forceplugin.use | Default: All Players (Requires Specialization Rank)

Admin Commands:

• /forceadmin (Alias: /fa) - Base admin command.
  Permission: forceplugin.admin | Default: OP

Sub-commands:

• /fa reload - Reloads config.yml, ranks.yml, and passives.yml.
• /fa check <player> - Displays detailed Force data for a player.
• /fa setside <player> <light|dark|none> - Sets a player's alignment.
• /fa reset <player> - Completely resets a player's Force data.
• /fa setlevel <player> <level> - Sets a player's Force Level.
• /fa givexp <player> <amount> - Gives a player Force XP.
• /fa givepoints <player> <amount> - Gives a player Force Points.
• /fa giveholocron <player> - Gives a player a new Holocron for their side.

You have full control over the plugin's balance, progression, abilities, passives, and ranks.

File: config.yml
This file controls the core mechanics, ability stats, and force enchanting.

• progression:
  • max-force-level: The level cap for players (set to 100).
  • points-per-level: How many Force Points are awarded on level up.
  • base-xp & xp-per-level-multiplier: These control the leveling curve. The formula is BaseXP + ((CurrentLevel - 1) * Multiplier). (Default multiplier is 25).
  • xp-gain: Control how much XP is awarded for using abilities, launching with Telekinesis, and killing mobs.
• abilities:
  Each ability has its own section:
  • unlock-cost: The number of Force Points required to unlock the ability for the first time.
  • max-level: The maximum level this ability can be upgraded to.
  • levels: A section containing the stats for each level.
  • upgrade-cost: (Optional) Inside a level's block, you can define the cost to upgrade to the next level. If not defined, it defaults to 1.
  Available Abilities in config:
  • Universal: FORCE_PUSH (Max Lvl 3), FORCE_PULL (Max Lvl 2), TELEKINESIS (Max Lvl 1), FORCE_SENSE (Max Lvl 3 - New!)
  • Light Side Exclusive: FORCE_HEAL (Max Lvl 3), FORCE_REPULSE (Max Lvl 2), FORCE_STASIS (Max Lvl 2), FORCE_BARRIER (Max Lvl 3), FORCE_JUDGMENT (Max Lvl 3), FORCE_DEFLECTION (Max Lvl 1), FORCE_CLARITY (Max Lvl 2 - New!), FORCE_MEND (Max Lvl 3 - New!), FORCE_VALOR (Max Lvl 2 - New!)
  • Dark Side Exclusive: FORCE_CHOKE (Max Lvl 2), FORCE_LIGHTNING (Max Lvl 3), FORCE_SCREAM (Max Lvl 2), FORCE_DRAIN (Max Lvl 2), FORCE_CRUSH (Max Lvl 2), FORCE_RAGE (Max Lvl 1), FORCE_CORRUPT (Max Lvl 2 - New!), SOUL_REND (Max Lvl 3 - New!), DARK_AURA (Max Lvl 2 - New!)
  • Ultimate Abilities (Specialization Required): FORCE_ABSORB, FORCE_CAMOUFLAGE, FORCE_SERENITY, UNSTOPPABLE_VENGEANCE, MARK_OF_THE_HUNT, CHAIN_LIGHTNING
• force-enchanting:
  • debuffs: Configure post-enchanting side effects like energy regeneration slowdown, hunger effects, and fatigue.
  • enchantments: List of all enchantments that can be applied, their max levels, and the energy cost per level.

File: ranks.yml
This file controls the thematic titles players earn as they level up.

• ranks:
  This section defines the linear ranks players progress through up to level 100:
  • Light Side Ranks:
    Level 1: &bPadawan | Level 11: &bJedi Knight | Level 25: &bJedi Master | Level 50: &bJedi High Council | Level 75: &bJedi Grand Master | Level 100: &bForce Transcendent
  • Dark Side Ranks:
    Level 1: &cAcolyte | Level 11: &cSith Apprentice | Level 25: &cSith Lord | Level 50: &cDark Council Member | Level 75: &cDark Lord of the Sith | Level 100: &cSith Emperor
• specializations (Unlocked at Level 31):
  • id: A unique, one-word uppercase identifier (e.g., "GUARDIAN", "WARRIOR").
  • display-name: The full, colored name of the rank.
  • description: The text that appears on the icon in the choice GUI.
  • material: The Minecraft item that will be used as the icon for this choice.

File: passives.yml (New!)
This file controls the passive skills players can unlock and upgrade using Force Points.

• passives:
  • Light Side Passives:
    SOOTHING_PRESENCE (Max Lvl 3): Passively heals the player over time.
    DEFLECTING_PALM (Max Lvl 3): Grants a chance to negate melee attack damage.
    MEDITATION (Max Lvl 3): Provides a passive bonus to Force energy regeneration.
    TRANSCENDENCE (Max Lvl 1): On death, cheat death once and unleash a powerful Force explosion.
  • Dark Side Passives:
    SIPHONING_STRIKES (Max Lvl 3): Damage abilities have a chance to siphon health.
    FORCE_FEROCITY (Max Lvl 3): Defeating an enemy grants a burst of speed.
    CORRUPTED_ENERGY (Max Lvl 3): Dark side abilities have a chance to inflict wither.
    BLOOD_PRICE (Max Lvl 2): When active, abilities consume health instead of energy if depleted.
  • Neutral / None Passives:
    FORCE_ATTUNEMENT (Max Lvl 3): Stand still for 3 seconds to rapidly regenerate Force energy.

If you have PlaceholderAPI installed, you can use these placeholders anywhere on your server.

• %forceplugin_side% - Player's side (LIGHT, DARK, NONE)
• %forceplugin_side_formatted% - Player's side with color
• %forceplugin_rank% - Player's full, colored rank title
• %forceplugin_level% - Player's Force Level number
• %forceplugin_points% - Player's available Force Points
• %forceplugin_xp% - Player's current XP
• %forceplugin_xp_needed% - XP needed for the next level
• %forceplugin_xp_bar% - A visual text-based XP bar