Transform System Overview

The transform system is one of the most important aspects of godot-bevy, handling position, rotation, and scale synchronization between Bevy ECS and Godot nodes.

Three Approaches to Movement

godot-bevy supports three distinct approaches for handling transforms and movement:

1. ECS Transform Components

Use standard bevy Transform components with automatic syncing from ECS to Godot. This is the default approach. You update transforms in ECS, and we take care of syncing the transforms to the Godot side at the end of each frame. You can also configure bi-directional synchronization, or disable all synchronization.

#![allow(unused)]
fn main() {
use godot_bevy::prelude::*;

fn move_entity(mut query: Query<&mut Transform>) {
    for mut transform in query.iter_mut() {
        transform.translation.x += 1.0;
    }
}
}

2. Direct Godot Physics

Use GodotNodeHandle to directly control Godot physics nodes. Perfect for physics-heavy games. This usually means you're calling Godot's move methods to have it handle physics for you.

#![allow(unused)]
fn main() {
fn move_character(mut query: Query<&mut GodotNodeHandle>) {
    for mut handle in query.iter_mut() {
        let mut body = handle.get::<CharacterBody2D>();
        body.set_velocity(Vector2::new(100.0, 0.0));
        body.move_and_slide();
    }
}
}

3. Hybrid Approach

Allows for modifying transforms both from Godot's side and from ECS side. Useful during migration from a GDScript project to godot-bevy or when you're using Godot's physics methods but still want transforms to be updated for reading on the ECS side.

Default Behavior

By default, godot-bevy operates in one-way sync mode:

  • ✅ Writing enabled: Changes to ECS transform components update Godot nodes
  • ❌ Reading disabled: Changes to Godot nodes don't update ECS components

This is optimal for pure ECS applications where all movement logic lives in Bevy systems.

When to Use Each Approach

Use ECS Transforms When:

  • Building a pure ECS game
  • Movement logic is simple (no complex physics)
  • You want clean separation between logic and presentation
  • Performance of transform sync is acceptable

Use Direct Godot Physics When:

  • Building platformers or physics-heavy games
  • You need Godot's collision detection features
  • Using CharacterBody2D/3D or RigidBody2D/3D
  • You want zero transform sync overhead

Use Hybrid Approach When:

  • Migrating an existing Godot project to ECS
  • Some systems need ECS transforms, others need physics
  • Gradually transitioning from GDScript to Rust

Key Concepts

Transform Components

Use standard bevy Transform components. This is the default approach. You update transforms in ECS, and we take care of syncing the transforms to the Godot side at the end of each frame. You can also configure bi-directional synchronization, or disable all synchronization.

Sync Modes

The transform system supports three synchronization modes:

  1. Disabled - No syncing, no transform components created
  2. OneWay - ECS → Godot only (default)
  3. TwoWay - ECS ↔ Godot bidirectional sync

Performance Considerations

Each approach has different performance characteristics:

  • ECS Transforms: Small overhead from syncing
  • Direct Physics: Zero sync overhead
  • Hybrid: Depends on usage pattern

Next Steps