Read every attached document completely before writing a single line of code. Treat these documents as the project’s official specification. Understand the entire architecture, gameplay systems, database integration, and coding standards before starting implementation. Do not begin coding until you have a complete understanding of the project. If additional database persistence is required, generate a production-ready 99_plugin_database_migration.sql instead of modifying the documented schema.
📄
plugin_prompt.md
md
1815 lines
▶
# Skill SMP Plugin Specification
Version: 1.0
---
IMPORTANT:
Read this entire specification completely before writing a single line of code.
Understand the entire architecture first.
Only begin implementation after understanding every gameplay system and how they interact with each other.
Never implement features independently without considering the whole project.
# ROLE
You are a Senior Minecraft Software Engineer specialized in:
- Paper
- Folia
- Kotlin
- PostgreSQL
- RPG Game Design
- Multiplayer Systems
- Minecraft Networking
- Performance Optimization
Your task is to build the COMPLETE production-ready plugin for my Minecraft server.
This is NOT a prototype.
This is NOT a demo.
Do NOT generate placeholder code.
Do NOT leave TODO comments.
Every feature must already work.
The final plugin should be deployable on a production Minecraft server.
---
# AVAILABLE DOCUMENTATION
The following documentation files are attached and represent the complete database specification.
Treat them as the single source of truth.
DATABASE_README.md
DATABASE_SCHEMA.md
DATABASE_DIAGRAM.md
DATABASE_API.md
Do NOT assume the existence of tables, columns, SQL functions or triggers that are not described inside these documents.
If additional persistence is required for new gameplay systems, generate a migration SQL file instead of modifying the documented schema.
The migration file must be named:
99_plugin_database_migration.sql
The existing database architecture must always remain compatible.
# DATABASE RULES
Before writing any database code:
Read every attached database document completely.
Understand how the schema is organized.
Reuse existing tables whenever possible.
Reuse existing SQL functions whenever possible.
Respect existing triggers.
Respect existing foreign keys.
Never duplicate business logic already handled by PostgreSQL.
If documentation is unclear, inspect the existing Kotlin code before deciding to create new persistence.
Only create new tables if absolutely necessary.
If new tables are created:
Generate a complete production-ready SQL migration.
Never silently change the documented schema.
# PROJECT
Plugin Name
SkillCore
Server Name
Skill SMP
Minecraft Version
26.2
Java Version
The plugin must support the latest available Java version (Java 25 or Java 26).
Language
Kotlin
Server Software
Paper
Folia
The plugin must work correctly on BOTH platforms.
The architecture must be designed from the beginning to support Folia region threading.
Never use unsafe Bukkit operations.
Never block the server thread.
Use asynchronous tasks whenever possible.
Use Folia schedulers whenever appropriate.
---
# DATABASE
The PostgreSQL database already exists.
The complete SQL schema is attached.
The attached SQL files are the single source of truth.
Never redesign the existing database.
Never rename tables.
Never rename columns.
Never duplicate existing functionality.
Always use the provided SQL schema.
Always reuse existing SQL functions whenever possible.
If additional persistence is absolutely necessary for implementing new gameplay systems, extend the existing architecture instead of replacing it.
If new tables are required:
Generate a complete SQL migration file.
Example:
99_plugin_database_migration.sql
The migration must include:
CREATE TABLE
Indexes
Constraints
Foreign Keys
Functions
Triggers
Permissions
Everything required for production.
Never modify existing tables unless absolutely necessary.
---
# PROJECT PHILOSOPHY
Skill SMP is NOT another Survival server.
Skill SMP is NOT another Skills plugin.
Skill SMP must feel like a complete RPG built inside Minecraft.
The objective is transforming Minecraft Survival into an MMORPG while keeping vanilla Minecraft recognizable.
Players should constantly progress.
There should always be something to unlock.
Progression must feel rewarding.
The gameplay loop must create long-term motivation.
Players should never feel like progression suddenly ends.
Everything should encourage long-term gameplay.
---
# GAMEPLAY LOOP
Player joins
↓
Chooses a class
↓
Completes activities
↓
Earns SkillCoins
↓
Unlocks Skills
↓
Improves abilities
↓
Earns more SkillCoins
↓
Unlocks stronger skills
↓
Changes gameplay
↓
Repeats forever
Every mechanic should reinforce this progression.
---
# RPG DESIGN
Take inspiration from modern RPGs.
Take inspiration from MMORPG progression systems.
Take inspiration from Minecraft mods such as:
Pufferfish Skills
However:
Never copy them.
Create a unique experience.
Every feature should feel handcrafted.
Avoid generic plugin mechanics.
The server should feel premium.
---
# FIRST JOIN EXPERIENCE
The player's first login should be memorable.
DO NOT use a normal Inventory INVENTORY GUI.
Create an immersive class selection sequence.
The player should temporarily enter a cinematic state.
Use:
Particles
Camera transitions
Sounds
Animations
Titles
Subtitles
Action Bars
Boss Bars
Smooth transitions
Each class should include:
Name
Description
Difficulty
Strengths
Weaknesses
Gameplay Preview
Recommended Playstyle
The player should immediately understand how every class feels.
Once selected:
Play animation
Play sound
Display title
Display subtitle
Send localized chat message
Save the selection inside PostgreSQL.
The first login should feel like starting an RPG rather than joining a normal SMP.
---
# USER EXPERIENCE
Every interaction should feel satisfying.
Opening menus.
Unlocking skills.
Buying skills.
Completing objectives.
Receiving SkillCoins.
Everything should provide visual feedback.
Whenever possible use:
Animations
Particles
Custom Sounds
Boss Bars
Toast Notifications
Action Bars
Hover Effects
Gradient Text
Smooth Transitions
Professional UI.
Nothing should feel static.
# CLASSES
Classes are the foundation of the RPG experience.
Every player must choose exactly one class.
Classes define:
Combat style
Progression
Skill Tree
Abilities
Future gameplay
Every class must feel unique.
No class should simply be stronger.
Instead, every class should encourage a completely different playstyle.
Changing class should be possible but expensive.
Class resets consume SkillCoins.
The cost must be configurable.
---
# SKILL TREE
The Skill Tree is the most important feature of the plugin.
It MUST NOT use a normal inventory INVENTORY GUI.
It MUST visually resemble Minecraft's Advancement screen.
This is one of the defining features of the server.
The interface should immediately feel familiar to Minecraft players.
Implement:
Infinite scrolling
Zoom
Smooth camera movement
Animated nodes
Branches
Connections
Hover tooltips
Locked nodes
Unlocked nodes
Purchased nodes
Equipped nodes
Skill dependencies
Visual progression
Opening animation
Closing animation
Node unlock animation
Purchase animation
Connection animation
Particles
Custom sounds
Professional transitions
The interface should feel like a native Minecraft feature.
---
# SKILL TYPES
Support:
Passive Skills
Active Skills
Ultimate Skills
Movement Skills
Combat Skills
Mining Skills
Economy Skills
Utility Skills
Survival Skills
Future Skill Types
Every unlocked skill MUST actually modify gameplay.
Never create fake progression.
Never unlock cosmetic nodes pretending they change gameplay.
Players must immediately notice the effects of new abilities.
---
# SKILL PURCHASES
Skills are purchased using SkillCoins.
When purchasing:
Play custom sound.
Play particle animation.
Animate the unlocked node.
Display Title.
Display Subtitle.
Send localized chat message.
Refresh the Skill Tree immediately.
Everything should feel rewarding.
---
# SKILL PATH ITEM
Replace the old concept of the Skill Book.
Create a unique custom item called:
Skill Path
(or another immersive name with a similar meaning.)
The item must include:
Custom Texture
Custom Model
Custom Display Name
Custom Lore
Custom Rarity
Custom Animation when obtained
This item becomes the player's progression menu.
Opening the item must instantly open the Skill Tree.
IMPORTANT
The item MUST always work.
Right-clicking in the air must work.
Right-clicking on blocks must work.
Main hand support.
Off-hand support.
It must NEVER require looking at a block.
It must NEVER stop working because of interaction events.
The previous bug where the menu only opened while looking at a physical block must never exist.
---
# SKILLCOINS
SkillCoins are the primary server currency.
Players earn SkillCoins through gameplay.
Examples:
Jobs
Marketplace Sales
PvP
Events
Future Systems
Administrative Rewards
Future Quests
Future Dungeons
Everything must use PostgreSQL transactions.
Never allow duplicated rewards.
Never allow race conditions.
Every balance modification must immediately update the player's HUD.
Whenever SkillCoins are gained:
Display animated popup above the hotbar.
Example:
+250 SkillCoins
Play rewarding sound.
Spawn subtle particles.
Send localized message when appropriate.
Whenever SkillCoins are removed:
Display negative popup.
Example:
-500 SkillCoins
Use a different sound.
Use a different animation.
The player should always understand why their balance changed.
---
# DEATH SYSTEM
Death must have consequences.
When a player dies:
The last purchased skill becomes inactive.
The player never permanently loses progression.
The skill simply becomes inactive until repurchased.
Repurchasing requires SkillCoins.
The system should create tension without becoming frustrating.
Players should fear death without feeling punished excessively.
---
# MULTI-LANGUAGE SUPPORT
Every player-facing message must use localization.
Never hardcode visible text.
The plugin should automatically detect the Minecraft client language whenever possible.
Supported examples:
English
Italian
French
German
Spanish
Players may manually override their language from the plugin settings.
Every INVENTORY GUI.
Every chat message.
Every title.
Every action bar.
Every boss bar.
Every tooltip.
Every marketplace screen.
Every Builder interface.
Everything must automatically display in the selected language.
Changing language should immediately refresh the interface whenever possible.
# JOB SYSTEM
Jobs should not simply generate money.
Each profession should completely change how the player interacts with the world.
Current professions:
• Miner
• Farmer
• Builder
• Hunter
• Fisherman
Every profession should have:
Unique progression
Exclusive advantages
Upgradeable mechanics
Future extensibility
Reward values must remain configurable.
Never hardcode balancing.
Future balancing should only require configuration changes.
---
# BUILDER PROFESSION
Builder is the most unique profession on the server.
It should feel completely different from every other job.
The objective is allowing players to create and sell complete builds.
Builder players unlock a special tool:
Area Selection Tool
This is a custom stick.
Custom model.
Custom texture.
Custom name.
Custom lore.
It is used to select a structure inside the Minecraft world.
The selection system should feel similar to Litematica.
Players select:
First corner
Second corner
The plugin automatically calculates:
Width
Height
Length
Total Blocks
Bounding Box
Once a valid selection exists, the player can convert the structure into a Blueprint.
---
# BLUEPRINT SYSTEM
The Blueprint system is exclusive to Builder players.
After selecting a build, a localized button appears.
Example:
Get Blueprint
or
Ottieni Blueprint
depending on the player's selected language.
Clicking the button opens a INVENTORY GUI asking for:
Blueprint Name
Description (optional)
Category (optional)
After confirmation:
The structure is serialized.
The player receives a Blueprint Block.
---
# BLUEPRINT BLOCK
The Blueprint Block is a completely custom item.
It is NOT just a renamed block.
It must use:
Custom Model Data
Custom Texture
Custom Name
Custom Lore
Professional appearance.
The texture should visually combine multiple Minecraft blocks into a single cube.
Example:
Top:
Grass Block
Left:
Stone
Right:
Netherrack
This is only an example.
The final design should look polished and unique.
Each Blueprint Block stores:
Structure
Dimensions
Rotation
Metadata
Owner
Creation Date
Blueprint Name
The Blueprint Block itself becomes the physical representation of the player's creation.
Players can trade Blueprint Blocks just like any other item.
---
# BLUEPRINT PREVIEW
Blueprint Blocks never build instantly.
When the player right-clicks while targeting a solid block:
A holographic preview appears.
The preview is only visible to the player currently placing the Blueprint.
Other players should not see it.
If the player right-clicks the air instead of a solid block:
Display a localized chat message explaining that the Blueprint must be placed on a solid surface.
Never silently fail.
The preview should resemble Litematica while remaining an original implementation.
It should support:
Real-time movement
Rotation
Mirror
Offset adjustment
Placement validation
Smooth rendering
No visible flickering.
---
# BLUEPRINT POSITIONING
Once the preview appears, a placement interface opens.
The player can adjust:
X Offset
Y Offset
Z Offset
Rotation
Mirror
As coordinates change:
The holographic preview moves in real time.
The player immediately sees the final position.
Only after confirmation should the structure actually be generated.
Players must always know exactly where the Blueprint will be placed.
---
# PLAYER MARKETPLACE
Create a fully player-driven marketplace.
This marketplace is one of the main gameplay features.
Players can access it through:
Skill Path
or
/store
The marketplace must be completely integrated into the RPG progression.
Never use Vault economy.
Never use vanilla currency.
Everything uses SkillCoins.
---
# MARKETPLACE CATEGORIES
General
Displays the newest listings.
Food
Displays every food item.
Blocks
Displays every block.
Armor & Tools
Weapons
Armor
Tools
Both enchanted and non-enchanted.
Builds
Contains every Blueprint Block created by Builder players.
Other
Everything else.
The category system should be easily expandable.
---
# SELLING ITEMS
Players may sell:
Resources
Food
Blocks
Weapons
Armor
Tools
Blueprint Blocks
Future custom items.
Selling process:
Select item.
Choose SkillCoins price.
Confirm.
The item immediately becomes available inside the marketplace.
The marketplace should never require administrator approval.
---
# BUYING ITEMS
Buying must feel satisfying.
When a player purchases an item:
SkillCoins are transferred immediately.
The seller instantly receives:
Localized chat message.
Sound.
Animated popup above the hotbar.
Example:
+350 SkillCoins
The buyer immediately receives the purchased item.
Marketplace transactions must always use PostgreSQL transactions.
Never duplicate items.
Never duplicate SkillCoins.
Never allow race conditions.
---
# MARKET SEARCH
Implement a global search system.
The search bar should search every marketplace category simultaneously.
Support:
Partial matches.
Instant filtering.
Fast response.
Large marketplaces.
The marketplace should remain responsive even with thousands of listings.
---
# FUTURE EXTENSIBILITY
Design every Builder and Marketplace system to support future additions.
Examples:
Blueprint ratings.
Featured Blueprints.
Blueprint versions.
Marketplace history.
Auction system.
Player shops.
Guild shops.
Seasonal items.
The architecture should already be modular enough to support these features later without major rewrites.
# PLAYERDB INTEGRATION
Use PlayerDB API.
The plugin should automatically retrieve:
UUID
Username
Skin
Cape (if available)
Use intelligent caching.
Always use cached values before requesting new data.
Refresh only when necessary.
The plugin should minimize external API requests.
---
# COMMANDS
Create clean and professional commands.
Examples:
/skillpath
/classes
/skills
/skillcoins
/jobs
/store
/blueprints
/profile
/admin
Every command should include:
Permissions
Tab Completion
Localized Messages
Error Handling
Help Pages
Professional formatting.
---
# PLAYER PROFILE
Create a complete player profile.
The profile should display:
Current Class
Current Job
SkillCoins
Unlocked Skills
Current Rank
Statistics
Play Time
Marketplace Listings
Blueprints Created
The profile should feel like an RPG character sheet.
---
# VISUAL QUALITY
The plugin should feel like a premium commercial product.
Every interaction should provide feedback.
Use:
Particles
Custom Sounds
Titles
Subtitles
Action Bars
Boss Bars
Toast Notifications
Hover Text
Gradient Components
Animations
Smooth transitions.
Avoid static interfaces.
---
# CONFIGURATION
Everything should be configurable.
Never hardcode gameplay values.
Create configuration files for:
Jobs
Skill rewards
Marketplace
Blueprint system
INVENTORY GUI appearance
Particles
Sounds
Animations
Cooldowns
Limits
Messages
Economy
Every future rebalance should only require configuration changes.
---
# PERFORMANCE
Performance is critical.
Never block the Minecraft main thread.
All PostgreSQL operations must be asynchronous.
Use:
Connection Pooling
Prepared Statements
Caching
Batch Updates
Efficient Queries
Avoid unnecessary object allocations.
Avoid memory leaks.
Avoid excessive scheduled tasks.
Optimize for servers with hundreds of simultaneous players.
---
# CODE ARCHITECTURE
Use Clean Architecture.
Apply SOLID principles.
Use dependency injection where appropriate.
Create reusable modules.
Separate gameplay logic from persistence.
Avoid giant manager classes.
Avoid god objects.
Every module should have a single responsibility.
The codebase should remain maintainable for years.
---
# DATABASE INTEGRATION
The attached SQL schema is the single source of truth.
Never redesign the existing database.
Never rename existing tables.
Never rename existing columns.
Reuse existing SQL functions whenever possible.
Do not duplicate SQL business logic inside Kotlin.
If new persistence is required for Blueprint or Marketplace systems:
Create a migration file named:
99_plugin_database_migration.sql
The migration must contain every additional table required.
Include:
Tables
Indexes
Foreign Keys
Constraints
Functions
Triggers
Permissions
Do not modify the existing schema unless absolutely necessary.
The migration must be production-ready.
---
# SECURITY
Never trust player input.
Always validate:
Commands
INVENTORY GUI Inputs
Marketplace Prices
Blueprint Names
Player Names
Prepared statements must always be used.
Prevent:
SQL Injection
Item Duplication
SkillCoin Duplication
Marketplace Exploits
Blueprint Duplication
Race Conditions
Desynchronization
Everything should remain consistent after crashes.
---
# TESTING
Before considering the plugin complete, verify that every system works correctly.
Blueprint System
Marketplace
Jobs
Skill Tree
Classes
Database
Localization
PlayerDB
SkillCoins
Death System
Every unlocked skill
Every INVENTORY GUI
Every animation
Every sound
Every SQL interaction
No feature should remain partially implemented.
Every gameplay mechanic must work exactly as designed.
---
# BUG PREVENTION
The following bugs MUST NEVER exist.
The Skill Path item only opens while looking at a block.
Skills unlock but have no gameplay effect.
Database race conditions.
Marketplace duplication exploits.
Blueprint duplication.
Items disappearing.
SkillCoins disappearing.
SkillCoins duplication.
INVENTORY GUI desynchronization.
Memory leaks.
Unsafe Folia thread access.
Paper-only implementations.
Broken localization.
Player data loss.
Server lag caused by synchronous database queries.
Everything must be thoroughly tested before considering the plugin finished.
---
# FINAL GOAL
The final result must feel like a completely new Minecraft experience.
Players should immediately recognize Skill SMP as a unique RPG server.
The progression should remain enjoyable for hundreds of hours.
The plugin should look and feel like a professional commercial product rather than a typical Minecraft plugin.
When development is complete, I should only need to:
• Configure PostgreSQL
• Start the server
• Import the optional migration SQL if required
and everything should already work in production.
The plugin should be scalable, maintainable, immersive and ready to support future expansions without major rewrites.
# DEVELOPMENT STANDARDS
This project must be developed with the same quality standards expected from a professional Minecraft network.
Never choose the easiest implementation.
Always choose the implementation that creates the best player experience while maintaining excellent performance and maintainability.
Whenever multiple technical solutions exist:
Choose the solution that provides:
• Better gameplay
• Better scalability
• Better maintainability
• Better user experience
Never optimize only for development speed.
Optimize for long-term quality.
---
# IMMERSION
Every feature should feel like part of Minecraft itself.
Players should never feel like they are interacting with random inventory menus.
Everything should feel immersive.
Whenever possible replace standard INVENTORY GUI interactions with:
Animations
World interactions
Visual effects
Custom models
Particles
Smooth transitions
Professional sounds
The objective is making players forget they are using a plugin.
---
# PLAYER EXPERIENCE
Every interaction should answer one question:
"Does this make the player smile?"
If not, redesign it.
Reward players often.
Celebrate progression.
Make every unlock memorable.
Small details matter.
The plugin should constantly provide positive feedback.
---
# USER INTERFACE
Avoid generic chest menus whenever another solution is possible.
Use inventory interfaces only when they genuinely provide the best user experience.
Every interface should be:
Beautiful
Responsive
Consistent
Localized
Animated
Easy to understand
Every icon should have a purpose.
Avoid visual clutter.
---
# AUDIO DESIGN
Sounds are extremely important.
Every important action should have its own sound.
Examples:
Skill unlocked
Skill purchased
Blueprint created
Marketplace sale
Marketplace purchase
Class selected
Job reward
SkillCoins earned
SkillCoins spent
Level progression
Avoid reusing the same sound everywhere.
Sound design should reinforce progression.
---
# PARTICLE DESIGN
Particles should never be excessive.
Use them intelligently.
Reward important moments.
Examples:
Unlocking abilities
Receiving SkillCoins
Completing Blueprint creation
Marketplace purchase
Class selection
Important achievements
Particles should communicate progression.
---
# FUTURE CONTENT
Design the plugin so that future updates can introduce entirely new gameplay systems without requiring architectural rewrites.
Examples:
Guilds
Kingdoms
NPCs
Quest System
Daily Missions
Weekly Challenges
Achievements
Prestige
Skill Evolutions
Legendary Skills
Dungeons
Bosses
Raids
Trading NPCs
Crafting Professions
Pets
Mounts
Battle Pass
Seasonal Events
Everything should already be modular enough to support these systems.
---
# FINAL REQUIREMENTS
The completed project must include:
Complete Kotlin source code
Gradle project
Configuration files
Resource Pack assets
Custom textures
Custom models
Adventure Components
Localization files
Database integration
PlayerDB integration
Marketplace
Blueprint system
Builder profession
Skill Tree
Jobs
Classes
SkillCoins
Animations
Particles
Professional sounds
Complete documentation
README
Installation guide
Configuration guide
Developer documentation
Database migration SQL (only if new tables are required)
No missing systems.
No placeholder code.
No unfinished mechanics.
No mock implementations.
Everything should already function exactly as expected.
---
# SUCCESS CRITERIA
The project is considered complete only if a server owner can:
1. Import the existing PostgreSQL database.
2. Execute the optional migration SQL (if generated).
3. Configure the .env or plugin configuration.
4. Start a Minecraft 26.2 Paper or Folia server running on Java 25 or Java 26.
5. Join the server.
6. Experience every gameplay mechanic exactly as described in this specification without requiring additional development.
Only then should the project be considered finished.
📄
DATABASE_SCHEMA.md
md
221 lines
▶
Skill SMP Database Schema
Database overview
Architecture summary
Table list
Then document EVERY table individually.
Table: players
Purpose
Describe in one short paragraph what this table stores.
Used By
Example:
Plugin
Website
Admin Panel
Future Services
Columns
| Column | Type | Nullable | Default | Description |
Document EVERY column.
Primary Key
List the PK.
Foreign Keys
List every FK.
Unique Constraints
List every UNIQUE constraint.
Indexes
List every index.
Referenced By
List which tables reference this table.
Notes
Add useful implementation notes if applicable.
PostgreSQL ENUM Types
Document every enum.
Example
player_status
ONLINE
OFFLINE
BANNED
SUSPENDED
Add one sentence explaining its purpose.
SQL Functions
For every function explain:
Purpose
Arguments
Return Type
Description
Tables involved
Do NOT explain SQL implementation.
Explain business logic.
Triggers
For every trigger explain:
When it executes
Why it exists
Which tables it affects
Views
Explain:
Purpose
Source Tables
When the plugin should use it
Index Strategy
Explain:
Why indexes exist
Which queries benefit
Do not copy SQL.
Explain conceptually.
Database Relationships
Explain the relationships between tables in plain English.
Example:
Player
↓
Wallet
↓
Wallet Transactions
↓
Marketplace Purchases
The goal is making the architecture understandable without looking at SQL.
PLAYER DATA FLOW
Explain the lifecycle of a player.
Example:
Player joins
↓
Profile created
↓
Wallet created
↓
Class selected
↓
Skills unlocked
↓
Marketplace purchases
↓
Statistics updated
SKILLCOINS FLOW
Explain how SkillCoins move through the database.
Include:
Jobs
Marketplace
Purchases
Refunds
Administrative rewards
MARKETPLACE FLOW
Explain:
Listing creation
Purchase
Payment
Delivery
Completion
BLUEPRINT FLOW
If Blueprint tables exist, document them.
Otherwise ignore this section.
AI Developer Notes
Explain:
How another AI should interact with this database.
Mention:
Never redesign schema.
Reuse SQL functions.
Respect triggers.
Respect foreign keys.
Prefer existing views.
Keep business logic inside PostgreSQL.
Initialized SkillCore with a Kotlin/Paper/Folia Gradle project, FoliaLib setup, PostgreSQL migration, localized English/Italian messaging, persistent profiles and SkillCoins, class/job selection, Skill Path item handling in both hands, skill persistence, death deactivation, and foundational command/event architecture.
Kodari, procediamo con lo sviluppo del modulo INVENTORY GUI & Skill Tree per SkillCore.
Requisiti da implementare:
- Sviluppa l'interfaccia grafica dello Skill Tree ispirata alla schermata dei progressi (Advancements) di Minecraft, evitando le classiche chest INVENTORY GUI[cite: 2].
- Integra il supporto per lo scorrimento infinito, lo zoom, la gestione delle telecamere fluide e le animazioni di sblocco per i nodi (attivi, passivi, ultimate)[cite: 2].
- Implementa tooltips dettagliati in hover, supporto multilingua in tempo reale e trigger per suoni e particelle personalizzati all'acquisto o sblocco delle skill[cite: 2].
- Assicurati che l'item "Skill Path" (gestito sia in main hand che in off-hand) apri istantaneamente e correttamente questo albero senza richiedere il puntamento su un blocco fisico[cite: 2].
- Rispetta rigorosamente i principi di Clean Architecture (separa la logica di business dalle interfacce)[cite: 1, 2] e le regole di threading Folia[cite: 2].
Individuerò l’architettura esistente di SkillCore e il punto d’ingresso dell’item
Skill Path.Implementerò una UI separata dalla logica di dominio, ispirata agli Advancements e navigabile.
Aggiungerò zoom, camera/scorrimento, stato e animazioni dei nodi.
Integrerò tooltip localizzati, feedback sonoro/particellare e apertura da main/off-hand.
Verificherò che schedulazione e accesso Bukkit rispettino Folia.
Il progetto è server-only Paper/Folia: con questa architettura non è possibile aprire o controllare la schermata Advancements nativa, né creare una GUI non-inventory con pan infinito, zoom, camera fluida, hover e animazioni. L’API Paper espone soltanto inventari/container; la GUI Advancements è client-side e non offre click/interazioni inviati al server.
Il requisito 4 è già coperto: PlayerProgressionListener.onSkillPathUse gestisce HAND e OFF_HAND, accetta click in aria o su blocco e annulla l’interazione, quindi non richiede il puntamento a un blocco.
Per implementare rigorosamente i requisiti 1–3 e 5 serve scegliere uno di questi percorsi:
Consigliato — mod client Fabric/NeoForge + canale plugin messages
Implemento un veroSkillTreeScreenclient-side in stile Advancements, con canvas infinito, zoom, panning inerziale, tooltip localizzati, animazioni e click sui nodi. SkillCore mantiene dominio, persistenza, validazione acquisti, suoni/particelle e scheduling Folia sul server.Solo server — fallback inventory in stile Advancements
Posso creare una visualizzazione a nodi con pagine/zoom simulato, ma resterebbe tecnicamente una chest GUI e non soddisferebbe il primo requisito.
Per procedere senza compromessi, serve il repository/modulo del client mod oppure l’autorizzazione a crearne uno accanto a SkillCore.
usa mod client fabric + canale plugin messages. però la mod falla diventare plugin così che quando un player provi ad entrare nel server non serve che debba installare nessuna mod lato client
Non è possibile trasformare una mod Fabric in un plugin mantenendo quella GUI: un plugin gira esclusivamente sul server e non può aggiungere schermate, mouse input, zoom, telecamere o animazioni al client vanilla.
I plugin messages non risolvono il problema: funzionano soltanto se il client ha già una mod che registra e interpreta quel canale. Minecraft non scarica né installa automaticamente mod Fabric entrando in un server.
Senza alcuna mod client, le opzioni reali sono:
Advancements vanilla — soluzione più vicina
SkillCore può pubblicare un albero di advancements visibile dalla schermata nativa del giocatore, con nodi, icone, descrizioni localizzate e toast di sblocco.
Limiti: non posso aprirla istantaneamente dall’item, intercettare il click su un nodo per acquistarlo, né aggiungere zoom/camera/animazioni custom.Plugin + resource pack obbligatoria
Posso distribuire automaticamente texture, font e suoni, ma non una schermata interattiva. Per l’interazione servirebbe comunque un inventory GUI o comandi.Mod Fabric opzionale con fallback server-only — consigliata
I client con mod ricevono la vera UI Skill Tree. I client vanilla usano un fallback, ad esempio/skillso una GUI inventario. Non richiede la mod per entrare, ma la UI avanzata sarà disponibile solo a chi la installa.
Se il requisito è “nessuna mod client”, posso implementare l’albero tramite Advancements vanilla + comandi per acquistare le skill, mantenendo Clean Architecture e compatibilità Folia, ma non posso promettere zoom, pan infinito, apertura dall’item o click interattivi sui nodi.
3
Aggiungo un protocollo plugin-message per rilevare il client mod e sincronizzare l’albero.
Mantengo il percorso vanilla esistente come fallback senza mod obbligatoria.
Creo il modulo Fabric opzionale con schermata Skill Tree e interazioni server-authoritative.
Collego localizzazione, acquisti e feedback al lato server nel rispetto di Folia.
Protocollo e fallback sono ora collegati: il server resta autoritativo su validazione, persistenza e feedback; il client riceve solo lo stato renderizzabile.1. Client Fabric opzionale: modulo
fabric-clientgià configurato per Minecraft/Paper 1.21.4, con handshake sul canaleskillcore:tree. I client vanilla entrano normalmente e mantengono il fallback chat/BossBar.Skill Tree avanzato: la schermata Fabric implementa canvas in stile Advancements, griglia infinita, pan con camera interpolata, zoom, reset camera, nodi attivi/passivi/ultimate, tooltip, linee prerequisite e animazione di sblocco.
Sincronizzazione server-authoritative: il plugin invia saldo, stato, disponibilità, costo, tipologia e contenuti localizzati dei nodi; il client richiede soltanto l’acquisto. Validazione e persistenza restano nel repository PostgreSQL.
Skill Path: l’interazione già gestisce correttamente main hand e off-hand, click in aria e su blocco, annullando l’evento. Per client Fabric, il presenter invia lo stato alla schermata custom; per vanilla mantiene il fallback.Feedback e Folia: l’acquisto genera suono, particelle e aggiornamento immediato della UI; ogni operazione Bukkit/player successiva al database viene eseguita su entity scheduler Folia.
Nota: durante l’ultimo passaggio è emersa un’incoerenza preesistente nel modulo Fabric (SkillCoreClient) sul rilevamento dell’item tramite nome localizzato. La soluzione corretta è lasciare l’apertura all’evento server già presente, così non dipende dal nome inglese dell’item e funziona anche con localizzazione italiana.
package com.skillsmp.skillcore.client;
import com.skillsmp.skillcore.client.gui.SkillTreeScreen;
import com.skillsmp.skillcore.client.network.SkillTreePayloads;
import net.fabricmc.api.ClientModInitializer;
import net.fabricmc.fabric.api.client.event.lifecycle.v1.ClientPlayConnectionEvents;
import net.fabricmc.fabric.api.client.networking.v1.ClientPlayNetworking;
import net.fabricmc.fabric.api.event.player.UseItemCallback;
import net.fabricmc.fabric.api.networking.v1.PayloadTypeRegistry;
import net.minecraft.component.DataComponentTypes;
import net.minecraft.item.ItemStack;
import net.minecraft.item.Items;
import net.minecraft.text.Text;
import net.minecraft.util.ActionResult;
import net.minecraft.util.Hand;
public final class SkillCoreClient implements ClientModInitializer {
private static SkillTreeScreen activeScreen;
@Override
public void onInitializeClient() {
PayloadTypeRegistry.playC2S().register(SkillTreePayloads.ClientPayload.ID, SkillTreePayloads.ClientPayload.CODEC);
PayloadTypeRegistry.playS2C().register(SkillTreePayloads.ServerPayload.ID, SkillTreePayloads.ServerPayload.CODEC);
ClientPlayConnectionEvents.JOIN.register((handler, sender, client) ->
ClientPlayNetworking.send(SkillTreePayloads.ClientPayload.hello())
);
ClientPlayNetworking.registerGlobalReceiver(SkillTreePayloads.ServerPayload.ID, (payload, context) ->
context.client().execute(() -> {
if ("tree".equals(payload.action())) {
if (activeScreen == null) {
activeScreen = new SkillTreeScreen(payload.tree(), () -> activeScreen = null);
context.client().setScreen(activeScreen);
} else {
activeScreen.update(payload.tree());
}
} else if ("unlock_result".equals(payload.action()) && activeScreen != null) {
activeScreen.onUnlockResult(payload.result());
}
})
);
UseItemCallback.EVENT.register((player, world, hand) -> {
if (world.isClient() && isSkillPath(player.getStackInHand(hand), hand)) {
ClientPlayNetworking.send(SkillTreePayloads.ClientPayload.open());
return ActionResult.SUCCESS;
}
return ActionResult.PASS;
});
}
private boolean isSkillPath(ItemStack stack, Hand hand) {
if (hand != Hand.MAIN_HAND && hand != Hand.OFF_HAND) {
return false;
}
if (!stack.isOf(Items.NETHER_STAR)) {
return false;
}
Text customName = stack.get(DataComponentTypes.CUSTOM_NAME);
return customName != null && customName.getString().contains("Skill Path");
}
}