🛡️ MW Idle: Medieval Warriors — Plano de Desenvolvimento

Regras do Mercado (Limites por Nível)

1. Visão Geral do Projeto

MW Idle é a versão idle/incremental do universo Medieval Warriors. O jogo roda de forma leve e em segundo plano em múltiplos dispositivos, permitindo que os jogadores progridem passivamente, dropem itens, gerenciem recursos e comercializem equipamentos em um mercado global de dinheiro real.

O grande diferencial do projeto é a integração direta com a API do Mercado Pago através de um ecossistema Peer-to-Peer (P2P). Isso possibilita que os jogadores criem suas próprias lojinhas e vendam itens diretamente para outros players, recebendo o saldo via Pix na sua própria conta bancária.

---

2. Arquitetura e Engenharia de Software

2.1. Multiplataforma (Flutter Core)

* Mobile & Web: Interface totalmente responsiva que se adapta perfeitamente a telas verticais (smartphones) e horizontais (monitores).

Desktop App: Compilação nativa para Windows, macOS e Linux. Implementação de ciclo de vida em segundo plano com a capacidade de minimizar o jogo diretamente para a bandeja do sistema (System Tray* usando o pacote tray_manager), garantindo consumo mínimo de CPU/RAM.

* Gerenciamento de Estado: Uso de BLoC, Provider ou Riverpod para garantir que o cálculo contínuo de ganho de recursos por segundo (+X moedas/recursos por segundo) seja preciso e fluido.

* Notificações: Sistema híbrido de alertas. Firebase Cloud Messaging (FCM) para o app Android, Web Push para navegadores e Notificações Locais da OS para a versão Desktop.

2.2. Back-end & Segurança (Mandatório)

* Tecnologia Sugerida: Node.js, Python ou Firebase Cloud Functions.

* Regra de Ouro (Server-Side): O cliente Flutter funciona estritamente como uma interface visual responsiva. Toda a lógica de jogo, taxas, inventários, tabelas de drops e transações financeiras são calculadas, validadas e processadas estritamente no servidor. Isso impede trapaças de memória ou velocidade (ex: Cheat Engine ou manipulação de variáveis no console F12 da Web).

---

3. Ecossistema Econômico & Monetização

Para eliminar o atrito psicológico de cobrar dinheiro real via Pix em cada microtransação e proteger a economia de taxas bancárias abusivas, o jogo adota uma moeda intermediária chamada Gemas.

3.1. Aquisição de Gemas pelo Jogador

1. Rewarded Ads (Anúncios Premiados): O jogador assistir voluntariamente a um anúncio de ~30 segundos para obter gemas gratuitamente (ex: ganha 10 Gemas).

Métrica Estimada (Brasil):* eCPM médio de US$ 2.50 a US$ 6.00 por 1.000 impressões (~R$ 0,012 a R$ 0,030 gerados para o desenvolvedor por anúncio).

2. In-App Purchases / Compra Direta: Jogadores que preferem conveniência podem comprar pacotes de gemas via Pix direto para o desenvolvedor (ex: 1.000 Gemas por R$ 4,90).

3.2. Abordagem de Anúncios Cross-Progression (Desktop/Web)

Como as redes de anúncio mobile (AdMob) não possuem SDK nativo para Desktop, o ecossistema de progresso será unificado de forma segura no servidor (Cross-Save):

* Jogadores de Desktop e Web utilizam a mesma conta do mobile. Se precisarem de Gemas gratuitas, podem abrir rapidamente o app no Android, assistir aos anúncios desejados e o saldo será atualizado instantaneamente em todas as plataformas.

Alternativamente, a versão Web pode integrar redes de anúncios focadas em H5 (como CrazyGames ou AdSense para Jogos*).

3.3. Mecânica do Mercado P2P (Mercado Pago API)

* Integração Segura: Autenticação feita via Mercado Pago Connect (OAuth). O jogador vendedor autoriza a aplicação do jogo uma única vez de forma segura no ambiente oficial do Mercado Pago.

