Skip to main content
Back to path

Welcome to a Grasp lesson

Create a free account to keep studying and create your own study path.

Lesson 5

Setting Up Your Pixel Art Game Project

Recommended resources

Hello! Welcome back to our journey into Godot.

In the last lesson, you mastered the fundamental workflow of Godot: creating, saving, and instantiating scenes. You now understand how to use scenes as blueprints to build complex game objects and levels.

This lesson focuses on a critical, foundational step: configuring project settings for a 2D pixel art game. Since your goal is to build a Metroidvania with a pixel art aesthetic, getting these settings right from the start is non-negotiable. It ensures your art looks crisp, your game scales correctly to modern monitors, and you avoid common visual artifacts. This aligns with your preference for understanding the "why" before the "how"—we'll first explore the theory of pixel art rendering before applying the settings.

1. The Challenge of Pixel Art on Modern Displays

Why do we need special settings? By default, game engines like Godot are optimized for high-resolution, smooth graphics. They use techniques like linear filtering to smooth out textures when scaled, which is the opposite of what we want for pixel art.

Pixel Perfect Rendering in Godot
This image starkly contrasts a crisp, pixel-perfect rendering (left) with a blurry, imprecise one (right). Our goal today is to ensure your project always looks like the one on the left.

The core challenge is rendering a small, fixed grid of "art pixels" onto a large, high-resolution grid of "display pixels." Mismatches in this scaling process can lead to ugly visual artifacts like blurriness or "pixel shimmer," where pixels appear to change size as they move.

To understand this challenge and the concept of "pixel perfection" more deeply, the following video provides an excellent theoretical foundation.

Pixel Perfection in Godot

Watch this segment from the video 'Pixel Perfection in Godot' by Arkade Games. It explains what pixel perfection means, why it's a challenge, and discusses common base resolutions for pixel art games.

Watch from 00:37 to 05:15. Pay close attention to: The definition of pixel perfection and how it constrains movement and rotation. The explanation of "pixel shimmer" and how it's caused by scaling. The analysis of different 16:9 base resolutions (like 256x144, 320x180, and 384x216) and their pros and cons for scaling to modern displays (720p, 1080p, 4K).

As the video explains, there is no single "correct" resolution; it's a design choice. For a Metroidvania aiming for a SNES-era feel, a resolution like 384x216 is a strong choice. It's close to the vertical resolution of those classic consoles and scales perfectly to 1080p and 4K, two of the most common monitor resolutions today. We will proceed using this as our target base resolution.

2. Configuring Godot's Project Settings

Now, let's translate this theory into practice by configuring a Godot project. All of these settings are found in Project > Project Settings.... Make sure the "Advanced Settings" toggle is enabled at the top right of the window.

Step 2.1: Texture Filtering

This is the first and most crucial step. We need to tell Godot to keep our pixels sharp, not blur them.

Setting up pixel art graphics in Godot 4

This article from GDQuest provides a clear, written explanation of texture filtering and why 'Nearest' is the correct choice for pixel art.

Read the section titled 'How to configure pixel art in Godot 4', focusing on the part about texture filtering. Note the visual comparison between 'linear' and 'nearest neighbor' filtering.

To apply this globally:

  1. Go to Project Settings.
  2. Navigate to Rendering > Textures.
  3. Change Default Texture Filter from Linear to Nearest.

This ensures that any texture you import will default to crisp, blocky scaling.

Step 2.2: Resolution, Stretch, and Scaling

This is where we tell Godot about our chosen base resolution and how to scale it up to fill the player's screen. The official Godot documentation provides the most comprehensive explanation of these settings.

Multiple resolutions - Godot Docs

The Godot documentation details all the available stretch settings. We will use it to understand the recommended setup for pixel art.

First, read the 'Base size' section to understand its role as your 'design size'. Next, skim the 'Stretch settings' section to familiarize yourself with the key properties: Stretch Mode, Stretch Aspect, and Stretch Scale Mode. Finally, read the 'Pixel art' recommendations under the 'Common use case scenarios' section carefully. This provides the exact recipe we will use.

