redot-engine Documentation

Technical Documentation: Redot-Engine/redot-engine

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

Redot Engine

2D and 3D cross-platform game engine Copy Chapter

Redot Engine is a feature-packed, cross-platform
game engine to create 2D and 3D games from a unified interface. It provides a
comprehensive set of common tools, so that
users can focus on making games without having to reinvent the wheel. Games can
be exported with one click to a number of platforms, including the major desktop
platforms (Linux, macOS, Windows), mobile platforms (Android, iOS), as well as
Web-based platforms and consoles.

Free, open source and community-driven Copy Chapter

Redot is a completely free and open source fork of Godot under the very permissive MIT license.
No strings attached, no royalties, nothing. The users' games are theirs, down
to the last line of engine code. Redot's development is fully independent and truly
community-driven, empowering users to help shape their engine to match their
expectations.

Before being open sourced in February 2014,
Godot had been developed by Juan Linietsky and
Ariel Manzur (both still maintaining Godot)
for several years as an in-house engine, used to publish several work-for-hire
titles.

Redot was forked from Godot in September 2024,
intending to improve upon Godot in order to fulfill its potential and contribute to the shared
codebase of both through a more genuinely community-driven model than Godot.

Kaetram - 2D Pixel Cross-Platform MMORPG by Keros

Getting the engine Copy Chapter

Binary downloads Copy Section

Official binaries for the Redot editor and the export templates can be found
on the Redot website and on the GitHub page.

Compiling from source Copy Section

See the official docs
for compilation instructions for every supported platform.

Using Nix (recommended)

If you have the Nix package manager installed, you can build and run the editor in one command:

nix run .

This will automatically install all build dependencies and compile Redot if the binary doesn't exist.

Detailed Nix usage, including passing SCons build flags through nix run, forwarding runtime arguments, and manual nix develop workflows, is documented in the Nix usage guide at doc/nix.md.

Community and contributing Copy Chapter

Redot is not only an engine but an ever-growing community of users and engine
developers. Please visit our Discord server!

To get started contributing to the project, see the contributing guide.
This document also includes guidelines for reporting bugs.

Follow Redot on X/Twitter!

Documentation and demos Copy Chapter

The class reference is accessible from the Redot editor.

AI Integration - Model Context Protocol (MCP) Copy Chapter

Redot supports AI integration using MCP. See the setup instructions.

Doc Mcp Integration (`doc/mcp-integration.md`) Copy Section

AI Integration (Model Context Protocol) Copy Chapter

Redot includes a native MCP (Model Context Protocol) server, allowing AI coding assistants (like OpenCode, Claude Desktop, Cursor, or Zed) to interact directly with your game project.

Tools Overview Copy Section

The MCP server provides 5 master controllers:

• redot_scene_action: Manage .tscn files (add nodes, set properties, instance scenes, and wire signals with automatic callback generation).
• redot_resource_action: Manage .tres files and assets (create/modify materials, themes, inspect .import metadata).
• redot_code_intel: Deep script analysis (GDScript syntax validation, symbol extraction, and engine documentation lookup).
• redot_project_config: Project-level control (configure Input Map, Autoloads, run/stop the game, read logs, and res:// I/O).
• redot_game_control: Vision & Interaction (capture screenshots, click UI elements with high-precision, and inspect the live scene tree recursively).

Running the MCP Server Copy Section

1. Using the compiled binary (Standard)

{
  "mcp": {
    "redot": {
      "type": "local",
      "command": [
        "/path/to/redot.editor.binary",
        "--headless",
        "--mcp-server",
        "--path",
        "/path/to/your/project"
      ],
      "enabled": true
    }
  }
}

2. Running Unit Tests

You can execute automated tests headlessly using the --run-tests flag:

./bin/redot.<platform> --headless --run-tests=res://tests/my_test.gd

Note: Your test script should have a func run(): method.

3. Using Nix (For Development)

If you are developing inside a Nix environment, use the provided wrapper to ensure all libraries are correctly linked:

1. Locate the redot-mcp.sh script in the engine root.
2. In your opencode.json or MCP client config, use:

{
  "mcp": {
    "redot": {
      "type": "local",
      "command": ["/path/to/redot-engine/redot-mcp.sh", "/path/to/your/project"],
      "enabled": true
    }
  }
}

AI Agent Best Practices Copy Section

To get the most out of Redot's MCP server, agents should follow these guidelines:

1. Scene Editing: Use redot_scene_action for all .tscn modifications. Avoid editing TSCN files as raw text to prevent breaking node UIDs and internal references.
2. Scripting: For existing .gd files, use native text editing tools (like edit) for precise logic changes. Use redot_project_config(action="create_file_res") only when creating new scripts from scratch.
3. Live Interaction: Always wait 3-5 seconds after run before attempting vision or input actions to allow the bridge to initialize.
4. Spatial Awareness: Use redot_game_control(action="inspect_live", recursive=true) to discover UI paths and their pre-calculated screen coordinates for 100% accurate clicking.
5. Debugging: Use redot_project_config(action="output") to read real-time logs and redot_code_intel(action="validate") to syntax-check fixes before running the game.
6. Script Editing Policy: The MCP tool create_file_res is restricted to creating new files. To edit existing .gd scripts, agents must use native text editing tools (like edit). This ensures precision and prevents accidental overwrites of complex logic.

Doc Nix (`doc/nix.md`) Copy Section

Nix workflow

If you have the Nix package manager installed, you can build and run the editor in one command:

nix run .

This automatically installs the required build dependencies and compiles Redot if a matching binary does not already exist.

Passing SCons build flags Copy Chapter

You can pass SCons build flags directly through nix run:

# Build with custom SCons flags, then run the editor.
nix run . -- target=editor dev_build=yes num_jobs=12

# Build a release template.
nix run . -- target=template_release production=yes

# Pass SCons build flags first, then `--`, then runtime args for the editor.
nix run . -- target=editor dev_build=yes -- --path /tmp/project

Argument handling works like this:

• The first -- is consumed by Nix.
• Arguments before the next -- are passed to scons.
• Arguments after the next -- are passed to the built Redot binary.

For a quick reminder of the wrapper syntax, run:

nix run . -- --help

This supports the same SCons flags documented by the build system, such as production=yes, target=template_release, module_mono_enabled=yes, precision=double, ccflags=..., and more.

The wrapper only uses a subset of those flags when deciding which existing binary can be reused: target, arch, dev_build, precision, threads, and extra_suffix. Other SCons flags such as production=yes, module_mono_enabled=yes, or custom ccflags are still forwarded to scons, but they do not change the wrapper's reuse check.

Manual builds with `nix develop` Copy Chapter

For full manual control over the build process:

# Enter the Nix development environment.
nix develop

# Build Redot (use 'macos' on macOS, 'linuxbsd' on Linux).
scons platform=linuxbsd  # or: scons platform=macos

# Example with extra build flags.
scons platform=linuxbsd target=template_release production=yes

# Run the editor - binary names can include optional suffixes.
# Examples:
#   redot.linuxbsd.editor.x86_64
#   redot.linuxbsd.editor.dev.x86_64
#   redot.linuxbsd.editor.double.x86_64
#   redot.linuxbsd.editor.x86_64.nothreads
./bin/redot.<platform>.<target>[.dev][.double].<arch>[.nothreads][.<extra_suffix>]

Notes Copy Chapter

• nix run . only auto-builds when the expected binary for the wrapper-managed naming fields does not exist yet.
• If you want to rebuild with different flags after a binary was already produced, remove the existing binary first or use nix develop and run scons manually.
• The flake app automatically detects your platform and architecture, and arch=auto resolves to the host architecture.
• Nix works on Linux and macOS, and is available at nixos.org/download.html.

--- METRICS ---

• Files Extracted: 3
• Estimated Token Budget: ~2406 tokens
• Canonical Reference: https://codewiki.google/github.com/Redot-Engine/redot-engine