* Fluxo de Compra: Quando o Jogador B decide comprar um item do Jogador A, o servidor do jogo consome o token autorizado do Jogador A e gera um Pix Copia e Cola / QR Code dinâmico associado diretamente à conta dele.

Segurança Anti-Fraude: Transações de mercado P2P liberadas exclusivamente via Pix. Isso zera o risco de chargebacks*, contestações de má-fé e cartões clonados que gerariam prejuízos aos vendedores e suporte massivo ao desenvolvedor.

Validação: O Mercado Pago envia uma notificação (Webhook*) para o servidor do jogo confirmando a liquidação do Pix. O servidor intercepta o sinal, transfere o item do vendedor para o comprador e notifica ambos.

---

4. Regras do Mercado (Níveis de Usuário) & Taxas P2P

Como medida essencial para combater spam de bots, manter o mercado saudável e estruturar o faturamento do jogo, os anúncios de itens seguem limitações estritas de slots, tempo de validade e taxas de comissão progressivas conforme o status do jogador:

Taxas de Comissão P2P (application_fee — Mercado Pago)

| Status do Vendedor | Taxa da Plataforma |

| :--- | :--- |

| Free | 10% |

| Free + Passe do Mercador | 7% |

| Premium | 6% |

| Premium + Passe do Mercador | 3% |

Pagamentos via PIX automático: o comprador paga com Pix, o vendedor recebe na hora na sua conta Mercado Pago (tempo médio de liquidação: < 1 minuto). A plataforma retém automaticamente a comissão via application_fee da API do Mercado Pago.

Slots e Limites

| Benefício / Limitação | Usuário Free | Usuário Premium | Passe do Mercador |

| :--- | :--- | :--- | :--- |

| Slots Simultâneos | Até 2 itens ativos | Até 10 itens ativos | Até 15 itens ativos |

| Tempo de Exposição | 48 horas | 7 dias | 7 dias |

| Custo por Anúncio | Taxa fixa em Gemas (ex: 50 gemas) | Isento ou Reduzido | Totalmente Isento |

Nota: O tempo limite de exposição limpa automaticamente o banco de dados de itens obsoletos de contas inativas ou abandonadas.

---

5. Sistemas de Gameplay & Progressão (Inspirado no Benchmark)

Para garantir retenção de longo prazo e profundidade RPG, o jogo conta com quatro pilares centrais de progressão:

5.1. Gerenciamento de Formação e Companheiros

* O jogador monta uma equipe de até 4 heróis de classes clássicas de RPG (Guerreiro, Arqueira, Mago, Sacerdote) e desbloqueia slots para Mascotes (Pets).

* Contratos P2P (Aluguel de Mercenários): Jogadores podem colocar seus heróis de alto nível para serem alugados por outros players em troca de Ouro do jogo, gerando engajamento econômico interno.

5.2. Crafting (Ofícios do Mercador)

Centro de ofícios com 5 bancadas. Atua como o principal regulador do mercado financeiro real, incentivando a queima constante de "itens lixo" para a criação de commodities valiosas.

* Vocações (6): Guerreiro, Arqueira, Mago, Sacerdote, Ladino, Necromante.

* Qualidades (11): Comum, Incomum, Raro, Lendário, Imortal, Arcano, Além, Celestial, Divino, Cósmico, Rainbow.

* Sub-nível por qualidade: 0-9. Cada qualidade pode subir 10 níveis antes de avançar para a próxima (ex: Comum+0 → Comum+9 → Incomum+0).

* Tipos de equipamento (15): Arma Principal, Arma Secundária, Elmo, Armadura, Luvas, Botas, Colar, Brincos, Anel, Pulseira, Calças, Capa, Asa, Promotion, Pedra dos Deuses.

* 12 slots de equipamento: Colar, Elmo, Capa/Asa, Mão Primária, Armadura, Mão Secundária, Anel 1, Calças, Anel 2, Pulseira, Botas, Promotion.

* Inventário: 24 slots. Stash: até 10 abas de 48 slots cada.

Moedas

* Ouro (💵): Moeda principal, obtida em caçadas e alquimia.

