MatrixMarket icon

MatrixMarket -----

Um mercado global robusto para Minecraft que permite aos jogadores anunciar e comprar itens

Download Now
Via external site



MatrixMarket - Documentacao
Referencia completa de instalacao, configuracao e API
​

Sumario

  1. Instalacao
  2. Configuracao (config.yml)
  3. Mensagens (messages.yml)
  4. Comandos
  5. Permissoes
  6. Mecanicas de Jogo
  7. Economias e Provedores
  8. Banco de Dados
  9. API para Desenvolvedores
  10. Arquitetura Interna
  11. Compatibilidade de Versoes
  12. Solucao de Problemas
  13. Changelog

[ANCHOR=instalacao]1. Instalacao[/ANCHOR]

Requisitos

  • Java 8 ou superior (recomendado Java 17+ para servidores modernos)
  • Paper ou Spigot nas versoes 1.8 ate 1.21+
  • (Opcional) Vault com um plugin de economia compativel (EssentialsX, CMI, etc.)
  • (Opcional) PlayerPoints

Passos

  1. Baixe o arquivo MatrixMarket-1.0.0.jar na aba Releases do repositorio
  2. Mova o .jar para a pasta plugins/ do seu servidor
  3. Reinicie o servidor completamente (nao use reload de servidor)
  4. Os arquivos de configuracao serao gerados automaticamente em plugins/MatrixMarket/
  5. Edite o config.yml conforme suas necessidades
  6. Use /mercado reload para aplicar as alteracoes sem reiniciar

Estrutura de Arquivos Gerada

Code (Text):

plugins/
  MatrixMarket/
    config.yml        <- Configuracoes principais
    messages.yml      <- Todas as mensagens do plugin
    data/
      market.db       <- Banco de dados SQLite (se configurado)
 
[ANCHOR=configuracao]2. Configuracao (config.yml)[/ANCHOR]

Abaixo esta o arquivo de configuracao completo com todos os campos documentados.

Code (YAML):

# Habilita ou desabilita o mercado globalmente
habilitado : true

# Modo de exibicao do mercado
# false = tela de categorias (padrao)
# true  = lista unica com scroll por todos os itens
modo-scroller : false

# Tempo padrao maximo de expiracao dos anuncios (em horas)
# 0 = sem expiracao automatica
tempo-expiracao : 48

# Limite de anuncios ativos por jogador
# Pode ser sobrescrito pela permissao matrixmarket.sell_limit.<N>
limite-vendas : 10

# Preco minimo permitido por anuncio
preco-minimo : 1.0

# Preco maximo permitido por anuncio
# 0 = sem limite maximo
preco-maximo : 0.0

# --- Destaques ---
# Maximo de anuncios destacados simultaneamente
limite-destaques : 2

# Custo para destacar um anuncio (na moeda padrao)
custo-destaque : 1000.0

# Duracao do destaque em horas
duracao-destaque : 24

# --- Taxa sobre vendas ---
taxa:
  habilitado : false
  percentual : 5.0   # porcentagem descontada do valor recebido pelo vendedor

# --- Anuncio no chat ao criar uma venda ---
anuncio:
  habilitado : true
  # true = somente jogadores com matrixmarket.announce recebem a mensagem
  somente-permissao : false

# --- Comportamento do correio ---
correio :
   # Entregar dinheiro de vendas via correio
  valores : true
  # Devolver itens de anuncios expirados via correio
  itens-expirados : true

# --- Blacklist de materiais ---
# Materiais desta lista nao podem ser vendidos
# Use os nomes exatos em maiusculas (ex: DIAMOND_SWORD)
blacklist :
  - BEDROCK
  - BARRIER
  - COMMAND_BLOCK

# --- Banco de dados ---
database :
   # SQLITE (sem configuracao adicional) ou MYSQL
  type : SQLITE
  host : localhost
  port : 3306
  database : matrixmarket
  username : root
  password : ""

