📦 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' }). |

🧩 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

<PainelQuiz3D> e <Botao3D>

Componentes imersivos inteligentes. O PainelQuiz3D cria uma interface cilíndrica customizável (posição, rotação, altura e ângulo) que "abraça" a visão do usuário, evitando distorções nas lentes VR, e compartilha seu raio de curvatura nativamente com os botões internos.

<QuizRelacional3D>

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

<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 de Play/Pause na Toolbar e pausa automaticamente em momentos predeterminados no JSON (trilha) para exibir Mini-games dinâmicos (como Quizzes ou Caça a Objetos), retomando o vídeo apenas quando o aluno acerta. Permite customização espacial profunda do HUD.

🛠️ 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:",
      alturaPainel: 2.2, // Customização direta no JSON
      rotacao: "0 -20 0",
      dados: { colunaA: [...], colunaB: [...] }
    }
  ];

  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> (Fotos, Vídeos e Controle Imperativo).
• [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.