* Diamonds (💎): Moeda premium. Comprada com dinheiro real ou obtida via anúncios/recompensas. Usada para: destravar abas do stash (50), comprar Promotion (1000), recuperar gemstones ao remover (100/gema).

* Gemstones (💠): Gemas dropadas por monstros/loot boxes: Topázio (+ATK), Rubi (+ATK), Esmeralda (+DEF), Safira (+DEF), Ametista (+ATK). Socketadas em equipamentos (máx: 1+qualidade). Cada gema aplicada sobe o tier efetivo do item.

Aba Alquimia — Quebra para ouro

* Seleciona N itens do inventário e "quebra" em troca de ouro.

* Botão "Selecionar todos por tier" para marcar rapidamente.

* Resultado exibido em dialog com total de ouro e breakdown por tipo de item.

* Itens bloqueados ou Pedra dos Deuses não aparecem na lista.

Aba Síntese — 9 itens → 1 item melhor

* Combina 9 itens do mesmo tier (sem gemas, não bloqueados) para forjar 1 item do tier seguinte.

* O tipo do equipamento resultante é aleatório.

* Botão "Auto (menor valor)" seleciona automaticamente os 9 itens mais baratos do tier.

* Animação fullscreen: 9 itens convergem ao centro em grade 3×3 → flash → resultado.

Aba Fusão — Avançar sub-nível de qualidade

* Une 2 itens com mesmo Tipo, Tier, Vocação, Sub-nível e Nome.

* Resultado: qualityIndex + 1. A cada 10 fusões, a qualidade avança (Comum+9 → Incomum+0).

* Nome do item após fusão: Nome Base [fusionLevel] (ex: "Espada [3]").

* Chance de sucesso por qualidade: Comum 95%, Incomum 80%, Raro 60%, Lendário 40%, Imortal 30%, Arcano 20%, Além 15%, Celestial 10%, Divino 5%, Cósmico 2%, Rainbow 1%.

* Falha sem Pedra: perde 1 dos 2 itens. Com Pedra: +25% chance e 0 itens perdidos.

* Animação fullscreen: itens convergem das extremidades → flash branco → fade → resultado.

* Janela de inventário especial mostra itens do inventário + stash que podem ser fundidos (3 linhas visíveis + scroll).

* Pedra dos Deuses: Consumível raro. Ao usar na fusão: +25% chance de sucesso, e em caso de falha, nenhum item é perdido (apenas a pedra é consumida). Pode ser obtida via gmlootbox de desenvolvimento.

Aba Adicionar Gemas — Socketar gemstone

* Grid visual do inventário mostrando equipamentos com slot livre.

* Escolhe uma gemstone da bag (Topázio, Rubi, etc.) para socketar.

* Cada gema aplicada adiciona +1 ao tier efetivo (max lendário).

* Pedra dos Deuses e itens bloqueados não aceitam gemas.

Aba Remover Gemas — Limpar slot

* Mostra slots de gemas ocupados. Cada slot tem 2 opções:

* Recuperar (100 Diamonds): gema volta para a bag.

* Apagar (grátis): gema é perdida permanentemente.

Sistema de Bloqueio de Itens

* Itens podem ser bloqueados/desbloqueados via dialog de ações.

* Itens bloqueados mostram cadeado dourado no canto e não podem ser: quebrados, sintetizados, fundidos, receber/remover gemas, movidos para o stash.

* Protege itens valiosos de processamento acidental.

Stash e Organização

* Botão "Depositar todos" (inventário → stash) e "Pegar todos" (stash → inventário).

* Ordenação por nome ou ordem original.

5.3. Árvore de Runas Globais (Meta-Progressão)

* Sistema de melhorias permanentes compradas com o Ouro obtido em jogo.

* Contém ramos dedicados ao Combate (Dano, Armadura, Vida), Utilidades (Ganho de Exp) e Comércio (Redução de impostos no jogo, slots de mercado temporários e velocidade de coleta).

5.4. Árvore de Habilidades por Herói

* Progressão de nível individual por herói destrava pontos para especialização em habilidades ativas/passivas.

* A escolha de habilidades molda a eficiência de abates por minuto ou a probabilidade de direcionar drops para itens específicos.

