Skip to content

About

Godot 4 shader and demo for reducing texture repetition with stochastic hex tiling and triplanar projection.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Hex Detiling for Godot

Break up repeated rock, dirt, sand, and other organic textures across large 3D surfaces. This Godot 4 shader uses stochastic hex-style tiling and world-space triplanar projection, with shared offsets and optional rotation for albedo, normal, and roughness maps.

The demo includes 19 CC0 source material sets. Browse the source albedo previews; these are textures, not shader renders. The original 17-material render comparison remains a historical matched test. Brick 4 is the qualified brick-palette preset; the two new brick sources are documented authoring examples with palette controls disabled.

A loop alternating between regular tiling and hex detiling on the same rock surface

The loop alternates two actual captures of the same terrain, camera, lights, and material settings. Detiling reduces the obvious repeating marks, but also changes contrast and costs more sampling work. It is not a one-click fix for every texture.

Prepared Brick 4 color variation

The opt-in palette mode varies actual brick interiors using source-aligned variants. In the accepted distant tests, source-repeat color correlation fell 56.7% / 59.2%, while inspected mortar stayed aligned and sharp. Joint shapes, weathering and some protected rims still repeat. The accepted 4×4 atlas requires about 85.3 MiB of theoretical uncompressed RGBA8 texels including mipmaps. Smaller 2×2/3×3 trials missed at least one quality check, so they did not replace the default.

Original Brick 4 left; accepted palette variation right, matched native crops

Start with Brick 4 → Mesh: Wall → Preserve pattern → Protect mortar → Vary individual brick colors. This mode uses aligned original normal/roughness maps; near interiors deliberately differ from coherent donor mixtures. Settings, failed compact trials, measured rendering costs, material examples and limits include the unfavorable distant-wall cost as well as the improvements. Corner and curved triplanar layouts are not guaranteed to form continuous brick courses.

Optional coherent material blending

The new coherent material mode uses color brightness and normal relief to guide one blend shared by albedo, normal slopes, and roughness. The existing shared-weight mode already keeps map weights aligned; coherent mode adds content guidance and optional relaxation as the pixel footprint grows. It is an opt-in experiment, with the original shared mode still the default.

Matched moving-camera views of shared, paper-inspired, and coherent material blending

The camera loop and 17-material comparison use matched settings across modes. Changes are often subtle. Structured brick, plank, and tile layouts still break, and distant relaxation can soften texture. The detailed evidence includes synthetic channel-alignment and footprint checks; these do not establish general visual or temporal superiority.

Optional pattern preservation

Enable Preserve pattern in the demo for Brick 4, Dark Wooden Planks, or Checkered Pavement Tiles to try source-specific constrained translations. This opt-in setting ignores rotation and works independently of the blend selector. It uses approximate motif periods, so irregular mortar, plank seams, and wrapped source boundaries can still misalign. It does not recognize patterns automatically or enforce a global layout around triplanar corners. The matched comparisons show checker grids and long plank seams retained more clearly than unconstrained offsets, while brick joints still soften or double. Periodic sampling remains the most faithful to the original layout. See settings, measured presets, and evidence.

Brick 4 now offers a separate Protect mortar option after enabling Preserve pattern. It anchors masked mortar to the original source and permits variation only in safe source and donor interiors, using common coherent weights. It returns to original sampling at coarse footprints. This retains the repeating mortar layout, restricts interior variation, and adds texture reads; it depends on a source-aligned mask. The native comparison below shows periodic, existing structured, and guarded brick sampling. See matched native crops, mask provenance, checks and cost. The demo packs the guard into albedo alpha, reducing full PBR worst-case source-level reads from 48 to 36; exact source-only cases avoid donor sampling. The separate-mask API remains supported. See packing requirements and optimization measurements and motion; read counts are not timing estimates.

Historical native comparison: periodic, structured and mortar-guarded brick.

Earlier unguarded brick, wood and paving comparisons.

The earlier macro-tone experiment remains clearly experimental; it did not adequately remove the repeated colored patches.

