Why pixel borders go blurry or fat
A normal TextureRect with Expand stretches every pixel, so a 2 px border becomes 6 px on a wide dialogue box and filtering blurs it. NinePatchRect solves this by cutting the texture into 9 parts: 4 corners that never stretch, 4 edges that stretch on one axis, and a center that fills the rest.
For pixel art you want corners copied 1:1, edges stretched only along their length, and no filtering. If any of those three is wrong you get the classic defects: soft borders, uneven corner sizes, or a border that looks twice as thick on large panels.
Set the project default once under Project Settings, then Rendering, Textures, Canvas Textures, Default Texture Filter to Nearest. That keeps all UI sharp unless a single CanvasItem overrides it. You can still override one portrait or background to Linear without changing the whole UI.
Draw a 9 slice safe panel texture
Make the source small and count the border pixels before you import it. A good starter is 24x24 with a 6 px safe border: 6 px corners, 12 px stretchable middle on each edge, and the same on the vertical axis.
- Create a 24x24 image with transparent background.
- Draw the outer border 2 px thick, inset by 1 px so there is a 1 px outline plus highlight. Keep corners as solid 6x6 blocks.
- Fill the center with a flat dark color. Keep the middle 12x12 area simple, it will be stretched or tiled.
- Export as PNG to
res://ui/panel_24.pngwith no scaling. Do not resize it in an image editor with smoothing.
If you draft art with Image Studio and templates workflow, generate a small square panel, then clean up the border pixels by hand and confirm the corner size. The same pixel counting habit used in the pixel sheet to SpriteFrames guide applies here: sharp pixels in, sharp pixels out.
Import settings matter as much as the drawing. Select the PNG, then in the Import dock set Compress Mode to Lossless, disable Mipmaps, set Filter to Nearest, and click Reimport. Lossy compression and mipmaps both soften 1 px details.
Set up NinePatchRect margins in Godot 4
Margins tell Godot where the cuts go. They are measured in texture pixels from each edge, not in screen pixels.
For the 24x24 panel with 6 px corners:
DialogueBox (NinePatchRect)
MarginContainer (margins: 8 left, 8 top, 8 right, 8 bottom)
Label (autowrap, custom minimum size)In the Inspector for the NinePatchRect:
| Property | Value for this panel | Reason |
|---|---|---|
| Texture | res://ui/panel_24.png | Source art |
| Patch Margin Left / Right / Top / Bottom | 6 | Matches drawn corner size |
| Draw Center | On for dialogue, Off for empty slot frame | Slot lets item icon show through |
| Axis Stretch Mode | Stretch | Tile is only for repeating patterns |
| Expand Mode | Ignore Size | Lets custom_minimum_size control layout |
| Texture Filter | Nearest | Overrides any inherited Linear filter |
patch_margin_* must equal the corner size you drew. If you drew 6 px corners and set 8 px margins, Godot stretches part of the border and the edge looks fat. If you set 4 px margins, part of the corner stretches and corners look warped.
Keep panel sizes on whole pixels when scale is 1. A 173 px wide panel forces the stretched middle to land on a fractional pixel. In containers this is normal, Nearest filtering keeps it acceptable, but avoid non integer scale such as 1.33 on the UI root.
Build the dialogue box, button, and slot
Build one panel correctly, then duplicate it for the other two. The script below creates a resizable dialogue box at runtime and shows the exact properties a hand built scene needs. Attach it to a Control root for testing, assign a Label path in your real scene, or let the demo code make its own nodes.
extends Control
const PANEL_TEX: Texture2D = preload("res://ui/panel_24.png")
@onready var dialogue: NinePatchRect = $DialogueBox
@onready var dialogue_label: Label = $DialogueBox/MarginContainer/Label
func _ready() -> void:
_configure_panel(dialogue, 6, true)
set_dialogue("The gate is locked. The guard wants 3 copper seals.")
_make_slot(Vector2(8, 120), Vector2(40, 40))
_make_button_background(Vector2(8, 172), Vector2(160, 36))
func _configure_panel(panel: NinePatchRect, margin: int, draw_center: bool) -> void:
panel.texture = PANEL_TEX
panel.patch_margin_left = margin
panel.patch_margin_right = margin
panel.patch_margin_top = margin
panel.patch_margin_bottom = margin
panel.draw_center = draw_center
panel.expand_mode = NinePatchRect.EXPAND_IGNORE_SIZE
panel.axis_stretch_mode = NinePatchRect.AXIS_STRETCH_MODE_STRETCH
panel.texture_filter = CanvasItem.TEXTURE_FILTER_NEAREST
func set_dialogue(p_text: String) -> void:
dialogue_label.text = p_text
dialogue.custom_minimum_size = Vector2(280, 80)
func _make_slot(pos: Vector2, box_size: Vector2) -> NinePatchRect:
var slot := NinePatchRect.new()
add_child(slot)
slot.position = pos
slot.size = box_size
_configure_panel(slot, 6, false)
return slot
func _make_button_background(pos: Vector2, box_size: Vector2) -> NinePatchRect:
var back := NinePatchRect.new()
add_child(back)
back.position = pos
back.size = box_size
_configure_panel(back, 6, true)
var button := Button.new()
back.add_child(button)
button.text = "Take seal"
button.set_anchors_preset(Control.PRESET_FULL_RECT)
button.flat = true
return backTo use this in the editor, create a Control with a NinePatchRect named DialogueBox, add a MarginContainer with 8 px theme constants, add a Label with Autowrap Words on, then attach the script. Run and resize DialogueBox in the editor: corners stay 6x6 texture pixels while the middle grows.
For buttons, keep the NinePatchRect as the visual and put a flat Button on top with PRESET_FULL_RECT as shown, or convert the same PNG to a StyleBoxTexture and set its content margins to 6 px on each side. Both use the same margin number. For inventory slots, reuse the same texture with draw_center off and a fixed size such as 32x32 or 40x40, then center an item TextureRect inside with Stretch Keep Centered and Nearest filter.
Fix blurry or thick borders
| Symptom | Likely cause | Fix |
|---|---|---|
| Soft or smeared border | Canvas filter Linear or import filter Linear | Set NinePatchRect Texture Filter to Nearest, reimport source as Nearest and Lossless |
| Border gets thicker on wide boxes | Patch margin larger than drawn corner | Measure corner in pixels, set all four patch_margin_* to that exact value |
| Corners stretched diagonally | Patch margin smaller than drawn corner | Increase margins until corners sit outside the stretch zone |
| Wavy 1 px lines inside panel | Panel size on fractional pixels with rotation or non integer scale | Keep UI scale at 1, 2, or 3, avoid rotating pixel UI |
| Different thickness top vs bottom | Unequal art borders with equal margins | Redraw so all four borders use the same pixel width, or set each margin to match its side |
If you ask an agent to convert your UI toNinePatchRect, treat it like a scene refactor. Commit before it starts, ask for one panel at a time, read the diff for renamed nodes and changedpatch_margin_*values, keep approvals on for deletes, then run the game at two window sizes and confirm signal connections still work. Agents often guess margins or replace aButtontheme when you only asked for a background, and the diff is where you catch it.