Mapas de teselas

El sistema de mapas de teselas te permite pintar mundos basados en teselas usando máscaras de auto-encaje, múltiples capas y extrusión de paredes con generación de colisiones integrada.

Agregar un mapa de teselas

Añade un Tilemap_Component a cualquier entidad. El mapa de teselas se centra en la posición de la entidad y abarca una cuadrícula de chunks (cada uno de 32×32 teselas). El tamaño total en teselas es width_in_chunks × 32 por height_in_chunks × 32.

Propiedades del mapa de teselas

Propiedad	Descripción
Ancho / Alto en chunks	Tamaño de la cuadrícula de teselas. Cada chunk es de 32×32 teselas. Un mapa de teselas de 10×10 da 320×320 teselas.

Las capas se configuran individualmente una vez que entras en el modo de edición (ver abajo).

Las nuevas capas de suelo tienen contornos transparentes. Las nuevas capas de pared tienen cuerpo y contornos superiores negros opacos y no tienen textura superior, por lo que la textura del cuerpo llena la fila superior. Ambas máscaras usan por defecto $AO/tile_mask.png. Elige por separado las texturas de relleno del suelo o del cuerpo de la pared. Estos valores predeterminados de creación se aplican en el editor, MCP, CSL y C#; cargar una capa existente conserva sus ajustes guardados.

Para las partes superiores negras de las paredes, añade un PNG negro opaco de 1×1 al proyecto como res/ao_black.png si no existe, y luego establécelo como textura superior de cada capa de pared. El motor ya no incluye $AO/black.png: las capas guardadas con él se cargan sin textura superior, y los scripts deben cargar ao_black.png en su lugar.

Cambiar el tipo de capa cambia el contorno predeterminado de suelo/cuerpo para que coincida con el nuevo tipo. Los colores de contorno personalizados se conservan.

Para un edificio, usa capas de suelo y pared en el mismo mapa de teselas. Extiende el suelo por debajo de cada tesela de pared, así como del interior; detenerse en el borde interior de la pared deja un hueco. Las aberturas de puertas eliminan las teselas de pared mientras conservan el suelo.

Creación en MCP

Los agentes deben mantener el tamaño de la tesela en su valor predeterminado 1, también en el código de ejecución, y mantener las entidades estructurales a escala unitaria. El tamaño de la tesela no es una opción de MCP. Cambia la huella mediante el número de teselas y el patrón del material mediante la escala de textura.

• tilemap_inspect lee los ajustes de la capa, los límites ocupados, las secuencias horizontales de ocupación paginadas y las conversiones tesela/mundo.

• asset_prepare_tileable recorta el relleno del borde transparente de las texturas de relleno descargadas mediante los ajustes de recorte del recurso y habilita la repetición. Conserva el recorte existente y el arte opaco; comprueba opaqueEdges si queda transparencia en los bordes. apply:false previsualiza el recorte. Proporciona crop para reemplazar los márgenes actuales cuando también haya que eliminar un borde difuminado conocido. Los recortes usan [left,bottom,right,top] márgenes en píxeles de origen y afectan a todos los usos del recurso sin cambiar la imagen de origen.

• tilemap_configure redimensiona la cuadrícula y añade, parchea, elimina o vacía capas. Las nuevas capas requieren texturas de relleno; proporcionar texturas reemplaza la lista completa. Las texturas de relleno del proyecto se preparan para repetirse sin recortarlas automáticamente. Las máscaras no se modifican.

• tilemap_paint establece o borra rectángulos, trazos de pincel conectados y celdas explícitas.

• tilemap_stamp copia la ocupación mediante asignaciones explícitas de capas, opcionalmente entre mapas. Las rotaciones son en sentido antihorario en la cuadrícula con eje Y hacia arriba. Merge conserva las celdas de destino bajo los huecos de origen; replace las borra.

Usa modify_scene para crear la entidad y Tilemap_Component. Las herramientas apuntan a una entidad por AOID o nombre, con componentId cuando sea necesario. Las coordenadas de tesela y los índices de capa empiezan en cero; los extremos de los rectángulos de teselas son inclusivos, y un rectángulo de mundo cubre las celdas cuyos centros están en [min,max). Usa tilemap_inspectde worldCenter al colocar objetos en los centros de teselas: la conversión nativa de tesela a mundo devuelve la esquina de la tesela. Se respetan la posición y la escala; se ignora la rotación de la entidad.

