gd 公式マニュアル

オンラインのマニュアル・APIリファレンスはブラウザーの優先言語に合わせて英語・日本語を表示し、対象外の言語では英語を表示します。 言語ボタンまたは?lang=jaで日本語へ切り替えられ、選択は端末内に保存されます。

gdは何のための道具か

gdは、GDScriptで端末の道具、Webサイト、Web API、定期処理、データ処理を書くための単体コマンドです。 Godotを画面なしで小さく組んであり、project.godotを用意せずに.gd fileを一枚書いて実行できます。

PythonやNode.jsでscriptを書く感覚で始められ、必要になった時点で型検査、test、package、database、 Web server、単一実行体へ同じGDScriptのまま進めます。ゲームの画面や描画を作る用途にはGodot本家を使ってください。

Godot本家とあわせれば、アプリもフロントもserverも端末ツールも、一つの言語GDScriptで書けます。 同じscriptがmacOS、Linux、Windowsで動き、通信とdatabaseの待ちはほかの処理を止めません。 GDExtensionでC++と直接つながります。AI agentが書いて動かすことを前提に設計しています。

HTTP/2の多重化とノンブロッキング通信を内蔵。UTF-8・JSON・hex処理にはSIMD/SWARを活用し、接続・バッファ・解析結果の再利用で不要な処理と割当を抑えています。

導入

対応環境はmacOS arm64/x86_64、Linux x86_64、Windows x86_64です。 ReleasesからOSに合うarchiveを取得し、 中のgdをPATHの通ったdirectoryへ置きます。gd --versionが版を表示すれば導入は完了です。 配布物のSHA-256は同梱のSHA256SUMSで照合できます。macOS版はDeveloper ID署名とAppleの公証を通しています。

macOS / Linux

curl -fsSL https://gd.progsha.com/install.sh | sh

チェックサムを照合して~/.local/binへ導入します。案内が出た場合は、このdirectoryをPATHへ追加してください。Linux配布バイナリにはx86_64とglibc 2.38以降が必要です。

Windows（PowerShell）

Invoke-WebRequest -UseBasicParsing https://gd.progsha.com/install.ps1 -OutFile install-gd.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\install-gd.ps1

PowerShellで実行してください。管理者権限は不要です。SHA-256を照合し、%LOCALAPPDATA%\gd\binへgd.exeを置き、ユーザーのPATHへ追加します。新しいターミナルを開き、gd --versionで確認します。

手動の場合はReleasesからgd-windows-x86_64.zipを取得して展開し、gd.exeを置いたdirectoryをユーザーのPATHへ追加します。PowerShellでUnix用のcurl | shは実行しません。

Homebrew（macOS）

brew tap prog-sha/gd https://github.com/prog-sha/gd
brew install prog-sha/gd/gd

製品リポジトリをtapとして使い、署名済みUniversal実行体を導入します。更新はbrew update && brew upgrade prog-sha/gd/gd、削除はbrew uninstall gdです。

apt（Linux amd64）

Ubuntu 24.04、Debian 13など、glibc 2.38以降のapt対応環境で利用できます。Ubuntu 22.04やDebian 12ではsourceからbuildしてください。専用の署名鍵を、この配布元だけに適用します。

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://gd.progsha.com/apt/gd.asc | sudo tee /etc/apt/keyrings/gd.asc >/dev/null
sudo chmod 0644 /etc/apt/keyrings/gd.asc
echo 'deb [arch=amd64 signed-by=/etc/apt/keyrings/gd.asc] https://gd.progsha.com/apt stable main' | sudo tee /etc/apt/sources.list.d/gd.list
sudo apt update
sudo apt install gd

以降は通常のapt更新で新しい版を取得できます。削除はsudo apt remove gdです。HTTPSに加え、aptが配布メタデータの署名を検証します。

winget（Windows）

公式カタログへの登録申請・審査は未完了です。登録までは上記のPowerShellインストーラーを使ってください。管理者向けの申請用マニフェストを用意していますが、winget install prog-sha.gdはまだ利用できません。

sourceからbuild

sourceからbuildする場合はPython、uv、SCons、C/C++ compilerを用意し、bin/にできるgd.*.template_release.*を使います。 TLSは内蔵しているため、別のTLSライブラリは要りません。

git clone --branch 0.7 https://github.com/prog-sha/gd.git
cd gd
scons platform=macos target=template_release -j8
# Linux: platform=linuxbsd
# Windows: platform=windows windows_subsystem=console

クイックスタート

hello.gdを一枚作ります。設定fileやpackageは要りません。main()が入口で、返した整数がprocessの終了codeになります。

func main():
	print("Hello, world")
	return 0

gd hello.gd

実行せずに型と構文を調べるにはcheckを使います。

gd check hello.gd

scriptの読み込みと共通定数

ローカルfileは@import "./settings"、導入済みpackageは@import hello。読み込んだ名前をそのまま使います。.gdやas settingsは省略できます。

共有する値をsettings.gdに置きます。

const TITLE = "Hello"
const USER = "world"

main.gdから使います。

@import "./settings"

func main():
	print(settings.TITLE, ", ", settings.USER, "!")
	return 0

これでHello, world!と表示します。共有が必要になったときの書き方です。

settings.TITLEのように使えば、値ごとのconst宣言を利用側へコピーする必要はありません。1つのscriptでしか使わない値や処理は、そのscriptに置けば十分です。asは名前の衝突や読み分けが必要なときだけ使います。組み込みのGD.webなどにはimportは不要です。

packageの導入とversion固定はpackageと配布を参照してください。

用途から選ぶ

標準APIの入口はGD一つで、用途ごとの子を持ちます。scriptからはこの名前をそのまま書きます。

GD.database.postgresとGD.database.redisは、接続先固有の機能が必要なときに使う高度な入口です。

APIの調べ方

gd docに、scriptへ書く綴りをそのまま渡します。署名は実行体から作るため、実装と一致します。

gd doc                     # Show a short guide and entry points.
gd doc manual              # Read the complete manual.
gd doc GD                  # List the standard modules.
gd doc GD.file             # file API
gd doc GD.http.fetch       # Inspect the returned HTTP response.
gd doc GD.web.app          # Web application
gd doc SceneTree           # Inspect a public engine class.
gd doc all                 # List public types.

戻り型のR、Err、GDWebRequestは名前だけで引きます。Node、SceneTree、TimerなどGodot由来の型は Godotのclass referenceも参照してください。 手引きの言語はLC_ALLまたはLANGがjaで始まるとき日本語、それ以外は英語です。 Web版はgd.progsha.comにあり、日本語と英語を切り替えられます。

GDScriptの基本

掲載例では型名を繰り返しません。:=で代入する変数と、return 値, 失敗で返す成功値は型を推論します。 注釈を省いた引数は動的型です。型で境界を固定したい箇所だけ注釈を足せます。

引数とflag

script名の後ろに置いた引数はmain(argv)で受け取ります。--name=gdのようにgd自身のflagと紛らわしい引数は、 --の後ろへ置くとscriptへ渡ります。

func main(argv):
	for arg in argv:
		print(arg)
	return 0

gd main.gd apple orange
gd main.gd -- --name=gd

flagとして解釈したいときはGD.cli.flags()を使います。--name gd、--name=gd、-name=gdのどの綴りも受けます。

func main(argv):
	var flags := GD.cli.flags()
	flags.flag_str("name", "world", "挨拶する相手")
	var parsed := flags.parse(argv)
	if not parsed.ok:
		print(flags.usage())
		return 1
	print("Hello, " + flags.get_str("name"))
	return 0

外のcommandを呼ぶ

外の道具はGD.cli.run()で呼びます。待つのは呼び出したGDScriptだけなので、gd serveのhandlerの中から呼んでも他のrequestは進みます。 --strictでは--allow-runが要ります。--allow-run=/usr/bin/gitのように相手を絞れます。

func main():
	var got := GD.cli.run("git", ["rev-parse", "HEAD"])
	if not got.ok:
		return 1
	print("code=", got.v["code"], " out=", got.v["output"])
	return 0

第3引数のoptsで挙動を変えられます。

子の非ゼロ終了はErrです。終了コードはvalue.codeとe.info.code、出力はvalue.outputで確認できます。期限や取消でも取得済み出力は残ります。

開発中のcommand

gd check main.gd        # Check syntax and types without execution.
gd fmt main.gd          # Format the source consistently.
gd test                 # Discover and run *_test.gd files.
gd --watch main.gd      # Restart after each source save.
gd eval 'print(1 + 1)'  # Evaluate one expression.
gd repl                 # Start an interactive session.

値と失敗

失敗しうる関数は、例外を投げる代わりに「成功値と失敗」の二つの値を返します。 受け取る側はvar 値, e :=の形で両方を受け、eがnullでなければ失敗です。

func main():
	var text, e := GD.file.read_text("note.txt")
	if e:
		print(e.text())
		return 1
	print(text)
	return 0

失敗を短く扱う

毎回if eを書く代わりに、呼出しの末尾へ?を付けると、失敗をそのまま呼出し元へ返して成功値だけが残ります。 ?を使う関数は、自分もreturn 値, 失敗で成功値と失敗を返します。

func title(path):
	var text := GD.file.read_text(path)?
	return text.strip_edges(), null

func main():
	var text, e := title("note.txt")
	if e:
		print(e.note("題名を読む").text())
		return 1
	print(text)
	return 0

失敗を呼出し元へ渡さないmain()ではvar 値, e :=か!で受けます。

file操作の失敗ではe.infoにop、path、source、source_codeが入ります。 renameはpathの代わりにoldとnewを持ちます。sourceはposix、win32、engineのいずれかです。 NotFoundなど意味が確定した場合だけkindが付き、未知のI/O失敗はErr.NONEのまま元情報を保ちます。

失敗しても処理済みの値が残るAPIがあります。復号、クエリ解析、子プロセス、Redisの一括実行では、var value, e := call()で両方を受け取ってください。元の原因はe.cause、分類の検査はe.is(kind)で辿れます。

GD.dataのMessagePack・CBOR・TAR・TOML・YAML・XML・dotenv・front matter生成とPBKDF2は、同期・asyncとも値とErrを返します。変換できない項目を黙って省略しません。

base64_decode(text)とbase32_decode(text)は標準padding付きで復号します。paddingなしは第2引数にtrueを渡します。Base32は大文字を使います。base64url_decode(text)は既定がpaddingなしで、付きの入力は第2引数をfalseにします。同期・asyncとも失敗時の部分byte列を保持します。

GD.http.decode_query(raw)はキーごとの全値をArrayで保持し、最初のErrと返します。req.queryは先頭値、req.query_allは全値です。NULや不正UTF-8を含むキー・値はPackedByteArrayのまま保持します。encode_query()は値のArrayを同じキーで繰り返し、バイト列も扱います。parse_url()のraw_queryは元の表記です。queryを編集してURLを組み直す場合は、先にurl.erase("raw_query")で元の表記を外してください。

戻り値の規則

型を書かなくても動きます。型を書く場合と細部の規則は次の通りです。

• 戻り型は-> int, Errのように成功型一つとErrの二つです。実行時の型はRで、-> Rや省略もできます。
• カンマ戻りは必ず二値です。末尾はErr型の値か成功時のnullに限ります。文字列は末尾に直接返せないのでErr.err(reason)で包みます。
• 失敗を入れる変数はvar e: Err = ...かvar e := Err.err(...)で型を固定します。型が変わりうるvar e = ...は末尾に使えません。
• 複数のdataはreturn [1, 0.0, ""], nullのように配列や辞書一つへまとめます。return null, nullはnullを成功値として返します。
• Rの分解はvar value, e := call()の二つの名前に固定です。var a, b, c := 1, "a", 0.0のように式を並べる宣言は別物で、個数の制限はなく、各名前を対応する式から推論します。新しい名前を一つ以上含めば、その関数で見えている変数（外側のblockの変数を含む）にも代入でき、右辺は代入の前に全て評価します。定数、引数、lambdaが外から取り込んだ変数には代入できません。
• 型注釈した戻り値に, Errが無い関数で?を書くとThe "?" operator needs a function returning "R" or "Err".になります。
• -> int, Errでreturn R.ok("a")と書くとcompile errorです。型が動的なら実行時に検査します。
• 型付きのArrayやDictionaryを成功値にするときは、元のcontainerにも同じ要素型を付けます。
• 成功値と失敗を返す関数は、全ての経路でreturnします。?で伝播するだけの関数も最後にreturn null, nullを書きます。
• 戻り型を-> intのように一つだけ書いた関数には、カンマ戻りを書けません。-> int, Errと書きます。
• lambdaにはカンマ戻りを書けません。return R.ok(値)とreturn R.err(理由)を使います。

