Módulo central para gerenciar todos os scripts do Popmundo
# 🛠️ PopControl — Centro de Controle do Ecossistema
> **Gerencie todos os scripts Popmundo de uma única barra · Personalize o menu do personagem · Favoritos, TOP VIP e sistema de ocultação**
---
## 📋 Sumário
- [Instalação](#-instalação)
- [O Que Ele Faz?](#-o-que-ele-faz)
- [Barra de Controle](#-barra-de-controle)
- [Painel de Configurações](#️-painel-de-configurações)
- [Gerenciamento do Menu do Personagem](#️-gerenciamento-do-menu-do-personagem)
- [Menu TOP VIP](#-menu-top-vip)
- [Favoritos](#-favoritos)
- [Mostrar / Ocultar](#-mostrar--ocultar)
- [Tela de Gerenciamento do Menu](#️-tela-de-gerenciamento-do-menu)
- [Atalhos do Teclado](#️-atalhos-do-teclado)
- [Suporte a Idioma Personalizado](#-suporte-a-idioma-personalizado-customize)
- [Ecossistema de Scripts](#-ecossistema-de-scripts)
- [Dicas](#-dicas)
- [Segurança e Privacidade](#-segurança-e-privacidade)
- [Histórico de Versões](#-histórico-de-versões)
- [Solução de Problemas](#-solução-de-problemas)
- [Suporte](#-suporte)
---
## 🚀 Instalação
### 1 · Extensão do Navegador
**Desktop**
| Navegador | Download |
|---|---|
| 🌐 Chrome | [tampermonkey.net/?browser=chrome](https://tampermonkey.net/?browser=chrome) |
| 🦊 Firefox | [tampermonkey.net/?browser=firefox](https://tampermonkey.net/?browser=firefox) |
**Mobile**
| Plataforma | Método Recomendado |
|---|---|
| 🤖 Android | Kiwi Browser + Tampermonkey |
| 🤖 Android | Firefox Mobile + Extensão Tampermonkey |
| 🍎 iPhone / iPad | Navegadores compatíveis com Userscripts |
### 2 · Instalação do Script
1. Abra [Greasyfork — PopControl](https://greatest.deepsurf.us/tr/scripts/569102)
2. Clique no botão **Install**
3. O script atualiza automaticamente — nada mais necessário
> 💡 **Recomendação:** Instale o PopControl **antes** de outros scripts. Quando o ecossistema está pronto, outros se conectam automaticamente.
---
## 🎯 O Que Ele Faz?
PopControl é a **camada de gerenciamento central** do ecossistema de scripts Popmundo. Ele tem duas tarefas principais:
**1 · Barra de Controle** — Coleta botões de todos os scripts ativos em uma única barra fixa. Você pode personalizar sua posição, cor e ordem. Você pode ligar e desligar scripts com um único clique.
**2 · Gerenciador de Menu do Personagem** — Permite personalizar o menu esquerdo na página do personagem: ocultar itens, adicionar aos favoritos, reordenar; exibir botões de scripts na seção TOP VIP.
> ℹ️ PopControl **não** joga o jogo **automaticamente** e não fornece vantagens injustas. Ele apenas gerencia a interface e coordenação de scripts.
---
## 📊 Barra de Controle
### Posições
A barra pode ser colocada em todas as quatro bordas da página:
| Posição | Descrição |
|---|---|
| `⬇ Inferior` | Faixa horizontal na parte inferior da página *(padrão)* |
| `⬆ Superior` | Faixa horizontal na parte superior da página |
| `◀ Esquerda` | Coluna vertical na borda esquerda |
| `▶ Direita` | Coluna vertical na borda direita |
### Ordenação de Botões
Botões na barra podem ser reordenados com **arrastar-e-soltar**:
- 🖱️ **Desktop** — Clique e arraste o botão
- 📱 **Toque** — Pressione longamente o botão (300ms), depois arraste
### Minimização
Quando você fecha a barra com o botão `▼`, um **botão FAB ⚙️** aparece no canto inferior direito. Você pode reabrir a barra clicando no FAB ou com `Alt+P`.
---
## ⚙️ Painel de Configurações
Aberto clicando no botão **⚙️ PopControl** na barra.
```
┌─────────────────────────────────────┐
│ 🛠️ PopControl v2.3 ✕ │
├─────────────────────────────────────┤
│ 📍 Posição ⬇ Inferior ⬆ Superior │
│ ◀ Esquerda ▶ Direita │
├─────────────────────────────────────┤
│ 🌍 Idioma TR EN PT Customize │
├─────────────────────────────────────┤
│ 🎨 Cor [Barra ▐] [Texto ▐] │
├─────────────────────────────────────┤
│ 🗂️ Menu Mgmt [ Gerenciar ] │ ← Apenas na página do personagem
├─────────────────────────────────────┤
│ 🔌 Scripts │
│ 🎨 Helper ●── (on) │
│ 🌐 Social ●── (on) │
│ 🗺️ Route49 ──○ (off) │
└─────────────────────────────────────┘
```
### Script Ligado / Desligado
Você pode desativar qualquer script com o **toggle** ao lado dele. Quando um script é desligado, sua função `onUndo` é executada e reverte todas as alterações que fez no DOM.
---
## 🗂️ Gerenciamento do Menu do Personagem
> Apenas ativo na página do personagem (`/World/Popmundo.aspx/Character/...`).
PopControl adiciona **três camadas extras** ao menu esquerdo na página do personagem:
```
┌─────────────────────────┐
│ ⭐ TOP VIP │ ← Botões registrados pelos scripts
├─────────────────────────┤
│ ⭐ Favoritos │ ← Itens que você adicionou aos favoritos
├─────────────────────────┤
│ Carreira │ ← Menu original do jogo
│ Atividade │
│ ... │
└─────────────────────────┘
```
---
### ⭐ Menu TOP VIP
Scripts (Helper, Guide, Route49, etc.) podem registrar seus próprios botões na seção **TOP VIP**. Esta seção:
- É posicionada **imediatamente acima** do menu Carreira
- Destaca-se do menu original com cabeçalho gradiente azul-roxo
- É **recolhível** clicando no cabeçalho — estado aberto/fechado é lembrado entre recarregamentos de página
- Botões dentro podem ser reordenados com arrastar-e-soltar usando o identificador **⇅ Ordenar**
- Itens podem ser **ocultados** da tela **Gerenciamento do Menu** 👁
---
### ⭐ Favoritos
Você pode favoritar qualquer item do menu com o botão ⭐:
- Aparece em uma seção separada imediatamente abaixo do TOP VIP, acima da Carreira
- Reconhecido pelo tema de cor gradiente rosa
- Pode ser reordenado com o identificador **⇅ Ordenar**
- Exibido como tags na tela **Gerenciamento do Menu**, removido com ✕
---
### 👁 Mostrar / Ocultar
Você pode ocultar qualquer item do menu com o botão **👁 / 🚫** ao lado dele:
- Funciona independentemente do idioma — reconhece baseado em URL / ID, não correspondência de texto
- Botões **TOP VIP** também podem ser ocultados *(adicionado em v2.3)*
- Segmentos de URL dinâmicos como ID do personagem são normalizados para correspondência — ocultação continua funcionando mesmo se a URL mudar
- Botão **🔄 Redefinir Tudo** limpa todas as configurações de ocultação e favoritos
> ⚠️ Itens na seção Favoritos estão fora do escopo da ocultação — você já os escolheu.
---
### 🗂️ Tela de Gerenciamento do Menu
Aberta com Configurações → botão **🗂️ Gerenciar**:
```
┌──────────────────────────────────────────────┐
│ 🗂️ Gerenciamento do Menu ✕ │
├──────────────────────────────────────────────┤
│ ⭐ Adicionar Favorito 👁 Mostrar/Ocultar ⇅ Ordenar │
├──────────────────────────────────────────────┤
│ ▼ ⭐ TOP VIP (3) │ ← Clique: abrir/fechar
│ 🛠️ Configurações PopControl 👁 │
│ 🧭 Painel Guide 👁 │
│ 🗺️ Route49 👁 │
├──────────────────────────────────────────────┤
│ ⭐ Favoritos │
│ [ Inventário ✕ ] [ Adicionar Show ✕ ] ... │
├──────────────────────────────────────────────┤
│ ▼ Carreira │ ← Clique: abrir/fechar
│ Inventário ☆ 👁 │
│ Oferecer Item ⭐ 🚫 │
│ ... │
│ ▼ Atividade │
│ ... │
├──────────────────────────────────────────────┤
│ 🔄 Redefinir Tudo [ Fechar ] │
└──────────────────────────────────────────────┘
```
O estado aberto/fechado das seções é armazenado com chaves `ppc-sec-*` — mesmo que você feche o painel, ele abrirá no mesmo estado da próxima vez.
---
## ⌨️ Atalhos do Teclado
| Atalho | Ação |
|---|---|
| `Alt + P` | Abrir / fechar barra de controle |
---
## 🌍 Suporte a Idioma Personalizado (Customize)
PopControl e todos os scripts conectados podem ser traduzidos para qualquer idioma **exceto TR / EN / PT-BR**.
### Como Usar?
1. Clique em Configurações → botão **🌍 Customize**
2. Copie todos os textos traduzíveis com **📋 Copy Export JSON**
3. Cole no [Google Gemini](https://gemini.google.com) ou outra IA, especifique o idioma alvo
4. Cole o JSON retornado na caixa **Import** e clique em **✅ Apply & Reload**
5. Todas as interfaces de scripts mudam instantaneamente para o novo idioma
### Scripts Suportados
| Script | Chave JSON |
|---|---|
| Helper | `helper` |
| Social | `social` |
| Social Mobile | `social_mobile` |
| Depot | `depot` |
| Guide | `guide` |
| Route49 | `route49` |
---
## 🔗 Ecossistema de Scripts
PopControl é o ponto central onde todos os scripts Popmundo se conectam:
```
┌──────────────────── PopControl ────────────────────┐
│ Barra central · Idioma · Cor · Gerenciamento de scripts │
└────────┬──────────┬──────────┬──────────┬──────────┘
│ │ │ │
┌────┴──┐ ┌────┴──┐ ┌───┴───┐ ┌───┴────┐
│Helper │ │Social │ │ Guide │ │Route49 │
└───────┘ └───┬───┘ └───────┘ └────────┘
│
┌───────┴────────┐ ┌──────────┐
│ Social Mobile │ │ Depot │
└────────────────┘ └──────────┘
```
| Script | Descrição |
|---|---|
| 🛠️ **PopControl** | Gerenciamento central — este script |
| 🎨 **Helper** | Melhorias de UI, painel de ferramentas, API HelperHub |
| 🌐 **Social** | Radar, Shelf, Card de Personagem, Busca Rápida |
| 📱 **Social Mobile** | Versão otimizada para mobile do Social |
| 📦 **Depot** | Gerenciamento de inventário |
| 🧭 **Guide** | Assistência de missões, busca de caminho |
| 🗺️ **Route49** | Planejamento de turnê mundial e reserva de shows |
> Todos os scripts podem funcionar independentemente. Sem o PopControl, eles continuam por conta própria.
---
## 💡 Dicas
### Instalação
- **Instale o PopControl primeiro** — outros scripts se conectarão automaticamente quando o encontrarem pronto
- **Organize a ordem dos scripts de acordo com seu fluxo de trabalho** — mais usados à esquerda/acima
- **Minimize a barra** — para economizar espaço enquanto joga, use `▼` ou `Alt+P`
### Performance
- **Desligue scripts que você não usa** — desative com o toggle para economizar recursos do navegador
- **Abra o Gerenciamento do Menu com moderação** — não o deixe aberto continuamente pois faz varredura pesada do DOM
- **Pequeno atraso em mudanças de cor** é normal — a barra é recriada
### Organização do Menu
- **Adicione páginas visitadas frequentemente aos favoritos** — acesso com um clique
- **Oculte itens de menu raramente usados** — reduza a desordem do menu
- **Ajuste a ordem do TOP VIP** baseado no seu botão mais usado
---
## 🔒 Segurança e Privacidade
- **Armazenamento local** — todos os dados armazenados apenas no seu navegador com `GM_setValue` / `localStorage`
- **Sem servidores externos** — nenhum dado é enviado para lugar nenhum
- **Acesso baseado em permissão** — usa apenas funções `GM_*` permitidas pelo Tampermonkey
- **Código aberto** — código completo pode ser inspecionado no Greasyfork
---
## 📦 Histórico de Versões
### v2.3 *(Atual)*
> Grande atualização do Gerenciamento do Menu — ocultação corrigida, TOP VIP separado
**🐛 Correções de Bugs**
- **Ocultação não estava funcionando** — em `applyNativeItemVisibility()`, chaves dos itens do menu eram verificadas antes de aplicar `_normalizePath()`. Links contendo ID do personagem na URL (como `/OfferItem/3117642`) nunca correspondiam com chaves normalizadas (`/OfferItem/`); todo o processo de ocultação falhava silenciosamente.
**✨ Novos Recursos**
- **Seção TOP VIP separada** — Na tela de Gerenciamento do Menu, itens TOP VIP não misturam com Carreira/Atividade; listados sob seu próprio cabeçalho
- **Ocultação TOP VIP** — Botões TOP VIP agora podem ser ocultados com 👁/🚫
- **Estado da seção persistente** — Estado aberto/fechado das seções do Gerenciamento do Menu é salvo no localStorage com chaves `ppc-sec-*`; painel não redefine toda abertura
**🧹 Limpeza de Código**
- CSS inline repetitivo em `openMenuCustomizeUI()` extraído para constantes `CSS_*`
- Código de criação de linha/botão movido para função auxiliar `mkItemRow()`
- `mkSecHdr()` recebeu parâmetro opcional `gradient` — tom de cor separado para TOP VIP
---
### v2.2
- Menu TOP VIP adicionado (`position: 'above-career'`)
- Seção de favoritos e ordenação arrastar-e-soltar
- Infraestrutura de ocultação do menu do personagem *(bug de normalização presente nesta versão)*
- Overlay de Gerenciamento do Menu
- Seletor de cor para personalização da cor da barra
- `_openCustomize()` — sistema de importação/exportação de idioma personalizado
---
### v2.1 e anteriores
- Barra de controle básica (posições horizontal/vertical)
- Sistema de registro de scripts (`PopControl.register()`)
- Ordenação de botões arrastar-e-soltar (desktop + toque)
- FAB (botão de estado minimizado)
- Atalho do teclado `Alt+P`
- Suporte a idiomas TR / EN / PT-BR
- Infraestrutura de importação/exportação de idioma personalizado (Customize)
---
## ❓ Solução de Problemas
**Barra não aparece de forma alguma?**
→ Tente o atalho `Alt+P`. Se ainda não estiver lá, atualize a página — PopControl espera pelo elemento `#ppm-main` ou `#ppm-footer`, não começa sem eles.
**Botões de scripts não aparecendo na barra?**
→ Verifique em Configurações → Scripts que o toggle do script está ligado.
**Itens do menu não estão sendo ocultados?**
→ Atualize para v2.3. Em versões mais antigas, ocultação não funcionava devido ao bug de normalização de URL.
**Menu TOP VIP não está visível?**
→ Visível apenas na página do personagem (`/World/Popmundo.aspx/Character/...`); não ativo em outras páginas.
**Favoritos não estão sendo salvos?**
→ Verifique que a permissão `GM_setValue` do Tampermonkey está ativada.
**Gerenciamento do Menu fecha toda vez que é aberto?**
→ Atualize para v2.3; a partir desta versão, estados das seções são lembrados.
**Barra mudou para modo FAB, não reabre?**
→ Clique no botão **⚙️** no canto inferior direito ou use `Alt+P`.
**Configurações não estão sendo salvas?**
→ Certifique-se que o Tampermonkey permite a função `GM_setValue`; verifique permissões de armazenamento do navegador.
---
## 📞 Suporte
| Recurso | Link |
|---|---|
| 🐛 Relatórios de bugs | [Seção de comentários do Greasyfork](https://greatest.deepsurf.us/tr/scripts/569102) |
| 🇬🇧 Ecosystem documentation | [rentry.org/PopControlEcosystem](https://rentry.org/PopControlEcosystem) |
| 🇹🇷 Ekosistem dokümantasyonu | [rentry.org/PopControlEkosistemi](https://rentry.org/PopControlEkosistemi) |
| 🇧🇷 Documentação do ecossistema | [rentry.org/EcossistemaPopControl](https://rentry.org/EcossistemaPopControl) |
---
*PopControl é o módulo de gerenciamento central do ecossistema de scripts Popmundo desenvolvido por luke-james-gibson.*
