grit README

项目的 README,来自 github.com/DasDarki/grit。合并为一个 markdown 文件:README.md。

[!IMPORTANT] Since the 09.11.2026 video by Gamefromscratch was released, this project has received a bit more attention again. A small piece of information regarding the apparent standstill from the outside: the project is not dead. There’s simply not much more to do. Currently, it mainly needs a lot of testing. And testing takes a lot of time, which I don’t have due to my private life. If Godot 4.8 is released, I will of course make sure to make Grit compatible. If you have any questions or find any bugs, or if you can help with testing or find bugs or problems there, please open an issue.

Grit logo

Grit

Ahead-of-time compilation of GDScript to native code for Godot 4.7

[!WARNING] Grit is highly experimental. It needs a patched engine, custom export templates and has so far only been tested on Linux x86_64 and Windows x86_64. Expect rough edges, do not ship games with it yet and always keep a way to fall back to the regular GDScript VM.

What is Grit?

Grit is a Godot engine module that turns the GDScript of your project into C++ when you export it. That C++ is compiled into your export template, so the game runs the same scripts as native machine code instead of bytecode.

Nothing changes in the editor: you write, run and debug GDScript exactly as before. Native code only exists in the exported game, and every function Grit cannot handle keeps running in the GDScript VM.

Features

How it works

  1. Engine patch. A small patch to the GDScript module (see patches/) adds a hook to GDScriptFunction::call that can jump into native code and lets Grit plug in its own code generator.
  2. Recording at export. When you export, Grit recompiles every .gd file of the project and every script embedded in a scene or resource. Its code generator forwards everything to the normal bytecode generator and records the same instructions into an intermediate representation. The recording mirrors the VM decisions exactly, which is how the semantics carry over.
  3. C++ generation. The emitter turns that representation into C++ and writes it to .godot/grit/generated.
  4. Template build. The generated C++ is compiled into a custom export template through the regular Godot build.
  5. Attaching at runtime. The exported game still loads and compiles its scripts as usual. Whenever a function is compiled, Grit looks up native code for it by script, class, function name and line, checks its signature and attaches it. A fingerprint of all script sources makes sure the template and the exported project belong together.

Coroutines are compiled as native coroutines: at an await, the native code stores its variables in the engine's function state and continues natively when the signal fires.

Benchmarks

Measured with the benchmark project in tests/projects/benchmark on an AMD Ryzen 9 7950X3D, Linux, GCC 16 and a release export template. Both columns come from the same binary; the VM run uses GRIT_DISABLE=1.

Benchmark What it does VM Grit Speedup
sum_to typed integer loop 196.3 ms 4.0 ms 49.1x
collatz_steps nested loops with integer math 1155.8 ms 27.8 ms 41.6x
count_primes trial division 202.0 ms 10.3 ms 19.6x
mandelbrot floating point math 346.4 ms 9.8 ms 35.3x
particles Vector2 math with arrays 31.7 ms 7.5 ms 4.2x
count_keys untyped dictionary updates 66.6 ms 42.8 ms 1.6x
build_text string building 20.5 ms 20.2 ms 1.0x
spawn_nodes creating and freeing nodes 23.4 ms 21.6 ms 1.1x
node_properties moving and rotating 1000 nodes 65.2 ms 26.5 ms 2.5x
self_properties a node moving itself 50.6 ms 21.8 ms 2.3x

Typed, computation heavy code gains the most. Code that mostly calls into the engine, such as string building or node creation, spends its time inside Godot itself, so compiling the script changes little there.

Getting started

Clone this repository first:

git clone https://github.com/DasDarki/grit.git
cd grit

Grit builds from source. You need everything required to build Godot from source (Python 3.9+, SCons 4.0+ and a C++ compiler) plus git. A full build takes a few minutes on a modern machine. Check your system first:

python3 tools/grit.py doctor

It reports whether Python, SCons, a C++ compiler and git are present, and where the Godot source and editor are.

To type grit instead of python3 tools/grit.py, install a launcher on your PATH:

python3 tools/grit.py install

On Unix this drops a small grit script into ~/.local/bin; on Windows it writes a grit.cmd. The launcher finds a working Python itself, and the build runs SCons under that same Python, so you do not have to pick an interpreter. install --uninstall removes it again. The rest of this README uses grit; without the launcher, prefix the commands with python3 tools/grit.py.

# Clone Godot 4.7.2-stable next to this repository and apply the Grit patch.
grit setup

# Build the Godot editor with the Grit module.
grit build editor

By default the engine lives in ../godot-4.7; use --engine to pick another location, or setup --godot-repository <path> to create a worktree from an existing Godot clone. Additional SCons options can be appended to any command, for example linker=lld.

One command to a packed game

grit game path/to/project "Linux"

This is the whole flow in one step. It checks out and patches Godot and builds the editor if that has not happened yet, exports the project (which generates the native C++), builds the export template with that code, and writes a ready-to-run game plus a .tar.gz archive into build/games/<name>/. "Linux" is the name of an export preset of the project. Add --target template_debug for a debug build, --output <dir> to choose the location or --no-archive to skip the archive.

Exporting a project

If you want the pack and template separately, use export instead:

python3 tools/grit.py export path/to/project "Linux" build/game.pck
./build/game.x86_64

This exports the project with the Grit editor, which generates the C++, builds the export template with that code and places it next to the pack. Add --target template_debug for a debug build.

The export log lists every function that stays in the VM together with the reason. To compare against the VM, run the game with GRIT_DISABLE=1.

You can also export from the editor UI. The C++ is then written to res://.godot/grit/generated; build a template from it and select that binary as the custom template in your export preset:

python3 tools/grit.py build template_release --generated path/to/project/.godot/grit/generated

Settings

Setting Default Description
grit/export/enabled true Generate native code when exporting.
grit/export/generated_directory res://.godot/grit/generated Where the generated C++ is written.
grit/strip_scripts (export preset option) false Remove the bodies of natively compiled functions from the exported scripts.
GRIT_DISABLE=1 (environment) unset Run the exported game entirely in the VM.

Stripping scripts

With the export preset option grit/strip_scripts, release exports no longer ship the code of functions that run natively. Grit replaces their bodies, including inline property setters and getters, with a stub that only keeps the declaration valid, both in .gd files and in scripts embedded in scenes and resources. Class structure, members, signals, constants and function signatures stay, because the engine and other scripts still need them. Functions that stay in the VM or contain lambdas keep their bodies.

Stripping also replaces the readable res://<file>::<function>:<line> keys that map native code to scripts with short hashes, so the export template no longer reveals that map. Script paths and inner-class names can still appear where the engine needs them to load a class.

A stripped game cannot fall back to the VM. It only runs with the export template that was built together with the export: with any other template it stops at startup with an error, and GRIT_DISABLE is ignored. Debug exports are never stripped.

Testing

# Run Godot's GDScript test suite with native code.
python3 tools/grit.py conformance

# Export the benchmark project, then run it in the VM and natively and compare results and timings.
python3 tools/grit.py export tests/projects/benchmark Linux build/benchmark.pck
python3 tools/grit.py compare build/benchmark.pck

# Export with stripped scripts and compare it against the VM run of the normal export.
python3 tools/grit.py export tests/projects/benchmark "Linux Stripped" build/stripped/benchmark.pck
python3 tools/grit.py compare build/stripped/benchmark.pck --reference build/benchmark.pck

To profile a single benchmark, run the exported game with -- --only=<name> and repeat it with --repeat=<count>, for example ./build/benchmark.x86_64 --headless -- --only=node_properties --repeat=20. Exporting with extra_suffix=profile debug_symbols=yes builds a separate template with symbols for tools such as perf.

grit package <dir> copies the built editor and templates into a directory, for example to share a build with someone else.

Flappy test game

tests/projects/flappy is a small Flappy Bird clone that uses Grit the way a real game would: an inner class for the pipes, typed arrays, vector math, signals with lambda handlers and an await on a timer. It needs no assets, everything is drawn in _draw(). It ships Linux, Linux Stripped and Windows Desktop export presets, so on a Windows machine you can build it the same way with grit game tests/projects/flappy "Windows Desktop".

python3 tools/grit.py export tests/projects/flappy Linux build/flappy.pck

# Play it with space, a mouse click or touch.
./build/flappy.x86_64

# Watch the autopilot play.
./build/flappy.x86_64 -- --autoplay

# Compare the VM and native code.
python3 tools/grit.py compare build/flappy.pck

When started headless, the game lets the autopilot play 120000 physics steps with a fixed seed and prints the result and the time, which is what compare uses. The simulation currently runs about 2.5x faster natively.

Limitations

grit (DasDarki/grit)

正在搜索数据库…

323 ·GitHub
这是什么?Grit 是一个 Godot 引擎模块,在导出时把项目的 GDScript 编译成 C++,因此导出的游戏运行的是原生机器码,而不是字节码。你仍然可以像以前一样在编辑器里编写和调试 GDScript。
它是引擎、插件还是独立工具?它是一个用于打过补丁的 Godot 4.7 引擎构建版本的模块,需要配合自定义导出模板使用。原生代码只存在于导出的游戏中,编辑器仍然使用普通的 VM。
我该怎么让它运行起来?克隆仓库并从源码构建,因为 Grit 没有预编译的下载版本。运行工具使用 python3 tools/grit.py,grit install 可以把启动器添加到你的 PATH 中。之后执行一条 grit 命令,即可构建编辑器并导出带有原生代码的打包游戏。
开始之前需要先安装什么?你需要满足从源码构建 Godot 的要求:Python 3.9+、SCons 4.0+、C++ 编译器,以及 git。在现代电脑上完整构建通常需要几分钟。
它能用于正式游戏吗?不能。README 称它是“高度实验性”的项目,建议暂时不要用它发布游戏,并且务必保留回退到 GDScript VM 的方式。
它在哪些平台上测试过?开发和测试是在 Linux x86_64(使用 GCC 和 Clang)上完成的,并在 Windows x86_64(使用 MSVC)上验证过。macOS、移动端和 Web 尚未测试。
实际能快多少?类型明确、计算密集的代码提速最明显:sumto 基准测试从 196.3 毫秒降至 4.0 毫秒(快 49.1 倍)。字符串拼接和节点创建几乎没有变化,仅为 1.0 到 1.1 倍。
Grit 无法编译的函数会怎样?它们仍然在 GDScript VM 中运行。不支持的函数、被修改过的脚本或签名不匹配的函数会逐个函数回退,因此游戏的其余部分依然是原生运行的。
脚本剥离是做什么的?启用 grit/stripscripts 导出选项后,发布版构建会从随游戏附带的脚本中删除已原生编译函数的函数体。剥离后的游戏只能配合与导出一同构建的模板运行,无法回退到 VM。
这个项目还在维护吗?作者表示项目并没有停止,但仍需要大量测试;如果 Godot 4.8 发布,之后会跟进兼容性。作者希望大家通过 issues 反馈 bug 或帮忙测试。
作者
DasDarki
大小
0.8 MB
星标
323
更新
提交Nov 09
时长
1个月
提交 · 90 天