🛠️ Hexagon Map Tool V2

✨ Configuración Automática (Recomendado)

1. Abre la herramienta Hexagon Map Tool V2 desde el menú de Unity.
2. Crea tu primer Layer: Haz clic en el botón [+] al lado del dropdown de Layers.
3. Asigna un nombre al layer en la ventana modal (ej: "Terrain", "Buildings", etc.).
4. ¡Listo! El sistema creará automáticamente:
   • Un Grid con valores por defecto (si no existe uno en la escena)
   • Un Layer con el nombre especificado
   • Todas las referencias y jerarquía configuradas automáticamente

📦 Paso 1: Preparar el Modelo 3D

1. Importa tu modelo a la carpeta Assets/.
2. ⚠️ Verifica la orientación:

   ⚠️ Importante: El modelo debe verse correctamente orientado cuando su rotación está en (0, 0, 0).

   Problema común: Algunos modelos importados tienen rotaciones incorrectas (ej: Y=-90°) y algunos desarrolladores compensan rotando el objeto en Unity.

   ❌ Esto causa problemas porque la herramienta usa rotación (0,0,0) como base para cálculos hexagonales y rotaciones del mesh.

   ✅ Solución recomendada: Corrige la orientación del modelo en tu software de modelado 3D.

   🔧 Solución alternativa: Si no puedes modificar el modelo:

   • Crea un GameObject vacío con rotación (0, 0, 0)
   • Añade el componente HexagonObject al objeto vacío
   • Coloca el modelo como hijo del objeto vacío
   • Rota el modelo hijo para corregir su orientación

3. Pivote del modelo:
   • Recomendado: Pivote en la base inferior bien centrado
   • No obligatorio: La herramienta permite ajustar el offset del pivote si es necesario

🔧 Paso 2: Configurar el HexagonObject

1. Arrastra el modelo a la escena (o crea el GameObject vacío si usas la solución alternativa)
2. Añade el componente HexagonObject
3. Configura las propiedades:
   • Pivot Offset: Ajusta si el pivote no está centrado (automático con botón Calculate Properties)
   • Height Cells: Cuántas celdas hexagonales de altura ocupa este objeto
   • Is Stackable: Permite que otros objetos se apilen encima
   • Is Hexagon Prop: Marca como decorativo (árboles, rocas). El pincel lo ignorará excepto con el borrador
   • Requires Floor: Requiere un objeto sólido debajo para ser colocado (excepto a nivel del suelo)
4. Tip: Usa el botón Calculate Properties en el menú contextual del componente para calcular automáticamente el Pivot Offset y Height Cells
5. Crea un prefab arrastrando el objeto a tu carpeta de Prefabs
6. (Opcional) Organiza tus prefabs en subcarpetas según tu preferencia

🎨 Paso 3: Añadir el Prefab como Pincel

Método 1: Arrastrar y Soltar (Rápido)

1. Abre la herramienta Hexagon Map Tool V2, ve al tab Tools
2. Arrastra tu prefab al botón verde de Drawing Palettes
3. Se abrirá un modal para crear un nuevo pincel con tu prefab
4. (Opcional) Añade más prefabs al pincel:
   • Haz clic en el botón verde [+] del modal o arrastra más prefabs en el mismo para crear variaciones
   • Esto permite usar patrones como Random para distribuir las variantes
5. Haz clic en Crear

Método 2: Botón [+] (Detallado)

1. Haz clic en el botón verde [+] de Drawing Palettes
2. Se abrirá el modal de crear pincel (vacío)
3. Para añadir prefabs tienes dos opciones:
   • Arrastrar: Arrastra tu prefab al botón [+] del modal
   • Seleccionar: Haz clic en el botón [+] del modal → se abrirá una lista de todos los HexagonObjects válidos en tu proyecto → selecciona el que desees
4. Haz clic en Crear

Propósito: Componente que convierte cualquier GameObject en un objeto hexagonal válido para el sistema.

Grid Integration

