🎮 RPG Educativo - Cliente Frontend

Plataforma educativa interativa baseada em RPG
Status: Em Desenvolvimento (Feature Branch: feature/quest)
Versão: 0.0.0
Última Atualização: Novembro de 2025

📋 Índice

Visão Geral
Características
Pré-requisitos
Instalação
Desenvolvimento
Estrutura do Projeto
Arquitetura
Sistemas Principais
Como Usar
Build e Deploy
Testes
Troubleshooting
Contribuindo

🎯 Visão Geral

O RPG Educativo é uma plataforma educativa inovadora que combina mecânicas de RPG (Role-Playing Game) com conteúdo educacional. Os alunos aprendem respondendo perguntas em batalhas, completando quests educativas, desbloqueando achievements e progressando através de diferentes níveis.

Objetivo Principal

Tornar o aprendizado mais engajador e divertido através de gamificação, motivando alunos a resolver problemas, responder perguntas e desenvolver habilidades enquanto avançam em uma narrativa imersiva.

Público-Alvo

Alunos de 8-16 anos
Professores e educadores
Instituições de ensino

✨ Características

🎮 Sistema de Batalhas

Batalhas RPG Clássicas: Sistema de turnos interativo
Combate Educacional: Responder perguntas para atacar e se defender
Diferentes Dificuldades: Fácil, Normal, Difícil com inimigos variados
Física de Jogo: Sistema de HP, dano, defesa e crítico
Feedback Visual: Animações e efeitos especiais

📜 Sistema de Quests

Missões Variadas: 5 tipos diferentes de objetivos
Rastreamento Automático: Progresso atualizado em tempo real
Recompensas: XP e ouro como incentivo
Limite de 1 Quest Ativa: Força o jogador a focar em uma tarefa
Status Progressivo: Disponível → Em Andamento → Completada

🏆 Sistema de Achievements

21 Conquistas Diferentes: Marcos alcançáveis durante o jogo
Categorias Variadas: Batalhas, Dano, Questões, Quests, Level, Monstros
Desbloqueio Automático: Sem necessidade de ação manual
Progresso Cumulativo: Rastreamento permanente

👤 Sistema de Personagens

Criação de Personagem: Seleção de classe ao começar
Sistema de Classes: Diferentes arquétipos com habilidades únicas
Progressão de Nível: Aumento de atributos com XP
Equipamento: Sistema de itens e equipamentos

💾 Sistema de Save/Load

Múltiplos Slots: 3+ slots de salvamento disponíveis
Quick Save: Salvamento rápido com F5
Auto-Save: Salvamento automático após eventos importantes
Restauração Completa: Recupera estado total do jogo

🎓 Sistema de Tutorial

Onboarding Interativo: Apresentação das mecânicas
Cutscenes: Narrativas visuais e orientações
Overlay Durante Jogo: Dicas contextuais

🔐 Sistema de Autenticação

Registro e Login: Criar conta e autenticar
JWT Tokens: Segurança baseada em tokens
Persistência de Sessão: Mantém usuário logado

📦 Pré-requisitos

Software Necessário

Node.js: Versão 18.0.0 ou superior
npm: Versão 9.0.0 ou superior (incluído com Node.js)
Git: Para controle de versão

Backend Necessário

