Gaeláctica

🎮 Componentes del Juego

37 archivos en _components/ — documentación de cada componente, sistema, hook, modelo y utilidad.

🧩
16
Componentes
⚙️
7
Sistemas
🪝
4
Hooks
🎨
5
Modelos 3D
🔧
5
Utilidades

🧩Componentes(16)

GameScene

Escena principal del juego. Orquesta todos los sistemas y componentes 3D.

componente
  • ▸Canvas R3F con física Rapier
  • ▸Carga y orquesta: SkySphere, WaterSphere, CloudSphere, AtmosphereSphere
  • ▸Gestión de chunks, NPCs, rocas, árboles GLB
  • ▸Sistema de construcción (BuildMenu)
  • ▸Ciclo día/noche, cámara planetaria
  • ▸Manejo de selección de NPCs y chat
frontend/app/admin/game/_components/GameScene.tsx

LoadingScreen

Pantalla de carga con progreso de pasos animados.

componente
  • ▸Muestra 6 pasos de carga secuenciales
  • ▸Espera a que los chunks estén listos (chunksReady)
  • ▸Spinner animado y detección de móvil
  • ▸Auto-oculta al completar la carga
frontend/app/admin/game/_components/LoadingScreen.tsx

SceneSetup

Configuración de la escena 3D: luces, niebla, fondo.

componente
  • ▸Luz ambiental, hemisférica y direccional con sombras
  • ▸Niebla con transición día/noche suave
  • ▸Sincronización con gameTimeRef para colores dinámicos
frontend/app/admin/game/_components/SceneSetup.tsx

DebugOverlay

Ventana flotante de debug con FPS, zoom, render distance y total de bloques.

componente
  • ▸Se muestra/oculta con la tecla O
  • ▸Muestra FPS, distancia de cámara, render distance dinámico
  • ▸Total de bloques renderizados y radio de isla
  • ▸Threshold del noise ajustable
frontend/app/admin/game/_components/DebugOverlay.tsx

MusicPlayer

Reproductor de música en la esquina superior derecha.

componente
  • ▸Select con canciones disponibles desde API /api/game/songs
  • ▸Controles de play/pause y mute
  • ▸Reproducción automática en orden aleatorio (shuffle)
frontend/app/admin/game/_components/MusicPlayer.tsx

GameClock

Reloj de 24h que avanza 1 minuto cada 250ms (15s reales = 1h en el juego).

componente
  • ▸Formato HH:MM en esquina superior derecha
  • ▸Actualiza gameTimeRef para ciclo día/noche
  • ▸Incrementa gameDayRef al pasar de 23:59 a 00:00
frontend/app/admin/game/_components/GameClock.tsx

BuildMenu

Menú de construcción con materiales, prefabs, árboles y modo destrucción.

componente
  • ▸Selección de material (piedra, madera, arena, hierba, cristal, etc.)
  • ▸Estilo de textura (default/lisa)
  • ▸Prefabs de construcción (mesa, silla, cama, escaleras, etc.)
  • ▸Selección de variantes de árbol para plantar
  • ▸Modo destrucción de bloques
  • ▸Categorías: Materiales, Prefabs, Árboles, Destruir
frontend/app/admin/game/_components/BuildMenu.tsx

PowersMenu

Menú de poderes del juego: crear NPCs y establecer zona de base.

componente
  • ▸Poder 'Crear NPC': click izquierdo en bloque para crear NPC con su forma
  • ▸Poder 'Establecer zona': marca zona de base (100 bloques a la redonda)
  • ▸Cada poder tiene nombre, descripción, costo y emoji
frontend/app/admin/game/_components/PowersMenu.tsx

NpcChatPanel

Panel de chat en la esquina inferior izquierda. Muestra mensajes de NPCs.

componente
  • ▸Solo lectura — muestra mensajes que los NPCs envían al jugador
  • ▸Auto-scroll al último mensaje
  • ▸Sincronizado con npcChatState
frontend/app/admin/game/_components/NpcChatPanel.tsx