# --- Provedores de economia ---
economies :
   # Provedor padrao usado em novas vendas
  default : money
  providers:
    money:
      provider : Money           # identificador interno (Vault)
      display : "Dinheiro"       # nome exibido nos menus
      abbreviated : "coins"       # abreviacao nos tooltips
      allow-offline : true       # permitir transacoes com jogador offline
      permission : matrixmarket.provider.money
    points:
      provider : PlayerPoints
      display : "Pontos"
      abbreviated : "pts"
      allow-offline : true
      permission : matrixmarket.provider.points
 
[ANCHOR=mensagens]3. Mensagens (messages.yml)[/ANCHOR]

O arquivo messages.yml controla todas as mensagens enviadas ao jogador. Suporta codigos de cor com & e variaveis dinamicas entre {}.

Variaveis Disponiveis

Variavel Descricao
{player} Nome do jogador
{item} Nome do item
{price} Valor formatado do anuncio
{seller} Nome do vendedor
{buyer} Nome do comprador
{economy} Nome da economia usada
{limit} Limite de anuncios do jogador


[ANCHOR=comandos]4. Comandos[/ANCHOR]

Todos os comandos possuem os aliases /market e /mk alem de /mercado.

/mercado
Abre o menu principal do mercado com todas as categorias disponiveis.
  • Permissao: matrixmarket.use

/mercado vender
Inicia o processo de criacao de anuncio com o item segurado na mao. O plugin ira solicitar o preco via chat e guiar o jogador pelas opcoes de configuracao do anuncio.
  • Permissao: matrixmarket.sell
  • O item nao pode estar na blacklist
  • O jogador nao pode estar banido do mercado
  • O limite de anuncios ativos nao pode ter sido atingido

/mercado vendas
Abre o menu com todos os anuncios ativos criados pelo proprio jogador. Permite cancelar anuncios e pagar por destaques.
  • Permissao: matrixmarket.use

/mercado pessoal
Lista os anuncios direcionados exclusivamente ao jogador por outros vendedores.
  • Permissao: matrixmarket.use

/mercado ban <jogador>
Bane um jogador de criar e comprar no mercado. O jogador banido ainda pode acessar o correio para resgatar itens pendentes.
  • Permissao: matrixmarket.ban
  • Funciona com jogadores offline

/mercado unban <jogador>
Remove o banimento de um jogador, restaurando seu acesso ao mercado.
  • Permissao: matrixmarket.ban

/mercado reload
Recarrega o config.yml e o messages.yml sem reiniciar o servidor. Anuncios ativos em memoria nao sao afetados.
  • Permissao: matrixmarket.reload

[ANCHOR=permissoes]5. Permissoes[/ANCHOR]

Permissao Descricao Padrao
matrixmarket.use Abrir o mercado e acessar menus true
matrixmarket.sell Criar anuncios de venda true
matrixmarket.admin Acesso total administrativo op
matrixmarket.reload Recarregar arquivos de configuracao op
matrixmarket.ban Banir e desbanir jogadores op
matrixmarket.announce Receber mensagens de novas vendas no chat true
matrixmarket.sponsor Destacar vendas sem custo false
matrixmarket.buy.sponsor Pagar para destacar um anuncio true
matrixmarket.staff.collect Remover qualquer item do mercado via Shift+Click op
matrixmarket.provider.money Usar economia Money (Vault) true
matrixmarket.provider.points Usar economia PlayerPoints true
matrixmarket.sell_limit.<N> Limite de anuncios ativos para o grupo (substitua N pelo numero) —


Limite de Vendas por Permissao

O sistema de limite de vendas e dinamico. Ao inves de um valor fixo, voce pode atribuir permissoes diferentes para grupos diferentes:

Code (Text):

matrixmarket.sell_limit.5   <- VIP basico: 5 anuncios
matrixmarket.sell_limit.20  <- VIP Plus: 20 anuncios
matrixmarket.sell_limit.50  <- Staff: 50 anuncios
 
