📦 ITED Tech 3D

Uma biblioteca React otimizada para a criação rápida de experiências imersivas (360° e 3D) em cursos EAD e pacotes SCORM.

Construída sobre o A-Frame, esta biblioteca abstrai a complexidade do WebXR, fornecendo componentes React focados na regra de negócio educacional, performance e rastreamento de interação (compatível com o padrão SCORM).

🚀 Instalação

Como a biblioteca utiliza A-Frame e plugins extras por baixo dos panos, certifique-se de instalar as dependências corretas:

npm install ited-tech-3d aframe aframe-environment-component scorm-api-wrapper

🎨 Design System e Tematização

<ItedThemeProvider>

O motor de estilos da biblioteca. Ao envelopar sua aplicação com este provedor, todas as interfaces 2D (HTML/CSS) e os componentes 3D (A-Frame) herdam automaticamente a paleta de cores correta, incluindo gerenciamento de estados (hover, disabled, selected).

🛠️ Como usar:

import React from 'react';
import { ItedThemeProvider, LayoutImersivo, Cena360 } from 'ited-tech-3d';

export default function App() {
  return (
    {/* Aplica o tema oficial do Senai em toda a experiência */}
    <ItedThemeProvider tema="senai">
      <LayoutImersivo>
        <Cena360>
          {/* Cenário e objetos */}
        </Cena360>
      </LayoutImersivo>
    </ItedThemeProvider>
  );
}

🎛️ Propriedades (Props):

| Propriedade | Tipo | Padrão | Descrição | | :--- | :--- | :--- | :--- | | tema | string | "padrao" | Define a paleta base. Aceita "padrao" ou "senai". | | customColors | object | {} | Permite sobrescrever cores específicas da paleta (ex: { primaria: '#ff00ff' }). |

<SFXProvider> e useSFX

Motor centralizado para Efeitos Sonoros (SFX). Previne vazamentos de memória (Memory Leak) ao não recriar instâncias de áudio a cada interação, além de padronizar a identidade sonora. Fornece fallback inteligente e expõe métodos como playAcerto, playErro, playClick e playCustom.

🛠️ Como usar:

import React from 'react';
import { SFXProvider } from 'ited-tech-3d';

export default function App() {
  return (
    <SFXProvider globalAcerto="/audios/acerto.mp3" globalErro="/audios/erro.mp3" globalClick="/audios/click.mp3" volumeGlobal={0.8}>
      <Rotas />
    </SFXProvider>
  );
}

🎛️ Métodos Expostos (useSFX):

• playAcerto(customSrc?): Toca o som de acerto (com fallback global).
• playErro(customSrc?): Toca o som de erro (com fallback global).
• playClick(customSrc?): Toca o som mecânico de hover/seleção (com fallback global).
• playCustom(src): Reproduz efeitos sonoros específicos de cenários (ex: sirenes, narrações) respeitando o volume central.

🧩 Componentes Base

<LayoutImersivo> e <ToolbarImersiva>

O casulo estrutural da experiência educacional. Fornece a interface 2D, gerencia a tela de carregamento e fornece a barra inferior de botões.

• Arquitetura de Slots: Permite injetar interfaces customizadas (ex: telaEspera e toolbar).
• Scroll-telling: Possui a propriedade scrollable e mostrarOverlay para permitir a criação de páginas estilo "Artigo", intercalando texto 2D com janelas 3D embedded.

<Cena360>

O coração da sua experiência imersiva. Wrapper inteligente para o <a-scene> do A-Frame.

• Auto-Fixes Inclusos: Corrige distorção de pixel no Android, inverte eixo Y no mobile e trava o horizonte automaticamente.
• Decoders: Suporte nativo ao compressor Draco do Google embutido.

🎛️ Propriedades (Props):

| Propriedade | Tipo | Padrão | Descrição | | :--- | :--- | :--- | :--- | | mostrarCursor | boolean | true | Define se o anel de foco (Gaze) será renderizado na tela. | | cameraPadrao | boolean | true | Se falso, desliga a câmera nativa (útil ao usar o <ControlesOrbita>). | | gazeTimeout | number | 2000 | Tempo (em ms) para acionar o clique pelo olhar. | | onCarregado | function | undefined | Callback disparado assim que a cena é montada na GPU. |

<ControlesOrbita>

Substitui a visão em primeira pessoa por um "Rig" de órbita. Ideal para experiências de inspeção técnica de maquinários e peças (Model Viewer), permitindo girar e dar zoom com inércia (damping) otimizada para toque (mobile) e mouse (desktop).