Chunk

Renderiza un chunk completo con sus bloques y árboles GLB.

componente
  • ▸Memoizado para evitar re-renderizados innecesarios
  • ▸Renderiza InstancedBlocks y GlbTreeModel
  • ▸Soporta bloque destacado (highlightedBlock)
  • ▸Posicionamiento esférico opcional
frontend/app/admin/game/_components/Chunk.tsx

GlbRockRenderer

Renderiza todas las rocas del mundo como modelos GLB decorativos.

componente
  • ▸Rocas decorativas NO agarrables
  • ▸Posicionadas cerca de montañas
frontend/app/admin/game/_components/GlbRockRenderer.tsx

SkySphere

Esfera de cielo con ciclo día/noche, estrellas parpadeantes y sol/luna.

componente
  • ▸320 estrellas con twinkle cada ~2s
  • ▸Transiciones de color día/noche progresivas
  • ▸Sol y luna posicionados dinámicamente
  • ▸Sincronizado con gameTimeRef
frontend/app/admin/game/_components/SkySphere.tsx

WaterSphere

Esfera de agua que envuelve el mundo con dos capas para ocultar bordes.

componente
  • ▸Dos capas: exterior semitransparente e interior más opaca
  • ▸48 segmentos para esfera suave
  • ▸Capa interior con radio ligeramente menor para evitar z-fighting
frontend/app/admin/game/_components/WaterSphere.tsx

CloudSphere

Esfera de nubes procedurales con textura seamless y rotación lenta.

componente
  • ▸Radio 170 (SPHERE_RADIUS + 20) para flotar sobre el terreno
  • ▸Textura procedural de nubes sin costuras
  • ▸Rotación muy lenta (0.0003 rad/s) para sensación de movimiento
  • ▸24 segmentos para optimizar
frontend/app/admin/game/_components/CloudSphere.tsx

AtmosphereSphere

Esfera de atmósfera con efecto Fresnel para halo brillante alrededor del planeta.

componente
  • ▸Radio 200 (SPHERE_RADIUS + 50) para visible desde el espacio
  • ▸Efecto Fresnel: más brillante en los bordes
  • ▸Color azul cielo sutil con tono violáceo en bordes
  • ▸32 segmentos para Fresnel suave
frontend/app/admin/game/_components/AtmosphereSphere.tsx

TerrainColliders

Colliders de física Rapier para el terreno.

componente
  • ▸CuboidCollider para cada bloque sólido
  • ▸Bloques decorativos (flower, mushroom, leaves, water) NO tienen collider
  • ▸Sincronizado con chunks para física en tiempo real
frontend/app/admin/game/_components/TerrainColliders.tsx

⚙️Sistemas(7)

PlanetCamera

Cámara planetaria AAA con base ortonormal local. Sin gimbal lock.

sistema
  • ▸Movimiento en espacio 3D real sobre la esfera
  • ▸Base ortonormal local (forward, right, up) recalculada cada frame
  • ▸W/S: avanzar/retroceder, A/D: yaw local, Q/E: strafe
  • ▸Sin gimbal lock, sin flips en polos, sin roll aleatorio
frontend/app/admin/game/_components/PlanetCamera.ts

noise

Sistema de generación de terreno por ruido (terrain noise).

sistema
  • ▸Tipos de bloques: grass, dirt, stone, sand, water, wood, leaves, snow, bedrock, minerales, etc.
  • ▸Generación de semilla aleatoria para cada carga de página
  • ▸Función hash para valores deterministas
  • ▸Sistema FBM (Fractional Brownian Motion) para ruido
frontend/app/admin/game/_components/noise.ts

chunkManager

Gestor de chunks: generación, coordenadas, NPCs, árboles, rocas.

sistema
  • ▸Tamaño de chunk: 16 bloques
  • ▸Altura máxima del terreno: 7 bloques
  • ▸Render distance configurable (escritorio/móvil)
  • ▸Generación de NPCs, árboles GLB y rocas
  • ▸Sistema de coordenadas de chunks