O plugin verifica todas as permissoes do jogador e aplica o maior valor encontrado. O campo limite-vendas do config.yml funciona como valor padrao para quem nao possui nenhuma permissao de limite.

[ANCHOR=mecanicas]6. Mecanicas de Jogo[/ANCHOR]

Fluxo de Criacao de Anuncio

  1. O jogador segura o item e usa /mercado vender
  2. O plugin verifica: habilitado, banimento, blacklist, limite de anuncios
  3. O jogador digita o preco no chat (deve respeitar preco-minimo e preco-maximo)
  4. Um menu e aberto para configurar: duracao, moeda e destinatario (todos ou especifico)
  5. O jogador confirma; o item e removido do inventario e o anuncio e salvo no banco
  6. Uma mensagem de anuncio e enviada no chat (se habilitado)

Fluxo de Compra

  1. O jogador abre o mercado e navega pelas categorias
  2. Clica no item para ver detalhes: vendedor, preco, economia, tempo restante
  3. Confirma a compra
  4. O plugin verifica saldo; debita do comprador
  5. O item vai direto ao inventario do comprador, ou ao correio se estiver cheio
  6. O valor (menos a taxa, se habilitada) vai ao correio do vendedor

Sistema de Correio

O correio funciona como uma caixa de entrada persistente. Ele e utilizado em tres situacoes:

  • Venda concluida: o dinheiro vai ao correio do vendedor
  • Inventario cheio: o item comprado vai ao correio do comprador
  • Anuncio expirado: o item retorna ao correio do vendedor

O correio e acessivel pelo menu principal do mercado. Cada entrada pode ser coletada individualmente. Administradores com matrixmarket.staff.collect podem coletar entradas de outros jogadores usando Shift+Click.

Sistema de Destaques

  • Acesse "Minhas Vendas" e clique com o botao direito no anuncio desejado
  • O custo e debitado imediatamente na moeda padrao configurada
  • O item aparece na aba de destaques pelo tempo configurado em duracao-destaque
  • Maximo de limite-destaques anuncios em destaque simultaneamente por jogador
  • Jogadores com matrixmarket.sponsor destacam sem pagar

Venda Pessoal

Ao criar um anuncio, o vendedor pode direciona-lo a um jogador especifico pelo nome. Esse anuncio:
  • Nao aparece na listagem geral do mercado
  • So e visivel ao destinatario em /mercado pessoal
  • Expira normalmente caso nao seja comprado

[ANCHOR=economia]7. Economias e Provedores[/ANCHOR]

O MatrixMarket suporta multiplos provedores de economia simultaneamente. Cada anuncio registra qual economia foi usada na criacao e a compra ocorre sempre nessa mesma moeda.

Vault (Money)

Requer o plugin Vault instalado e ativo, alem de um plugin de economia compativel (EssentialsX, CMI, iConomy, etc.).

Code (YAML):

economies:
  providers:
    money:
      provider : Money
      display : "Dinheiro"
      abbreviated : "coins"
      allow-offline : true
      permission : matrixmarket.provider.money
 
PlayerPoints

Requer o plugin PlayerPoints instalado e ativo.

Code (YAML):

economies:
  providers:
    points:
      provider : PlayerPoints
      display : "Pontos"
      abbreviated : "pts"
      allow-offline : true
      permission : matrixmarket.provider.points
 
Adicionando Provedores Customizados

Novos provedores podem ser adicionados via API estendendo a classe base de provedor e registrando-os no EconomyManager. Consulte a secao de API para detalhes.

[ANCHOR=banco]8. Banco de Dados[/ANCHOR]

SQLite (Padrao)

Nenhuma configuracao adicional e necessaria. O arquivo market.db e criado automaticamente em plugins/MatrixMarket/data/.

Code (YAML):

database:
  type : SQLITE
 
MySQL