• Parent Layer Reference: Referencia al HexagonTileLayer donde se registra
• Cell Coordinate: Coordenada de la celda hexagonal que ocupa
• ParentGrid: Referencia de solo lectura al HexagonGrid3D padre (accesible vía el TileLayer)

Cell Properties

• Pivot Offset: Ajuste del pivote del objeto (se calcula automáticamente)
• Height Cells: Cuántas celdas hexagonales de altura ocupa (1 por defecto)
• Is Stackable: Permite que otros objetos se apilen encima
• Is Hexagon Prop: Marca el objeto como decorativo (árboles, rocas, etc.)
• Requires Floor: Requiere objeto sólido debajo para ser colocado
• Rotation Index: Índice de rotación (0–5) en incrementos de 60°. 0=0°, 1=60°, 2=120°, 3=180°, 4=240°, 5=300°

Métodos Públicos

• CalculateProperties(): Calcula automáticamente Pivot Offset y Height Cells basándose en el modelo 3D
• DoSnapToGrid(): Alinea el objeto a la celda hexagonal más cercana del grid
• SnapRotation(): Redondea la rotación Y al múltiplo de 60° más cercano y actualiza RotationIndex
• ApplyRotationFromIndex(): Aplica la rotación en el Transform para que coincida con el valor actual de RotationIndex
• MoveTo(Vector3Int cellCoord): Mueve el objeto a una coordenada de celda específica
• ChangeLayer(HexagonTileLayer newLayer): Cambia el objeto a un layer diferente
• RegisterInLayer(): Registra manualmente el objeto en su layer asignado
• UnregisterFromLayer(): Desregistra el objeto de su layer actual

Uso en Runtime

• Usa DoSnapToGrid() para alinear objetos movidos dinámicamente
• Usa MoveTo() para mover objetos entre celdas durante el juego
• Accede a CellCoordinate para saber en qué celda está el objeto
• Usa SnapRotation() tras rotar un objeto en runtime para mantener el índice sincronizado

Propósito: Define la geometría y parámetros del grid hexagonal 3D que sirve como base para todo el mapa.

Grid Geometry

• Radius (R): Distancia del centro a cualquier vértice del hexágono
• Apothem (A): Distancia del centro al punto medio de cualquier lado
• Height (H): Altura del prisma hexagonal (distancia entre niveles)
• Side Length: Longitud del lado del hexágono (calculado automáticamente)

Cell Configuration

• Cell Gap: Espacio adicional entre celdas
• Cell Swizzle: Configuración de ejes espaciales (XYZ, XZY, etc.)

Debug & Visualization

• Show Grid: Muestra/oculta el grid en Scene View
• Grid Color: Color de las líneas del grid
• Show Coordinates: Muestra coordenadas hexagonales en Scene View
• Neighbor Radius: Radio de vecinos a mostrar en debug
• Height Range: Rango de altura a mostrar en debug

Métodos Públicos

• WorldToCell(Vector3 worldPos): Convierte posición del mundo a coordenadas de celda hexagonal
• CellToWorld(Vector3Int cellPos): Convierte coordenadas de celda a posición del mundo
• GetCellCenterWorld(Vector3Int cellPos): Obtiene el centro de una celda en coordenadas del mundo
• GetHorizontalNeighbors(Vector3Int center, int range): Obtiene vecinos en el plano horizontal
• GetVerticalNeighbors(Vector3Int center, int range): Obtiene vecinos en el eje vertical
• GetNeighbors3D(Vector3Int center, int hRange, int vRange): Obtiene vecinos en un volumen 3D

Uso en Runtime

• Usa WorldToCell() para convertir posiciones de mouse/raycast a celdas
• Usa GetNeighbors3D() para encontrar celdas adyacentes (movimiento, rango de ataque, etc.)
• Usa CellToWorld() para posicionar objetos en celdas específicas

Propósito: Administra una capa de objetos sobre el grid. Cada layer representa un nivel o categoría de objetos (terreno, edificios, decoración, etc.).

Layer Configuration