Pintar y estampar rechazan destinos fuera de límites a menos que clip: true. Las operaciones ordenadas se validan antes de aplicar cada edición y se detienen en el primer error, conservando los éxitos anteriores. MCP limita cada solicitud a 128 operaciones, 1.000.000 visitas a celdas y 1.000.000 instancias de teselas expandidas, con cuadrículas de 2 a 100 chunks por eje.

Inspecciona las huellas de colisión con editor_scene_screenshot(colliderDebug: true). Solo las capas de pared con la colisión activada generan estas formas; verifica las aberturas y los límites sólidos con el jugador en el juego.

Programación en tiempo de ejecución

Tilemap_Component expone los mismos datos persistentes de capa que usa el editor. Las capas se direccionan por índice empezando en cero. Eliminar una capa desplaza todos los índices posteriores una posición hacia abajo, así que no conserves un índice tras eliminar una capa a menos que lo actualices.

CSL

tilemap := entity.get_component(Tilemap_Component);
ground := tilemap.add_layer(.GROUND);

tilemap.set_layer_tint(ground, v4{0.8, 0.9, 1, 1});
grass := tilemap.add_layer_texture(ground, get_asset(Texture_Asset, "tiles/grass.png"), 1);
tilemap.set_layer_texture_scale(ground, grass, {2, 1});
tilemap.set_layer_texture_offset(ground, grass, {0.5, 0});
tilemap.set_layer_mask(ground, get_asset(Texture_Asset, "$AO/tile_mask.png"));
tilemap.set_tile(ground, 10, 12);

world_position := tilemap.tile_to_world(ground, 10, 12);
tile_x, tile_y := tilemap.world_to_tile(ground, world_position);

Las mutaciones del mapa de teselas en CSL son un estado de escena ordinario. Participan en la predicción, el rollback y la reconciliación del servidor como cualquier otro estado de juego de CSL.

C#

Tilemap_Component tilemap = Entity.GetComponent<Tilemap_Component>();
int ground = tilemap.AddLayer(TilemapLayerKind.Ground);

tilemap.SetLayerTint(ground, new Vector4(0.8f, 0.9f, 1.0f, 1.0f));
int grass = tilemap.AddLayerTexture(ground, Assets.GetAsset<Texture>("tiles/grass.png"));
tilemap.SetLayerTextureScale(ground, grass, new Vector2(2.0f, 1.0f));
tilemap.SetLayerTextureOffset(ground, grass, new Vector2(0.5f, 0.0f));
tilemap.SetLayerMask(ground, Assets.GetAsset<Texture>("$AO/tile_mask.png"));
tilemap.SetTile(ground, 10, 12);

Vector2 worldPosition = tilemap.TileToWorld(ground, 10, 12);
tilemap.WorldToTile(ground, worldPosition, out int tileX, out int tileY);

Las llamadas de C# solo mutan la simulación actual. Para un cambio en tiempo de ejecución multijugador, usa el flujo RPC existente del juego para invocar la misma mutación en cada par; la API del mapa de teselas no crea un nuevo canal de replicación.

La API de tiempo de ejecución incluye:

• Redimensionar, dimensiones de chunks/teselas y conversión de coordenadas local/mundo con conocimiento de capas.

• Agregar, eliminar y vaciar capas; tipo; modo/orden de renderizado; tinte; máscaras; contornos; ajustes de pared; y ajustes de colisión.

• Agregar, reemplazar, reponderar, eliminar y buscar texturas con peso, y escala/desplazamiento por textura.

• Operaciones individuales para consultar, establecer y borrar teselas.

Los mapas de teselas tienen al menos 2×2 chunks. Al redimensionar se conserva el centro del mapa, se desplazan las coordenadas de tesela existentes la mitad de la diferencia de tamaño y se recortan las teselas fuera de los nuevos límites. Las escrituras de teselas fuera de límites no hacen nada y las consultas devuelven false. Los pesos de textura deben ser no negativos, y cada capa admite como máximo 256 texturas.

Los índices de capa o de textura inválidos y los ajustes de capa inválidos se rechazan en el límite de la programación. La escala de textura debe ser positiva en ambos ejes. C# lanza una ArgumentOutOfRangeException (o ArgumentException para el límite de cantidad de texturas), mientras que CSL informa de un error de script que contiene el valor inválido y el rango válido.

El tinte de capa multiplica la capa completa, incluidos los contornos y las partes superiores de las paredes. Los cambios de tinte se aplican como un uniforme de renderizado y no vuelven a hornear teselas ni reconstruyen la colisión. Varios cambios de teselas y colisión realizados antes de la siguiente actualización del mapa de teselas se agrupan en una sola reconstrucción de geometría/colisión.