frontend/app/admin/game/_components/chunkManager.ts

npcMovementSystem

Sistema centralizado de movimiento de NPCs con colisión, detección de atasco y registro.

sistema
  • ▸Movimiento independiente del renderizado (los NPCs se mueven siempre)
  • ▸Colisión volumétrica con radio de esfera (ESFERA_RADIUS = 0.5)
  • ▸Altura máxima de escalón: 1 bloque
  • ▸Registro y desregistro de NPCs
  • ▸Sistema de agarre y lanzamiento
  • ▸Detección de atasco: si no avanza 1 bloque en 2s, cancela destino
  • ▸Repulsión entre NPCs para evitar solapamiento
frontend/app/admin/game/_components/npcMovementSystem.ts

npcChatState

Estado compartido para el sistema de chat de NPCs y zona de base.

sistema
  • ▸Mensajes de chat con NPC name, key, mensaje, timestamp, hora del juego y día
  • ▸Sistema de zona de base (getBaseZone, setBaseRequestedBy)
  • ▸Notificaciones de cambio vía callbacks
frontend/app/admin/game/_components/npcChatState.ts

protaFaceState

Estado compartido para la textura de la cara del prota.

sistema
  • ▸Comunicación entre componentes dentro/fuera del canvas
  • ▸Notificación de cambios vía callback
frontend/app/admin/game/_components/protaFaceState.ts

sharedRefs

Referencias compartidas entre componentes del juego.

sistema
  • ▸cameraDistRef: distancia de cámara al centro
  • ▸gameTimeRef: hora del juego (0-23)
  • ▸gameTimeContinuousRef: hora con minutos como decimal
  • ▸gameDayRef: día del juego
  • ▸dynamicRenderDistRef, totalBlocksRef, islandRadiusRef, thresholdRef
  • ▸fogOverrideRef, chunkGenerationPausedRef
frontend/app/admin/game/_components/sharedRefs.ts

🪝Hooks(4)

useChunkManager

Hook React que gestiona chunks, terreno, NPCs, árboles y rocas en tiempo real.

hook
  • ▸Generación procedural de chunks con TerrainNoise
  • ▸Spawn de NPCs, árboles GLB y rocas
  • ▸Sistema de espíritus de animales
  • ▸Renderizado por frustum (visibleChunksFrustum)
  • ▸Gestión de almacenes (treeStore, rockStore)
frontend/app/admin/game/_components/useChunkManager.ts

usePlayerMovement

Hook que controla el movimiento de la cámara planetaria con auto-rotación y zoom.

hook
  • ▸Auto-rotación orbital alrededor del planeta
  • ▸Zoom con rueda del ratón
  • ▸Movimiento manual WASD/flechas con inercia
  • ▸Detección de inactividad para reanudar auto-rotación
  • ▸Sincronización con sharedRefs (cameraDistRef)
frontend/app/admin/game/_components/usePlayerMovement.ts

useKeyboardControls

Hook que rastrea el estado del teclado para movimiento WASD/flechas.

hook
  • ▸Expone un ref con el conjunto de teclas actualmente presionadas
  • ▸Previene scroll con teclas de flecha
frontend/app/admin/game/_components/useKeyboardControls.ts

useMusicPlayer

Hook que gestiona la lista de canciones y reproducción shuffle.

hook
  • ▸Obtiene canciones desde API /api/game/songs
  • ▸Reproducción automática en orden aleatorio
  • ▸Control de play/pause y mute
frontend/app/admin/game/_components/useMusicPlayer.ts

🎨Modelos 3D(5)

VoxelModel

Cargador de modelos GLB voxel con animación procedural y outline.

modelo
  • ▸Carga modelos GLB con caché global
  • ▸Soporta animación procedural (idle, walk, attack, collect, death)
  • ▸Outline negro alrededor del modelo
  • ▸Soporte para Z-up (Blender) y Y-up (Three.js)
  • ▸Color tint opcional para el modelo
frontend/app/admin/game/_components/VoxelModel.tsx