Recomendado para servidores com alto volume de transacoes ou que usam banco de dados compartilhado entre instancias. Utiliza HikariCP para pool de conexoes.

Code (YAML):

database:
  type : MYSQL
  host : localhost
  port : 3306
  database : matrixmarket
  username : seu_usuario
  password : sua_senha
 
O plugin cria as tabelas necessarias automaticamente na primeira inicializacao. O usuario do banco deve ter permissoes CREATE, SELECT, INSERT, UPDATE e DELETE.

[ANCHOR=api]9. API para Desenvolvedores[/ANCHOR]

O MatrixMarket expoe uma API publica para que outros plugins possam interagir com o mercado programaticamente.

Dependencia (build.gradle)

Code (Groovy):

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    compileOnly 'com.github.m4trixdev:MatrixMarket:1.0.0'
}
 
Acessando os Servicos

Code (Java):

Main plugin = (Main ) Bukkit. getPluginManager ( ). getPlugin ( "MatrixMarket" ) ;

MarketManager  market   = plugin. getMarketManager ( ) ;
MailManager    mail     = plugin. getMailManager ( ) ;
EconomyManager economy = plugin. getEconomyManager ( ) ;
 
MarketManager

Code (Java):

// Listar todos os anuncios ativos
List <MarketItem > itens = market. getAllActive ( ) ;

// Anuncios de um jogador especifico
List <MarketItem > meus = market. getBySeller (player. getUniqueId ( ) ) ;

// Anuncios filtrados por categoria
List <MarketItem > espadas = market. getByCategory ( "espadas" ) ;

// Anuncios pessoais direcionados a um jogador
List <MarketItem > pessoais = market. getPersonalFor (player. getName ( ) ) ;

// Cancelar um anuncio pelo ID
market. cancelListing (player, itemId ) ;

// Executar uma compra
market. buyItem (player, itemId ) ;
 
MailManager

Code (Java):

// Enviar dinheiro ao correio de um jogador
mail. addMoney (player. getUniqueId ( ), 500.0, "Espada de Diamante" ) ;

// Enviar item ao correio de um jogador
mail. addItem (player. getUniqueId ( ), itemStack ) ;

// Verificar se um jogador tem entradas no correio
boolean temCorreio = mail. hasEntries (player. getUniqueId ( ) ) ;

// Coletar uma entrada especifica
boolean sucesso = mail. collectEntry (player, entryId ) ;
 
[ANCHOR=arquitetura]10. Arquitetura Interna[/ANCHOR]

Code (Text):

Main
├── ConfigManager         -> Carregamento e validacao do config.yml
├── MessagesManager       -> Mensagens e substituicao de variaveis
├── MenusConfig           -> Configuracao visual dos menus de inventario
├── DatabaseManager       -> Gerenciamento do banco de dados (SQLite/MySQL)
│   └── BaseSQLStorage    -> Implementacao base SQL
│       ├── SQLiteStorage -> Driver SQLite
│       └── HikariStorage -> Driver MySQL com pool HikariCP
├── EconomyManager        -> Registro e gerenciamento de provedores de economia
│   ├── VaultProvider     -> Integracao com Vault
│   └── PlayerPointsProvider -> Integracao com PlayerPoints
├── CategoryManager       -> Classificacao automatica de itens por categoria
├── MarketManager         -> Logica central: criar, comprar, cancelar anuncios
├── MailManager           -> Sistema de correio (dinheiro e itens)
├── PlayerManager         -> Dados dos jogadores (limite de vendas, banimentos)
└── SoundManager          -> Efeitos sonoros dos menus
 
Listeners de Eventos

  • MenuClickListener — Gerencia todos os cliques nos menus de inventario
  • ChatInputListener — Captura entrada de texto no chat (preco, destinatario)

Modelos de Dados

Modelo Descricao
MarketItem Representa um anuncio ativo no mercado
SellSession Estado temporario de uma venda em andamento
MailEntry Entrada no correio (dinheiro ou item)
PlayerData Dados persistentes do jogador (banimento, limites)
Category Categoria de item com icone e lista de materiais