Rで持ち運ぶ

値と失敗を一つの値として持ち運びたいときはRを使います。okで成否、vで成功値、eで失敗を読みます。 R.ok(値)とR.err(理由, 種類, 部分値)で作ります。Webのhandlerやdatabaseのtransactionは、このRを返す形でも書けます。

func find(items, want):
	for item in items:
		if item == want:
			return R.ok(item)
	return R.err("not found: " + want, Err.NOT_FOUND)

func main():
	var got = find(["a", "b"], "c")
	if not got.ok:
		print(got.e.text())
		return 1
	print(got.v)
	return 0

R.ok()の成功値はnullで、intの0にはなりません。途中まで進むI/O APIは、失敗したときも完了した量を部分値としてvに残します。 note()は部分値を保ち、v_or(代替値)は失敗なら代替値を返します。 ?で伝播するとき、部分値が呼出し元の成功型に合わなければ部分値だけを捨て、失敗の理由と種類は保ちます。

待つ処理と同時実行

HTTP、database、GD.net、fileなどの待つmethodは、普通の関数呼出しとして書けます。 待つのは呼び出したGDScriptだけで、ほかの通信やtimerは進みます。

func main():
	var res := GD.http.fetch("https://example.com/")!
	print(res.status)
	return 0

複数の処理を同時に始めたいときは、末尾が_asyncの版とGD.async.all()を使います。

func main():
	var got = await GD.async.all([
		GD.http.fetch_async.bind("https://example.com/a"),
		GD.http.fetch_async.bind("https://example.com/b"),
	])
	for result in got:
		var res, e := result as R
		if e:
			print(e.text())
			return 1
		print(res.status)
	return 0

all()へはSignalよりCallableを渡してください。開始前に完了を購読するため、先に終わった結果を取りこぼしません。

:=で保存したSignalは完了時の型も保持します。異なる型や型不明のSignalへの再代入は拒否します。 実行時に型を決める場合は受け側をSignalと明示し、完了値にも必要な型を付けます（例: var result: R = await pending）。 spawn()はCPU処理を別threadへ移す機能ではありません。長いGDScriptは自動的にほかの処理へ実行権を譲りますが、 native methodの内部は中断しないため、大きな入力を標準moduleへ渡すときは_asyncの版を使います。 待つmethodを呼べるのは、GDScriptから呼ばれた関数の中だけです。Array.map()のcallback、_init()、member変数の初期化、_to_string()などのnative callbackは完了を待てません。callback内にawaitを加えても、nativeの呼出し元は結果を待ちません。非同期の初期化はmain()へ移し、非同期のmap()は非同期関数内のfor、または上のGD.async.all()へ渡すCallableで書きます。

チュートリアル: SQLiteを使うメモAPI

ここまでの知識で、JSONを受けてSQLiteへ保存する小さなAPIを一枚のscriptで作ります。 できあがるのは、入力検査とSQLのparameter bindを備え、権限を絞って起動する開発用serverです。

1. 作業directoryを作る

mkdir notes-api
cd notes-api

2. APIを書く

次をmain.gdとして保存します。

# Store notes in an embedded database and expose a JSON API.
extends RefCounted


const PORT := 18080 # Development listener port on loopback.
const DB_PATH := "user://notes.sqlite3" # Writable storage isolated per user.

var app := GD.web.app()
var db := GD.database.client()


# Return notes as JSON in newest-first order.
func list_notes(_req):
	var got := db.query("SELECT id, title FROM notes ORDER BY id DESC")?
	return GD.web.json(got.rows)


# Save a validated title and return the created row.
func add_note(req):
	var body := req.valid("body")
	var made := db.query(
		"INSERT INTO notes(title) VALUES($1) RETURNING id, title",
		[body.title]
	)?
	return GD.web.json(made.rows[0], 201)


# Prepare the database and routes, then listen on loopback.
func main():
	db.open({"driver": "sqlite", "path": DB_PATH})?
	db.query("CREATE TABLE IF NOT EXISTS notes(id INTEGER PRIMARY KEY, title TEXT NOT NULL)")?
	app.route("GET", "/notes", list_notes)
	app.route("POST", "/notes", add_note, [GD.web.json_body(GD.web.object_rule({
		"title": GD.web.text_rule({"min": 1, "max": 120}),
	}))])
	app.listen(PORT, "127.0.0.1")?
	print("listening on http://127.0.0.1:%d" % PORT)
	return 0, null

上から順に読みます。

• appはrouter、dbはdatabase接続です。main()が返った後もserverが動き続けられるよう、両方ともscriptの変数として持ちます。
• main()はまずSQLiteを開き、表を作ります。DB_PATHのuser://は、gdが利用者ごとに用意する書込み領域です。
• app.route()に、HTTP method、path、そのときに呼ぶ関数（handler）を登録します。
• handlerはGDWebRequestを受け取り、GD.web.json()で返事を作ります。途中の?は失敗をserverへ返し、状態番号500などになります。
• POSTにはGD.web.json_body()を付けています。本文がruleに合うときだけhandlerが呼ばれ、通った値がreq.valid("body")に入ります。
• SQLの値は$1へbindします。文字列連結でSQLを組み立てません。

3. 権限を絞って起動する

未確認のscriptや外へ公開するserverは、権限を既定で拒否する--strictで実行します。ここでは待受先をloopbackの一つのportに絞ります。 serveはmain()が返った後もprocessを残すcommandで、serverにはこれを使います。

gd check main.gd
gd --strict --allow-net=127.0.0.1:18080 serve main.gd

4. 別の端末から使う

curl -s -X POST http://127.0.0.1:18080/notes \
  -H 'Content-Type: application/json' \
  -d '{"title":"gdを試す"}'
curl -s http://127.0.0.1:18080/notes

最初はstatus 201と作成した一件、次は保存済みの配列が返ります。空の題名、120文字を超える題名、 JSONでない本文は400で拒否されます。止めるときは起動した端末でCtrl-Cを押します。

公開環境ではこのprocessをloopbackのままTLS reverse proxyの後ろへ置き、異常終了耐性が必要な保存先は PostgreSQLへ切り替えます。接続情報はsourceへ書かず、許可した環境変数から読みます。

権限

最初は通常実行を使います。--strictは、必要な権限を自分で設計・設定する上級者向けの実行方式です。

v0.7.3のmacOS/Linuxでは、--strictでも起動directory外の絶対pathを読めました。

--strictでは、使うものを挙げて起動します。

gd --strict \
  --mount store=/srv/app:rw \
  --allow-net=db.example.com:5432 \
  --allow-env=DATABASE_URL \
  main.gd

fileの置き場

scriptから見えるfileの置き場は次の4種類です。置き場の名前をpathの先頭に書くか、絶対pathをそのまま書きます。

• res://より上へ遡る相対pathは、どちらの方式でも拒否します。
• --strictの暗黙read範囲は起動時の作業directoryです。entry scriptが子directoryにあっても基準は変わりません。配下の絶対pathはres://と同じread-only検査を通し、親・兄弟directoryは拒否します。リンクでも外へ出られません。外部は明示的にmountし、store://などの名前で使います。-Aでもfileの範囲は広がりません。
• --mountと絶対pathはLinuxとmacOS用です。Windowsでは拒否するので、fileはres://かuser://へ置いてください。
• mount名に使えるのは小文字の英数字と-です。res、user、uid、pipe、local、libgodot、tcp、unix、http、https、file、data、cacheは予約済みで選べません。

networkとextensionの許可

• --allow-netのlocalhost:8080は、同じportのIPv4 loopback 127.0.0.0/8とIPv6 ::1も表します。
• *.example.com:443はその下位hostを許します。
• native extensionは同じprocessで動くため、信頼できるものに限ってください。

serveとSceneTree

gd serveはSceneTreeを作らない常駐用の実行方式です。通信、timer、await、自作Signal、GD.async.sleep()、 ツリー外Nodeのqueue_free()は動きます。仕事が無ければ次の期限か通信の通知まで眠るため、周期の調整は要りません。

serveではNodeを継承しただけのscriptはツリーへ追加されません。 --no-scene-treeはSceneTreeが作られた時点で診断を出し、終了code 1で止まります。--watchと--workersの子にも引き継がれます。 通常実行は暗黙にSceneTreeを作るため、この旗を付けると失敗します。

TCPとUDP

低水準の通信にはGD.netを使います。Godot本家の低水準型も互換用に残っていますが、新しいcodeはGD.netで書きます。

func echo():
	var listener := GD.net.listen_tcp("127.0.0.1", 8080)?
	var conn := listener.accept()?
	var data := conn.read(65536)?
	conn.write(data)?
	conn.close()
	return 0, null

• GDTCPConnのreadとwriteは別々の列なので、複数のGDScriptから同時に呼べます。
• 期限methodは今からの秒数を設定し、0で解除します。
• close()は未完了のread/writeをErr.INTERRUPTEDで起こします。listenerの受付待ちも同じです。
• 接続は名前解決で得たIPv4とIPv6の候補を順に試し、成功した一本だけを残します。全体のtimeoutは延びません。

TLS

TLSはGD.net.dial_tls(host, port, opts)で開きます。既定で証明書の鎖とhost名を検証し、失敗しても平文へ戻りません。 戻り値はTCPと同じGDTCPConnです。

交渉結果はconnection_state()のnegotiated_protocolとversionで読めます。TLS1.2は771、TLS1.3は772です。

信頼するCAは、未指定ならmacOSとWindowsではOSの信頼設定、Linuxではsystem CA bundleです。 起動前にSSL_CERT_FILEまたはSSL_CERT_DIRを設定すると、どのOSでも指定したCAを使います。 directoryの区切りはUnixで:、Windowsで;です。

serverがclient証明書を求めるときは、app.listen_tls(port, cert, key, host, opts)のoptsへclient_ca（信頼CA bundle）とclient_authを渡します。 client_caが未指定ならsystemの信頼設定を使います。

UDPと名前解決

GD.net.listen_udp()はGDUDPPacketConnを返します。read_from()はdata、host、port、truncatedを持つ辞書を返します。 write_to()のhostにはGD.net.resolve()で解決したIP addressを渡します。packetは結合されません。 buffer=0（既定）はOSの受信bufferをそのまま使い、正の値を指定した場合だけ変更を要求します。

GD.net.resolve()はOSが選んだ先頭のaddressを一つ返します。名前のcacheは持ちません。 GD.net.local_addresses()は機械のaddress一覧を返し、空の一覧とOSの失敗を区別します。 失敗のe.infoにはsyscall、source、source_codeが入ります。

fileとdata

GD.fileでfileの読み書きとpath操作をします。起動したdirectoryがres://で、絶対pathも書けます。 strictで外部directoryへ書くときは--mount store=/srv/app:rwで付けた名前をstore://users.csvのように書きます。

func main():
	var rows := GD.data.csv_objects(GD.file.read_text("store://users.csv")?)?
	GD.file.write_text("store://users.json", JSON.stringify(rows))?
	return 0, null

fileの操作は、通常名でも呼び出したGDScriptだけを待たせます。Web serverのhandlerから読んでも他のrequestは進みます。 複数の操作を同時に始めるときだけ、末尾が_asyncの版を使います。

func handler(_req):
	var body := GD.file.read_text("store://big.json")
	if not body.ok:
		return GD.web.text("読めません", 500)
	return GD.web.text(body.v)

compileで同梱したfileも、同じAPIで読取、列挙、static配信ができます。

大きなfileを読む

全量をmemoryへ置かず読むときはGD.file.open(path, mode)でGDFileStreamを開きます。 modeはread、write、append、read_writeで、使い終えたらclose()を呼びます。

