Ultimate PinataParty

!Version !Minecraft !License !PlaceholderAPI

Ultimate PinataParty turns server votes into a shared event where the whole community works toward one goal while players compete for the top contribution.

Each accepted hit advances a fixed session target. Players can follow the event through a boss bar and inventory menu, compare their contribution, and earn rewards based on how they participated instead of relying on a single final prize.

Community events with fair competition

• Fixed hit target for every event session.
• Live contribution ranking based only on accepted hits.
• Configurable cooldown between hits.
• Maximum contribution per player to prevent one person from controlling the event.
• Minimum participation requirement for community rewards.
• Configurable event duration and maximum number of simultaneous events.
• Allowed and blocked hit-item lists.

Five reward stages

Rewards are separated into independent groups:

• Per accepted hit.
• Final hit.
• Qualified participation.
• Top contributor.
• Lucky contributor.

The lucky contributor is selected using accepted hits as weighted tickets. More participation provides a better chance without guaranteeing the result.

Each reward group supports ALL, INDEPENDENT, and WEIGHTED_ONE selection modes. Entries can define their own chance, weight, and console commands with player, hit, rank, total, and session placeholders.

MCVote and NuVotifier

Ultimate PinataParty can receive event progress from:

• MCVote.
• NuVotifier.
• Administrative commands.

AUTO mode prefers MCVote and falls back to NuVotifier when MCVote is unavailable. Only one vote listener is enabled at a time, preventing the same vote from being counted twice.

Event presentation

• Configurable living entity used as the pinata.
• Shared boss bar with current and required hits.
• Hit particles and sounds.
• Configurable completion fireworks.
• Player menu for status, voting progress, streak, and ranking.
• Separate administrative menu for common event controls.

Menu positions remain separate from Java behavior and can be edited in menu/main.yml and menu/admin.yml.

MythicMobs, BetterModel, and ModelEngine

The event entity and its visual model are configured independently. This keeps the setup flexible without moving event progress or rewards into another plugin:

• Ultimate PinataParty controls hits, participation, progress, rewards, expiration, and cleanup.
• MythicMobs can provide the living entity and run custom skills at each event stage.
• BetterModel or ModelEngine can provide the visual model and its animations.

Entity references accept vanilla:<entity> and mythicmobs:<mob>. Model references accept none, bettermodel:<model>, and modelengine:<model>.

event:
  appearance:
    entity-source: 'mythicmobs:UltimatePartyPinata'
    model-source: 'modelengine:party_pinata'
    fallback-on-error: true
    fallback-entity-source: 'vanilla:llama'
    cleanup-delay-ticks: 30
    animations:
      spawn: spawn
      hit: hit
      complete: break
      expire: despawn
    mythic-signals:
      spawn: PINATASPAWN
      hit: PINATAHIT
      complete: PINATACOMPLETE
      expire: PINATAEXPIRE

Lifecycle hooks

Ultimate PinataParty plays the configured spawn, hit, complete, and expire animations when the selected model provider supports them. A MythicMobs entity also receives the matching PINATASPAWN, PINATAHIT, PINATACOMPLETE, and PINATAEXPIRE signals, allowing server owners to attach particles, sounds, mechanics, and other MythicMobs skills. Hit and completion skills can use the responsible player as their trigger.

Choose one model owner

There are two supported setups:

1. Recommended: select bettermodel:<model> or modelengine:<model> in model-source. Ultimate PinataParty attaches the model and controls its lifecycle animations. Do not also attach that model from the MythicMobs mob.
2. Advanced: use model-source: 'none' and let the MythicMobs mob own its Model: configuration and state{} skills. The lifecycle signals remain available for changing states.

Using both methods for the same mob can attach the model twice. Pick one owner and keep that responsibility in one configuration.

Safe fallback and diagnostics

When fallback-on-error is enabled, a missing optional plugin, invalid mob ID, or unavailable model can fall back to fallback-entity-source so the event remains usable. /pinataadmin providers reports which integrations are currently available. Custom models still require the corresponding resource pack to be installed and delivered to players.

Languages

English and Spanish are included. The selected locale controls chat messages, inventory titles, item names, and lore without requiring changes to every menu layout.

plugins/UltimatePinataParty/
|-- config.yml
|-- ultimate-pinata-party.db
|-- languages/
|   |-- en_US.yml
|   `-- es_ES.yml
`-- menu/
    |-- main.yml
    `-- admin.yml

Requirements

Requirement	Purpose
Paper 1.21.x	Server platform
Java 21	Runtime

MCVote, NuVotifier, and PlaceholderAPI are optional integrations.

Commands

Command	Description
/pinata	Open the event panel.
/pinata top	Open the panel and view current contributors.
/pinataadmin	Open the administration panel.
/pinataadmin spawn	Start an event at the default location.
/pinataadmin stop	Stop all active events without rewards.
/pinataadmin location set <id>	Save the current position.
/pinataadmin location remove <id>	Remove a saved position.
/pinataadmin location list	List saved positions.
/pinataadmin votes set <amount>	Set local vote progress.
/pinataadmin reload	Validate and reload user files.
/pinataadmin validate	Validate user files without applying them.

PlaceholderAPI

• %ultimatepinataparty_votes%
• %ultimatepinataparty_vote_goal%
• %ultimatepinataparty_votes_left%
• %ultimatepinataparty_active%
• %ultimatepinataparty_hits%
• %ultimatepinataparty_required_hits%
• %ultimatepinataparty_player_hits%
• %ultimatepinataparty_player_rank%
• %ultimatepinataparty_vote_streak%

Support

When reporting a problem, include the Paper and Ultimate PinataParty versions, the selected vote source, installed vote integration, and the complete console error.

Discord: https://discord.com/invite/5vjhNfeVDS