godot-plugin-std

A Godot 4.7+ plugin providing standard GDScript functions and components.

Usage

Add as a dependency

Add this repository's dist branch as a submodule of a Godot project, typically under the addons directory:

git submodule add -b dist https://github.com/coffeebeats/godot-plugin-std addons/std

Each release is a commit on dist, tagged dist/vX.Y.Z. Versions follow semantic versioning independently of Godot; raising the minimum Godot version is a major release.

Plugin API

config

The config directory contains replacement classes for ConfigFile, which shouldn't be used due to security issues. The Config class is an in-memory, typed, categorized key-value store. To synchronize the configuration data to the file system, use ConfigWithFileSync instead.

fsm

The fsm directory contains an implementation of a hierarchical StateMachine suited for most applications. State machines are constructed as a scene with the node hierarchy used to define the level of state nesting. Each state should utilize a custom script to implement its behavior, and users can input events into the state machine to trigger transitions or update states.

Additionally, the StateMachine implementation provides a "compaction" process which is enabled by default. The state machine extracts the scripts of all child State nodes and stores those objects internally without adding children to the scene tree. This improves performance, especially for state machines which are instantiated often.

input

Note

GodotSteam is a peer-dependency for Steam-backed implementations of certain classes (e.g. JoypadMonitor and multiple StdInputDevice components). The GodotSteam addon must be installed alongside this one, from the dist branch of coffeebeats/GodotSteam.

The input directory contains types for setting up an action set-based input system, along with abstractions for device and player slot APIs. When used, both Steam and Godot-backed implementations can be easily switched between.

iter

The iter directory contains helpful functions for interacting with sequences and collections of various types.

scene

The scene directory contains an implementation of a StateMachine specialized for declaratively managing scene transitions. See the examples folder for a sample main scene.

Development

Setup

The following instructions outline how to get the project set up for local development:

1. Clone this repository using the --recurse-submodules flag, ensuring all submodules are initialized. Alternatively, run git submodule sync to update all submodules to latest.
2. Follow the instructions to install gdenv. Then, install the pinned version of Godot with gdenv i.
3. Install uv, then run uv sync. That installs the Python tooling from uv.lock, and downloads the interpreter named by .python-version if the machine has none. Invoke each tool as uv run <tool>.
4. The edit checks and godot-check come from the godot agent plugin, declared in .claude/settings.json for Claude Code and .codex/config.toml for Codex. Claude Code installs it once per machine with claude plugin install godot@godot-infra --scope project. Codex installs it itself once the folder is trusted, then asks you to trust the edit hook in /hooks, and asks again whenever that hook changes — until you do, it silently does nothing. If the hook or godot-check goes missing, see the "Agent plugin" section of godot-infra's README.

Code submission

When submitting code for review, ensure the following requirements are met:

1. The project adheres as closely as possible to the official GDScript style guide.

2. The project is correctly formatted using gdformat:

   uv run gdformat --check .

3. All gdlint linter warnings are addressed:

   uv run gdlint .

4. All Gut unit tests pass:

   godot \
       --headless \
       -s addons/gut/gut_cmdln.gd \
       -gdir="res://" \
       -ginclude_subdirs \
       -gprefix="" \
       -gsuffix="_test.gd" \
       -gexit

Releasing

Semantic Versioning is used for versioning and Conventional Commits is used for commit messages. A release-please integration via GitHub Actions automates releases.

Version history

See CHANGELOG.md.

License

MIT License