同じstreamの操作は受付順、別のstreamは並列に進みます。appendはseekの後も常に末尾へ書きます。 read_bytes()も途中で失敗したときは取得済みのbyte列をR.vに残します。 read_text()はStringに収まらない大きさの入力を切り詰めずエラーにするので、大きなfileはbyte列かstreamで扱います。

同時に更新されるfile

複数のprocessが同じfileを更新するときはGD.file.replace_text(path, old, body)を使います。 読み取ったoldと現在の内容が同じときだけ置き換えるため、並行編集を黙って上書きしません。新規作成ではoldにnullを渡します。

data形式の入口

環境変数と.envは、読む対象で入口が分かれます。

memory上の変換は通常名がその場で計算し、_asyncの版は別のthreadで計算します。大きな入力には_asyncを使います。 正確な一覧はgd doc GD.fileとgd doc GD.dataで引けます。形式ごとの検査と上限は、APIリファレンスの各入口の説明にあります。

GD.collectionのCallableを使う操作は、約1 msごとにほかの処理へ実行権を譲ります。 GD.logの各呼出しは書込み完了まで待ち、本文を切り捨てません。失敗は戻り値のRで確認でき、GD.log.flush()でそれ以前の出力完了を待てます。

JSONの規則

値はGD.data.json_encode(value)でJSON byte列にし、外から受けたbyte列はGD.data.json_decode(bytes)で読みます。 どちらも成功値とErrを返します。GDWebRequest.json()、GDHTTPResponse.json()、JSONLの各行も同じ規則です。

• 不正UTF-8、重複名、非有限数、非対応型、循環参照は、曖昧な値へ変えず失敗にします。
• signed 64-bitに収まる整数はintのまま戻り、小数、指数、範囲外だけがfloatになります。文字列とキーの\u0000は保持します。
• 署名やcache keyのように同じ値から同じbyte列が必要なときは{"deterministic": true}を指定します。
• 設定はdeterministicとescape_htmlがbool、max_bytesとmax_depthがintです。不正な型はErr.INVALID_DATA、上限超過はErr.LIMITEDです。
• json_encode_async()が終わるまで、入力のArray・Dictionaryとその子要素を変更しないでください。設定の辞書は開始時に複製されます。

hashと鍵導出

GD.dataはSHA-1、SHA-224/256/384/512、SHA3-224/256/384/512を返します。HMAC、PBKDF2、HKDFでは sha1、sha224、sha256、sha384、sha512、sha3-224、sha3-256、sha3-384、sha3-512から方式を選べます。 PBKDF2とHKDFは出力長を指定でき、不正な方式や表現範囲外の設定はRの失敗として返します。PBKDF2の反復回数が1以下なら1回として計算します。

threadの上限

GD.async.set_max_threads(max)はgdが管理するOS threadの上限を設定し、以前の値を返します。既定は10000です。 上限を越えるとprocessが終了します。現在数より小さい値への変更も終了します。外部libraryが直接作るthreadは数えません。

Webフレームワーク

同じディレクトリにmain.gdとindex.htmlを作ります。一方のrouteでHTMLテンプレートに挨拶を埋め込み、もう一方で同じデータをJSONとして返します。

main.gd:

# Serve a greeting as an HTML page and a JSON response.
var app := GD.web.app()

# Build the shared response data from the requested name.
func greeting(req):
	var name := req.query.get("name", "world")
	if not name is String:
		return null, Err.err("name must be text", Err.INVALID_DATA)
	return {"name": name, "message": "Hello, " + name + "!"}, null

# Render the page with escaped template values.
func home(req):
	return GD.web.view("index.html", greeting(req)?)

# Return the same data as JSON.
func hello(req):
	return GD.web.json(greeting(req)?)

# Listen locally, using an optional port argument.
func main(args):
	var port := 8080 if args.is_empty() else int(args[0])
	app.route("GET", "/", home)
	app.route("GET", "/api/hello", hello)
	app.listen(port, "127.0.0.1")!
	print("http://127.0.0.1:", app.port())
	return 0

index.html:

<!doctype html>
<!-- Display a greeting and let visitors choose the name. -->
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{{message}}</title>
  <style>
    body { max-width: 36rem; margin: 4rem auto; padding: 0 1rem; font-family: system-ui, sans-serif; line-height: 1.6; }
    input, button { padding: .6rem; font: inherit; max-width: 100%; box-sizing: border-box; }
  </style>
</head>
<body>
  <h1>{{message}}</h1>
  <form action="/" method="get">
    <label>Your name <input name="name" value="{{name}}"></label>
    <button type="submit">Say hello</button>
  </form>
  <p><a href="/api/hello?name={{name}}">View the JSON response</a></p>
</body>
</html>

そのディレクトリで実行します。

gd serve main.gd

http://127.0.0.1:8080/?name=Aliceを開くと、{{message}}へ「Hello, Alice!」を埋め込みます。/api/hello?name=Aliceは{"name":"Alice","message":"Hello, Alice!"}を返します。テンプレートの値はHTMLの文脈に応じてエスケープされます。

serveはmain()が返ったあとも待受けを続けます。終了はCtrl+Cです。

routeと返事

route(method, pattern, handler)でHTTP methodとpathをhandlerへ結びます。patternの:nameはreq.params["name"]に入ります。 handlerはGDWebRequestを受け取ります。本文はreq.read()、bytes()、text()、json()、save()で必要な分だけ読みます。 HTMLのformから届く本文はGD.http.decode_query(req.text()?)で辞書にします。

reqは受信した要求です。失敗する操作はvar value, e := call()で確認してreturn null, eを返すか、call()?で伝播します。return 応答, nullは、すべての失敗を確認した成功経路だけで使います。

GD.web.view()とGD.web.json()は応答, Errを返します。handlerではreturn GD.web.json(data)のように結果をそのまま返せます。テンプレートの読込み・描画やJSON変換の失敗は、元のErrを保持してapp.on_error(req, e)へ届きます。middleware、after、自動JSON変換も同じ経路です。エラーハンドラ自身が失敗した場合は500で終了し、呼び直しません。streamの送信開始後はHTTP状態を変更できないため、writerのErrを処理します。

handlerが返した値が返事になります。

ハンドラとmiddlewareは、awaitの後も含めてSignalを返せます。完了時の引数が0個ならnull、1個ならその値、複数ならArrayとして処理を再開します。利用できないSignalはエラーハンドラへ渡します。要求終了やapp停止時には待機中の購読を解除します。

• text/htmlは第2引数、bytesは媒体型の後の引数で状態番号を変えられます。
• GD.web.header(reply, name, value)で返事にheaderを足します。
• GD.web.guard(reply)でX-Content-Type-Options、X-Frame-Options、Content-Security-Policyなどの防御headerをまとめて足します。
• 失敗の理由は既定では本文に出しません。開発中にapp.show_errors(true)とした間だけ出します。
• req.pathは各segmentを一度だけ復号したpath、req.targetはpercent escapeとqueryを保った原文です。%2Fは経路の区切りになりません。
• pathのsegmentを復号した結果が正しいUTF-8でない、または制御文字を含むと400を返します。queryの任意byteはPackedByteArrayとして保持するため、文字列として使う前に型を検査してください。req.queryは壊れた組を省略します。正常な組とErrを両方受け取るにはGD.http.decode_query()を使います。
• GD.web.json()やview()へ渡した値は、返事を送り終えるまで変更しないでください。

routerには次も登録できます。

middleware

middlewareは、handlerの前に呼ばれる関数です。GDWebRequestを受け取り、nullを返すと次へ進み、返事を返すとそこで止まります。 handle(req)を持つobjectも使えます。後段へ渡す値はreq.keep(name, value)で置き、req.kept(name)で読みます。

入力検査もmiddlewareです。GD.web.json_body(rule)、GD.web.query(rule)、GD.web.params(rule)が本文、query、pathの値を検査し、 通った値をreq.valid("body")、req.valid("query")、req.valid("params")に入れます。 ruleはGD.web.text_rule()、int_rule()、number_rule()、bool_rule()、list_rule()、object_rule()で組み、 GD.web.optional()とGD.web.one_of()で省略と選択肢を表します。queryとparamsの値は文字列なのでtext_rule()で検査し、必要ならto_int()で変換します。

var app := GD.web.app()

func show(req):
	var params := req.valid("params")
	return GD.web.json({"id": params.id})

func main():
	app.route("GET", "/posts/:id", show, [GD.web.params(GD.web.object_rule({"id": GD.web.text_rule({"min": 1, "max": 20})}))])
	app.listen(8080)!
	return 0

組込みのmiddlewareはGD.web.sessions()、GD.web.csrf()、GD.web.jwt()、GD.web.rate()です。認証の節で使います。

HTML雛形

頁が増えてきたらHTMLを雛形fileへ出し、GD.web.view(path, data)で描画します。 雛形はgdhtml（Mustache構文のマイクロテンプレート）で、{{name}}、{{{html}}}、#if、#unless、#each、 #with、else、{{> header}}を扱います。views/page.htmlから{{> header}}を使うと、 同じ階層のviews/partials/header.htmlを読みます。

<!-- views/page.html -->
{{> header}}
<main><h1>{{title}}</h1></main>

<!-- views/partials/header.html -->
<header><a href="/">gd app</a></header>

func page(_req):
	return GD.web.view("views/page.html", {"title": "Top"})

二重括弧の値は、置かれた位置から文脈を判定してescapeします。雛形の作者を信頼し、差し込む値を信頼しない前提です。

• 三重括弧{{{html}}}はescapeしない唯一の入口で、HTML本文以外では使えません。固定HTMLか十分に検査済みの値だけを渡してください。
• 「検査済み」の印を付けて二重括弧のescapeを省く方法はありません。
• 分岐の両側やeachの反復が異なる文脈で終わる雛形、閉じていないtag、曖昧なURLやJavaScript文脈は描画の失敗になります。
• 雛形の大きさに固定上限はありません。再帰する部品の深さだけは100000までです。
• 描画が終わるまで、渡した辞書を変更しないでください。

同じ雛形を何度も描画するserverでは、起動時にGD.html.template(source, partials)?で一度だけ解析し、 返った値のexecute(data)?を各要求から呼びます。解析結果は不変で、複数の要求から同時に使えます。 execute_bytes(data)?はUTF-8のbyte列を直接作るので、GD.web.bytes(body, "text/html; charset=utf-8")でそのまま返せます。

認証とCSRF

loginの状態はGD.web.sessions()で持ちます。issue(value)でsession IDを作り、cookie(id)の値をSet-Cookieで返します。 同じstoreをmiddlewareとして付けたrouteでは、cookieのIDに対応する値がreq.kept("user")に入り、無ければ401になります。

var app := GD.web.app()
var sessions := GD.web.sessions()

func login(req):
	var form := GD.http.decode_query(req.text()?)?
	var user := str(form.get("user", [""])[0])
	if user.is_empty():
		return GD.web.text("user is required", 400), null
	var reply := GD.web.redirect("/me")
	return GD.web.header(reply, "Set-Cookie", sessions.cookie(sessions.issue(user)?)), null

func me(req):
	return GD.web.text("hello, " + str(req.kept("user"))), null

func main():
	app.route("POST", "/login", login)
	app.route("GET", "/me", me, [sessions])
	app.listen(8080)!
	return 0

cookie(id)はSecureとHttpOnly付きで作ります。TLSなしの開発中に届かない場合はcookie(id, false)にします。 logoutはdrop(id)とclear_cookie()で行います。sessionはprocess内で持つため、--workersで複数processにするときはJWTか外部の保存先を使います。

cookieで認証する書き込み経路にはGD.web.csrf()を付けます。GET、HEAD、OPTIONS以外はBrowserの Sec-Fetch-Site: same-originが必要です。古いBrowserやBrowser以外のclientも受ける場合に GD.web.csrf({"allow_missing": true})を選び、別のtoken検証を組み合わせてください。

var app := GD.web.app()
var sessions := GD.web.sessions()

func save_email(_r):
	return "saved"

func main():
	app.route("POST", "/account/email", save_email, [GD.web.csrf(), sessions])
	app.listen(8080)!
	return 0

