Matt Games

Getting Started With Matt Games

Matt Games is a lightweight open-source framework built on top of Godot 4 for creating 2D platformers and sidescrollers. It gives you a pre-built component system, sprite animation state machine, and built-in level pipeline instead of starting from scratch every time. If you've ever watched a 5-minute tutorial that shows a working game and then spent three weeks figuring out why your character phases through walls, this tool exists for that reason. The core selling point is the scene-graph setup: you drop a PlayerController node into your project and immediately have gravity, double-jump, coyote time, and wall-slide wired up. The animation state machine handles input buffering so you don't have to write your own velocity math for jumps or ladders. Most people install it because they want to prototype a level in an afternoon, not spend two months learning how Godot's physics layers work before shipping anything. The community is small but responsive. There's no corporate backing, no enterprise support tier, and the documentation is mostly GitHub READMEs and YouTube walkthroughs from the creator. That said, the code is readable enough that you can trace most bugs by yourself if you know basic GDScript.

How the Pipeline Actually Works

When you drop Matt Games into a new Godot 4 project, the first thing you need to do is point the project settings at your asset folders. The framework expects sprites, sounds, and level data in specific directories. If your paths are wrong, you'll spend an hour debugging a missing texture error that turns out to just be a folder naming mismatch. I learned this the hard way on my first project. The error message points to a null reference in the animation loader, which makes you think the problem is in the code when it's actually just that your sprites folder is called textures instead of sprites. Level creation works through a tilemap layer system. You paint your level in Godot's tileset editor, save it, and the Matt Games level loader reads the metadata tags to spawn enemies, hazards, and collectibles at the right positions. The metadata tags are optional, which means the game runs fine even if you forget them, but nothing will happen. I once shipped a prototype with zero enemy spawning because I didn't add the tag to a single tile. Took me four hours to figure out why my boss room was empty. The state machine is probably the trickiest part. Each character entity gets a GameState node that handles transitions between idle, run, jump, fall, hurt, and death. You can override individual states by subclassing, which is powerful but easy to mess up. When you override on_land() or on_jump() and accidentally call the parent function twice, you'll get a physics desync where the character either tunnels through the floor or gets stuck mid-air. I fixed this by adding a debug print to every state transition during development, which caught the double-call issue immediately. It's a bit verbose but it saved me from pulling my hair out.

What You Need to Know Before Starting

Matt Games assumes you already know how Godot 4 works. It doesn't teach you scenes, signals, or nodes. If you've never used a game engine before, you'll hit a wall within the first day that has nothing to do with Matt Games itself and everything to do with not understanding how autoloads work. The framework uses an autoload singleton for global state like score, level progress, and pause menu toggles. Messing with that singleton incorrectly will break your entire save system. The physics implementation relies heavily on Godot's built-in CharacterBody2D. This is both a strength and a limitation. It means your collisions are solid and your movement feels predictable, but it also means you can't easily do custom physics like momentum-based movement or ragdoll responses without rewriting significant portions of the core code. If you're building a standard Mario-style platformer, this is fine. If you want something more experimental, you'll fight the framework. One counter-intuitive thing about Matt Games is that the built-in animation system can actually slow you down if you rely on it too much. The state machine is rigid by design, and adding custom animations that don't fit the predefined states requires modifying the controller script itself. I spent a weekend trying to implement a dash animation that combined horizontal and vertical movement, and ended up just bypassing the animation handler entirely and writing a custom tween. It took twenty minutes. That's the pattern you'll see a lot: the framework is good enough for 80% of tasks, but the remaining 20% requires you to stop using it and write your own code.

Where Matt Games Falls Apart

There are real limitations worth knowing before you commit. The multiplayer implementation is essentially nonexistent. You can add network sync yourself but there's no template or example to follow. If you need cooperative or competitive multiplayer out of the box, you'll need a different engine. The mobile export path works but requires manual tweaking of touch controls. The default input map is keyboard and mouse only, and the touch overlay isn't configurable through the UI. You'll edit XML config files directly to remap buttons for a phone build. Performance is generally good for small-to-medium projects, but the sprite batching isn't optimized for large numbers of on-screen entities. I ran into a framerate drop when I had over 150 animated sprites on screen in a single level, which forced me to disable background animations and reduce the particle count. For a mobile device, expect the frame rate to dip below 30fps once you push past that threshold. The biggest practical bottleneck is the lack of a visual debugging tool. When your collision shapes don't align with your sprites, you're troubleshooting entirely through trial and error. There's no built-in collision visualization the way you'd get in a full engine like Unity or Unreal. I solved this by writing a quick GDScript that renders collision outlines in red during play mode, which cut my debugging time down significantly. It's a five-minute script but it's not included in the framework.

Practical Steps to Get Your First Game Running

Download the latest release from the Matt Games GitHub repository and extract it into a new Godot 4 project. Open the project.godot file that comes with the template and click run. You should see a basic character move, jump, and collide with platforms. This confirms the engine is working before you start adding your own assets. Next, replace the placeholder assets with your own sprites. Keep the same file names and directory structure until you're comfortable changing paths. The animation state machine reads sprite sheets based on convention, so renaming files early will just cause confusion. Once your characters look right, open a sample level and start editing the tilemap. Add enemies by tagging the appropriate tiles and placing them in the editor. The level loader handles the rest. For audio, place your sound files in the assets/audio folder and reference them by name in the node properties. The framework supports OGG and WAV by default. MP3 support depends on your export target and Godot version, so if you need MP3 for a commercial release, test that separately.

If you run into a bug, the first place to check is the Godot output panel. The Matt Games framework doesn't use custom error messages, so the stack trace will point you to the exact line in its source code. Read the relevant script, follow the call chain, and you'll usually find the issue within an hour. The codebase is well-organized and the comments are mostly accurate, which helps more than you'd expect.

When to Choose Something Else

If your project needs advanced lighting, 3D elements, online leaderboards, or a visual scripting system, Matt Games isn't going to help you. It's a focused tool for 2D platformers and nothing else. There's nothing wrong with that, but it's worth being honest about what it can and can't do before you invest weeks into it. For what it does, it's efficient and straightforward. Just don't expect it to be a Swiss Army knife.