Block

Sistema de bloques instanciados con múltiples texturas y estilos.

modelo
  • ▸Renderiza bloques con InstancedMesh para alto rendimiento
  • ▸Soporta múltiples tipos: grass, dirt, stone, sand, wood, leaves, snow, etc.
  • ▸Estilos de textura: default (perfilado) y lisa
  • ▸Colocación esférica con rotación radial
  • ▸Sistema de color por bioma (flower power)
frontend/app/admin/game/_components/Block.tsx

GlbTreeModel

Carga modelos GLB de árboles con caché global y posicionamiento esférico.

modelo
  • ▸Caché global: cada modelo se carga UNA VEZ y se clona
  • ▸Soporta múltiples variantes (roble, invierno, otoño, palmera, pantano)
  • ▸Rotación radial para mundo esférico
frontend/app/admin/game/_components/GlbTreeModel.tsx

GlbRockModel

Carga modelos GLB de rocas (rock-1 a rock-8) con caché global.

modelo
  • ▸Caché global: cada modelo se carga UNA VEZ y se clona
  • ▸8 variantes de roca diferentes
  • ▸Sombras desactivadas para rendimiento
frontend/app/admin/game/_components/GlbRockModel.tsx

BlockNpcModel

NPC de bloque con estadísticas, selección, chat, patrulla y movimiento por zona.

modelo
  • ▸Renderiza un NPC con forma de bloque y cara expresiva
  • ▸Estadísticas: vida, daño, velocidad, visión, edad, felicidad, energía
  • ▸Seleccionable con clic (onSelect)
  • ▸Muestra barra de vida y nombre
  • ▸Movimiento por zona (ZONE_RADIUS = 2.5) en lugar de punto exacto
  • ▸Patrulla autónoma con cambio de dirección al colisionar
  • ▸Detección de atasco: si no avanza 1 bloque en 2s, reinicia patrulla
  • ▸Integrado con chat (npcChatState)
frontend/app/admin/game/_components/BlockNpcModel.tsx

🔧Utilidades(5)

SphericalWorld

Sistema de coordenadas esféricas para el mundo planeta.

utilidad
  • ▸Convierte coordenadas planas (x,y,z) a esféricas
  • ▸Calcula rotación radial para alinear objetos con la superficie
  • ▸Objetos reutilizables para evitar GC pressure
frontend/app/admin/game/_components/SphericalWorld.tsx

blockPrefabs

Definiciones de prefabs de construcción (conjuntos de bloques).

utilidad
  • ▸Cada prefab es un conjunto de bloques en posiciones relativas
  • ▸Soporta: medio bloque, escalera, rotación X/Y
  • ▸Usado por BuildMenu para construir estructuras predefinidas
frontend/app/admin/game/_components/blockPrefabs.ts

blockNpcStats

Tipos y estadísticas de NPCs de bloque (stone, wood, sand, grass).

utilidad
  • ▸Estadísticas: vidaMax, damage, speed, vision, age, maxAge, happiness, energy
  • ▸Felicidad (0-100): afecta expresión facial
  • ▸Energía (0-100): se reduce 10 por hora, a 0 se convierte en bloque inmóvil
frontend/app/admin/game/_components/blockNpcStats.ts

findGreenZones

Escanea el terreno para encontrar áreas verdes y planas ideales para construir ciudades.

utilidad
  • ▸Busca zonas con tierra firme, no montaña, terreno plano, no costa
  • ▸Evalúa densidad de puntos verdes en área circular
  • ▸Retorna las 3 mejores zonas verdes encontradas
frontend/app/admin/game/_components/findGreenZones.ts

constants

Constantes globales del juego: radio de esfera, nivel del mar.

utilidad
  • ▸SPHERE_RADIUS = 150 (radio del mundo)
  • ▸SEA_LEVEL = 4 (altura del agua)
  • ▸WATER_RADIUS = SPHERE_RADIUS + SEA_LEVEL
frontend/app/admin/game/_components/constants.ts
37 componentes documentados • Game Engine