Try the demo

  1. Open project.godot in Godot 4 and allow the textures to import.
  2. Press F5 to run. Press Space or click the button to toggle the effect.
  3. For bricks, choose Brick 4 and Mesh: Wall; enable Preserve pattern, Protect mortar and Vary individual brick colors. The palette option is validated for Brick 4; Red Brick and Large Red Bricks remain disabled authoring examples.
  4. Choose among 19 source sets and Terrain, Wall, Box/corner or Cylinder. Press 1, 2 or 3 for framed views; drag to rotate and use the wheel over the surface to zoom. The controls scroll in smaller windows. Organic surfaces retain the shared, paper-inspired and coherent comparison modes.

Tested with Godot 4.7.2, Compatibility renderer, on macOS. Other versions and hardware need testing. From a terminal, run godot --path . --editor --quit to import, then godot --path ..

Front: regular Front: detiled
Front view with ordinary tiling Front view with detiling
Oblique: regular Oblique: detiled
Oblique view with ordinary tiling Oblique view with detiling
Elevated: regular Elevated: detiled
Elevated view with ordinary tiling Elevated view with detiling

A second material

The following captures use Sandstone Cracks, with rotation at 0.75, blend contrast at 0.65, and roughness-map sampling enabled. The left and right images use the same camera and material settings apart from the detiling toggle.

Regular Detiled
Sandstone with regular tiling Sandstone with detiling

Material and mesh gallery

These GPU captures compare the same camera, lighting, mesh, and material settings with detiling off and on. All four use rotation strength 0.65, blend contrast 0.65, and the matching roughness map. The repeat size is 1.5 m for Rocks Ground and Sandstone Cracks, and 2.5 m for Rock Boulder Cracked. Each image uses albedo, normal, and roughness maps. They are visual examples, not a proof that seams or artifacts are absent under every light or viewing distance.

Material / mesh Regular tiling Detiling
Rocks Ground 04 on procedural terrain Rocks terrain, regular tiling Rocks terrain, detiled
Sandstone Cracks on a sphere Sandstone sphere, regular tiling Sandstone sphere, detiled
Rock Boulder Cracked on a vertical box Cracked rock wall, regular tiling Cracked rock wall, detiled
Rock Boulder Cracked on a sphere Cracked rock sphere, regular tiling Cracked rock sphere, detiled

The cracked-rock wall makes the regular grid especially easy to see; the detiled version breaks it up, but changes and softens some detail. The sandstone sphere has less prominent repetition to begin with, so the difference is subtler. These are three rock or sandstone materials; they do not establish performance on wood, brick, or strongly directional textures. Sphere and box examples are controlled primitive meshes, not scans or detailed production assets.

Wider material stress test

These examples use six additional CC0 materials on a vertical box, terrain, or sphere. Each row holds the camera, lighting, maps, roughness sampling, and blend contrast (0.65) fixed. The middle column enables detiling with rotation 0; the last uses rotation 0.65. Texture repeat size is 2.5 m for brick, wood, paving, and cobblestone and 1.5 m for grass and denim. Images were captured in Godot 4.7.2 Compatibility on Apple M5.

Material / mesh Regular tiling Detiled, no rotation Detiled, rotation 0.65
Brick / box Regular brick Brick with offsets Brick with offsets and rotation
Wood planks / box Regular wood Wood with offsets Wood with offsets and rotation
Grass / terrain Regular grass Grass with offsets Grass with offsets and rotation
Denim / sphere Regular denim Denim with offsets Denim with offsets and rotation
Checkered paving / box Regular paving Paving with offsets Paving with offsets and rotation
Cobblestone / terrain Regular cobblestone Cobblestone with offsets Cobblestone with offsets and rotation

Comparing blend modes

Paper-inspired weighting is optional and off by default. The following images compare it with the existing shared-weight mode, using the same textures, rotation (0.65), roughness maps, lighting, and camera. Paper mode uses falloff 0.6 and normal blend contrast 0.5; both modes use color blend contrast 0.65. See the six *-paper.jpg images in docs/variety for the rest of the set.

Cobblestone and brick comparing shared weights with paper-inspired weights

Differences in these renders are modest, and the paper-inspired mode does not repair the broken brick pattern. Separate per-map weights can also change the alignment of blended features, even though the cell transforms are shared. Choose the mode by comparing your own material; these examples do not establish that either is universally better.