JWTをlogin sessionに使う場合は、password変更やlogoutで既発行tokenを失効させます。 checkは署名と標準claimの検証後に呼ばれ、trueを返したときだけ認証を通します。 例えばtokenへ利用者のverを入れ、password変更時に保存済みversionを増やします。 複数workerでは各processの辞書でなく、共有DBから同期したcacheなどで照合します。

func token_auth(key, versions):
	return GD.web.jwt(key, {"check": func(claims):
		return versions.get(claims.get("sub", ""), -1) == claims.get("ver", -2)
	})

reverse proxyの後ろでIP単位に制限するときは、そのproxyのIPまたはCIDRをtrusted_proxiesへ明示します。 gdはX-Forwarded-Forの右端から信頼済みproxyを除き、最初の未信頼IPをkeyにします。 未指定のときと未信頼の接続元からのX-Forwarded-Forは無視するため、client自身によるIP偽装を許しません。 IPv4とIPv4-mapped IPv6は別物として照合するので、mapped addressを信頼する場合はIPv6のCIDRを指定します。zone付きのproxy設定は拒否します。

var per_ip := GD.web.rate({"limit": 60, "trusted_proxies": ["127.0.0.1", "172.18.0.0/16"]})

停止

終了待ちはapp.shutdown(context)を使います。新規受付とkeep-aliveを止め、処理中requestの完了を待ちます。 期限を越えた場合はErr.TIMED_OUTを返しますが、処理中requestは強制終了しません。 直ちに全接続を閉じる必要がある場合にapp.stop()を使います。

func close(app):
	var context := GD.async.context().with_timeout(10.0)
	var stopped := app.shutdown(context)
	if not stopped.ok:
		app.stop()

handlerではreq.contextからrequestの完了と切断を受け取れます。 with_cancel()とwith_timeout()は親を変更せず子のcontextを返し、親の打ち切りは子へ伝わります。 HTTP、database、processなどの待ちを打ち切れるようにするには、contextを先頭に渡してwith_context()で包みます。 処理が先に終わればその結果を返し、contextが先に終われば処理を取り消します。

func load(req, db):
	var result = await GD.async.with_context(req.context, db.query_async("SELECT * FROM posts"))
	return result

func main():
	var limited_app := GD.web.app()
	limited_app.limits({"header_bytes": 1048576, "header_values": 500, "header_timeout": 15.0, "body_timeout": 10.0, "job_timeout": 30.0, "jobs": 128})
	return 0

func main():
	var app := GD.web.app()
	app.limits({"body_timeout": 600.0})
	app.route("POST", "/upload", func(req):
		req.limit(1000 * 1000 * 1000)?
		req.save("uploads://package.zip")?
		return GD.web.text("saved")
	)
	return 0 if app.listen(8080, "127.0.0.1").ok else 1

gd --strict --allow-net=127.0.0.1:8080 --mount=uploads=/srv/uploads:rw serve main.gd

database

GD.database.client()が返すclientは、SQLiteとPostgreSQLを同じ書き方で扱います。 local開発は組込みSQLite、本番はPostgreSQLという切り替えは、open()に渡すdriverで行います。

func main():
	var local := GD.cli.env("DB_DRIVER", "sqlite") == "sqlite"
	var db := GD.database.client()
	db.open({
		"driver": "sqlite" if local else "postgres",
		"path": "user://app.sqlite3",
		"host": "127.0.0.1",
		"database": "app",
		"user": "app",
		"password": GD.cli.env("PGPASSWORD", ""),
	})?
	db.query("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")?
	db.query("INSERT INTO users (id, name) VALUES ($1, $2) ON CONFLICT (id) DO NOTHING", [1, "ada"])?
	var out := db.query("SELECT id, name FROM users WHERE id=$1", [1])?
	print(out.rows[0].name)
	db.close()
	return 0, null

表の作成もINSERTもSELECTもquery()一つで送ります。受け取るのはcolumns、rows、tagを持つ辞書で、 rowsは列名を鍵にした辞書の配列です。上の例ならout.rows[0].nameがadaになります。 SQLの値は$1、$2の順でbindし、両driverで同じ書き方です。SQLは変換しないため、両方で通るSQLを使います。

query_rows()はwhile rows.next()で進め、scan()で列名付きの辞書、values()で列順の配列を得ます。 next()がfalseになったらerr()を調べます。途中で止める場合はclose()を呼びます。

func list_users(db):
	var rows := db.query_rows("SELECT id, name FROM users ORDER BY id")?
	while rows.next():
		var user := rows.scan()?
		print(user.id, " ", user.name)
	if rows.err() != null:
		return R.err(rows.err())
	return R.ok()

制約違反ではresult.e.infoに機械判定用の情報が入ります。violationはduplicate、not_null、foreign_keyのいずれか、 columnsは関係する列名です。PostgreSQLではcode、table、constraintもserverが返した場合に入ります。 値そのものはinfoへ残しません。SQLite自身が報告した失敗ではsource="sqlite"と拡張source_codeを保ちます。 SQLiteのforeign key文面には列名が無いため、その場合のcolumnsは空です。

func save(db):
	var saved := db.query(
		"INSERT INTO users(id,name) VALUES($1,$2)",
		[1, "ada"])
	if not saved.ok and saved.e.info.get("violation") == "duplicate":
		var columns := saved.e.info.get("columns", PackedStringArray())
		print("重複した列: ", columns)

transactionとmigration

複数の更新を一つの成否にするときはtransaction()を使います。callbackには同じ接続へ固定された GDDatabaseTxが渡ります。callbackが成功のRを返すとcommitし、失敗のRを返すとrollbackします。

func save(db, id, title):
	return db.transaction(func(tx):
		tx.query("INSERT INTO posts(id,title) VALUES($1,$2)", [id, title])?
		tx.query("UPDATE counters SET value=value+1 WHERE name='posts'")?
		return R.ok(id)
	)

• callbackでは渡されたtxを使い、必ずRを返してください。transaction中は元のclientのquery()と二重transactionを拒否します。
• commitの失敗はそのまま失敗として返ります。
• closeや取消はCOMMITの開始前ならrollbackし、開始後なら結果が確定してから接続を閉じます。
• callbackが終わった後は、保存しておいたtxも新しいSQLを受け付けません。

schemaを順番に適用するときは、SQLをsemicolonで分割せず、statementの配列をmigrate()へ渡します。 途中の一文が失敗すると全体をrollbackし、成功時は適用した文の数を返します。 versionとchecksumはapplication側で管理します。

func migrate(db):
	return db.migrate([
		"CREATE TABLE posts(id INTEGER PRIMARY KEY, title TEXT NOT NULL)",
		"CREATE INDEX posts_title ON posts(title)",
	])

定期処理

決まった時刻に一度だけ動かす仕事は、普通のscriptとして書き、OSのcronやsystemd timerから呼びます。 gd側に常駐の仕組みは要りません。

func collect():
	var now := GD.time.to_iso(GD.time.now())
	GD.file.append_text("store://log.txt", now + "\n")?
	return 0, null

func main():
	collect()?
	return 0, null

gd --strict --mount store=/var/lib/app:rw collect.gd

自分で間隔を持って回り続ける仕事は、GD.async.spawn()へ渡してgd serveで常駐させます。 spawn()へ渡した処理はmain()が返った後も動き続けます。

func every(sec, fn):
	while true:
		await GD.async.sleep(sec)
		fn.call()

func collect():
	print(GD.time.to_iso(GD.time.now()))

func main():
	var _job := GD.async.spawn(every.bind(60.0, collect))
	return 0

gd serve schedule.gd

止めるときはprocessを終わらせます。Web serverと同じ常駐なので、ここでもserveが必要です。

公式拡張モジュール

本体を小さく保ち、外部service固有の機能は必要なprojectだけへGDScript packageまたはGDExtensionとして加えます。

各文書に公開class、method、戻り値、制限値、strict実行例をまとめています。任意導入のため、 本体だけから生成するAPIリファレンスには含まれません。

• gd addで入れた拡張は起動時に信頼して読み込むため、旗は要りません。接続先の--allow-netは必要です。
• --allow-extと--deny-extが効くのは、scriptが実行中にGDExtensionManager.load_extension()で読む場合です。
• 入れた拡張はprocessと同じ権限で動くので、信頼する版をgd.lockで固定してcommitしてください。

packageと配布

scriptが増えたり他のpackageを使ったりする段階で、gd initでgd.jsonを作ります。依存はgd.jsonとgd.lockで固定します。

gd init
gd search discord bot
gd add gd:@scope/script-package@^1.0.0
gd add ext:@scope/name@^1.0.0
gd add short-name https://example.com/module.gd
gd install --frozen
gd task test

packageを使う

入れたpackageは、利用側が決めた呼び名を使ってpkg://<呼び名>/から読みます。

@import hello

• pkg://は利用者ごとの共有cacheを指し、projectへは何も複製しません。
• gd.jsonに書いた依存がcacheに無ければ、最初の実行で取得します。--strictでは登録所への--allow-netが要ります。
• gd addの既定の呼び名は、package名の-と.を_にした識別子です。engine classやkeywordと同じ呼び名は断ります。
• commitするのはgd.jsonとgd.lockです。gd initはpkg/を.gitignoreへ書きます。
• --frozenはlockを変更しません。offlineの配布先では、networkのある環境で先に取得し、--cached-onlyを併用します。
• install、add、updateが途中で失敗したときは、projectの配置とlockを元へ戻します。
• lockは登録所に結び付いています。別の登録所へ切り替えるには明示的なlock移行が必要です。

importの短い書き方

@importはconst 名 = preload(...)の短い書き方です。

外部依存がなくても使えます。実際の登録所の依存とlockfileを含むsamples/packagesを用意しています。

@import greet
@import "./util"
@import greet/style as theme

• 引用符の無い名前は、gd.jsonのimportsに宣言した呼び名だけを解決します。同名のfileを探しに行きません。
• 相対fileは引用符で./または../から書きます。 .gdは省略できます。同名のfileとdirectoryが両方あるときは"./util.gd"のように指定します。
• 識別子はasが無ければ最後の要素そのままで、mod.gdを持つdirectoryはdirectory名です。
• gd fmtは@importをそのまま残します。
• 本家Godotは@importを知らないので、Godotと共有するfileではconstとpreloadを書いてください。

packageを作る

packageはgd.jsonを根に持つ一つのprojectです。gd init @scope/nameがmod.gdとtestの雛形を作り、 gd testで回し、gd publishで公開します。

{"name":"@scope/hello","version":"1.0.0","main":"src/mod.gd","include":["src"]}

gd publish
gd add hello gd:@scope/hello@^1.0.0

• 入口はmod.gdです。複数fileならincludeへfileまたはdirectoryを明示します。
• mainのdirectoryがpackageの根になるので、package内の相対preloadはそのまま動きます。
• packageは自分のgd.jsonのimportsで他の登録所packageを使えます。gd publishがそのimportsを登録所へ載せます。
• class_nameは公開できます。installは同名classの衝突を検査し、衝突すれば全体を元へ戻します。
• gd.jsonのgodotをtrueにすると、gd固有のAPIを使わず本家Godotでも動くという作者の宣言になり、gd searchが[godot]と示します。

開発中のpackageはgd add ../pathでlocalから足します。呼び名は先のgd.jsonのnameから取ります。 checkoutをpkg/<呼び名>/へ複製し、内容の指紋が変われば次の実行で複製し直します。 .で始まるfile、pkg/、tmp/、gd.jsonを持つ下位directory、tokenは複製しません。 gd publishは、local importの先にnameとversionのあるgd.jsonがあれば登録所の範囲に変換し、無ければ拒みます。

依存の解決

gd installは依存graph全体を解決します。版は、gd.lockが固定した版、今回すでに選んだ版のうち範囲を満たすもの、 登録所の最新一致の順で選びます。

gd.lockは解決したimportsの設定も保持します。設定が変わった実行では同じresolverで再解決し、要求外の古い版を使いません。 --frozenは設定の不一致を拒否します。同じpackageに複数の別名がある場合、辞書順で最初の別名を配置先に使います。