• Hexagon Grid Reference: Referencia al HexagonGrid3D asociado
• Floor Cell: Nivel base donde se colocan objetos por defecto (puede ser negativo para capas subterráneas)

Gizmos Visualization

• Base Gizmo Color: Color del plano base hexagonal en los gizmos de Scene View

Layer Statistics (Solo lectura)

• Occupied Cells: Número de celdas ocupadas en esta capa
• Total Objects: Número total de objetos en esta capa

Métodos Públicos

• IsCellOccupied(Vector3Int cellCoord): Verifica si una celda está ocupada
• GetCellOccupants(Vector3Int cellCoord): Obtiene todos los objetos en una celda específica
• GetStackingHeight(Vector3Int cellCoord): Calcula la altura para apilar el siguiente objeto
• GetAllOccupiedCells(): Obtiene lista de todas las celdas ocupadas
• GetCellWorldPosition(Vector3Int cellCoord): Convierte coordenada de celda a posición del mundo
• RegisterCellOccupant(Vector3Int cellCoord, HexagonObject obj): Registra un objeto en una celda
• UnregisterCellOccupant(Vector3Int cellCoord, HexagonObject obj): Desregistra un objeto de una celda
• CleanupNullReferences(): Limpia referencias nulas del registro
• RebuildFromHierarchy(): Reconstruye el registro desde la jerarquía de objetos

Uso en Runtime

• Usa IsCellOccupied() para verificar si puedes colocar algo en una celda
• Usa GetCellOccupants() para obtener todos los objetos en una posición (útil para interacciones)
• Usa GetAllOccupiedCells() para iterar sobre todos los objetos del mapa

No. El componente HexagonObject es obligatorio para que el sistema reconozca y gestione los objetos correctamente.

Razón: El componente define propiedades esenciales como Height Cells, Stack Priority, Requires Floor y si es Prop, que el sistema necesita para calcular colisiones, apilamientos y comportamientos de pintado.

Solución: Añade el componente a todos los prefabs antes de usarlos en paletas. Usa el botón "Calculate Properties" para configuración automática basada en la geometría del modelo.

Verifica que el punto de pivote del modelo esté en la base central del objeto, no en el centro geométrico.

Solución ideal: En tu software de modelado 3D (Blender, Maya, etc.), ajusta el pivot point antes de exportar. En Unity no se puede cambiar fácilmente el pivot de un modelo importado.

Solución en Unity - PivotOffset: El componente HexagonObject tiene un parámetro PivotOffset que permite compensar la posición sin modificar el modelo. Ajusta los valores X, Y, Z en el Inspector para corregir el offset.

Alternativa avanzada: Crea un GameObject vacío, coloca el modelo como hijo, y ajusta su Transform local para compensar el offset del pivot. Añade el componente HexagonObject al padre vacío.

Causas comunes y soluciones:

1. Registro desincronizado: Haz clic en el botón "↻ Actualizar" al lado del dropdown de Layer selection. Esto reconstruye el registro de ocupación desde la jerarquía.
2. Objetos ocultos: Ve al Layer Tab → Object Catalog y verifica que ningún grupo esté oculto con el toggle de visibilidad. Los objetos invisibles siguen ocupando celdas.
3. HexagonObject invisible: Puede haber un GameObject con componente HexagonObject pero sin modelo 3D visible. Busca en el Hierarchy del layer objetos sospechosos.
4. Props y Stackables:
   • IsHexagonProp = true: El objeto bloquea la ocupación a objetos encima de él. Perfecto para elementos decorativos.
   • IsStackable = true: Permite que múltiples objetos con esta propiedad activa puedan ocupar la misma celda simultáneamente. Útil para combinar elementos decorativos.

Alturas diferentes: Sí. Usa la propiedad HeightCells del componente HexagonObject para definir cuántas celdas verticales ocupa cada prefab sobre la geometría base del grid.

Dimensiones horizontales diferentes: No en el mismo grid. Cada HexagonGrid3D tiene geometría fija (Cell Radius, Cell Height) que define el tamaño base de todas las celdas hexagonales.