Modo de edición

Selecciona la entidad del mapa de teselas y haz clic en el Editar botón del inspector para entrar en el modo de edición del mapa de teselas. Haz clic en Cancelar para salir. El modo de edición se desactiva automáticamente si deseleccionas la entidad.

Mientras editas, un borde rojo delimita los límites del mapa de teselas y se dibuja una cuadrícula superpuesta en la vista de escena.

Herramientas

El editor de mapas de teselas tiene tres modos de herramienta, que se cambian mediante atajos de teclado:

Herramienta	Atajo	Descripción
Pincel	B/W	Pinta teselas haciendo clic y arrastrando.
Borrador	E	Elimina teselas haciendo clic y arrastrando.
Sello	S/R	Selecciona una región para copiarla y luego pégala en otro lugar.

También puedes mantener Shift mientras estás en modo Pincel para borrar temporalmente.

Pintura con pincel

Haz clic y arrastra para pintar teselas en la capa seleccionada. El pincel usa interpolación de línea de Bresenham entre fotogramas, de modo que nunca te saltas teselas incluso al moverte rápido.

El tamaño del pincel se ajusta con [ y ] (rango 1–32). El pincel es circular: las teselas dentro del radio se ven afectadas.

Alt+click dibuja una línea recta desde tu última posición de clic hasta la tesela actual, útil para bordes largos y rectos.

Ctrl+drag cambia al modo de relleno rectangular: arrastra para definir un rectángulo, y todas las teselas de la región se rellenan (o se borran si también mantienes Shift) cuando sueltas.

Capas

Cada mapa de teselas admite múltiples capas. Haz clic en una capa del inspector para seleccionarla y pintar. La capa seleccionada se resalta en azul.

Agregar y eliminar capas

• Haz clic en Añadir capa en la parte inferior para crear una nueva capa.

• Haz clic en Eliminar capa dentro del panel de una capa para eliminarla.

Propiedades de la capa

Propiedad	Descripción
Tipo	Suelo o Pared. Las teselas de suelo son planas; las teselas de pared se extruyen verticalmente.
Modo de capa	Predeterminado usa una organización automática de capas (suelo detrás del jugador, paredes ordenadas por Y). Manual te permite establecer un valor fijo de capa de renderizado.
Capa manual	Solo se muestra en modo Manual. El valor explícito de la capa de renderizado.
Tamaño de la tesela	Tamaño visual de cada tesela en unidades de mundo; el valor predeterminado es 1. Los agentes deben dejarlo sin cambios.
Tinte	Multiplicador de color para la capa completa, incluidas las partes superiores de las paredes y los contornos.
Texturas	Una o más texturas con pesos para variedad aleatoria, además de controles independientes de escala y desplazamiento para el patrón repetido de cada textura. El motor calcula un hash de las coordenadas de tesela para elegir determinísticamente una textura por tesela según los pesos.
Máscara	Una textura de cuadrícula 8×8 usada para el auto-encaje. Cada celda corresponde a una configuración distinta de adyacencia (bordes, esquinas, aisladas, etc.). Se incluye un mapa predeterminado $AO/tile_mask.png
Contorno	Color para los contornos de las teselas (alfa 0 = sin contorno).

Variedad de múltiples texturas

Cada capa puede tener múltiples texturas con pesos. Las teselas seleccionan determinísticamente una variante de textura basándose en un hash de sus coordenadas de cuadrícula, por lo que el patrón es estable entre guardados y no cambia cuando añades o quitas teselas.

Cada textura se muestra como una tarjeta con un selector de recurso de ancho completo y controles separados de Peso, Escala (teselas), y Desplazamiento (teselas) en filas. El peso controla con qué frecuencia aparece la textura en relación con las demás.

La escala controla el tamaño de una repetición en unidades de tesela. Por ejemplo, una escala Y de 2 hace que la textura se repita cada dos teselas apiladas verticalmente. La escala debe mantenerse positiva. El desplazamiento mueve el origen de repetición en unidades locales de tesela; un valor positivo en X o Y mueve el origen en esa dirección positiva del mapa de teselas. Estos controles afectan solo al patrón de textura, no a la geometría de las teselas, las máscaras, la colisión ni la selección de textura.

Autoencaje

Las teselas seleccionan automáticamente la celda de máscara correcta según su configuración de vecinos en 8 direcciones. El sistema:

1. Comprueba los 8 vecinos (N, NE, E, SE, S, SW, W, NW).