• 純GDScript packageは、版ごとに別のものとして共存できます。
• native拡張はprocessに一つしか読めないため、一つの版に揃えます。範囲が両立しなければ取得前に止まります。
• 同じhost instanceを共有するpluginの仕組み（peer依存）はありません。
• 登録所packageの正式なpathはpkg://@scope/name@版/です。pkg://<呼び名>/は、書いたscriptが属するpackageのimportsで正式pathへ展開されます。同じ呼び名でもpackageごとに違う版を指せ、同じ版はどこから辿っても一つのscriptです。
• gd.lockには各packageのimportsの解決先も記録され、gd infoが一覧します。
• gd removeとgd updateは、どのpackageも使わなくなったものをgd.lockとpkg/から外します。
• 検索の順位が変わっても、既知のpackageのinstallとlockの検証には影響しません。

Godotと共有する置き場

本家Godotなどres://しか読めない環境と共有するときは、gd.jsonへ"place": "project"を書きます。 packageをpkg/<呼び名>/へ複製し、pkg://もres://pkg/もそこを指します。 他のpackageだけが使うものはpkg/@scope/name@版/へ置きます。

• project.godotのあるdirectoryではplaceの既定がprojectになり、.gitignoreは書きません。gdの無い同僚が開けるようpkg/をcommitします。
• installはpreload、load、extendsに書かれたres://参照を配置先へ書き換えます。文字列、コメント、実行時に組み立てるpathは書き換えません。
• placeはfileの置き場を決めるだけで、gd固有のAPIや構文をGodot向けに変換する機能ではありません。共有するsourceは標準構文と相対preloadで書きます。

native拡張のpackage

• native拡張は読込みに実fileが要るため、placeに関わらずpkg/<呼び名>/へ置きます。
• scriptから名指せるのは、自分のpackageがext:で取り込んだ拡張のclassだけです。projectのscriptならgd.json、packageのscriptならそのpackageのimportsが基準です。
• 登録所の外にある拡張はprojectのscriptだけが使えます。
• 登録所のpackageの拡張が、manifestの[classes]に無いclassを登録すると起動時に止まります。
• 配布先のOSで取得するか、gd compileを配布先のOSで実行してください。

設定と環境変数

gd.jsonの設定は次の10件です。

gdが読む環境変数は次の通りです。scriptから環境を読む実行では--allow-envで名前を許可します。

遠隔packageと登録所はHTTPSを使います。loopbackの開発用登録所に限りHTTPも使えます。 取得したpackageとnative libraryは登録所索引のSHA-256と照合します。 .gdextension manifestは16 MiB、packageの全file合計は500 MiBまでです。

単一実行体で配布する

compileで、script、view、静的file、migration、依存package、対象OSのGDExtensionを一つの実行体へまとめます。配布先にcacheは要りません。

gd compile -o app main.gd
./app

• gd.jsonが名指すpackageと、それらが取り込むpackageを全部同梱します。
• 同梱したWebアプリも./app serve --no-scene-tree --allow-netで常駐できます。
• local pathのpackageからは、.envなど.で始まるfileとgd.jsonのtokenを除きます。
• secretをsourceへ埋め込まないでください。compileは.envを除外しますが、sourceに書いた値は実行体へ残ります。

対応範囲と報告

gdはAPIが固まる前の公開版です。後方互換は前提にしないでください。変更した点と基準にしたGodotの版は CHANGELOGに書きます。 gdはGodot FoundationまたはGodot Engine projectの公式製品ではありません。

不具合はIssuesへ、公開すべきでない脆弱性は GitHubの非公開報告から知らせてください。

gd Manual

The online manual and API reference uses your browser’s preferred English or Japanese language, with English as the fallback. Use the language button or ?lang=ja for Japanese; an explicit selection is remembered locally.

What gd is for

gd is a single command for writing command-line tools, websites, Web APIs, scheduled jobs, and data processing in GDScript. It is Godot built small without a display, and it runs a single .gd file without a project.godot.

You start the way you would with a Python or Node.js script. When you need them, type checking, tests, packages, databases, a Web server, and a standalone executable are available in the same GDScript. For game screens and rendering, use upstream Godot.

Together with Godot itself, apps, frontends, servers, and CLI tools can all be written in one language, GDScript. The same script runs on macOS, Linux, and Windows, and waits on networking and databases do not stop other work. It links directly with C++ through GDExtension. It is designed for AI agents to write and run code.

Built-in HTTP/2 multiplexing and nonblocking networking keep concurrent connections moving. SIMD/SWAR paths accelerate UTF-8, JSON, and hex processing, while connection, buffer, and parsed-template reuse reduce repeated work and allocations.

Install

Supported platforms are macOS arm64/x86_64, Linux x86_64, and Windows x86_64. Download the archive for your OS from Releases and put the gd inside on your PATH. When gd --version prints a version, the install is done. The SHA-256 of each archive can be checked against the bundled SHA256SUMS. The macOS build is signed with a Developer ID and notarized by Apple.

macOS / Linux

curl -fsSL https://gd.progsha.com/install.sh | sh

The installer checks the archive checksum and installs to ~/.local/bin. Add that directory to your PATH if prompted. Linux binaries require x86_64 and glibc 2.38 or newer.

Windows (PowerShell)

Invoke-WebRequest -UseBasicParsing https://gd.progsha.com/install.ps1 -OutFile install-gd.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\install-gd.ps1

Run these commands in PowerShell. Administrator access is not required. The installer verifies the SHA-256 checksum, installs gd.exe into %LOCALAPPDATA%\gd\bin, and adds that directory to your user PATH. Open a new terminal and run gd --version.

For a manual install, download gd-windows-x86_64.zip from Releases, extract it, and add the directory containing gd.exe to your user PATH. Do not run the Unix curl | sh command in PowerShell.

Homebrew (macOS)

brew tap prog-sha/gd https://github.com/prog-sha/gd
brew install prog-sha/gd/gd

This tap lives in the product repository and installs the signed Universal binary. Update with brew update && brew upgrade prog-sha/gd/gd; remove with brew uninstall gd.

apt (Linux amd64)

Use an apt-based distribution with glibc 2.38 or newer, such as Ubuntu 24.04 or Debian 13. Ubuntu 22.04 and Debian 12 need a source build. The dedicated repository uses a signing key restricted to this source:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://gd.progsha.com/apt/gd.asc | sudo tee /etc/apt/keyrings/gd.asc >/dev/null
sudo chmod 0644 /etc/apt/keyrings/gd.asc
echo 'deb [arch=amd64 signed-by=/etc/apt/keyrings/gd.asc] https://gd.progsha.com/apt stable main' | sudo tee /etc/apt/sources.list.d/gd.list
sudo apt update
sudo apt install gd

Subsequent versions arrive through normal apt updates. Remove with sudo apt remove gd. Repository metadata and packages use HTTPS; apt also verifies the signed metadata.

winget (Windows)

The official winget catalog entry is pending submission and review. Until it is accepted, use the PowerShell installer above. Maintainers can validate or submit the prepared manifests; winget install prog-sha.gd is not yet an available installation route.

Build from source

Building from source needs Python, uv, SCons, and a C/C++ compiler. The executable is gd.*.template_release.* under bin/. TLS is built in, so no separate TLS library is needed.

git clone --branch 0.7 https://github.com/prog-sha/gd.git
cd gd
scons platform=macos target=template_release -j8
# Linux: platform=linuxbsd
# Windows: platform=windows windows_subsystem=console

Quick start

Create one file, hello.gd. No config file or package is needed. main() is the entry point, and the integer it returns becomes the process exit code.

func main():
	print("Hello, world")
	return 0

gd hello.gd

To check types and syntax without running, use check.

gd check hello.gd

Import scripts and shared constants

Use @import "./settings" for a local file and @import hello for an installed package. Use the imported name directly; .gd and as settings can be omitted.

Put shared values in settings.gd:

const TITLE = "Hello"
const USER = "world"

Use them from main.gd:

@import "./settings"

func main():
	print(settings.TITLE, ", ", settings.USER, "!")
	return 0

This prints Hello, world!. Use this pattern when values need to be shared.

Access values as settings.TITLE instead of copying a const declaration for each value into the caller. Keep values and functions used by only one script in that script. Use as when a name conflicts or needs clarification. Built-in APIs such as GD.web need no import.

See Packages and distribution for installation and version locking.

Pick by purpose

The standard API has one entry point, GD, with a child per purpose. Scripts write these names as they are.

GD.database.postgres and GD.database.redis are advanced entries for features specific to one backend.

Looking up the API

Pass the same spelling you write in a script to gd doc. Signatures come from the executable, so they match the implementation.

gd doc                     # short guide and entry points
gd doc manual              # the full manual
gd doc GD                  # the children of GD
gd doc GD.file             # file API
gd doc GD.http.fetch       # the returned HTTP response
gd doc GD.web.app          # Web application
gd doc SceneTree           # Inspect a public engine class.
gd doc all                 # every public class

Return types such as R, Err, and GDWebRequest are looked up by name alone. For Godot classes such as Node, SceneTree, and Timer, see the Godot class reference as well. The manual is shown in Japanese when LC_ALL or LANG starts with ja, and in English otherwise. The web version at gd.progsha.com switches between Japanese and English.

GDScript basics

The examples avoid repeating type names. Variables assigned with := and success values returned as return value, failure infer their types. Parameters without annotations remain dynamic. Add annotations only where you want to fix a type boundary.

Arguments and flags

Arguments placed after the script name arrive in main(argv). An argument that could be mistaken for gd's own flag, such as --name=gd, reaches the script when placed after --.

func main(argv):
	for arg in argv:
		print(arg)
	return 0

gd main.gd apple orange
gd main.gd -- --name=gd

To interpret them as flags, use GD.cli.flags(). It accepts --name gd, --name=gd, and -name=gd alike.

func main(argv):
	var flags := GD.cli.flags()
	flags.flag_str("name", "world", "who to greet")
	var parsed := flags.parse(argv)
	if not parsed.ok:
		print(flags.usage())
		return 1
	print("Hello, " + flags.get_str("name"))
	return 0

Calling external commands

Call external tools with GD.cli.run(). Only the calling GDScript waits, so other requests proceed even when it is called from a gd serve handler. Under --strict it needs --allow-run. You can narrow the target, as in --allow-run=/usr/bin/git.

func main():
	var got := GD.cli.run("git", ["rev-parse", "HEAD"])
	if not got.ok:
		return 1
	print("code=", got.v["code"], " out=", got.v["output"])
	return 0

A nonzero child exit returns Err. Inspect value.code or e.info.code for its status and value.output for captured output. Timeout and cancellation retain captured output too.

The third argument, opts, changes the behavior.

Commands during development

gd check main.gd        # check types and syntax without running
gd fmt main.gd          # normalize formatting
gd test                 # collect and run *_test.gd
gd --watch main.gd      # run again on every save
gd eval 'print(1 + 1)'  # try one line
gd repl                 # try interactively

Values and failures

A function that can fail returns two values, the success value and the failure, instead of throwing. The caller receives both with var value, e :=, and a non-null e means failure.

func main():
	var text, e := GD.file.read_text("note.txt")
	if e:
		print(e.text())
		return 1
	print(text)
	return 0

Shorter failure handling

Instead of writing if e every time, append ? to the call. The failure is returned to the caller as is, and only the success value remains. A function that uses ? also returns a success value and a failure itself, with return value, failure.

func title(path):
	var text := GD.file.read_text(path)?
	return text.strip_edges(), null

func main():
	var text, e := title("note.txt")
	if e:
		print(e.note("read the title").text())
		return 1
	print(text)
	return 0

In main(), which does not pass failures up, receive them with var value, e := or !.

File-operation failures put op, path, source, and source_code in e.info. A rename has old and new instead of path. source is one of posix, win32, and engine. A kind is set only when its meaning, such as NotFound, is known; an unknown I/O failure keeps its source details with Err.NONE.

Some APIs retain processed values on failure. Receive both with var value, e := call() when decoding, parsing queries, running child processes, or executing Redis batches. Causes remain accessible through e.cause; use e.is(kind) to inspect their categories.

The MessagePack, CBOR, TAR, TOML, YAML, XML, dotenv, front-matter encoding, and PBKDF2 APIs in GD.data return a value and Err in both synchronous and async forms. Unrepresentable entries are not silently omitted.

