From 37d2a9f0e92fd1fc058a34e485f4b9d5defcb599 Mon Sep 17 00:00:00 2001 From: David Chavez Date: Mon, 23 Feb 2026 17:25:21 +0100 Subject: [PATCH 01/10] Start anew --- .cursor/rules/devenv-workflow.mdc | 21 + book/src/SUMMARY.md | 71 +-- book/src/core-concepts/chapter-1.md | 3 + book/src/core-concepts/chapter-2.md | 3 + book/src/core-concepts/index.md | 3 + book/src/debugging/index.md | 83 --- book/src/getting-started/basic-concepts.md | 245 --------- book/src/getting-started/examples.md | 18 - book/src/getting-started/index.md | 6 - book/src/getting-started/installation.md | 224 -------- book/src/getting-started/plugins.md | 275 ---------- book/src/input/bevy-vs-godot.md | 246 --------- book/src/input/index.md | 4 - book/src/input/signals.md | 323 ----------- book/src/introduction.md | 53 +- book/src/migration/index.md | 9 - book/src/migration/v0.10-to-v0.11.md | 385 ------------- book/src/migration/v0.6-to-v0.7.md | 518 ------------------ book/src/migration/v0.7-to-v0.8.md | 393 ------------- book/src/migration/v0.8-to-v0.9.md | 233 -------- book/src/migration/v0.9-to-v0.10.md | 249 --------- book/src/part-1/chapter-1.md | 3 + book/src/part-1/chapter-2.md | 3 + book/src/part-1/index.md | 3 + book/src/part-2/chapter-1.md | 1 + book/src/part-2/chapter-2.md | 1 + book/src/part-2/index.md | 1 + book/src/part-3/chapter-1.md | 3 + book/src/part-3/index.md | 3 + book/src/platform-targets/android.md | 94 ---- book/src/platform-targets/index.md | 5 - book/src/profiling/profiling.md | 48 -- book/src/project-transition/index.md | 6 - .../transitional-mailbox-bridge.md | 94 ---- .../custom-nodes/automatic-markers.md | 38 -- book/src/scene-tree/custom-nodes/index.md | 14 - .../nodes-from-components-and-bundles.md | 95 ---- .../property-mapping-with-bevy-bundle.md | 185 ------- book/src/scene-tree/index.md | 5 - book/src/scene-tree/querying.md | 182 ------ book/src/scene-tree/spawning-scenes.md | 198 ------- book/src/scene-tree/timing.md | 91 --- book/src/testing/index.md | 332 ----------- book/src/threading/index.md | 54 -- book/src/timing/index.md | 175 ------ book/src/transforms/custom-sync.md | 416 -------------- book/src/transforms/index.md | 93 ---- book/src/transforms/sync-modes.md | 208 ------- devenv.nix | 11 + 49 files changed, 76 insertions(+), 5651 deletions(-) create mode 100644 .cursor/rules/devenv-workflow.mdc create mode 100644 book/src/core-concepts/chapter-1.md create mode 100644 book/src/core-concepts/chapter-2.md create mode 100644 book/src/core-concepts/index.md delete mode 100644 book/src/debugging/index.md delete mode 100644 book/src/getting-started/basic-concepts.md delete mode 100644 book/src/getting-started/examples.md delete mode 100644 book/src/getting-started/index.md delete mode 100644 book/src/getting-started/installation.md delete mode 100644 book/src/getting-started/plugins.md delete mode 100644 book/src/input/bevy-vs-godot.md delete mode 100644 book/src/input/index.md delete mode 100644 book/src/input/signals.md delete mode 100644 book/src/migration/index.md delete mode 100644 book/src/migration/v0.10-to-v0.11.md delete mode 100644 book/src/migration/v0.6-to-v0.7.md delete mode 100644 book/src/migration/v0.7-to-v0.8.md delete mode 100644 book/src/migration/v0.8-to-v0.9.md delete mode 100644 book/src/migration/v0.9-to-v0.10.md create mode 100644 book/src/part-1/chapter-1.md create mode 100644 book/src/part-1/chapter-2.md create mode 100644 book/src/part-1/index.md create mode 100644 book/src/part-2/chapter-1.md create mode 100644 book/src/part-2/chapter-2.md create mode 100644 book/src/part-2/index.md create mode 100644 book/src/part-3/chapter-1.md create mode 100644 book/src/part-3/index.md delete mode 100644 book/src/platform-targets/android.md delete mode 100644 book/src/platform-targets/index.md delete mode 100644 book/src/profiling/profiling.md delete mode 100644 book/src/project-transition/index.md delete mode 100644 book/src/project-transition/transitional-mailbox-bridge.md delete mode 100644 book/src/scene-tree/custom-nodes/automatic-markers.md delete mode 100644 book/src/scene-tree/custom-nodes/index.md delete mode 100644 book/src/scene-tree/custom-nodes/nodes-from-components-and-bundles.md delete mode 100644 book/src/scene-tree/custom-nodes/property-mapping-with-bevy-bundle.md delete mode 100644 book/src/scene-tree/index.md delete mode 100644 book/src/scene-tree/querying.md delete mode 100644 book/src/scene-tree/spawning-scenes.md delete mode 100644 book/src/scene-tree/timing.md delete mode 100644 book/src/testing/index.md delete mode 100644 book/src/threading/index.md delete mode 100644 book/src/timing/index.md delete mode 100644 book/src/transforms/custom-sync.md delete mode 100644 book/src/transforms/index.md delete mode 100644 book/src/transforms/sync-modes.md diff --git a/.cursor/rules/devenv-workflow.mdc b/.cursor/rules/devenv-workflow.mdc new file mode 100644 index 00000000..395bf36e --- /dev/null +++ b/.cursor/rules/devenv-workflow.mdc @@ -0,0 +1,21 @@ +--- +description: Use devenv for all build, run, and compilation tasks +alwaysApply: true +--- + +# devenv Workflow + +This project uses [devenv](https://devenv.sh/) to manage tooling, environment variables, and scripts. All build and run operations must go through devenv. + +## Key Commands + +| Task | Command | +|------|---------| +| Run all validations (JS + native) | `validate` | + +## Rules + +- Always use devenv scripts instead of raw commands. The scripts set required environment variables. +- When adding a new example, add corresponding `run-` scripts to `devenv.nix`, and update the `enterShell` help text. +- When adding a new dependency or tool, add it to the `packages` list in `devenv.nix`. +- Keep `devenv.nix` as the single source of truth for all project scripts and tooling. diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 0554bbb1..10e043d4 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -1,71 +1,20 @@ -- [Introduction](./introduction.md) - ---- - -- [Getting Started](./getting-started/index.md) - - [Installation](./getting-started/installation.md) - - [Basic Concepts](./getting-started/basic-concepts.md) - - [Plugin System](./getting-started/plugins.md) - - [Examples](./getting-started/examples.md) - ---- - -- [Scene Tree](./scene-tree/index.md) - - [Initialization and Timing](./scene-tree/timing.md) - - [Querying with Node Type Markers](./scene-tree/querying.md) - - [Custom Nodes](./scene-tree/custom-nodes/index.md) - - [Automatic Markers](./scene-tree/custom-nodes/automatic-markers.md) - - [Property Mapping (BevyBundle)](./scene-tree/custom-nodes/property-mapping-with-bevy-bundle.md) - - [Nodes from Components and Bundles](scene-tree/custom-nodes/nodes-from-components-and-bundles.md) - - [Spawning Scenes](scene-tree/spawning-scenes.md) - ---- - -- [Transform System](./transforms/index.md) - - [Sync Modes](./transforms/sync-modes.md) - - [Custom Transform Sync](./transforms/custom-sync.md) - ---- - -- [Input Handling](./input/index.md) - - [Bevy vs Godot Input](./input/bevy-vs-godot.md) - - [Signal Handling](./input/signals.md) - ---- - -- [Timing & Schedules](./timing/index.md) - ---- - -- [Threading & Main Thread Access](./threading/index.md) - ---- +# Summary -- [Bevy Godot Profiling](./profiling/profiling.md) - ---- - -- [Debugging](./debugging/index.md) - ---- - -- [Integration Testing](./testing/index.md) +- [Introduction](./introduction.md) --- -- [Platform Targets](./platform-targets/index.md) - - [Android](./platform-targets/android.md) +- [Part 1: Getting Started](./part-1/index.md) + - [Chapter 1](./part-1/chapter-1.md) + - [Chapter 2](./part-1/chapter-2.md) --- -- [Project Transition Patterns](./project-transition/index.md) - - [Transitional Mailbox Bridge (Godot -> Bevy Messages)](./project-transition/transitional-mailbox-bridge.md) +- [Part 2: Core Concepts](./core-concepts/index.md) + - [Chapter 1](./core-concepts/chapter-1.md) + - [Chapter 2](./core-concepts/chapter-2.md) --- -- [Migration Guides](./migration/index.md) - - [v0.10 to v0.11](./migration/v0.10-to-v0.11.md) - - [v0.9 to v0.10](./migration/v0.9-to-v0.10.md) - - [v0.8 to v0.9](./migration/v0.8-to-v0.9.md) - - [v0.7 to v0.8](./migration/v0.7-to-v0.8.md) - - [v0.6 to v0.7](./migration/v0.6-to-v0.7.md) +- [Part 3: Advanced Topics](./part-3/index.md) + - [Chapter 1](./part-3/chapter-1.md) diff --git a/book/src/core-concepts/chapter-1.md b/book/src/core-concepts/chapter-1.md new file mode 100644 index 00000000..45cd1587 --- /dev/null +++ b/book/src/core-concepts/chapter-1.md @@ -0,0 +1,3 @@ +# Chapter 1 + +*Add your content here.* diff --git a/book/src/core-concepts/chapter-2.md b/book/src/core-concepts/chapter-2.md new file mode 100644 index 00000000..7bce191c --- /dev/null +++ b/book/src/core-concepts/chapter-2.md @@ -0,0 +1,3 @@ +# Chapter 2 + +*Add your content here.* diff --git a/book/src/core-concepts/index.md b/book/src/core-concepts/index.md new file mode 100644 index 00000000..42002741 --- /dev/null +++ b/book/src/core-concepts/index.md @@ -0,0 +1,3 @@ +# Part 2: Core Concepts + +*Add an overview of this part here.* diff --git a/book/src/debugging/index.md b/book/src/debugging/index.md deleted file mode 100644 index 41c1e937..00000000 --- a/book/src/debugging/index.md +++ /dev/null @@ -1,83 +0,0 @@ -# Debugging - -Godot-bevy includes a built-in entity inspector that displays your Bevy ECS state directly in the Godot editor. When running your game, you can see all entities, their components, and parent-child relationships in real time. - -## Entity Inspector - -The inspector appears as a "Entities" tab next to the Scene tab in the editor's left dock. It shows: - -- All Bevy entities with their names and appropriate icons -- Entity hierarchy (scene tree via `GodotChildOf`/`GodotChildren`) -- Components attached to each entity with type-specific icons -- Entities with Godot nodes show their node type icon (e.g., Node2D, Sprite2D) - -### Enabling the Inspector - -The inspector is included in `GodotDefaultPlugins`: - -```rust -#[bevy_app] -fn build_app(app: &mut App) { - app.add_plugins(GodotDefaultPlugins); -} -``` - -Or add it individually: - -```rust -#[bevy_app] -fn build_app(app: &mut App) { - app.add_plugins(GodotDebuggerPlugin); -} -``` - -### Configuration - -Control the inspector through the `DebuggerConfig` resource: - -```rust -fn configure_debugger(mut config: ResMut) { - config.enabled = true; // Toggle on/off - config.update_interval = 0.5; // Seconds between updates -} -``` - -### Using the Inspector - -1. Open your project in Godot -2. Look for the "Bevy" tab in the left dock (next to Scene/Import) -3. Run your game -4. The inspector populates with your ECS state - -Entities display as a tree. Click to expand and see: -- Child entities (nested under parents) -- Components (shown in blue, with full type path on hover) - -Entity icons indicate the Godot node type when a marker component is present (e.g., `Node2DMarker` shows the Node2D icon). Entities with a `GodotNodeHandle` but no specific marker show the Godot logo. - -### Debugging Hierarchy Issues - -The inspector mirrors the Godot scene tree via `GodotChildOf`/`GodotChildren`, not Bevy's -built-in `ChildOf`/`Children`. If an entity appears at the wrong level: - -1. Verify the Godot node was in the scene tree when the entity was created -2. If you reparent nodes, wait a frame for the hierarchy update to process - -### Performance Considerations - -The inspector sends data every 0.5 seconds by default. For games with thousands of entities, you may want to increase the interval or disable it in release builds: - -```rust -fn setup_debugger(mut config: ResMut) { - #[cfg(debug_assertions)] - { - config.enabled = true; - config.update_interval = 1.0; // Slower updates for large scenes - } - - #[cfg(not(debug_assertions))] - { - config.enabled = false; - } -} -``` diff --git a/book/src/getting-started/basic-concepts.md b/book/src/getting-started/basic-concepts.md deleted file mode 100644 index 67c18497..00000000 --- a/book/src/getting-started/basic-concepts.md +++ /dev/null @@ -1,245 +0,0 @@ -# Basic Concepts - -Before diving into godot-bevy development, it's important to understand the key concepts that make this integration work. - -## The Hybrid Architecture - -godot-bevy creates a bridge between two powerful systems: - -### Godot Side -- **Scene tree** with nodes -- **Visual editor** for level design -- **Asset pipeline** for resources -- **Rendering engine** -- **Physics engine** - -### Bevy Side -- **Entity Component System (ECS)** -- **Systems** for game logic -- **Components** for data -- **Resources** for shared state -- **Schedules** for execution order - -### The Bridge -godot-bevy seamlessly connects these worlds: -- Godot nodes ↔ ECS entities -- Node properties ↔ Components -- Signals → Events -- Resources ↔ Assets - -## Core Components - -### Entities -In godot-bevy, Godot nodes are automatically registered as ECS entities: - -```rust -// When a node is added to the scene tree, -// it becomes queryable as an entity -fn find_player( - query: Query<&Name, With>, -) { - for name in query.iter() { - if name.as_str() == "Player" { - // Found the player node! - } - } -} -``` - -### Components -Components store data on entities. godot-bevy provides several built-in components: - -- `GodotNodeHandle` - Reference to the Godot node -- `Name` - Node name -- `Groups` - Godot node groups - -For collision detection, use the `Collisions` system param (see [Plugins](./plugins.md)). - -### Systems -Systems contain your game logic and run on a schedule: - -```rust -fn movement_system( - time: Res