1. Información general
ProImpuestos es un plugin para Paper 1.21.1 desarrollado en Java 21. Su objetivo es manejar una bolsa central de impuestos con almacenamiento seguro en MySQL, operaciones asíncronas, retiros atómicos, integración con Vault, historial y API pública para otros plugins.
Code (Text):
Nombre: ProImpuestos
Main class: mcbyte.proImpuestos.ProImpuestos
Versión: 1.0.0
Minecraft: Paper 1.21.1
Java: 21
Build system: Maven
Comando principal: /auroraimpuestos
[HR][/HR]
2. Requisitos
- Servidor Paper 1.21.1.
- Java 21.
- Vault instalado.
- Plugin de economía compatible con Vault, por ejemplo EssentialsX Economy.
- Servidor MySQL o MariaDB.
Nota: HikariCP y MySQL Connector/J se empaquetan dentro del JAR usando Maven Shade, por lo que no necesitas instalarlos manualmente en el servidor.
[HR][/HR]
3. Instalación
- Compila el plugin con Maven.
- Copia el JAR generado en la carpeta /plugins.
- Instala Vault y un plugin de economía compatible.
- Inicia el servidor una vez para generar la configuración.
- Edita plugins/ProImpuestos/config.yml.
- Configura los datos de MySQL.
- Reinicia el servidor o usa /auroraimpuestos reload.
Comando de compilación:
Code (Bash):
mvn clean package
El JAR final se genera en:
Code (Text):
target/ProImpuestos-1.0.0.jar
[HR][/HR]
4. Configuración de MySQL
Ejemplo de configuración:
Code (YAML):
mysql:
host
:
"localhost"
port
: 3306
database
:
"aurora"
user
:
"root"
password
:
"password"
useSSL
: false
allowPublicKeyRetrieval
: true
table-prefix
:
"proimpuestos_"
pool:
maximum-pool-size
: 10
minimum-idle
: 2
connection-timeout-ms
: 10000
idle-timeout-ms
: 600000
max-lifetime-ms
: 1800000
Explicación:
- host: IP o dominio del servidor MySQL.
- port: puerto de MySQL, normalmente 3306.
- database: base de datos donde se crearán las tablas.
- user: usuario de MySQL.
- password: contraseña del usuario.
- table-prefix: prefijo de las tablas del plugin.
- maximum-pool-size: máximo de conexiones abiertas por HikariCP.
- minimum-idle: conexiones mínimas en espera.
- connection-timeout-ms: tiempo máximo esperando una conexión.
[HR][/HR]
5. Tablas creadas
Por defecto, el plugin crea:
Code (Text):
proimpuestos_wallet
proimpuestos_transactions
proimpuestos_wallet guarda el saldo actual de la bolsa.
proimpuestos_transactions guarda el historial completo de movimientos:
- ID de transacción.
- Tipo de movimiento.
- Estado.
- Monto bruto.
- Monto neto.
- Monto quemado.
- Saldo anterior.
- Saldo nuevo.
- Fuente.
- Motivo.
- Nombre del actor.
- UUID del actor.
- Fecha.
[HR][/HR]
6. Sistema de ingresos
El comando de ingreso registra dinero dentro de la bolsa.
Code (Text):
/auroraimpuestos ingreso <cantidad> <motivo>
Ejemplo:
Code (Text):
/auroraimpuestos ingreso 50000 Impuestos de tiendas del centro
Si la quema está en 5%, al ingresar 50,000:
- Bruto: 50,000
- Quemado: 2,500
- Neto para la bolsa: 47,500
El movimiento se guarda en MySQL y puede enviarse a Discord por webhook.
[HR][/HR]
7. Sistema de egresos
Un egreso retira dinero de la bolsa y lo deposita a un jugador usando Vault.
Retirar hacia ti mismo:
Code (Text):
/auroraimpuestos egreso <cantidad> <motivo>
Ejemplo:
Code (Text):
/auroraimpuestos egreso 10000 Presupuesto para evento policial
Retirar hacia otro jugador:
Code (Text):
/auroraimpuestos egreso <jugador> <cantidad> <motivo>
Ejemplo:
Code (Text):
/auroraimpuestos egreso AndroNeko 25000 Pago de contrato municipal
Seguridad del egreso:
- El plugin verifica que Vault esté disponible.
- Bloquea la wallet con una transacción SQL.
- Comprueba saldo suficiente.
- Registra el egreso.
- Deposita el dinero al jugador.
- Si Vault falla, revierte el egreso.
Esto evita duplicaciones causadas por retiros simultáneos o errores de economía.
[HR][/HR]
8. Consultar saldo
Code (Text):
/auroraimpuestos saldo
Muestra el saldo actual de la bolsa central.
[HR][/HR]
9. Historial
Code (Text):
/auroraimpuestos historial [pagina] [limite]
Ejemplos:
Code (Text):
/auroraimpuestos historial
/auroraimpuestos historial 2
/auroraimpuestos historial 1 15
El límite máximo se controla desde config.yml:
Code (YAML):
historial:
default-limit
: 8
max-limit
: 20
[HR][/HR]
10. Porcentaje de quema
La quema permite destruir un porcentaje de cada ingreso antes de agregarlo a la bolsa.
Code (Text):
/auroraimpuestos quemar <porcentaje>
Ejemplo:
Code (Text):
/auroraimpuestos quemar 5
También se puede configurar en config.yml:
Code (YAML):
impuestos:
burn-percentage
: 5.0
Rango permitido: 0 a 100.
[HR][/HR]
11. Reload
Code (Text):
/auroraimpuestos reload
Recarga la configuración del plugin sin reiniciar el servidor.
Este comando actualiza mensajes, webhooks, porcentaje de quema y configuración general. Para cambios profundos de MySQL, se recomienda reiniciar.
[HR][/HR]
12. Comandos completos
Code (Text):
/auroraimpuestos ingreso <cantidad> <motivo>
/auroraimpuestos egreso <cantidad> <motivo>
/auroraimpuestos egreso <jugador> <cantidad> <motivo>
/auroraimpuestos saldo
/auroraimpuestos historial [pagina] [limite]
/auroraimpuestos quemar <porcentaje>
/auroraimpuestos reload
Alias disponibles:
Code (Text):
/auroraimpuesto
/impuestos
/proimpuestos
/pimpuestos
Subcomandos alternativos:
Code (Text):
ingreso, add, deposito
egreso, retirar, withdraw
saldo, balance, bolsa
quemar, burn
historial, history
reload, recargar
[HR][/HR]
13. Permisos
Code (Text):
proimpuestos.admin
Permite acceso completo.
Code (Text):
proimpuestos.ingreso
Permite registrar ingresos manuales.
Code (Text):
proimpuestos.egreso
Permite retirar dinero hacia uno mismo.
Code (Text):
proimpuestos.egreso.others
Permite retirar dinero hacia otro jugador.
Code (Text):
proimpuestos.saldo
Permite consultar el saldo.
Code (Text):
proimpuestos.quemar
Permite cambiar el porcentaje de quema.
Code (Text):
proimpuestos.reload
Permite recargar la configuración.
Code (Text):
proimpuestos.historial
Permite consultar el historial.
Permisos legacy:
Code (Text):
aurora.impuestos.egresos
aurora.impuestos.saldo
[HR][/HR]
14. Webhooks de Discord
ProImpuestos permite enviar notificaciones a Discord por tipo de movimiento.
Configuración:
Code (YAML):
webhooks:
enabled
: true
username
:
"ProImpuestos"
avatar-url
:
""
timeout-ms
: 7000
ingreso:
enabled
: true
url
:
""
content
:
""
title
:
"Ingreso de impuestos"
color
: 5763719
egreso:
enabled
: true
url
:
""
content
:
""
title
:
"Egreso de impuestos"
color
: 15548997
cancelado:
enabled
: true
url
:
""
content
:
""
title
:
"Movimiento revertido"
color
: 10038562
Tipos de webhook:
- ingreso: cuando entra dinero a la bolsa.
- egreso: cuando sale dinero de la bolsa.
- cancelado: cuando un egreso se revierte.
Los webhooks usan embeds con información de la transacción, montos, balance, motivo y actor.
[HR][/HR]
15. Mensajes personalizables
Los mensajes se editan desde config.yml.
Ejemplo:
Code (YAML):
mensajes:
prefix
:
"&6[ProImpuestos]&f "
sin-permiso
:
"%prefix%&cNo tienes permiso para usar esto."
procesando
:
"%prefix%&7Procesando operación..."
saldo
:
"%prefix%Saldo de la bolsa: &a$%saldo%"
Placeholders internos disponibles en mensajes:
Code (Text):
%prefix%
%bruto%
%neto%
%quemado%
%saldo%
%cantidad%
%player%
%motivo%
%porcentaje%
%pagina%
%id%
%fecha%
%tipo%
%estado%
%actor%
[HR][/HR]
16. API para otros plugins
ProImpuestos expone una API pública mediante Bukkit ServicesManager.
Obtener la API:
Code (Java):
RegisteredServiceProvider
<ProImpuestosApi
> provider
=
Bukkit.
getServicesManager
(
).
getRegistration
(ProImpuestosApi.
class
)
;
if
(provider
==
null
)
{
return
;
}
ProImpuestosApi api
= provider.
getProvider
(
)
;
Registrar un ingreso:
Code (Java):
api.
registerIncome
(
BigDecimal.
valueOf
(
1000
),
"ProStores",
"Compra en tienda de minería",
player.
getName
(
),
player.
getUniqueId
(
)
).
thenAccept
(result
->
{
if
(result.
success
(
)
)
{
Bukkit.
getLogger
(
).
info
(
"Impuesto registrado. Saldo: "
+ result.
balance
(
)
)
;
}
}
)
;
Registrar un egreso interno:
Code (Java):
api.
registerExpense
(
BigDecimal.
valueOf
(
5000
),
"MiPlugin",
"Pago interno autorizado",
player.
getName
(
),
player.
getUniqueId
(
)
).
thenAccept
(result
->
{
if
(result.
success
(
)
)
{
Bukkit.
getLogger
(
).
info
(
"Egreso registrado: "
+ result.
transaction
(
).
id
(
)
)
;
}
}
)
;
Consultar saldo:
Code (Java):
api.
getBalance
(
).
thenAccept
(balance
->
{
Bukkit.
getLogger
(
).
info
(
"Saldo de impuestos: "
+ balance
)
;
}
)
;
Consultar historial:
Code (Java):
api.
getHistory
(
1,
10
).
thenAccept
(history
->
{
for
(TaxTransaction tx
: history
)
{
Bukkit.
getLogger
(
).
info
(
"#"
+ tx.
id
(
)
+
" "
+ tx.
type
(
)
+
" "
+ tx.
amount
(
)
)
;
}
}
)
;
Métodos disponibles:
Code (Java):
CompletableFuture
<TaxTransactionResult
> registerIncome
(
BigDecimal grossAmount,
String source,
String reason,
String actorName,
UUID actorUuid
)
;
CompletableFuture
<TaxTransactionResult
> registerExpense
(
BigDecimal amount,
String source,
String reason,
String actorName,
UUID actorUuid
)
;
CompletableFuture
<TaxTransactionResult
> cancelExpense
(
long transactionId,
String cancelReason
)
;
CompletableFuture
<BigDecimal
> getBalance
(
)
;
CompletableFuture
<List
<TaxTransaction
>> getHistory
(
int page,
int limit
)
;
double getBurnPercentage
(
)
;
[HR][/HR]
17. Ejemplo de integración con una tienda
Supongamos que un jugador compra un item por $10,000 y quieres mandar $1,000 a la bolsa de impuestos.
Code (Java):
BigDecimal tax
=
BigDecimal.
valueOf
(
1000
)
;
api.
registerIncome
(
tax,
"ProStores",
"Impuesto por compra de "
+ itemName,
player.
getName
(
),
player.
getUniqueId
(
)
).
thenAccept
(result
->
{
if
(
!result.
success
(
)
)
{
Bukkit.
getLogger
(
).
warning
(
"No se pudo registrar impuesto: "
+ result.
message
(
)
)
;
return
;
}
```
Bukkit.
getLogger
(
).
info
(
"Impuesto registrado correctamente."
)
;
```
}
)
;
Importante: La API trabaja de forma asíncrona. Si necesitas usar Bukkit API después del resultado, vuelve al hilo principal con el scheduler del servidor.
[HR][/HR]
18. Seguridad y buenas prácticas
- No entregues proimpuestos.admin a rangos normales.
- Usa proimpuestos.egreso.others solo para administradores o roles financieros.
- Activa webhooks para auditar todos los egresos.
- Usa motivos claros y obligatorios.
- Configura límites de historial razonables.
- Haz backups de MySQL.
- No edites manualmente la tabla wallet sin saber lo que haces.
[HR][/HR]
19. Solución de problemas
Vault no está disponible
Verifica que tengas Vault y un plugin de economía compatible instalado.
No conecta a MySQL
Revisa host, puerto, usuario, contraseña, permisos y firewall.
Los webhooks no llegan
Revisa que la URL esté bien copiada y que
enabled esté en true.
El egreso se revierte
Esto significa que la bolsa sí descontó inicialmente, pero Vault no pudo depositar el dinero al jugador. El plugin revierte el movimiento automáticamente.
El historial está vacío
Asegúrate de haber registrado ingresos o egresos correctamente.
[HR][/HR]
20. Migración desde AuroraImpuestos
ProImpuestos usa un esquema nuevo y más seguro.
La tabla antigua:
No se reutiliza automáticamente.
El nuevo esquema usa:
Code (Text):
proimpuestos_wallet
proimpuestos_transactions
Si tienes datos reales en AuroraImpuestos, migra manualmente antes de borrar la tabla antigua.