Spring Boot: API backend em execução (padrão: http://localhost:8000)
PostgreSQL: Banco de dados do backend

🚀 Instalação

1. Clonar o Repositório

git clone https://github.com/Projeto-RPG-Educativo/FrontEnd-Client.git
cd FrontEnd-Client

2. Instalar Dependências

npm install

Este comando instalará todas as dependências listadas em package.json:

react: 19.1.1 - Biblioteca UI
react-dom: 19.1.1 - DOM rendering
react-router-dom: 7.9.4 - Roteamento
styled-components: 6.1.19 - Estilização CSS-in-JS
framer-motion: 12.23.24 - Animações
axios: 1.12.2 - Cliente HTTP

3. Configurar Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

VITE_API_URL=http://localhost:8000
VITE_APP_NAME=RPG Educativo
VITE_APP_VERSION=0.0.0

4. Iniciar o Servidor de Desenvolvimento

npm run dev

A aplicação estará disponível em http://localhost:5173

💻 Desenvolvimento

Comandos Disponíveis

# Servidor de desenvolvimento com hot reload
npm run dev

# Build para produção
npm run build

# Lint - Verificar código
npm run lint

# Preview - Visualizar build
npm run preview

Estrutura de Pastas

src/
├── app/                    # Componente raiz da aplicação
├── assets/                 # Imagens, ícones, mídia
│   └── Images/
│       ├── background/     # Fundos de tela
│       ├── characters/     # Sprites de personagens
│       ├── cutScene/       # Imagens de cutscenes
│       ├── enemy/          # Sprites de inimigos
│       ├── icons/          # Ícones da UI
│       ├── loading/        # Telas de carregamento
│       └── npc/            # NPCs (personagens não-jogáveis)
├── components/             # Componentes reutilizáveis
│   ├── auth/               # Componentes de autenticação
│   ├── error/              # Tratamento de erros
│   ├── layout/             # Layout principal
│   └── tutorial/           # Componentes de tutorial
├── constants/              # Constantes globais
│   ├── QuestAchievementMetadata.ts
│   └── assets/             # Mapeamento de assets
├── contexts/               # React Contexts (estado global)
│   ├── AuthContext.tsx     # Autenticação
│   ├── GameContext.tsx     # Estado do jogo
│   ├── FullscreenContext.tsx
│   ├── TutorialContext.tsx # Tutorial
│   └── tutorial/           # Contextos de tutorial
├── hooks/                  # Custom React Hooks
│   ├── screen/             # Hooks específicos de telas
│   ├── services/           # Hooks para serviços
│   └── ui/                 # Hooks de UI/lógica
├── screen/                 # Telas principais
│   ├── auth/               # Telas de autenticação
│   ├── battle/             # Batalha
│   ├── classSelection/     # Seleção de classe
│   ├── cutscene/           # Cutscenes
│   ├── hub/                # Central do jogo (hub)
│   ├── intro/              # Introdução
│   ├── loading/            # Carregamento
│   ├── menu/               # Menus
│   ├── quests/             # Interface de quests
│   ├── quiz/               # Perguntas/Quiz
│   └── user/               # Perfil do usuário
├── services/               # Serviços (lógica de negócio)
│   ├── api/                # Cliente HTTP
│   ├── auth/               # Autenticação
│   ├── achievement/        # Achievements
│   ├── battle/             # Batalhas
│   ├── character/          # Personagens
│   ├── hub/                # Hub/central
│   ├── menu/               # Menu
│   ├── quest/              # Quests
│   ├── question/           # Perguntas
│   └── tutorial/           # Tutorial
├── types/                  # Definições de tipos TypeScript
│   ├── dto/                # Data Transfer Objects
│   └── mapper/             # Mapeadores de tipos
├── utils/                  # Funções utilitárias
│   └── responsiveUtils.ts  # Design responsivo
├── index.css               # Estilos globais
└── main.tsx                # Ponto de entrada

🏗️ Arquitetura

Arquitetura Geral

┌─────────────────────────────────────────────┐
│         Frontend (React + TypeScript)       │
│  (Vite + Styled Components + Framer Motion) │
└─────────────────────────────────────────────┘
              ↓↑ (HTTP/REST)
┌─────────────────────────────────────────────┐
│       Backend API (Spring Boot Java)        │
│    (PostgreSQL, JWT Authentication)         │
└─────────────────────────────────────────────┘

Fluxo de Dados

┌─────────────────────────────────────────────────────────┐
│                    USER INTERFACE                        │
│                  (React Components)                      │
└─────────────────────────────────────────────────────────┘
                           ↑↓
┌─────────────────────────────────────────────────────────┐
│                   STATE MANAGEMENT                       │
│              (React Contexts + Hooks)                    │
├─────────────────────────────────────────────────────────┤
│ • AuthContext - Autenticação e usuário                 │
│ • GameContext - Estado do jogo                         │
│ • TutorialContext - Tutorial                           │
│ • FullscreenContext - Modo fullscreen                  │
└─────────────────────────────────────────────────────────┘
                           ↑↓
┌─────────────────────────────────────────────────────────┐
│                   CUSTOM HOOKS                          │
│              (Lógica de Negócio)                        │
├─────────────────────────────────────────────────────────┤
│ • useBattle() - Lógica de batalha                      │
│ • useCharacter() - Personagem                          │
│ • useQuest() - Quests                                  │
│ • useAchievement() - Achievements                      │
│ • useSave() - Save/Load                                │
└─────────────────────────────────────────────────────────┘
                           ↑↓
┌─────────────────────────────────────────────────────────┐
│                   API SERVICES                          │
│              (Cliente HTTP - Axios)                     │
├─────────────────────────────────────────────────────────┤
│ • api.ts - Configuração base                           │
│ • BattleService - Endpoint de batalhas                 │
│ • QuestService - Endpoint de quests                    │
│ • AchievementService - Endpoint de achievements        │
│ • SaveService - Endpoint de save/load                  │
└─────────────────────────────────────────────────────────┘
                           ↑↓
┌─────────────────────────────────────────────────────────┐
│              BACKEND API (Spring Boot)                  │
│          http://localhost:8000/api/...                 │
└─────────────────────────────────────────────────────────┘

Fluxo de Autenticação

1. Usuário acessa a aplicação
   ↓
2. Frontend verifica token em localStorage
   ↓
3. Se token válido → Carrega GameContext
   Senão → Redireciona para tela de Auth
   ↓
4. Usuário faz Login/Registro
   ↓
5. Backend valida credenciais
   ↓
6. Backend retorna JWT token
   ↓
7. Frontend salva token em localStorage
   ↓
8. Frontend inclui token em todas as requisições
   (Header: Authorization: Bearer {token})
   ↓
9. Usuário autenticado - Acesso ao jogo

🎮 Sistemas Principais

1. Sistema de Autenticação

Arquivos Principais:

contexts/AuthContext.tsx - Gerenciar estado de autenticação
services/auth/ - Serviços de login/registro
screen/user/auth/ - Telas de login/registro

Funcionalidades:

Registro de novo usuário
Login com email/senha
JWT token management
Logout
Persistência de sessão

Fluxo:

Tela de Auth → Serviço Auth → API Backend → Token JWT → Salvo em localStorage

2. Sistema de Batalhas

Arquivos Principais:

screen/battle/BattleScreen.tsx - Componente principal
services/battle/BattleService.ts - Lógica de batalha
hooks/screen/battle/ - Hooks específicos

Mecânicas:

Turnos baseados em tempo
Sistema de HP/defesa
Cálculo de dano
Sistema de crítico
Perguntas durante batalha

Fluxo de Turno:

1. Exibe pergunta do inimigo
2. Jogador responde
3. Se correto → Jogador ataca
4. Se incorreto → Inimigo ataca
5. Atualiza HP de ambos
6. Verifica vitória/derrota
7. Próximo turno ou Fim da Batalha

3. Sistema de Quests

Arquivos Principais:

screen/quests/ - Interface de quests
services/quest/QuestService.ts - Lógica de quests
hooks/services/useQuest.ts - Hook de quests

Tipos de Quests:

ANSWER_QUESTIONS - Acertar X perguntas
DEFEAT_MONSTER - Derrotar monstro específico X vezes
WIN_BATTLES - Vencer X batalhas
REACH_LEVEL - Alcançar nível específico
DEAL_DAMAGE - Causar X de dano

Regras:

Apenas 1 quest ativa por personagem
Progresso atualizado automaticamente
Recompensas ao completar

4. Sistema de Achievements

Arquivos Principais:

services/achievement/AchievementService.ts - Lógica
hooks/services/useAchievement.ts - Hook

21 Conquistas em 6 categorias:

🗡️ Batalha (4)
💥 Dano (3)
📚 Questões (3)
📜 Quests (3)
⬆️ Level (3)
🐉 Monstros (3)

Desbloqueio Automático: Sem necessidade de ação manual

5. Sistema de Save/Load

Arquivos Principais:

hooks/ui/SaveLogic.ts - Lógica de save
services/ - Serviços de save/load

Funcionalidades:

3+ slots de salvamento
Quick Save (F5)
Auto-Save após eventos
Restauração completa do estado

6. Sistema de Tutorial

Arquivos Principais:

contexts/TutorialContext.tsx - Gerenciador
screen/cutscene/ - Telas de cutscene
components/tutorial/ - Componentes

Características:

Onboarding inicial
Cutscenes narrativas
Overlays contextuais
Explicações de mecânicas

📖 Como Usar

Fluxo de Usuário Típico

1. Primeira Vez (Novo Usuário)

1. Abre aplicação
2. Vê tela de Autenticação
3. Clica "Registrar"
4. Preenche email, senha, nome
5. Clica "Criar Conta"
6. Backend cria usuário
7. Frontend faz login automático
8. Redireciona para Seleção de Classe
9. Usuário escolhe classe (Mago, Lutador, Ranger)
10. Personagem criado
11. Inicia Tutorial

2. Depois (Usuário Existente)

1. Abre aplicação
2. Vê tela de Login
3. Preenche email e senha
4. Clica "Entrar"
5. Backend autentica e retorna token
6. Frontend salva token
7. Redireciona para Menu Principal
8. Menu: [Novo Jogo], [Carregar Jogo], [Configurações]

3. Jogando

1. Usuário está no Hub (Central)
2. Pode ir para: Arena, Inn, Torre, etc.
3. Arena: Iniciar batalha
4. Responde pergunta
5. Ataca ou se defende
6. Completa batalha
7. Ganha XP e ouro
8. Progresso de quests/achievements atualiza
9. Volta ao Hub

Navegação de Telas

┌──────────────────┐
│   Auth Screen    │
│ (Login/Registro) │
└────────┬─────────┘
         │ Autenticado
         ↓
┌──────────────────┐
│  Main Menu       │
│ Novo/Carregar    │
└────────┬─────────┘
         │
    ┌────┴───┬─────────┐
    ↓        ↓         ↓
┌─────┐  ┌────────┐  ┌──────────┐
│Class│  │Loading │  │LoadGame  │
│Sel. │  │Screen  │  │Screen    │
└──┬──┘  └───┬────┘  └────┬─────┘
   │         │             │
   └─────────┼─────────────┘
             ↓
       ┌──────────┐
       │Tutorial  │ (Primeira vez)
       └─────┬────┘
             ↓
       ┌──────────┐
       │   Hub    │
       │ (Central)│
       └─┬──┬──┬──┘
         │  │  │
    ┌────┘  │  └────────────┬────────┐
    ↓       ↓               ↓        ↓
  Arena    Inn            Torre  Taverna
    │       │               │        │
    ↓       ↓               ↓        ↓
 Battle   Rest           Quest   Stats

🔨 Build e Deploy

Build para Produção

# Build otimizado
npm run build

# Saída em dist/

O build gera:

dist/index.html - HTML principal
dist/assets/ - JS, CSS, imagens otimizadas
Código minificado e otimizado

Preview do Build

npm run preview

Visualiza o build em http://localhost:4173

Deployment

Opção 1: Vercel

npm i -g vercel
vercel

Opção 2: Netlify

npm i -g netlify-cli
netlify deploy --prod --dir=dist

Opção 3: Docker

FROM node:18 AS build
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

✅ Testes

Lint (ESLint)

npm run lint

Verifica:

Código TypeScript/JavaScript
Uso de React hooks
Variáveis não utilizadas
Style guide do projeto

Testes Manuais Recomendados

1. Autenticação

2. Criação de Personagem

Selecionar diferentes classes
Personagem criado corretamente
Estadísticas corretas por classe

3. Batalhas

4. Quests

5. Achievements

Achievements desbloqueados
Progresso visível
Notificação ao desbloquear

6. Save/Load

Salvar jogo
Carregar jogo
Estado restaurado corretamente

🐛 Troubleshooting

Problema: "Cannot find module"

Causa: Dependências não instaladas
Solução:

rm -rf node_modules
npm install

Problema: CORS Error

Causa: Backend não aceita requisições do frontend
Solução: Verificar CORS no backend (Spring Boot)

// Adicionar ao backend
@CrossOrigin(origins = "http://localhost:5173")

Problema: Token expirado

Causa: JWT token vencido
Solução: Fazer logout e login novamente

localStorage.removeItem('token');
// Redireciona para login

Problema: Assets não carregam

Causa: Path de imagens incorreto
Solução: Verificar imports em constants/assets/

// Correto
import { backgroundImages } from '@/constants/assets/background'

// Incorreto
import backgroundImages from '../../../assets/Images/background'

Problema: Estado do jogo perdido ao refresh

Causa: Estado não persistido
Solução: Fazer save antes de sair, ou implementar auto-save mais frequente

🤝 Contribuindo

Antes de Começar

Faça fork do repositório
Clone seu fork
Crie uma branch feature
```
git checkout -b feature/minha-feature
```

Convenção de Commits

feat: Nova funcionalidade
fix: Correção de bug
docs: Documentação
style: Formatação de código
refactor: Refatoração
test: Testes

Pull Request

Push para sua branch
Crie Pull Request
Descreva mudanças
Aguarde revisão

Estilo de Código

TypeScript strict mode
Componentes funcionais com hooks
Nomes descritivos
Comentários para lógica complexa
Máximo 80 caracteres por linha

📚 Documentação Adicional

Consulte estes arquivos para informações específicas:

QUESTS_ACHIEVEMENTS_SYSTEM.md - Sistema de Quests e Achievements
SAVE_LOAD_SYSTEM.md - Sistema de Save/Load
QUEST_ACHIEVEMENT_USAGE.md - Guia de Uso de Quests e Achievements

🛠️ Tech Stack

Frontend

Tecnologia	Versão	Propósito
React	19.1.1	Biblioteca UI
React Router	7.9.4	Roteamento
TypeScript	5.9.3	Type safety
Styled Components	6.1.19	Estilização CSS-in-JS
Framer Motion	12.23.24	Animações
Axios	1.12.2	Cliente HTTP
Vite	7.1.7	Build tool

Backend (Referência)

Spring Boot 3.x
PostgreSQL
JWT Authentication
REST API

DevTools

ESLint - Linting
TypeScript - Type checking
Vite - Build e HMR

📈 Roadmap

Fase Atual (v0.0.0)

✅ Sistema de autenticação
✅ Batalhas básicas
✅ Sistema de quests
✅ Sistema de achievements
🟡 Sistema de save/load (Em desenvolvimento)
🟡 Tutorial integrado (Em desenvolvimento)

Próximas Fases

📞 Suporte

Reportar Bugs

Crie uma issue no GitHub com:

Descrição do problema
Steps para reproduzir
Screenshots/vídeos
Sistema operacional e browser

Fazer Sugestões

Discussões e sugestões são bem-vindas via GitHub Discussions

📄 Licença

👥 Autores

Projeto RPG Educativo - Desenvolvimento
Xavier - Frontend Lead Developer

🙏 Agradecimentos

Todos os contribuidores
Comunidade educativa
Testadores beta

⚖️ Conformidade

Este projeto segue as políticas de:

Microsoft Content Policies
Proteção de dados (LGPD/GDPR)
Acessibilidade web (WCAG)

Última atualização: 19 de Novembro de 2025
Versão da Documentação: 1.0

🔗 Links Úteis

Boa sorte e divirta-se desenvolvendo! 🎮✨

Name		Name	Last commit message	Last commit date
Latest commit History 47 Commits
src		src
.dockerignore		.dockerignore
.env		.env
.gitignore		.gitignore
Dockerfile		Dockerfile
QUESTS_ACHIEVEMENTS_SYSTEM.md		QUESTS_ACHIEVEMENTS_SYSTEM.md
QUEST_ACHIEVEMENT_USAGE.md		QUEST_ACHIEVEMENT_USAGE.md
README.md		README.md
SAVE_LOAD_SYSTEM.md		SAVE_LOAD_SYSTEM.md
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
index.html		index.html
nginx.conf		nginx.conf
package-lock.json		package-lock.json
package.json		package.json
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Projeto-RPG-Educativo/FrontEnd-Client

Folders and files

Latest commit

History

Repository files navigation

🎮 RPG Educativo - Cliente Frontend

📋 Índice

🎯 Visão Geral

Objetivo Principal

Público-Alvo

✨ Características

🎮 Sistema de Batalhas

📜 Sistema de Quests

🏆 Sistema de Achievements

👤 Sistema de Personagens

💾 Sistema de Save/Load

🎓 Sistema de Tutorial

🔐 Sistema de Autenticação

📦 Pré-requisitos

Software Necessário

Recomendado

Backend Necessário

🚀 Instalação

1. Clonar o Repositório

2. Instalar Dependências

3. Configurar Variáveis de Ambiente

4. Iniciar o Servidor de Desenvolvimento

💻 Desenvolvimento

Comandos Disponíveis

Estrutura de Pastas

🏗️ Arquitetura

Arquitetura Geral

Fluxo de Dados

Fluxo de Autenticação

🎮 Sistemas Principais

1. Sistema de Autenticação

2. Sistema de Batalhas

3. Sistema de Quests

4. Sistema de Achievements

5. Sistema de Save/Load

6. Sistema de Tutorial

📖 Como Usar

Fluxo de Usuário Típico

1. Primeira Vez (Novo Usuário)

2. Depois (Usuário Existente)

3. Jogando

Navegação de Telas

🔨 Build e Deploy

Build para Produção

Preview do Build

Deployment

Opção 1: Vercel

Opção 2: Netlify

Opção 3: Docker

✅ Testes

Lint (ESLint)

Testes Manuais Recomendados

1. Autenticação

2. Criação de Personagem

3. Batalhas

4. Quests

5. Achievements

6. Save/Load

🐛 Troubleshooting

Problema: "Cannot find module"

Problema: CORS Error

Problema: Token expirado

Problema: Assets não carregam

Problema: Estado do jogo perdido ao refresh

🤝 Contribuindo

Antes de Começar

Convenção de Commits

Pull Request

Estilo de Código

📚 Documentação Adicional

🛠️ Tech Stack

Frontend

Backend (Referência)

DevTools

📈 Roadmap

Packages