base64_decode(text) and base32_decode(text) require standard padding; pass true as the second argument for raw input. Base32 uses uppercase letters. base64url_decode(text) uses raw input by default; pass false for padded input. Both synchronous and async decoders retain partial bytes on failure.

GD.http.decode_query(raw) returns Arrays of all values per key and the first Err. req.query provides the first value; req.query_all retains every value. Keys and values containing NUL or invalid UTF-8 remain PackedByteArray, preserving their exact bytes. encode_query() repeats Array values and accepts byte arrays. parse_url() preserves the original spelling in raw_query. After editing query, call url.erase("raw_query") before rebuilding the URL to use the edited dictionary.

Return value rules

Code works without written types. When you do write types, these are the detailed rules.

• A result signature has two types, such as -> int, Err: one success type and Err. The runtime type is R; -> R or no return annotation is also allowed.
• A comma return always has two values. The last must have type Err or be null for success. A string cannot be returned there directly; wrap it with Err.err(reason).
• Fix a failure variable's type with var e: Err = ... or var e := Err.err(...). A variable declared with var e = ... can change type and cannot occupy the last slot.
• To return several items, put them in one array or dictionary, as in return [1, 0.0, ""], null. return null, null returns null as the success value.
• Unpack an R with exactly two names: var value, e := call(). A declaration that lists expressions, such as var a, b, c := 1, "a", 0.0, is a different thing: it has no count limit and infers each name from its expression. It may also assign variables visible in the function, including those of enclosing blocks, when it introduces at least one new name, and every right-hand expression is evaluated before any assignment. Constants, parameters, and variables a lambda captured cannot be assigned.
• Using ? in a function whose annotated return type lacks , Err gives The "?" operator needs a function returning "R" or "Err".
• Writing return R.ok("a") under -> int, Err is a compile error. When the type is dynamic, it is checked at runtime.
• When a typed Array or Dictionary is the success value, give the original container the same element type.
• A function returning a value and a failure returns on every path. One that only propagates with ? still ends with return null, null.
• A function declaring a single return type such as -> int cannot use a comma return. Declare -> int, Err.
• A lambda cannot use a comma return. Use return R.ok(value) and return R.err(reason).

Carrying results in R

To carry the value and the failure around as one value, use R. Read ok for the outcome, v for the success value, and e for the failure. Build one with R.ok(value) or R.err(reason, kind, partial_value). Web handlers and database transactions can also be written to return this R.

func find(items, want):
	for item in items:
		if item == want:
			return R.ok(item)
	return R.err("not found: " + want, Err.NOT_FOUND)

func main():
	var got = find(["a", "b"], "c")
	if not got.ok:
		print(got.e.text())
		return 1
	print(got.v)
	return 0

R.ok() carries null as its success value, not integer 0. I/O APIs that make partial progress keep the completed amount in v as a partial value even on failure. note() preserves the partial value, and v_or(fallback) returns the fallback on failure. When ? propagates a failure whose partial value does not fit the caller's success type, only the partial value is dropped; the reason and kind are kept.

Waiting and concurrency

Waiting methods in HTTP, databases, GD.net, files, and others are written as ordinary function calls. Only the calling GDScript waits; other networking and timers keep running.

func main():
	var res := GD.http.fetch("https://example.com/")!
	print(res.status)
	return 0

To start several operations together, use the variants ending in _async with GD.async.all().

func main():
	var got = await GD.async.all([
		GD.http.fetch_async.bind("https://example.com/a"),
		GD.http.fetch_async.bind("https://example.com/b"),
	])
	for result in got:
		var res, e := result as R
		if e:
			print(e.text())
			return 1
		print(res.status)
	return 0

Pass Callables rather than Signals to all(). It subscribes to completion before starting each one, so it cannot lose a result that finishes early.

A signal saved with := retains its completion type. Reassignment from a different or unknown completion type is rejected. For dynamic completions, declare the receiver as Signal and annotate the awaited value as needed, for example var result: R = await pending.

spawn() does not move CPU work to another thread. Long GDScript yields to other work automatically, but the inside of a native method is not interrupted, so use the _async variant when passing large input to a standard module. A waiting method may be called only from a function that GDScript itself called. Native callbacks such as Array.map(), _init(), member initializers, and _to_string() cannot wait for it. Adding await inside such a callback does not make the native caller await the result. Move asynchronous initialization into main(); replace asynchronous map() callbacks with a for loop in an asynchronous function or the Callables passed to GD.async.all() above.

Tutorial: a notes API on SQLite

With what you have read so far, this builds a small API that accepts JSON and stores it in SQLite, in one script. The result is a development server with input validation and SQL parameter binding, started with narrowed permissions.

1. Create a working directory

mkdir notes-api
cd notes-api

2. Write the API

Save the following as main.gd.

# Store notes in an embedded database and expose a JSON API.
extends RefCounted


const PORT := 18080 # development port listening on loopback
const DB_PATH := "user://notes.sqlite3" # per-user writable area provided by gd

var app := GD.web.app()
var db := GD.database.client()


# Return notes as JSON, newest first.
func list_notes(_req):
	var got := db.query("SELECT id, title FROM notes ORDER BY id DESC")?
	return GD.web.json(got.rows)


# Store a validated title and return the created row.
func add_note(req):
	var body := req.valid("body")
	var made := db.query(
		"INSERT INTO notes(title) VALUES($1) RETURNING id, title",
		[body.title]
	)?
	return GD.web.json(made.rows[0], 201)


# Prepare the database and routes, then listen on loopback.
func main():
	db.open({"driver": "sqlite", "path": DB_PATH})?
	db.query("CREATE TABLE IF NOT EXISTS notes(id INTEGER PRIMARY KEY, title TEXT NOT NULL)")?
	app.route("GET", "/notes", list_notes)
	app.route("POST", "/notes", add_note, [GD.web.json_body(GD.web.object_rule({
		"title": GD.web.text_rule({"min": 1, "max": 120}),
	}))])
	app.listen(PORT, "127.0.0.1")?
	print("listening on http://127.0.0.1:%d" % PORT)
	return 0, null

Read it from the top.

• app is the router and db is the database connection. Both are script variables so the server can keep running after main() returns.
• main() first opens SQLite and creates the table. user:// in DB_PATH is a per-user writable area provided by gd.
• app.route() registers an HTTP method, a path, and the function to call for it (the handler).
• A handler receives a GDWebRequest and builds the reply with GD.web.json(). A ? in the middle returns the failure to the server, which becomes a status such as 500.
• The POST route carries GD.web.json_body(). The handler is called only when the body matches the rule, and the value that passed arrives in req.valid("body").
• SQL values are bound to $1. SQL is never built by string concatenation.

3. Start with narrowed permissions

Run unverified scripts and servers exposed to the outside with --strict, which denies permissions by default. Here the listener is limited to one loopback port. serve keeps the process alive after main() returns, and it is the command to use for servers.

gd check main.gd
gd --strict --allow-net=127.0.0.1:18080 serve main.gd

4. Use it from another terminal

curl -s -X POST http://127.0.0.1:18080/notes \
  -H 'Content-Type: application/json' \
  -d '{"title":"try gd"}'
curl -s http://127.0.0.1:18080/notes

The first call returns status 201 with the created row, the second the stored array. An empty title, a title over 120 characters, or a non-JSON body is rejected with 400. Press Ctrl-C in the terminal that started it to stop.

In production, keep this process on loopback behind a TLS reverse proxy, and switch storage that must survive crashes to PostgreSQL. Keep connection details out of the source and read them from allowed environment variables.

Permissions

Start with normal execution. --strict is an advanced mode for explicitly designing and configuring the permissions a script needs.

On macOS/Linux, v0.7.3 --strict still permitted absolute reads outside the startup directory.

Under --strict, start by listing what the script uses.

gd --strict \
  --mount store=/srv/app:rw \
  --allow-net=db.example.com:5432 \
  --allow-env=DATABASE_URL \
  main.gd

File locations

A script sees files through four kinds of location. Write the name of the location at the start of the path, or write an absolute path as it is.

• A relative path that climbs above res:// is refused in either mode.
• Under --strict, the startup working directory is the implicit read boundary, even when the entry script is in a subdirectory. Absolute paths inside it use the same read-only checks as res://; parent and sibling directories are denied. Links cannot bypass this boundary. To access an outside directory, explicitly mount it and use its named scheme, such as store://. -A does not expand file access.
• --mount and absolute paths are for Linux and macOS. Windows rejects them, so put files under res:// or user:// there.
• A mount name uses lowercase letters, digits, and -. res, user, uid, pipe, local, libgodot, tcp, unix, http, https, file, data, and cache are reserved and cannot be chosen.

Network and extension permissions

• In --allow-net, localhost:8080 also covers IPv4 loopback 127.0.0.0/8 and IPv6 ::1 on the same port.
• *.example.com:443 allows its subdomains.
• Native extensions run in the same process, so allow only ones you trust.

serve and SceneTree

gd serve is the resident way to run, and it creates no SceneTree. Networking, timers, await, custom Signals, GD.async.sleep(), and queue_free() on nodes outside a tree all work. With no work to do, it sleeps until the next deadline or network notification, so there is no cycle to tune.

Under serve, a script that only extends Node is not added to a tree. --no-scene-tree reports a diagnostic as soon as a SceneTree is created and exits with code 1. It is inherited by --watch and --workers children. Normal execution creates an implicit SceneTree, so it fails with this flag.

TCP and UDP

Use GD.net for low-level networking. Godot's low-level types remain for compatibility, but new code should use GD.net.

func echo():
	var listener := GD.net.listen_tcp("127.0.0.1", 8080)?
	var conn := listener.accept()?
	var data := conn.read(65536)?
	conn.write(data)?
	conn.close()
	return 0, null

• GDTCPConn keeps reads and writes in separate queues, so several GDScripts may call it concurrently.
• Deadline methods set durations from now; zero clears them.
• close() releases pending reads and writes with Err.INTERRUPTED. Listener accepts behave the same way.
• A connection tries the IPv4 and IPv6 candidates from name resolution in order and keeps only the one that succeeds. The overall timeout is never extended.

TLS

Open TLS with GD.net.dial_tls(host, port, opts). It verifies the certificate chain and host name by default, and a failure never falls back to plaintext. The result is the same GDTCPConn used for TCP.

Read the negotiated result from negotiated_protocol and version in connection_state(). TLS 1.2 is 771 and TLS 1.3 is 772.

Without other settings, the trusted CAs are the OS trust settings on macOS and Windows, and the system CA bundle on Linux. Set SSL_CERT_FILE or SSL_CERT_DIR before starting the process to use the given CAs on any OS. Directory lists use : on Unix and ; on Windows.

When a server requires client certificates, pass client_ca (a trusted CA bundle) and client_auth in the opts of app.listen_tls(port, cert, key, host, opts). A missing client_ca uses the system trust settings.

UDP and name resolution

GD.net.listen_udp() returns a GDUDPPacketConn. read_from() returns a dictionary containing data, host, port, and truncated. Pass an IP address resolved by GD.net.resolve() as the host of write_to(). Packets are never merged. The default buffer=0 keeps the OS receive buffer as it is; only a positive value requests a change.

GD.net.resolve() returns the first address selected by the OS. It keeps no name cache. GD.net.local_addresses() returns the machine's address list and distinguishes an empty list from an OS failure. The failure's e.info carries syscall, source, and source_code.

Files and data

GD.file reads and writes files and handles paths. The directory you started from is res://, and absolute paths work as written. To write to an outside directory under strict, write the name given by --mount store=/srv/app:rw as in store://users.csv.

func main():
	var rows := GD.data.csv_objects(GD.file.read_text("store://users.csv")?)?
	GD.file.write_text("store://users.json", JSON.stringify(rows))?
	return 0, null

File operations suspend only the calling GDScript, even under their regular names. Other requests proceed while a Web server handler reads a file. Use the variants ending in _async only to start several operations together.

func handler(_req):
	var body := GD.file.read_text("store://big.json")
	if not body.ok:
		return GD.web.text("cannot read", 500)
	return GD.web.text(body.v)

Files embedded by compile can be read, listed, and served statically through the same API.

Reading large files

To read without holding the whole file in memory, open a GDFileStream with GD.file.open(path, mode). Modes are read, write, append, and read_write. Call close() when done.