Based on the documentation and our goal, here are the settings we'll apply under Display > Window:

  • Viewport Width / Height: Set this to your base resolution. We'll use 384 and 216. This defines your game's "canvas" size.
  • Stretch Mode: Set to viewport. This mode renders your entire game at the low base resolution (384x216) and then scales that single image up. This is key to achieving an authentic low-res look, as everything, including movement and rotation, is constrained to that low-res grid.
  • Stretch Aspect: Set to keep. This maintains your 16:9 aspect ratio, adding black bars ("pillarboxing" or "letterboxing") if the player's screen is a different shape. This prevents your art from being stretched and distorted.
  • Stretch Scale Mode: Set to integer. This feature (available since Godot 4.2) constrains scaling to whole numbers (2x, 3x, 4x, etc.). It guarantees that your pixels remain perfectly square, eliminating shimmer at the cost of sometimes having larger black bars if the window isn't a perfect multiple of your base resolution.

The alternative to viewport mode is canvas_items. The key difference is that canvas_items scales the individual 2D elements but renders the final scene at the full monitor resolution. This allows for smoother movement and rotation, as well as high-res UI or particle effects, but it breaks the "pixel perfect" constraints. For an authentic retro Metroidvania, viewport is the preferred choice.

Test your understanding!

Imagine you have a sprite that is rotating.

  1. In viewport stretch mode, how will the rotation look?
  2. In canvas_items stretch mode, how will it look?
  3. Why is there a difference?
Show answer
  1. In viewport mode, the rotation will look chunky and "stepped." The sprite will snap to the low-resolution pixel grid as it rotates.
  2. In canvas_items mode, the rotation will look smooth, using the full resolution of the monitor to anti-alias the edges of the rotating sprite.
  3. The difference is because viewport mode renders the entire game scene to a low-resolution buffer (e.g., 384x216) first, then scales that final image up. All calculations, including rotation, happen within that low-res constraint. In contrast, canvas_items mode upscales the assets but performs rendering calculations in the high-resolution space of the final window, allowing for "sub-pixel" rotation and positioning.

Step 2.3: Snapping to the Pixel Grid

Our final setting ensures that node positions are always aligned to the pixel grid, preventing the sub-pixel movement that causes shimmer.

  1. Go to Project Settings.
  2. Navigate to Rendering > 2D.
  3. Enable Snap 2D Transforms to Pixel.

Do not enable "Snap 2D Vertices to Pixel." As the Arkade Games video mentions, this is for niche use cases and can cause unwanted visual distortions by moving the corners of your sprites independently. Snap 2D Transforms to Pixel snaps the entire object (Node2D or Control) position, which is what we want.

3. Putting It All Together: A Complete Walkthrough

Now that you understand the individual components, let's watch a complete walkthrough that applies all these settings in the correct order.

Pixel Perfection in Godot

Let's return to the 'Pixel Perfection in Godot' video. This segment demonstrates the entire setup process we just discussed.

Watch from 05:15 to 09:58. Follow along in your own empty Godot project and apply these settings: Set the Default Texture Filter to Nearest. Set the Viewport Width/Height and Window Overrides. Set the Stretch Mode to viewport. Enable Snap 2D Transforms to Pixel. The video also includes a valuable tip about setting a camera's 'Process Priority' to a higher number to fix jitter, which is a good note for the future.

Here is a summary table of the recommended settings for your project:

Category Setting Value Reason
Rendering > Textures Default Texture Filter Nearest Keeps pixel art crisp and sharp, preventing blurriness.
Display > Window Viewport Width / Height 384 / 216 Sets the low-resolution canvas for a SNES-like feel.
Display > Window Stretch Mode viewport Renders at low resolution first for an authentic retro look.
Display > Window Stretch Aspect keep Maintains the 16:9 aspect ratio, adding black bars to prevent distortion.
Display > Window Stretch Scale Mode integer Guarantees perfect square pixels by using only whole-number scaling.
Rendering > 2D Snap 2D Transforms to Pixel On Snaps object movement to the pixel grid, preventing shimmer.

Conclusion

You have now configured your project with a robust foundation for creating a professional-looking pixel art game. This initial setup saves immense headaches down the line and ensures your visual presentation is consistent and intentional.

Key Takeaways:

  • Pixel art requires specific project settings to counteract the engine's default high-res, anti-aliased behavior.
  • The core settings are: Nearest filtering for crisp textures, a low base resolution (e.g., 384x216), viewport stretch mode for authentic low-res rendering, and transform snapping for pixel-perfect movement.
  • Using integer scaling is a modern feature that solves the age-old problem of pixel distortion on non-integer-multiple screen sizes.

In our next lesson, we will build upon this setup by focusing on organizing your project files using a scalable folder structure. With your project settings configured, the next logical step is to create a clean, maintainable directory layout before we start adding assets, scripts, and scenes for your Metroidvania.