[ANCHOR=compatibilidade]11. Compatibilidade de Versoes[/ANCHOR]

O plugin detecta automaticamente a versao do servidor e adapta seu comportamento internamente, sem necessidade de configuracao adicional.

Versao Materiais Action Bar / Title Cabecas Customizadas
1.8 – 1.12 (Legacy) Nomes antigos + data values Via NMS reflection Via GameProfile reflection
1.13 – 1.17 Nomes modernos Via BungeeCord API Via GameProfile reflection
1.18.1+ Nomes modernos Via BungeeCord API Via PlayerProfile API


Limitacoes Conhecidas

  • Dados sao carregados em memoria na inicializacao; uma queda abrupta do servidor pode perder anuncios recentes nao persistidos
  • Versoes legadas (1.8–1.12) usam WOOL com data values — alguns materiais de menu podem ter aparencia diferente do esperado
  • Cabecas de jogador com texturas customizadas requerem acesso a internet no servidor para carregar corretamente
  • PlayerPoints so funciona se o plugin estiver instalado e ativo no momento da inicializacao

[ANCHOR=problemas]12. Solucao de Problemas[/ANCHOR]

O mercado nao abre
  • Verifique se habilitado: true esta no config.yml
  • Confirme que o jogador tem a permissao matrixmarket.use
  • Revise os logs do servidor na inicializacao para erros de carregamento

Banco de dados nao conecta
  • Para MySQL: confira host, porta, usuario e senha
  • Verifique se o banco de dados existe e se o usuario tem as permissoes necessarias
  • Para SQLite: verifique se o servidor tem permissao de escrita em plugins/MatrixMarket/data/

Economia nao funciona
  • Certifique-se de que Vault e um plugin de economia compativel estao instalados e ativos
  • Para PlayerPoints, confirme que o plugin esta ativo
  • Use /mercado reload apos alterar as economias no config
  • Verifique nos logs se o provedor foi registrado com sucesso na inicializacao

Configuracao nao recarrega corretamente
  • Valide a sintaxe YAML do config.yml em um validador online (ex: yaml-online-parser.appspot.com)
  • Certifique-se de que o arquivo esta salvo em codificacao UTF-8
  • Cheque os logs do servidor imediatamente apos o reload por erros de parsing

Itens nao aparecem nas categorias corretas
  • Use o nome exato do material em maiusculas (ex: DIAMOND_SWORD, OAK_LOG)
  • Revise os materiais configurados em cada categoria no config.yml
  • Use /mercado reload apos qualquer alteracao nas categorias
[ANCHOR=changelog]13. Changelog[/ANCHOR]

v1.0.0 - Lancamento Inicial
  • Sistema completo de anuncios com criacao, compra e cancelamento
  • Categorias configuraveis com classificacao automatica por material
  • Sistema de destaques com custo e duracao configuraveis
  • Correio integrado para entrega de dinheiro e itens
  • Suporte a multiplas economias simultaneas (Vault + PlayerPoints)
  • Filtro por categoria e paginacao em todos os menus
  • Venda pessoal direcionada a jogador especifico
  • Sistema de banimento de jogadores
  • Limite de vendas dinamico por permissao (sell_limit.<N>)
  • Expiracao automatica com devolucao via correio
  • Banco de dados SQLite e MySQL com HikariCP
  • Taxa percentual configuravel sobre vendas
  • Compatibilidade com versoes 1.8 a 1.21+


Desenvolvido por M4trixDev
GitHub | Reportar Bug | Discussoes
​
View on SpigotMC
Resource Information
Author:
----------
Total Downloads: 5
First Release: Mar 11, 2026
Last Update: Mar 11, 2026
Category: ---------------
All-Time Rating:
0 ratings
Version -----
Released: --------------------
Downloads: ------
Version Rating:
----------------------
-- ratings