# Skein

A Bevy Plugin and a Blender extension for improving the efficiency of Bevy/Blender workflows: Store reflected component data in glTF extras using software like Blender, and insert components based on those extras.

tldr:

1. Reflect component data in Bevy
2. Apply Bevy Components to objects, meshes, or materials in Blender
3. Export to glTF
4. Components are instantiated when spawning in Bevy

## Quickstart

Add the plugin and reflect component data (`reflect(Component)` is important!)

```rust no_run
use bevy::prelude::*;
use bevy_skein::SkeinPlugin;

fn main() {
    App::new()
        .add_plugins((
            DefaultPlugins,
            SkeinPlugin::default(),
        ))
        .run();
}

#[derive(Component, Reflect, Debug)]
#[reflect(Component)]
struct Player {
    name: String,
    power: f32,
    test: i32,
}
```

- Install the Blender Extension
  - Drag and drop the installation link from the website, as detailed in the [installation](https://bevyskein.dev/docs/installation) docs.
- Fetch the Bevy registry using the Blender Operator
- Select and apply a component
- Export to glTF
- Spawn a Scene from the glTF file, which will have components instantiated

```rust ignore
commands.spawn(SceneRoot(asset_server.load(
    GltfAssetLabel::Scene(0).from_asset("my_export.gltf"),
)));
```

## Use Cases

- Apply Bevy Components in Blender
- Replace materials from Blender with materials defined in Bevy ([example](examples/replace_material.rs))
- Use Blender Drivers to power Bevy Component values

## Compatible Bevy versions

The Bevy plugin and the Blender addon have separate release cycles and versions. The contact points are the BRP Registry API format for ingesting Bevy data into Blender and the glTF format we store data in to get data back into Bevy. These clearly-defined API points mean the Bevy Plugin and the Blender addon can evolve independently.

All versions of `bevy_skein` are currently compatible with all versions of the `skein` Blender addon. However, the extension format export support was added in addon verison `0.1.14`, and is only supported by `Bevy 0.18+`.

| Bevy version | `bevy_skein` version |
| :----------- | :------------------- |
| `0.19`       | `0.6`                |
| `0.18`       | `0.5`                |
| `0.17`       | `0.3-4`              |
| `0.16`       | `0.2`                |
| `0.15`       | `0.1`                |

The skein addon current release and main branch support as far back as 4.2. Upgrading Blender to new versions requires updating the addon to at least the minimum version here as well.

| Blender version  | `skein` minimum addon version | notes                                                                         |
| :--------------- | :---------------------------- | ----------------------------------------------------------------------------- |
| `>=5.2`          | `0.1.16`                      | upstream glTF exporter has critical bug fixes for `extensions` export feature |
| `>=5.0`          | `0.1.13`                      |                                                                               |
| `>=4.2 && < 5.0` | `0.1.0`                       |                                                                               |
| `>=4.2`          | branch `main`                 |                                                                               |

## Why is it named Skein?

Its a tool that aims to improve the efficiency of Bevy (group of birds) and Blender workflows.

> A flock of wild geese or swans in flight, typically in a V-shaped formation.
>
> - [Oxford Dictionary](https://web.archive.org/web/20190107072506/https://en.oxforddictionaries.com/definition/skein)

> A V formation is a symmetric V- or chevron-shaped flight formation. In nature, it occurs among geese, swans, ducks, and other migratory birds, improving their energy efficiency
>
> - [Wikipedia](https://en.wikipedia.org/wiki/V_formation)

Its also thread/yarn related which is cool too.