use Godot script to create a picture

undeb · November 24, 2025, 3:45pm

4.5.1

I am trying to use Godot script to create a picture, using Debian 12. Using opengl3, PNG is checker gray and white. Using xvfb-run, PNG is black. This text document is 8 KB.

Obtain Godot. From Download for Linux – Godot Engine, use the web browser firefox to download Godot_v4.5.1-stable_linux.x86_64.zip. Use the default target folder, Downloads.

Install and setup Godot.[code]

mkdir -p project/godot/4.5.1/primitive
cp Downloads/Godot_v4.5.1-stable_linux.x86_64.zip project/godot/4.5.1
cd project/godot/4.5.1
unzip Godot_v4.5.1-stable_linux.x86_64.zip
chmod +x project/godot/4.5.1/Godot_v4.5.1-stable_linux.x86_64
[/code]

test Godot

ls Downloads/Godot_v4.5.1-stable_linux.x86_64.zip
ls project/godot/4.5.1/Godot_v4.5.1-stable_linux.x86_64.zip
ls project/godot/4.5.1/Godot_v4.5.1-stable_linux.x86_64
ls .local/share/godot/
ls .local/share/godot/app_userdata
project/godot/4.5.1/Godot_v4.5.1-stable_linux.x86_64 --version

4.5.1.stable.official.f62fdbde1

Check if your system can run the headless version. Headless version is a special Godot binary that does not use graphics. If this runs and prints command-line options, your system can run Godot without GUI.

project/godot/4.5.1/Godot_v4.5.1-stable_linux.x86_64 --headless --help
[/code]

Create a small test directory and files (no graphics yet):[code]

mkdir -p project/godot/4.5.1/small
[/code]

Create these files:
Content of text file project/godot/4.5.1/small/project.godot:[application] config/name="small" config/version="0.1" run/main_scene="res://main.tscn"

Content of text file project/godot/4.5.1/small/main.tscn:[gd_scene load_steps=2 format=3] [ext_resource path="res://main.gd" type="Script" id=1] [node name="Node" type="Node"] script = ExtResource("1")

Content of text file project/godot/4.5.1/small/main.gd:extends Node func _ready(): print("Hello from Godot headless test") get_tree().quit()

Bash commands to check if files exist and are in correct place:[code]
ls project/godot/4.5.1/small/project.godot
ls project/godot/4.5.1/small/main.gd
ls project/godot/4.5.1/small/main.tscn
ls .local/share/godot/app_userdata/PrimitiveRenderer/logs/godot.log

Run small headless:[code]

project/godot/4.5.1/Godot_v4.5.1-stable_linux.x86_64 --headless --path project/godot/4.5.1/small --quit
[/code]

it prints “Hello from Godot headless test” in terminal, Godot is working correctly.

Create a directory and files (primitive graphics):[code]

mkdir -p project/godot/4.5.1/primitive
[/code]

Content of text file project/godot/4.5.1/primitive/project.godot:[application] config/name="PrimitiveRenderer" run/main_scene="res://main.tscn"

Content of text file project/godot/4.5.1/primitive/main.tscn:[code]
[gd_scene load_steps=3 format=3]

[ext_resource path=“res://main.gd” type=“Script” id=1]

[node name=“Main” type=“Node3D”]
script = ExtResource(1)

[node name=“Camera3D” type=“Camera3D” parent=“.”]
transform = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 5)

[node name=“Light” type=“DirectionalLight3D” parent=“.”]
light_energy = 1.5
[/code]

Content of text file project/godot/4.5.1/primitive/main.gd:[code]
extends Node3D

func _ready():
print(“Scene ready”)

var mesh_instance = MeshInstance3D.new()
mesh_instance.mesh = BoxMesh.new()
mesh_instance.transform.origin = Vector3(0, 0, 0)
add_child(mesh_instance)

var environment = WorldEnvironment.new()
environment.environment = Environment.new()
environment.environment.background_mode = Environment.BG_COLOR
environment.environment.background_color = Color(0.1, 0.1, 0.1)
add_child(environment)

var camera = $Camera3D
camera.current = true

await get_tree().process_frame
await get_tree().process_frame
capture_screenshot()
get_tree().quit()