Operations on one stream run in arrival order, and separate streams proceed in parallel. Append always writes at the end, even after a seek. read_bytes() also retains the bytes already read in R.v when it fails partway. read_text() rejects input too large for a String instead of truncating it, so handle large files as bytes or a stream.

Files updated concurrently

When several processes update the same file, use GD.file.replace_text(path, old, body). It replaces the content only when the old you read still matches the current content, so a concurrent edit is never silently overwritten. Pass null as old to create a new file.

Entry points by data format

Environment variables and .env have separate entries by what you read.

In-memory conversions compute in place under their regular names, and their _async variants compute on another thread. Use _async for large inputs. Run gd doc GD.file and gd doc GD.data for the exact lists. Checks and limits per format are in the description of each entry in the API reference.

GD.collection operations that take a Callable yield to other work about every 1 ms. Each GD.log call waits until the write completes and never truncates the message. Check failures through the returned R; GD.log.flush() waits for all earlier output.

JSON rules

Use GD.data.json_encode(value) to produce JSON bytes and GD.data.json_decode(bytes) to read bytes received from outside. Both return a success value and an Err. GDWebRequest.json(), GDHTTPResponse.json(), and each JSONL line follow the same rules.

• Invalid UTF-8, duplicate names, non-finite numbers, unsupported types, and cycles fail instead of being turned into ambiguous values.
• An integer within the signed 64-bit range returns as int; only fractions, exponents, and out-of-range values become float. Strings and keys preserve \u0000.
• Pass {"deterministic": true} when the same value must give the same bytes, as for signatures or cache keys.
• The options deterministic and escape_html are bool; max_bytes and max_depth are int. An invalid type returns Err.INVALID_DATA, and exceeding a limit returns Err.LIMITED.
• Keep the input Arrays, Dictionaries, and their children unchanged until json_encode_async() finishes. The options dictionary is copied at the start.

Hashes and key derivation

GD.data returns SHA-1, SHA-224/256/384/512, and SHA3-224/256/384/512 digests. HMAC, PBKDF2, and HKDF accept sha1, sha224, sha256, sha384, sha512, sha3-224, sha3-256, sha3-384, or sha3-512 as the hash name. PBKDF2 and HKDF accept an output length and return an R failure for an invalid hash or settings outside the supported range. PBKDF2 iteration counts of one or less perform one iteration.

Thread limit

GD.async.set_max_threads(max) sets the limit on OS threads managed by gd and returns the previous value. The default is 10000. Exceeding the limit terminates the process. Lowering it below the current count also terminates it. Threads created directly by external libraries are not counted.

Web framework

Create main.gd and index.html in the same directory. One route renders a greeting through an HTML template; another returns the same data as JSON.

main.gd:

# Serve a greeting as an HTML page and a JSON response.
var app := GD.web.app()

# Build the shared response data from the requested name.
func greeting(req):
	var name := req.query.get("name", "world")
	if not name is String:
		return null, Err.err("name must be text", Err.INVALID_DATA)
	return {"name": name, "message": "Hello, " + name + "!"}, null

# Render the page with escaped template values.
func home(req):
	return GD.web.view("index.html", greeting(req)?)

# Return the same data as JSON.
func hello(req):
	return GD.web.json(greeting(req)?)

# Listen locally, using an optional port argument.
func main(args):
	var port := 8080 if args.is_empty() else int(args[0])
	app.route("GET", "/", home)
	app.route("GET", "/api/hello", hello)
	app.listen(port, "127.0.0.1")!
	print("http://127.0.0.1:", app.port())
	return 0

index.html:

<!doctype html>
<!-- Display a greeting and let visitors choose the name. -->
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{{message}}</title>
  <style>
    body { max-width: 36rem; margin: 4rem auto; padding: 0 1rem; font-family: system-ui, sans-serif; line-height: 1.6; }
    input, button { padding: .6rem; font: inherit; max-width: 100%; box-sizing: border-box; }
  </style>
</head>
<body>
  <h1>{{message}}</h1>
  <form action="/" method="get">
    <label>Your name <input name="name" value="{{name}}"></label>
    <button type="submit">Say hello</button>
  </form>
  <p><a href="/api/hello?name={{name}}">View the JSON response</a></p>
</body>
</html>

Run from that directory:

gd serve main.gd

Open http://127.0.0.1:8080/?name=Alice to insert “Hello, Alice!” into {{message}}. /api/hello?name=Alice returns {"name":"Alice","message":"Hello, Alice!"}. Template values are escaped for their HTML context.

serve keeps listening after main() returns. Stop with Ctrl+C.

Routes and replies

route(method, pattern, handler) binds an HTTP method and a path to a handler. :name in the pattern arrives in req.params["name"]. A handler receives a GDWebRequest. It reads only the needed body through req.read(), bytes(), text(), json(), or save(). A body sent by an HTML form becomes a dictionary with GD.http.decode_query(req.text()?).

req is the incoming request. Inspect fallible operations with var value, e := call() and return null, e, or propagate with call()?. Use return response, null only on a successful path after handling every possible failure.

GD.web.view() and GD.web.json() return response, Err. A handler can forward the result directly: return GD.web.json(data). Template loading/rendering and JSON encoding preserve the original Err for app.on_error(req, e). Middleware, postprocessors, and automatic JSON encoding share that boundary. If the error handler itself fails, the server returns 500 without invoking it again. Once streaming starts, the HTTP status is committed; handle errors returned by the writer.

The value a handler returns becomes the reply.

Route handlers and middleware may return a Signal, including after await. Processing resumes when it completes: no arguments become null, one argument becomes that value, and multiple arguments become an Array. An unavailable Signal goes through the error handler. Pending subscriptions are removed when the request ends or the app stops.

• text and html take the status as the second argument; bytes takes it after the media type.
• GD.web.header(reply, name, value) adds a header to a reply.
• GD.web.guard(reply) adds the defensive headers such as X-Content-Type-Options, X-Frame-Options, and Content-Security-Policy at once.
• The reason for a failure is not written to the body by default. It is shown only while app.show_errors(true) is set during development.
• req.path is the path with each segment decoded once. req.target is the original text, keeping percent escapes and the query. %2F does not become a path separator.
• A path whose percent-decoded segments contain invalid UTF-8 or control characters gets a 400. Query values preserve arbitrary bytes as PackedByteArray; validate their type before using them as text. req.query skips malformed pairs; use GD.http.decode_query() to receive both the valid pairs and an Err.
• Do not modify values passed to GD.web.json() or view() until the reply has been sent.

The router also accepts the following.

Middleware

Middleware is a function called before the handler. It receives a GDWebRequest, returns null to continue, or returns a reply to stop there. An object with handle(req) also works. Pass values to later stages with req.keep(name, value) and read them with req.kept(name).

Input validation is middleware too. GD.web.json_body(rule), GD.web.query(rule), and GD.web.params(rule) check the body, query, and path values, and put the values that pass into req.valid("body"), req.valid("query"), and req.valid("params"). Rules are built from GD.web.text_rule(), int_rule(), number_rule(), bool_rule(), list_rule(), and object_rule(), with GD.web.optional() and GD.web.one_of() for omission and choices. Query and path values are strings, so check them with text_rule() and convert with to_int() when needed.

var app := GD.web.app()

func show(req):
	var params := req.valid("params")
	return GD.web.json({"id": params.id})

func main():
	app.route("GET", "/posts/:id", show, [GD.web.params(GD.web.object_rule({"id": GD.web.text_rule({"min": 1, "max": 20})}))])
	app.listen(8080)!
	return 0

The built-in middleware are GD.web.sessions(), GD.web.csrf(), GD.web.jwt(), and GD.web.rate(). The authentication section uses them.

HTML templates

As pages grow, move the HTML into template files and render them with GD.web.view(path, data). The template language is gdhtml, a micro template with Mustache syntax. It handles {{name}}, {{{html}}}, #if, #unless, #each, #with, else, and {{> header}}. Using {{> header}} from views/page.html reads views/partials/header.html at the same level.

<!-- views/page.html -->
{{> header}}
<main><h1>{{title}}</h1></main>

<!-- views/partials/header.html -->
<header><a href="/">gd app</a></header>

func page(_req):
	return GD.web.view("views/page.html", {"title": "Top"})

Double-brace values are escaped by the context they appear in. The template author is trusted, the values inserted are not.

• Triple braces {{{html}}} are the only unescaped entry, and they work only in the HTML body. Pass only fixed HTML or a sufficiently checked value.
• A double brace cannot be marked "checked" to skip escaping.
• A template whose branches or each iterations end in different contexts, an unclosed tag, or an ambiguous URL or JavaScript context fails to render.
• Template size has no fixed limit. Only the depth of recursive partials is limited, to 100000.
• Do not modify the dictionary you passed until rendering finishes.

For a server that renders the same template repeatedly, parse it once at startup with GD.html.template(source, partials)?, then call execute(data)? on the returned value from each request. The parsed value is immutable and can be used by several requests at once. execute_bytes(data)? produces UTF-8 bytes directly, so they can be returned as is with GD.web.bytes(body, "text/html; charset=utf-8").

Authentication and CSRF

Login state is held by GD.web.sessions(). issue(value) creates a session ID, and the value of cookie(id) is returned as Set-Cookie. On routes that carry the same store as middleware, the value behind the cookie's ID arrives in req.kept("user"), and a missing session is a 401.

var app := GD.web.app()
var sessions := GD.web.sessions()

func login(req):
	var form := GD.http.decode_query(req.text()?)?
	var user := str(form.get("user", [""])[0])
	if user.is_empty():
		return GD.web.text("user is required", 400), null
	var reply := GD.web.redirect("/me")
	return GD.web.header(reply, "Set-Cookie", sessions.cookie(sessions.issue(user)?)), null

func me(req):
	return GD.web.text("hello, " + str(req.kept("user"))), null

func main():
	app.route("POST", "/login", login)
	app.route("GET", "/me", me, [sessions])
	app.listen(8080)!
	return 0

cookie(id) sets Secure and HttpOnly. If the cookie does not arrive during development without TLS, use cookie(id, false). Log out with drop(id) and clear_cookie(). Sessions live in one process, so with several processes under --workers use JWT or an external store.

Attach GD.web.csrf() to write paths that authenticate with cookies. Requests other than GET, HEAD, and OPTIONS need the browser's Sec-Fetch-Site: same-origin. When old browsers or non-browser clients must be accepted, choose GD.web.csrf({"allow_missing": true}) and combine it with separate token verification.

var app := GD.web.app()
var sessions := GD.web.sessions()

func save_email(_r):
	return "saved"

func main():
	app.route("POST", "/account/email", save_email, [GD.web.csrf(), sessions])
	app.listen(8080)!
	return 0

When JWT is used as a login session, revoke issued tokens on password change and logout. check is called after the signature and standard claims are verified, and authentication passes only when it returns true. For example, put the user's ver in the token and increment the stored version on password change. With several workers, compare against something like a cache synced from a shared DB, not a per-process dictionary.

func token_auth(key, versions):
	return GD.web.jwt(key, {"check": func(claims):
		return versions.get(claims.get("sub", ""), -1) == claims.get("ver", -2)
	})

To limit per IP behind a reverse proxy, list the proxy's IPs or CIDRs in trusted_proxies. gd strips trusted proxies from the right end of X-Forwarded-For and uses the first untrusted IP as the key. X-Forwarded-For is ignored when trusted_proxies is unset and when it comes from an untrusted peer, so a client cannot forge its own IP. IPv4 and IPv4-mapped IPv6 are matched as different things, so use an IPv6 CIDR to trust mapped addresses. Proxy settings with zones are rejected.

var per_ip := GD.web.rate({"limit": 60, "trusted_proxies": ["127.0.0.1", "172.18.0.0/16"]})

Shutdown

Wait for shutdown with app.shutdown(context). It stops accepting new connections and keep-alive, then waits for in-flight requests. Past the deadline it returns Err.TIMED_OUT but does not kill in-flight requests. Use app.stop() when every connection must close immediately.

func close(app):
	var context := GD.async.context().with_timeout(10.0)
	var stopped := app.shutdown(context)
	if not stopped.ok:
		app.stop()