What to look for: The stochastic sampling disrupts the regular mortar lines, planks, and checkerboard; rotation makes that especially obvious. Turning rotation off preserves orientation but random offsets can still break alignment. These are failure cases for architecture that must retain its pattern, not examples of a seamless structural fix. Grass, denim, and irregular stone are less constrained, although blending can still soften details or create patches. The terrain, sphere, and box are controlled examples; results will vary with scale, lighting, source textures, and geometry.

Add it to your project

Copy the entire addons/hex_detile folder to your project's addons folder, including coherent_blend.gdshaderinc alongside hex_detile.gdshader. Create a ShaderMaterial, select hex_detile.gdshader, and assign a repeatable albedo map and its matching OpenGL-style normal map. Enable mipmaps on both textures in the Godot Import dock. Set texture_scale_m to control the world-space repeat size, and tune the other controls in the inspector. Optionally enable Hex Detiling under Project Settings → Plugins. Select one MeshInstance3D without a material override and use the dock to create a ShaderMaterial; assign its textures and tune its parameters in the Inspector. The action is undoable and will not replace an existing override. The shader also works without enabling the plugin.

The shader is a complete spatial material. To use it in an existing custom material, integrate its sampling functions and fragment logic into that shader. The material uses constant roughness by default; enable use_roughness_map and assign a matching map to use texture roughness. Height maps are not sampled.

Control Purpose
detile_enabled Compare stochastic and ordinary periodic sampling.
texture_scale_m Size of one repeat in world units, normally meters.
variation_seed Choose a different deterministic cell-offset and rotation pattern; 0 preserves the original pattern. Matching maps share the seed. Duplicate the material to give different surfaces different seeds.
rotation_strength Rotate cell samples; zero preserves the source orientation. Ignored while structure_enabled is on.
structure_enabled Constrain cell transforms to a source-specific lattice and force identity rotation. Off by default; independent of blending.
structure_guard_enabled, structure_guard_map Optional source-mask protection, active only with structure and detiling. Black retains original material; white permits safe donor variation. Missing mask defaults black. Overrides the blend selector with coherent common weights; off by default.
structure_guard_in_albedo_alpha Read the linear guard from albedo alpha instead of the separate mask; requires matching mask/albedo dimensions and safe RGBA import settings. Off by default.
brick_individual_enabled, brick_individual_map Optional prepared brick palette mode with aligned original PBR; requires detiling, structure and guard. Off by default.
brick_individual_tiles_per_axis Atlas source-tile count; defaults to 4. UVs, gradients and integer offsets use this count. Each tile retains native source resolution.
brick_individual_stochastic Mix source-aligned color variants; defaults true. False directly repeats the finite atlas as a comparison.
structure_period Source-UV X/Y translation steps; zero locks that coordinate. Default (1,1) gives no meaningful variation with zero stagger.
structure_stagger Fraction of the X step added per Y step, e.g. 0.5 for a matching running-bond lattice. Default zero.
blend_contrast Adjust the color and roughness weight curve (and normals in shared-weight mode); 0.5 is neutral. Higher values may reveal the lattice.
paper_blend Enable separate luminance-weighted color/roughness and slope-weighted normal blending. Off by default; ignored when coherent_blend is enabled.
coherent_blend Use one content-guided mixture for color, normal slopes, and roughness. Off by default; takes precedence over paper_blend.
coherent_filter Relax coherent blend sharpness and content guidance as footprint grows. On by default; used only in coherent mode. This heuristic can soften texture.
paper_falloff Controls content influence in paper and coherent modes; default 0.6.
normal_blend_contrast Weight curve for normal samples in paper mode; 0.5 is neutral. Ignored in coherent mode.
use_roughness_map, roughness_map Enable and assign a matching roughness texture.
detile_blend_power Sharpen the blend between offset samples.
detile_detrend Adjust color tone normalization; zero disables it.
detile_detrend_lod Normalization blur level relative to a 512-pixel map; scales with texture dimensions.
normal_strength, roughness Surface appearance controls. In coherent mode normal_strength also controls the normal cue in the shared mixture.

How it works and when to use it