---

6. Funcionalidades Core da Lojinha (Gamificação)

Customização Comercial: Cada jogador pode gerenciar e nomear sua própria banca de mercado de forma pública (ex: "Bazar do Cleber"*).

Notificações de Venda: Disparos nativos ou push avisando o jogador instantaneamente sobre o sucesso financeiro: "Seu item foi vendido! R$ X,XX foram direto para o seu Mercado Pago."*

* Gráficos de Commodities: Tela integrada no Flutter utilizando o pacote fl_chart, mostrando gráficos de linha com o histórico de flutuação de preço médio de cada item nas últimas 24h/7dias (estilo bolsa de valores).

Ordens de Compra (Buy Orders): Jogadores podem deixar ofertas automáticas de compra abertas no sistema (ex: "Compro 500 barras de ferro por R$ 0,10 cada"*). Isso gera liquidez instantânea para jogadores casuais que preferem vender recursos rápido em vez de esperar um comprador.

---

7. Roadmap de Desenvolvimento

• [x] Fase 1 (Back-end Core): Setup do servidor, banco de dados seguro, arquitetura server-side e rotinas de autenticação (Node.js/Fastify + JWT).
• [x] Fase 2 (Jogo Base + Crafting): Protótipo funcional do loop Idle em Flutter (caçada, loot boxes, inventário 24 slots, stash 10 abas). Sistema completo de Crafting com 5 bancadas (Alquimia, Síntese, Fusão, Add/Rem Gemas). Sistema de Gemstones (Topázio, Rubi, Esmeralda, Safira, Ametista) + Diamonds (moeda premium). Tela de Herói com 12 slots de equipamento. Sistema de bloqueio de itens. 6 vocações. Progressão por sub-nível de qualidade (0-9 por tier). 11 raridades (Comum→Rainbow). Tela de caçada reformulada (heróis no topo, monstros front-line + back-line, boss final que restaura HP e dropa loot lendário). Sistema de XP com level-up por herói.
• [x] Fase 3 (Integração Financeira): Fluxo PIX automático implementado (criação de pagamento, QR code, copia-e-cola, idempotência, split de comissão por status do vendedor via application_fee). OAuth do MercadoPago (PKCE). Webhooks de confirmação. Notificações de venda no app. Mercado de heróis P2P. Cancelamento e recuperação de anúncios com cooldown de 10min. Sistema de notificações com badge não-lido e polling a cada 15s. Mensageria interna.
• [x] Fase 4 (Interface do Mercado + Admin): Telas de mercado P2P (Itens, Heróis, Minhas Ofertas). Filtros por tier/vocação/tipo. Sistema de taxa progressiva. Painel Admin separado com 7 abas (Dashboard, Players, Itens Global, Fases, Lootbox, Item Creator, Notificar). Item Creator com CRUD de TierConfig (11 tiers, cor, slots, affix count), ItemModifier (18 modificadores) e ItemBase (atributos fixos dinâmicos). CRUD de GameItem, Difficulty, Stage, Wave, Lootbox.
• [x] Fase 5 (Desktop & Protocolo): Registro do protocolo nativo mwidle://. Página de callback com botões "Jogar na Web"/"Abrir no Windows". Botão lateral "MSGS" com indicador de não-lidos. Ordenação de inventário/stash por nome/tier. Aba de loot box recolhível. Suporte a deep links com globalRouter.
• [ ] Fase 6 (Sistemas de Progressão): Desenvolvimento das interfaces e lógicas para a Árvore de Runas, Alocação de Habilidades e Formação de Equipe.
• [ ] Fase 7 (Monetização Híbrida): Integração dos SDKs de anúncios (AdMob para Android / H5 para Web) e do sistema centralizado de Diamonds.
• [ ] Fase 8 (Otimização Desktop): Desenvolvimento de features nativas de Desktop como atalhos de teclado (hotkeys), janelas flutuantes e comportamento do app na bandeja do sistema (System Tray).
• [ ] Fase 9 (Validação): Testes Alfa multiplataforma fechados focados exclusivamente na validação da segurança de inventário e estresse econômico.