A handler can observe request completion and disconnection through req.context. with_cancel() and with_timeout() return a child context without changing the parent, and the parent's cancellation reaches the child. To make HTTP, database, process, and other waits cancelable, wrap them with with_context(), passing the context first. The operation result is returned when it finishes first; when the context finishes first, the operation is canceled.

func load(req, db):
	var result = await GD.async.with_context(req.context, db.query_async("SELECT * FROM posts"))
	return result

func main():
	var limited_app := GD.web.app()
	limited_app.limits({"header_bytes": 1048576, "header_values": 500, "header_timeout": 15.0, "body_timeout": 10.0, "job_timeout": 30.0, "jobs": 128})
	return 0

func main():
	var app := GD.web.app()
	app.limits({"body_timeout": 600.0})
	app.route("POST", "/upload", func(req):
		req.limit(1000 * 1000 * 1000)?
		req.save("uploads://package.zip")?
		return GD.web.text("saved")
	)
	return 0 if app.listen(8080, "127.0.0.1").ok else 1

gd --strict --allow-net=127.0.0.1:8080 --mount=uploads=/srv/uploads:rw serve main.gd

Database

The client returned by GD.database.client() handles SQLite and PostgreSQL with the same code. Switching from the embedded SQLite in local development to PostgreSQL in production is done through the driver passed to open().

func main():
	var local := GD.cli.env("DB_DRIVER", "sqlite") == "sqlite"
	var db := GD.database.client()
	db.open({
		"driver": "sqlite" if local else "postgres",
		"path": "user://app.sqlite3",
		"host": "127.0.0.1",
		"database": "app",
		"user": "app",
		"password": GD.cli.env("PGPASSWORD", ""),
	})?
	db.query("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")?
	db.query("INSERT INTO users (id, name) VALUES ($1, $2) ON CONFLICT (id) DO NOTHING", [1, "ada"])?
	var out := db.query("SELECT id, name FROM users WHERE id=$1", [1])?
	print(out.rows[0].name)
	db.close()
	return 0, null

Table creation, INSERT, and SELECT all go through the one query(). It yields a dictionary with columns, rows, and tag, where rows is an array of dictionaries keyed by column name. In the example, out.rows[0].name is ada. SQL values are bound in order as $1, $2, and the spelling is the same on both drivers. SQL is not translated, so use SQL that works on both.

Advance query_rows() with while rows.next(). scan() returns a dictionary keyed by column name and values() returns an array in column order. After next() returns false, inspect err(). Call close() when stopping early.

func list_users(db):
	var rows := db.query_rows("SELECT id, name FROM users ORDER BY id")?
	while rows.next():
		var user := rows.scan()?
		print(user.id, " ", user.name)
	if rows.err() != null:
		return R.err(rows.err())
	return R.ok()

On a constraint violation, result.e.info carries machine-readable details. violation is one of duplicate, not_null, or foreign_key, and columns lists the related column names. On PostgreSQL, code, table, and constraint are included when the server returns them. Values themselves are never kept in info. A failure reported by SQLite itself keeps source="sqlite" and its extended source_code. SQLite's foreign key message has no column names, so columns is empty there.

func save(db):
	var saved := db.query(
		"INSERT INTO users(id,name) VALUES($1,$2)",
		[1, "ada"])
	if not saved.ok and saved.e.info.get("violation") == "duplicate":
		var columns := saved.e.info.get("columns", PackedStringArray())
		print("duplicate columns: ", columns)

Transactions and migrations

To make several updates one success or failure, use transaction(). The callback receives a GDDatabaseTx pinned to one connection. Returning a successful R commits, returning a failed R rolls back.

func save(db, id, title):
	return db.transaction(func(tx):
		tx.query("INSERT INTO posts(id,title) VALUES($1,$2)", [id, title])?
		tx.query("UPDATE counters SET value=value+1 WHERE name='posts'")?
		return R.ok(id)
	)

• Use the given tx in the callback and always return an R. During a transaction, query() on the original client and a nested transaction are rejected.
• A commit failure is returned as a failure.
• Close or cancel before COMMIT begins rolls back; after it begins, the connection closes once the result is settled.
• After the callback finishes, a retained tx no longer accepts new SQL.

To apply a schema in order, pass an array of statements to migrate() instead of splitting SQL on semicolons. If one statement fails, everything rolls back. On success it returns the number of statements applied. Versions and checksums are managed by the application.

func migrate(db):
	return db.migrate([
		"CREATE TABLE posts(id INTEGER PRIMARY KEY, title TEXT NOT NULL)",
		"CREATE INDEX posts_title ON posts(title)",
	])

Scheduled jobs

A job that runs once at a fixed time is an ordinary script, called from the OS's cron or a systemd timer. gd needs no resident scheduler for it.

func collect():
	var now := GD.time.to_iso(GD.time.now())
	GD.file.append_text("store://log.txt", now + "\n")?
	return 0, null

func main():
	collect()?
	return 0, null

gd --strict --mount store=/var/lib/app:rw collect.gd

A job that loops on its own interval is passed to GD.async.spawn() and kept resident with gd serve. Work passed to spawn() keeps running after main() returns.

func every(sec, fn):
	while true:
		await GD.async.sleep(sec)
		fn.call()

func collect():
	print(GD.time.to_iso(GD.time.now()))

func main():
	var _job := GD.async.spawn(every.bind(60.0, collect))
	return 0

gd serve schedule.gd

Stop it by ending the process. It is resident like a Web server, so serve is needed here too.

Official extension modules

The core stays small. Features specific to an external service are added as GDScript packages or GDExtensions only to projects that need them.

Each document lists public classes, methods, return values, limits, and strict-mode examples. Because they are optional, they are not part of the API reference generated from the core alone.

• Extensions added with gd add are trusted and loaded at startup, so no flag is needed. --allow-net for their target is still needed.
• --allow-ext and --deny-ext apply when a script loads one while running with GDExtensionManager.load_extension().
• An added extension runs with the same privileges as the process, so pin the versions you trust in gd.lock and commit it.

Packages and distribution

When scripts multiply or you start using other packages, create gd.json with gd init. Dependencies are pinned with gd.json and gd.lock.

gd init
gd search discord bot
gd add gd:@scope/script-package@^1.0.0
gd add ext:@scope/name@^1.0.0
gd add short-name https://example.com/module.gd
gd install --frozen
gd task test

Using packages

An installed package is read from pkg://<alias>/, using the alias chosen by the consumer.

@import hello

• pkg:// points into the per-user shared cache and copies nothing into the project.
• A dependency named in gd.json but absent from the cache is fetched on the first run. Under --strict the registry needs --allow-net.
• The default alias of gd add is the package name with - and . turned into _, so it is an identifier. Aliases that are engine classes or keywords are refused.
• Commit gd.json and gd.lock. gd init writes pkg/ into .gitignore.
• --frozen does not change the lock. For an offline target, fetch first where a network is available, and add --cached-only.
• When install, add, or update fails partway, project files and the lock are restored.
• The lock is bound to its registry. Switching to another registry requires explicit lock migration.

Short import syntax

@import is the short form of const Name = preload(...).

It is useful even without external dependencies: see samples/packages for a real registry dependency and its lockfile.

@import greet
@import "./util"
@import greet/style as theme

• Unquoted names resolve only aliases declared in the imports of gd.json. Files with the same name are not searched.
• Quote relative files, starting with ./ or ../. The .gd extension is optional. If a file and directory share a name, specify the file as "./util.gd".
• Without as, the identifier is the last segment as written, and a directory holding mod.gd binds its directory name.
• gd fmt keeps @import as it is.
• Upstream Godot does not know @import, so files shared with Godot should spell out const and preload.

Creating a package

A package is one project rooted at its gd.json. gd init @scope/name seeds mod.gd and a test, gd test runs it, and gd publish releases it.

{"name":"@scope/hello","version":"1.0.0","main":"src/mod.gd","include":["src"]}

gd publish
gd add hello gd:@scope/hello@^1.0.0

• The entry is mod.gd. For multiple files, list files or directories in include.
• The main file's directory becomes the package root, so relative preloads inside the package keep working.
• A package may use other registry packages through the imports of its own gd.json. gd publish records those imports in the registry.
• class_name may be published. Installation checks for conflicts between classes of the same name and rolls everything back on a conflict.
• Setting godot to true in gd.json is the author's declaration that the package runs on upstream Godot without gd's own API, and gd search marks it [godot].

A package under development is added from a local path with gd add ../path. Its alias comes from the name in its gd.json. The checkout is copied under pkg/<alias>/ and copied again on the next run whenever its content fingerprint changes. Files starting with ., pkg/, tmp/, subdirectories holding a gd.json, and token are not copied. gd publish turns a local import into its registry range when the target's gd.json has name and version, and refuses it otherwise.

Dependency resolution

gd install resolves the whole dependency graph. It picks a version in this order: the version gd.lock pins, a version already chosen this time that satisfies the range, then the newest match in the registry.

gd.lock also records the resolved imports configuration. A run after a configuration change uses the same resolver instead of silently loading an outdated version. --frozen rejects mismatched requests. When multiple aliases name one package, the lexicographically first alias selects its copy directory.

• Pure GDScript packages coexist as distinct versions.
• A native extension loads only once per process, so it is unified to one version. If the ranges cannot agree, it stops before anything is fetched.
• There is no mechanism for plugins that share one host instance (peer dependencies).
• The canonical path of a registry package is pkg://@scope/name@version/. pkg://<alias>/ expands to it through the imports of the package the script belongs to. The same alias may name different versions in different packages, and one version is one script however it is reached.
• gd.lock also records each package's resolved imports, and gd info lists them.
• gd remove and gd update drop what no package uses any more from gd.lock and pkg/.
• A change in search ranking does not affect installation or lock verification for a known package.

Sharing a location with Godot

To share a project with tools that only read res://, such as upstream Godot, set "place": "project" in gd.json. Packages are copied under pkg/<alias>/, and both pkg:// and res://pkg/ point there. A package that only other packages use goes under pkg/@scope/name@version/.

• Where project.godot exists, place defaults to project and no .gitignore is written. Commit pkg/ so teammates without gd can open the project.
• Installation rewrites res:// references written in preload, load, and extends to the placement. Strings, comments, and paths built at run time are not rewritten.
• place only selects where files live. It does not convert gd's own API or syntax for Godot. Shared source should use standard syntax and relative preloads.

Native extension packages

• A native extension needs real files to load, so it lives under pkg/<alias>/ whatever place is.
• A script may only name classes of the extensions its own package imports with ext:: the project's gd.json for project scripts, the package's own imports for package scripts.
• An extension outside the registry is usable by project scripts only.
• A registry package's extension that registers a class missing from its manifest's [classes] stops startup.
• Fetch on the target OS, or run gd compile on the target OS.

Settings and environment variables

gd.json has these ten settings.

gd reads these environment variables. A script that reads the environment needs the names allowed with --allow-env.

Remote packages and registries use HTTPS. A development registry on loopback may also use HTTP. Fetched packages and native libraries are checked against the SHA-256 in the registry index. A .gdextension manifest is limited to 16 MiB, and all files in a package to 500 MiB in total.

Distributing a single executable

compile collects scripts, views, static files, migrations, dependency packages, and the target OS's GDExtensions into one executable. The target needs no cache.

gd compile -o app main.gd
./app

• Every package gd.json names, and every package those import, is embedded.
• An embedded Web app can also stay resident with ./app serve --no-scene-tree --allow-net.
• From a local path package, files starting with . such as .env and the token in gd.json are left out.
• Do not embed secrets in source. compile excludes .env, but values written in source remain in the executable.

Scope and reporting

gd is a public release before the API has settled. Do not assume backward compatibility. Changes and the Godot version used as the base are recorded in the CHANGELOG. gd is not an official product of the Godot Foundation or the Godot Engine project.

Report bugs in Issues. Report vulnerabilities that should not be public through GitHub private reporting.

APIリファレンスAPI reference

gd固有の入口と、そこから返るobjectの署名です。Godot由来の型はGodotのclass referenceを参照してください。

Signatures of gd's own entry points and of the objects they return. For Godot classes, see the Godot class reference.

一致するAPIがありません。No matching API.