2. Los vecinos diagonales solo cuentan si ambos vecinos cardinales adyacentes están presentes (evita artefactos visuales en las esquinas).

3. Mapea la máscara de adyacencia resultante de 8 bits a una de 64 celdas en la textura de máscara 8×8.

Esto significa que solo necesitas pintar la presencia de teselas: los visuales correctos de borde, esquina e interior se calculan automáticamente.

Capas de pared

Establecer el tipo de una capa en Pared habilita la extrusión vertical. Las teselas de pared se colocan en la cuadrícula como las teselas de suelo, pero cada tesela colocada genera una columna de teselas de cuerpo que se extiende hacia arriba por la Altura de la pared.

Propiedades de la pared

Propiedad	Descripción
Altura de la pared	Número de teselas de altura que tiene cada columna de pared (mínimo 2).
Textura superior	Textura separada para la fila superior de la pared (la "corona"), con los mismos controles de escala y desplazamiento que las texturas del cuerpo. Su tarjeta siempre es visible en lugar de estar anidada en la sección Textures.
Máscara superior	Textura de máscara para la parte superior de la pared (usa el mismo autoencaje de 8 vecinos que el suelo).
Contorno superior	Color del contorno para las teselas superiores de la pared.

Los cuerpos de las paredes usan la textura principal de la capa. Las partes superiores usan los vecinos de la fila base, lo que mantiene limpios los bordes de la corona.

Las paredes se ordenan por Y según su fila base, así los jugadores caminan detrás de las paredes que están por encima y delante de las paredes que están por debajo.

El mapa de teselas sigue la escala X/Y de su entidad. El renderizado, la pintura y selección en la vista de escena, la conversión de coordenadas, la colisión de paredes y la entrada para la navmesh usan toda la geometría de teselas escalada. Una escala negativa refleja el mapa de teselas. Un eje con escala cero colapsa la geometría y no puede usarse para edición o conversión de mundo a tesela.

Colisión de paredes

Propiedad	Descripción
Colisión	Genera bordes de obstáculos para la reconstrucción de la navmesh.
Margen interno	Reduce hacia adentro los bordes de colisión desde los límites de las teselas para una colisión más ajustada. Los valores están en unidades de mundo locales al mapa de teselas sin escalar y siguen la escala de la entidad.
Desplazamiento	Desplaza todos los bordes de colisión en unidades de mundo locales al mapa de teselas sin escalar y luego sigue la escala de la entidad.
Dibujo de depuración	Dibuja bordes de colisión verdes en la vista de escena para depuración.

Cuando la colisión está activada, el motor construye bordes de obstáculo a partir de los límites expuestos de las teselas. Las navmeshes con reconstrucción automática activada toman esos bordes. En CSL, los bordes bloquean el movimiento solo para agentes bloqueados a una navmesh así; de lo contrario, añade colliders.

Herramienta de sello (copiar y pegar)

Pulsa S para cambiar al modo Sello. Esto habilita un flujo de trabajo de selección de región:

1. Seleccionar: haz clic y arrastra para resaltar una región rectangular. Las teselas seleccionadas se copian al portapapeles. Un mensaje emergente "Copied" confirma la acción.

2. Pegar: pulsa Ctrl+V para entrar en modo fantasma. Una vista previa translúcida del portapapeles sigue el cursor.

3. Rotar: desplaza la rueda del ratón para rotar la vista previa fantasma en incrementos de 90 grados.

4. Colocar: haz clic para estampar las teselas. Mantén Shift mientras haces clic para colocar varias copias sin salir del modo fantasma.

5. Cancelar: pulsa Escape para salir del modo fantasma sin colocar nada.

Mantén Ctrl mientras empiezas una selección de sello para copiar teselas de todas las capas a la vez, conservando las estructuras multicapa.

Resumen de atajos de teclado

Atajo	Acción
B o W	Cambiar a la herramienta Pincel
E	Cambiar a la herramienta Borrador
S o R	Cambiar a la herramienta Sello
Shift (mantenido)	Borra temporalmente mientras estás en modo Pincel
[ / ]	Disminuir / aumentar el tamaño del pincel
Ctrl+drag	Relleno rectangular con la herramienta Pincel o Borrador activa
Alt+click	Dibujar una línea recta desde el último clic
Ctrl+V	Entrar en modo pegar/fantasma
Rueda de desplazamiento	Rotar la vista previa fantasma (en modo fantasma)
Shift+click	Colocar varias copias (en modo fantasma)
Escape	Cancelar el modo fantasma