FyroxEngine/Fyrox · error

Missing hole mask texture

Error message

Missing hole mask texture

What it means

When painting a terrain's hole mask brush target, the terrain collects each chunk's hole_mask texture and calls expect on it, panicking if any chunk has no hole mask assigned. Invariant: using the hole-mask brush requires every chunk to have a hole mask texture.

Solutions

1. Assign a hole mask texture to every chunk before using the hole-mask brush (Chunk::set_hole_mask with a valid texture handle).
2. Iterate chunks and guard: if chunk.hole_mask().is_none(), create/assign a default mask before invoking the brush.
3. Re-save the terrain in the current editor version so the hole masks are serialized with the scene.

Example fix

// before
for chunk in terrain.chunks_ref() { /* no hole mask set */ }
brush.apply(&mut terrain, ...); // panics
// after
for mut chunk in terrain.chunks_mut() {
    if chunk.hole_mask().is_none() {
        chunk.set_hole_mask(default_mask_texture.clone());
    }
}
brush.apply(&mut terrain, ...);

if terrain.chunks_ref().iter().any(|c| c.hole_mask().is_none()) {
    // set hole masks before using BrushTarget::HoleMask
}

When it happens

Trigger: Applying a brush with BrushTarget::HoleMask while at least one terrain chunk was created without a hole_mask texture (e.g. chunks built via code or older saved scenes predating hole masks).

Common situations: Programmatically constructing Terrain chunks at runtime without assigning hole_mask; loading terrains saved by older engine versions where the field did not exist; editing hole masks in the editor after regenerating chunks.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• only rectangle textures can be used as render target!
• Invalid pixel position
• Height data type error
• Graphics context is uninitialized!
• only rectangle textures can be used as render target!

AI-assisted analysis of FyroxEngine/Fyrox@76c91aad8e (2026-09-10). Data as JSON: /api/errors/61ff34407af25061. Report an issue: GitHub.

Appendix: source

Thrown at fyrox-impl/src/scene/terrain/mod.rs:2236

            BrushTarget::LayerMask { .. } => TerrainTextureKind::Mask,
            BrushTarget::HoleMask => TerrainTextureKind::Mask,
        };
        let resources: FxHashMap<Vector2<i32>, TextureResource> = match target {
            BrushTarget::HeightMap => self
                .chunks_ref()
                .iter()
                .map(|c| (c.grid_position(), c.heightmap().clone()))
                .collect(),
            BrushTarget::HoleMask => self
                .chunks_ref()
                .iter()
                .map(|c| {
                    (
                        c.grid_position(),
                        c.hole_mask
                            .as_ref()
                            .cloned()
                            .expect("Missing hole mask texture"),
                    )
                })
                .collect(),
            BrushTarget::LayerMask { layer } => self
                .chunks_ref()
                .iter()
                .map(|c| (c.grid_position(), c.layer_masks[layer].clone()))
                .collect(),
        };
        TerrainTextureData {
            chunk_size,
            kind,
            resources,
        }
    }
    /// Modify the given BrushStroke so that it is using the given Brush and it is modifying this terrain.
    /// The BrushStroke will now hold references to the textures of this terrain for the target of the given brush,
    /// and so the stroke should not be used with other terrains until the stroke is finished.

View on GitHub (pinned to 76c91aad8e)