Solución para múltiples dimensiones: Crea múltiples HexagonGrid3D en la escena, cada uno con sus propias dimensiones. Cada grid puede tener sus propios layers independientes.

Usa la Collision Matrix en el tab Grid para controlar las interacciones entre layers.

Funcionamiento:

• Marcado (✓): Los layers colisionan - NO pueden superponerse en la misma celda
• Desmarcado ( ): Los layers NO colisionan - SÍ pueden compartir celdas

Pasos para configurar:

1. Ve a Grid Tab → Collision Matrix
2. Localiza la intersección entre los layers que quieres configurar
3. Marca/desmarca según necesites

Define si el objeto necesita suelo debajo para ser colocado. Usado principalmente en modo Fill Volume.

• RequiresFloor = true: Solo se coloca si hay otro objeto directamente debajo. Ideal para edificios, árboles, decoración.
• RequiresFloor = false: Se puede colocar en el aire. Ideal para terreno base, plataformas flotantes, nubes.

Uso práctico: Al rellenar un volumen con Fill Volume, el sistema verifica automáticamente esta propiedad para evitar decoración flotante sin base.

Limitación: La herramienta instancia objetos reales en la escena. Miles de GameObjects pueden causar problemas de rendimiento en editor y runtime.

Estrategias recomendadas:

• Escenarios pequeños/modulares: Divide el mundo en secciones más pequeñas (chunks) y carga/descarga según la posición del jugador.
• Técnicas de optimización:
  • Static Batching para objetos inmóviles
  • GPU Instancing para objetos idénticos
  • LODs (Level of Detail) para reducir complejidad a distancia
  • Occlusion Culling para ocultar geometría no visible
• Sistema de streaming: Exporta layers a JSON (botón Exportar en Layer Tab) y crea un sistema custom que:
  1. Carga datos de posiciones desde JSON
  2. Usa Object Pooling para reutilizar instancias
  3. Solo instancia hexágonos visibles por la cámara
  4. Destruye/desactiva hexágonos fuera de rango

Usa la función de Exportar/Importar en el Layer Tab:

Exportar:

1. Ve a Layer Tab → Data Management → Exportar Layer
2. Guarda el archivo JSON en una ubicación accesible
3. El JSON contiene: posiciones, rotaciones, referencias a prefabs, configuración del layer y geometría del grid

Importar:

1. En la escena destino, crea un HexagonGrid3D con las mismas dimensiones
2. Crea un Layer o selecciona uno existente
3. Ve a Layer Tab → Data Management → Importar Layer
4. Selecciona el archivo JSON
5. Revisa el Preview Obligatorio para reasignar prefabs faltantes
6. Confirma la importación

No. Hexagon Map Tool V2 es una herramienta de editor solamente (Edit Mode).

Diseño: Está pensado para construir y diseñar mapas hexagonales durante el desarrollo, no para permitir edición dinámica durante el juego.

En Runtime: Los objetos creados son GameObjects normales que existen en la escena. Puedes acceder a ellos mediante código, pero no puedes usar las herramientas de pintado/edición.

Si necesitas edición en runtime: Los componentes (HexagonGrid3D, HexagonTileLayer, HexagonObject) tienen APIs públicas que puedes usar para crear tu propio sistema de edición en runtime.

Usa un brush con múltiples variantes del mismo tipo de objeto.

Técnica:

1. Crea 3-5 variantes del mismo elemento (ej: césped con flores diferentes)
2. Añádelas todas al mismo brush
3. Selecciona el patrón Random en Patrón de Distribución
4. Activa Rotación Aleatoria y permite varios ángulos

Resultado: El sistema distribuirá aleatoriamente las variantes con diferentes rotaciones, creando apariencia orgánica y natural.

Los patrones definen cómo se distribuyen los prefabs del brush dentro del área de pintado.

Validación: El sistema muestra warnings si no tienes suficientes prefabs para el patrón seleccionado.