<CenarioVirtual> e <Objeto3D>

Componentes para construção rápida do mundo 3D. O CenarioVirtual herda cores do Tema para criar ambientes procedurais. O Objeto3D abstrai o carregamento de GLTF/GLB e permite sintaxe curta de vetores.

<Ambiente>

Responsável por renderizar o cenário 360° (imagem ou vídeo). Gerencia automaticamente o <a-assets>, o Autoplay condicional explícito e as políticas de playsInline (crítico para iOS). Aceita forwardRef para controle de reprodução (play, pause, seek).

🎮 Interatividade 3D e Gamificação

<Botao3D>

Componente de botão universal 3D com sistema de hitboxes ajustado para Raycaster (Gaze). Suporta texturas 2D (Sprites) mapeadas por estado (normal, hover, sucesso, erro, selecionado), com fallback automático e inteligente para as cores sólidas do ItedThemeProvider caso as imagens não sejam fornecidas.

• Anti-Ghosting (Hitbox Precisa): A geometria plana do botão está acoplada à entidade pai, garantindo 100% de precisão na colisão com o raio do olhar.

🛠️ Exemplo de Injeção de Sprites:

<Botao3D 
  id="btn-iniciar" texto="INICIAR MÁQUINA" 
  sprites={{ normal: '/img/btn.png', hover: '/img/btn-glow.png', sucesso: '/img/btn-green.png' }} 
/>

<PainelQuiz3D>

Componente imersivo que atua como o "Chassi Visual" para interações educacionais. Focado em conforto visual e Ergonomia Imersiva (padrão ouro em RV), o painel distribui os elementos em geometria curva (tipo="curvo"), garantindo que textos e botões mantenham a mesma distância focal dos olhos do usuário. Recebe propriedades geométricas como raio e altura, orquestrando automaticamente a distância (Z-Offset) do título e do conteúdo interno (children).

<QuizRelacional3D>

Máquina de estados educacional automatizada para quizzes de "Ligue as Colunas". Gerencia áudios, verificações de acerto/erro e feedback visual nativamente.

• Lógica Integrada: Gerencia seleções e verificações de correspondência (matchId), comunicando-se com o SFXContext para áudio.
• UX Controlada: Renderiza componentes <Botao3D> e aguarda a ação do usuário num botão flutuante de "Concluir Desafio" ao finalizar todas as ligações.
• Auto-Layout e Pivô Bússola: Calcula automaticamente a altura (Y) dos itens pela ordem da lista e utiliza uma arquitetura de "pivôs aninhados" (Nested Pivots) para grudar os botões no vidro curvo do PainelQuiz3D. Isso elimina "Z-fighting" e a necessidade de cálculos matemáticos de posicionamento ao escrever o JSON da aula.

<QuizMultiplaEscolha3D>

Módulo interativo clássico. Implementa a diretriz de Ouro em UX Educacional: permite ao aluno selecionar, pensar e trocar de opção livremente antes de clicar em "Confirmar", reduzindo a ansiedade em avaliações VR. Trava a interface após confirmação e exibe visualmente qual era a alternativa correta.

<QuizSpotlight3D> (Quiz Detetive / Inspeção)

Sistema de inspeção espacial. Instancia recortes visuais ("Pontos Quentes") usando shader: flat e sobreposição de texturas PNG por cima do vídeo ou imagem de fundo. O aluno "foca a visão" em partes do cenário e confirma a seleção num painel central, concluindo um Loop de Resolução Fechado com feedback visual e sonoro imediato.

• Como funciona: O objeto de dados necessita de propriedades espaciais para criar a ilusão óptica: { id: '1', posicao: '0 2 -6', largura: 1.5, altura: 1.5, srcDestaque: '/img/valvula-png.png' }.

<CacaObjetos3D>

Mecânica avançada de gamificação. Espalha objetos interativos pelo cenário e monitora quando todos são encontrados de forma imutável (seguro contra cliques rápidos).

• Cores Dinâmicas: Herda opacidades e cores do ItedThemeProvider automaticamente.
• HUD 3D: Suporte a painel de pontuação flutuante (plano ou curvo), totalmente customizável em largura, altura e rotação para feedback em tempo real.

🛠️ Como usar:

<CacaObjetos3D 
  visivel={true}
  opacidadeEsfera={false} // Esferas invisíveis até o usuário focar
  itens={[
    { id: 'luva', texto: 'LUVA ESQUECIDA', posicao: '2 1 -3' },
    { id: 'bota', posicao: '-1 0 -2', raio: 0.3, exibirTexto: false } // Sem texto flutuante
  ]} 
  painelProgresso={{ visivel: true, tipo: "curvo", largura: 2.75, posicao: "0 2 -3" }} // Placar 3D HUD
  sfxColeta="/audios/pop.mp3"
  onCompletar={() => alert("Missão Cumprida!")} 
/>

🏗️ Templates (Modo Low-Code)

A biblioteca oferece High-Order Components que orquestram a interface 2D, o motor 3D e a gamificação de uma vez. O desenvolvedor só precisa fornecer um objeto de configuração (JSON).

<TemplateVideoInterativo>

Orquestrador SCORM. Executa um vídeo 360, gerencia os controles na Toolbar e pausa automaticamente em momentos predeterminados na trilha para exibir interações e avaliações 3D. Suporta o poderoso modelo de Playlist Interativa Condicional, permitindo carregar vídeos de feedback de ramificação dependendo da resposta do aluno nos minigames.

🛠️ Como usar:

import React from 'react';
import { TemplateVideoInterativo } from 'ited-tech-3d';

export default function AulaEAD() {
  const roteiroAula = [
    {
      id: "quiz-epi",
      tempoPausa: 15.5,
      tipo: "quiz-relacional",
      pergunta: "Ligue o equipamento à sua função:",
      tipoPainel: "plano", // Customização estrutural direta no JSON ("plano" ou "curvo")
      larguraPainel: 6,
      alturaPainel: 3.5, 
      rotacao: "0 -20 0",
      dados: {
        colunaA: [{ id: '1', texto: 'Óculos', matchId: 1 }],
        colunaB: [{ id: '2', texto: 'Proteção Visual', matchId: 1 }]
      },
      // O template redireciona o vídeo magicamente após o término
      sfxAcerto: "/audio/acerto.mp3",
      urlFeedbackPositivo: "/assets/aula-torno-continuacao.mp4" 
    }
  ];

  return (
    <TemplateVideoInterativo 
      titulo="Operação de Torno Mecânico"
      videoSrc="/assets/aula-torno.mp4"
      trilha={roteiroAula}
      onFinalizarVideo={() => console.log("Enviar nota ao LMS!")}
    />
  );
}

🔌 Integração LMS (SCORM)

useScorm

Um React Hook blindado que abstrai a complexidade das APIs SCORM 1.2 e 2004, facilitando a comunicação bidirecional com plataformas LMS (Moodle, Canvas, etc.).

• Isolamento de Bundler: Possui uma função de extração robusta (extrairAPI) que previne erros comuns de empacotamento (t.init is not a function ou scormWrapper is not defined) ao compilar o projeto com Vite ou Rollup.

🛠️ Como usar:

import React from 'react';
import { TemplateVideoInterativo, useScorm } from 'ited-tech-3d';

export default function AulaComNota() {
  // Inicializa a conexão SCORM (passando 'true' para ativar logs de debug)
  const { scormIniciado, nomeAluno, salvarNota, finalizarCurso } = useScorm(true);

  const lidarComSucesso = () => {
    salvarNota(100);       // Salva a nota no LMS
    finalizarCurso(true);  // Muda o status para "Passed" e fecha a conexão
  };

  return (
    <TemplateVideoInterativo 
      titulo={scormIniciado ? `Aluno: ${nomeAluno}` : "Modo Local"}
      videoSrc="..."
      onFinalizarVideo={lidarComSucesso} 
    />
  );
}

🗺️ Roadmap de Desenvolvimento

• [x] Core: Configuração Base, Fixes Nativos de WebXR embutidos e Design System (Theming).
• [x] Cena e Mundo 3D: <Cena360>, <CenarioVirtual>, <Objeto3D>.
• [x] Layout UI: <LayoutImersivo>, <ToolbarImersiva>.
• [x] Cenários 360: <Ambiente> (Autoplay explícito e otimização para iOS inline).
• [x] Interatividade: <Botao3D>, <PainelQuiz3D>, <QuizRelacional3D>.
• [x] Gamificação: <CacaObjetos3D> (Com HUD 3D e Cores Tematizadas).
• [x] Templates de Autoria: <TemplateCacaEstatica>, <TemplateVideoInterativo>.
• [x] Controles Avançados: <ControlesOrbita> (Câmera look-at com inércia para modo de inspeção de modelo técnico).
• [x] Integração LMS: Hook useScorm encapsulado e robusto para rastreamento de notas.

Mantido pela equipe de Tecnologia Educacional do ITED.