func capture_screenshot():
var dir = DirAccess.open(“user://”)
if not dir.dir_exists(“renders”):
dir.make_dir(“renders”)
var image = get_viewport().get_texture().get_image()
var path = “user://renders/box.png”
image.save_png(path)
print("Saved screenshot to: ", path)
[/code]

Bash commands to check if files exist and are in correct place:[code]

ls project/godot/4.5.1/primitive/project.godot
ls project/godot/4.5.1/primitive/main.gd
ls project/godot/4.5.1/primitive/main.tscn
ls .local/share/godot/app_userdata/PrimitiveRenderer/logs/godot.log
ls .local/share/godot/app_userdata/PrimitiveRenderer/renders/box.png
cp .local/share/godot/app_userdata/PrimitiveRenderer/logs/godot.log project/godot/4.5.1/primitive
cp .local/share/godot/app_userdata/PrimitiveRenderer/renders/box.png project/godot/4.5.1/primitive
[/code]

Godot in --headless mode does not support rendering, so this will not work: project/godot/4.5.1/Godot_v4.5.1-stable_linux.x86_64 --headless --path project/godot/4.5.1/primitive --quit

This does work without warning message: Use --rendering-driver opengl3 instead of --headless. Graphic output is checker gray and white.[code]

project/godot/4.5.1/Godot_v4.5.1-stable_linux.x86_64 --rendering-driver opengl3 --quit --path project/godot/4.5.1/primitive
mkdir -p project/godot/4.5.1/primitive/opengl3
cp .local/share/godot/app_userdata/PrimitiveRenderer/logs/godot.log project/godot/4.5.1/primitive/opengl3
cp .local/share/godot/app_userdata/PrimitiveRenderer/renders/box.png project/godot/4.5.1/primitive/opengl3
[/code]

.local/share/godot/app_userdata/PrimitiveRenderer/logs/godot.log saysGodot Engine v4.5.1.stable.official.f62fdbde1 - https://godotengine.org OpenGL API 4.5 (Core Profile) Mesa 22.3.6 - Compatibility - Using Device: AMD - KABINI (, LLVM 15.0.6, DRM 2.50, 6.1.0-41-amd64) Saved screenshot to: user://renders/box.png
.local/share/godot/app_userdata/PrimitiveRenderer/renders/box.png is checker gray and white.

Another option is to use a virtual framebuffer (Xvfb). Install and use Xvfb to simulate a display environment for Godot to render in. This gives Godot a virtual display, enabling rendering. Graphic output is black.[code]

sudo apt install xvfb
ls /usr/bin/xvfb-run

As is so far, when run, this warning appears.

WARNING: XOpenIM failed
     at: DisplayServerX11 (platform/linuxbsd/x11/display_server_x11.cpp:6973)
WARNING: XCreateIC couldn't create wd.xic
     at: _create_window (platform/linuxbsd/x11/display_server_x11.cpp:6568)
Vulkan 1.3.230 - Forward+ - Using Device #0: Unknown - llvmpipe (LLVM 15.0.6, 256 bits)

Here are some ways that might fix the warning, I tried some.ibus-daemon -drx GTK_IM_MODULE=none QT_IM_MODULE=none XMODIFIERS=@none godot sudo apt install ibus ibus-gtk4 ibus-gtk3 ibus-gtk ibus-x11 sudo apt install fcitx5 fcitx5-config-qt fcitx5-frontend-gtk3 fcitx5-frontend-gtk4 fcitx5-frontend-qt5I hear the warning has no effect, so I ignore it and move on.

/usr/bin/xvfb-run -a project/godot/4.5.1/Godot_v4.5.1-stable_linux.x86_64 --quit --path project/godot/4.5.1/primitive
mkdir -p project/godot/4.5.1/primitive/xcfb
cp .local/share/godot/app_userdata/PrimitiveRenderer/logs/godot.log project/godot/4.5.1/primitive/xcfb
cp .local/share/godot/app_userdata/PrimitiveRenderer/renders/box.png project/godot/4.5.1/primitive/xcfb

.local/share/godot/app_userdata/PrimitiveRenderer/logs/godot.log saysGodot Engine v4.5.1.stable.official.f62fdbde1 - https://godotengine.org Saved screenshot to: user://renders/box.png

.local/share/godot/app_userdata/PrimitiveRenderer/renders/box.png is black.