The shader samples three randomly offset copies of a repeatable texture on a triangular lattice, blends them, and projects the result along three world axes. The material maps share cell offsets and rotations. In the default mode they also share geometric blend weights; optional paper-inspired weighting calculates weights separately for color, roughness, and normals, which can shift how corresponding features blend. Optional rotation transforms texture derivatives for mip selection and rotates sampled normal components back into projection space. Rotation is off by default; directional textures may work better without it. blend_contrast changes the blend-weight curve to retain more definition, but high values can expose the grid; it does not guarantee contrast preservation. Optional tone normalization can reduce broad patches but can change color or suppress features; it defaults to off. World-space projection means moving or rotating an object moves it through the texture. In paper-inspired mode, color and roughness weights use sample luminance; normal samples are converted to slopes, weighted by slope magnitude, and blended before normal reconstruction. The implementation reconstructs normal Z from XY and caps grazing slopes for stability. This adapts the paper to the triplanar material; it is not a complete or exact reproduction. Normal mapping remains an approximation based on the geometric normal and sampled tangent components, not a general substitute for a mesh's tangent-space material.

Large organic surfaces are a useful starting point. Strong, recognizable features can still repeat or form patches. Triplanar projection, multiple texture samples, and normalization add GPU work; legacy detiling keeps sampling its donors, while protected and palette routes can skip donor work in their exact or coarse fallback cases. Source-level counts are not runtime cost estimates. See the benchmark and its limitations, and profile on your target hardware.

Research and experiments

The experiments notes describe later texture-blending research and an exploratory two-band prototype that did not demonstrate a clear improvement on the current material set. The supported shader retains the existing modes and adds an optional project-specific synthesis, with no research-novelty claim.

Project checks

After importing assets, run godot --headless --path . --script res://tests/smoke.gd to check scene loading, texture binding, and the sampling toggle. On a machine with a graphics display, godot --path . --script res://tests/gpu_probe.gd checks that a flat normal map leaves lighting unchanged at full rotation. Run godot --path . --script res://tests/capture.gd to regenerate the initial stills, or godot --path . --script res://tests/material_gallery.gd for the paired material and mesh gallery in docs/gallery/. Run godot --path . --script res://tests/variety_gallery.gd to regenerate the six-material stress test in docs/variety/. Run the coherent GPU fixtures and capture scripts for the new mode. These checks do not establish correctness for every normal map or renderer.

Credits and license

Adapted from the author's chain-racing material and cliff study. Based on Morten S. Mikkelsen's Practical Real-Time Hex-Tiling, JCGT, 2022. This adaptation includes optional cell rotation, blend-weight curves, and a paper-inspired mode for luminance- and slope-based weighting; it also offers a separate multiplicative color normalization. It is not a verbatim implementation of every technique in the paper. See third-party notices for the original Godot reference and its license.

Code and documentation: MIT License. The example texture sets are Rocks Ground 04 and Sandstone Cracks, by Rob Tuytel / Poly Haven, plus Rock Boulder Cracked, photography by Dimitrios Savva and processing by Dario Barresi / Poly Haven. All are CC0. The sandstone and boulder maps were resized to 1024 pixels for this demo. Screenshots depict those textures. Godot is distributed separately under its own license.

Additional gallery maps are from Poly Haven under CC0: Brick 4 and Denim Fabric by Rob Tuytel; Dark Wooden Planks and Checkered Pavement Tiles by Amal Kumar; Grass Ground by Charlotte Baglioni; and Cobblestone 01 by Rob Tuytel. The 1K maps and their source URLs and checksums are listed in SOURCES.json.

The eight-material expansion adds Snow 02, Brown Mud 02, Brown Leather, and Mossy Rock by Rob Tuytel; Blue Plaster Wall by Dimitrios Savva; Sand 03 by Charlotte Baglioni; and Rubber Tiles and Terrazzo Tiles by Amal Kumar, all Poly Haven / CC0. Matching original 1K albedo, OpenGL normal, and roughness maps have verified download hashes in SOURCES.json; preparation notes explain the selection and imports.

The prepared-source extension adds Red Brick and Large Red Bricks, both by Rob Tuytel / Poly Haven under CC0. Their native PBR/height downloads, authored mask exclusions and failed palette qualification results are documented in source provenance. They remain controlled authoring examples rather than fully qualified palette presets.

About

Godot 4 shader and demo for reducing texture repetition with stochastic hex tiling and triplanar projection.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages