Communitygithub.com

Mobile-First 3D

Experiência dedicada para dispositivos móveis e tablets em sites pesados de 3D/WebGL — detecção de perfil do dispositivo, configurações de renderização mais leves, enquadramento de câmera em retrato para que assuntos (planetas com anéis, galáxias) nunca sejam cortados, painel inferior, folha de menu, áreas seguras, comportamento de toque e scroll reduzido. Use sempre ao construir um site 3D e sempre que alguém disser 'no celular está cortado / não aparece direito / lento / feio'.

O que é Mobile-First 3D?

Este skill, 'Mobile-First 3D', é projetado para desenvolvedores que criam experiências 3D com WebGL (como sites de planetas ou galáxias) em dispositivos móveis e tablets, onde o comportamento de desktop não se traduz adequadamente. Ele aborda problemas comuns como recorte de assuntos, baixo desempenho e layout inadequado em telas pequenas. O skill oferece uma abordagem completa: detecção automática do perfil do dispositivo (trocando a classe `html.mobile`), um perfil de renderização otimizado (reduzindo DPR, resolução de texturas e amostragem), enquadramento específico para retrato (com inclinação da câmera e iluminação frontal para evitar cortes), e um layout móvel com painéis inferiores, folha de menu e scroll reduzido. Suporta qualquer plataforma que use WebGL (Claude Code, Cursor, Codex, etc.) e inclui uma matriz de teste mínima para garantir que o conteúdo seja visível e funcional. Implementar este skill resolve a maioria dos bugs relatados como 'está cortado' ou 'está lento' em dispositivos móveis.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/forpc1428-eng/cosmic-forge/tree/HEAD/skills/mobile-first-3d

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Mobile-First 3D faz?

Celulares não são desktops pequenos. Construa um perfil separado, ativado por uma classe: html.mobile.

1. Detecção

const MOBILE = qs.get('m') === '1' || (qs.get('m') !== '0' &&
  (matchMedia('(pointer: coarse)').matches || Math.min(innerWidth, innerHeight) < 600));
document.documentElement.classList.toggle('mobile', MOBILE);

?m=1 / ?m=0 forçam a detecção — essencial para testar em emulação de desktop.

2. Perfil de renderização

ConfiguraçãoDesktopCelular
Limite de DPR / pixels máximos1.5 / 3.2 MP1.25 / 1.0 MP
Passos geodésicos220150
Amostras de volume3624
Tamanho do sky bake768 / 512384 / 256
Conjunto de texturastextures/hd (~6 MB)textures/m (~1.2 MB)
Paralaxe com mouse / olhar ao redorativadodesativado (apenas toque; emuladores enviam eventos de mouse)

3. Enquadramento em retrato (de onde vêm a maioria dos bugs "está cortado")

  • O FOV horizontal em retrato é pequeno: tan(hFOV/2) = tan(vFOV/2)·aspect (≈0.22 a 52° e 0.46 de aspecto).
  • A distância de cada assunto = max(R·distMul·1.25, visibleRadius·7.6); visibleRadius inclui anéis (Saturno ≈ 2.35 R, Urano ≈ 1.8 R).
  • Aponte para o assunto, depois incline toda a visão para baixo ≈ 0.21 rad para que fique no terço superior, acima do painel de texto. (Deslocar o alvo em vez disso faz com que ele se mova lateralmente quando a câmera se move.)
  • Ilumine mais frontalmente (fase ~45°): planetas iluminados lateralmente, com metade preta, parecem "cortados" em telas pequenas.
  • Trave a mira durante retenções de conteúdo (tangentes do alvo zero) — sem desvio do centro.
  • Verifique numericamente: renderize um quadro, readPixels linhas cruzando o assunto, verifique se o intervalo iluminado está dentro de 5–95 % da largura.

4. Layout

  • Painéis → painel inferior: left:0; right:0; bottom:0; max-height:60vh; overflow:auto, fundo gradiente, padding-bottom: calc(54px + env(safe-area-inset-bottom)).
  • Títulos clamp(34px, 10vw, 52px); nome do herói dividido em 2 linhas.
  • Navegação → hambúrguer + folha desfocada em tela cheia com links serifados de 44 px.
  • Oculte trilhos decorativos; encurte rótulos (apenas nome); oculte a dica de scroll de aterrissagem se colidir.
  • Scroll mais curto: introdução ~320vh, jornada ~2600vh (celulares rolam mais rápido com momentum).
  • viewport-fit=cover, estágios fixos 100svh, sem overflow horizontal a 320 px.

5. Matriz de teste (emulação não é suficiente, mas é o mínimo)

375×812 e 390×844 retrato, 412×915 Android, 768×1024 tablet. Cada batida de conteúdo: assunto totalmente visível e centralizado acima do painel, texto legível, nada sob o notch/barra inicial. Avise o usuário honestamente quando um teste em dispositivo real não foi feito.

Individual skills in this repo

This repo contains 3 individual skills — each has its own dedicated page.

Habilidades Relacionadas