Write quickstart

README.md

@@ -2,7 +2,7 @@
 [![License](https://img.shields.io/crates/l/blenvy)](https://github.com/kaosat-dev/Blenvy/blob/main/LICENSE.md)
 [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/F1F5TO32O)
 
-# BLENVY: a friendly Blender <=> Bevy workflow !
+# BLENVY: a friendly Blender <=> Bevy workflow
 
 ![demo](./docs/blender_bevy.png)
 
@@ -13,6 +13,10 @@ inside Blender. Aka "Blender as editor for Bevy"
 
 It also allows you to setup 'blueprints' in Blender by using collections (the recomended way to go most of the time), or directly on single use objects .
 
+## Quickstart
+
+Want to jump right in? See the [quickstart guide](./docs/quickstart/readme.md) for how to setup a basic project as fast as possible.
+
 ## Features
 
 * Useful if you want to use Blender as your Editor
@@ -24,7 +28,7 @@ It also allows you to setup 'blueprints' in Blender by using collections (the re
 * hot reload of your levels & blueprints
 * minimal setup & code, you can have something basic running fast
 * minimal dependencies: Bevy, Serde & Ron only !
-* opensource 
+* opensource
 
 > If you were previously using the individual bevy_gltf_xxx crates & Blender add-ons please see the [migration guide](./Migration_guide.md)
 
@@ -32,26 +36,26 @@ It also allows you to setup 'blueprints' in Blender by using collections (the re
 
 One crate to rule them all !
 
-- [blenvy](./crates/blenvy/) This crate allows you to 
+* [blenvy](./crates/blenvy/) This crate allows you to
-    * define components direclty inside gltf files and instanciate/inject the components on the Bevy side.
+  * define components direclty inside gltf files and instanciate/inject the components on the Bevy side.
-    * export your project's Bevy registry to json, in order to be able to generate custom component UIs on the Blender side in the Blender [blenvy](./tools/blenvy/README.md) add-on
+  * export your project's Bevy registry to json, in order to be able to generate custom component UIs on the Blender side in the Blender [blenvy](./tools/blenvy/README.md) add-on
-    * define Blueprints/Prefabs for Bevy inside gltf files and spawn them in Bevy. With the ability to override and add components when spawning, efficient "level" loading etc
+  * define Blueprints/Prefabs for Bevy inside gltf files and spawn them in Bevy. With the ability to override and add components when spawning, efficient "level" loading etc
-    * the ability to save & load your game state in a relatively simple way, by leveraging the blueprint functionality to only save a minimal subset of dynamic data, seperating dynamic & static parts of levels etc.
+  * the ability to save & load your game state in a relatively simple way, by leveraging the blueprint functionality to only save a minimal subset of dynamic data, seperating dynamic & static parts of levels etc.
 
     OLD videos:
     There is a [video tutorial/explanation](https://youtu.be/-lcScjQCA3c) if you want, or you can read the crate docs.
     There is a [video tutorial/explanation](https://youtu.be/CgyNtwgYwdM) for this one too, or you can read the crate docs
 
-    The examples for the crate are [here](./examples/blenvy/) 
+    The examples for the crate are [here](./examples/blenvy/)
 
 ## Tools
 
 ### Blender: blenvy
 
-- an all in one [Blender addon](./tools/blenvy/README.md) for the Blender side of the workflow: 
+* an all in one [Blender addon](./tools/blenvy/README.md) for the Blender side of the workflow:
-    - allow easilly adding & editing Bevy components , using automatically generated UIs for each component
+  * allow easilly adding & editing Bevy components , using automatically generated UIs for each component
-    - automatically exports your level/world from Blender to gltf whenever you save your Blend file
+  * automatically exports your level/world from Blender to gltf whenever you save your Blend file
-    - automatically export your [Gltf blueprints](./crates/blenvy/README.md) & assets
+  * automatically export your [Gltf blueprints](./crates/blenvy/README.md) & assets
 
 ## Examples
 
@@ -67,37 +71,36 @@ you can find all examples, [here](./examples/blenvy)
 
 The workflow goes as follows (once you got your Bevy code setup)
 
-
+* create & register all your components you want to be able to set from the Blender side (this is basic Bevy, no specific work needed)
-- create & register all your components you want to be able to set from the Blender side (this is basic Bevy, no specific work needed)
 
 ![component registration](./docs/component_registration.png)
 
-- setup & then use the Blenvy [Bevy crate](./crates/blenvy/README.md) 
+* setup & then use the Blenvy [Bevy crate](./crates/blenvy/README.md)
-- setup & then use the Blenvy [Blender add-on](./tools/blenvy/README.md) 
+* setup & then use the Blenvy [Blender add-on](./tools/blenvy/README.md)
-- iterate 
+* iterate
-- have fun !
+* have fun !
 
-- then add your components to objects in Blender **with a nice UI** see [here](./README-workflow-ui.md) for more details 
+* then add your components to objects in Blender **with a nice UI** see [here](./README-workflow-ui.md) for more details
 
 ## Limitations / issues
 
-- Some of `avian` or `bevy_rapier` /physics code / ways to define colliders could perhaps be done better/visually within Blender
+* Some of `avian` or `bevy_rapier` /physics code / ways to define colliders could perhaps be done better/visually within Blender
 
 ## Contributors
 
 Thanks to all the contributors helping out with this project ! Big kudos to you, contributions are always appreciated ! :)
 
-- [GitGhillie](https://github.com/GitGhillie)
+* [GitGhillie](https://github.com/GitGhillie)
-- [Azorlogh](https://github.com/Azorlogh)
+* [Azorlogh](https://github.com/Azorlogh)
-- [BSDGuyShawn](https://github.com/BSDGuyShawn)
+* [BSDGuyShawn](https://github.com/BSDGuyShawn)
-- [yukkop](https://github.com/yukkop)
+* [yukkop](https://github.com/yukkop)
-- [killercup](https://github.com/killercup)
+* [killercup](https://github.com/killercup)
-- [janhohenheim ](https://github.com/janhohenheim)
+* [janhohenheim](https://github.com/janhohenheim)
-- [BUGO07](https://github.com/BUGO07)
+* [BUGO07](https://github.com/BUGO07)
 
 ## License
 
 This repo, all its code, contents & assets is Dual-licensed under either of
 
-- Apache License, Version 2.0, ([LICENSE-APACHE](./LICENSE_APACHE.md) or https://www.apache.org/licenses/LICENSE-2.0)
+* Apache License, Version 2.0, ([LICENSE-APACHE](./LICENSE_APACHE.md) or <https://www.apache.org/licenses/LICENSE-2.0>)
-- MIT license ([LICENSE-MIT](./LICENSE_MIT.md) or https://opensource.org/licenses/MIT)
+* MIT license ([LICENSE-MIT](./LICENSE_MIT.md) or <https://opensource.org/licenses/MIT>)

docs/quickstart/readme.md

@@ -0,0 +1,285 @@
+# Quickstart
+
+This guide assumes you use Blender 4.2 or newer.
+
+> [!NOTE]  
+> This is not a Blender tutorial. No worries, we will make sure you find all necessary buttons to click, but we will not explain in detail what Blender concepts like "collections" or "scenes" are. If you are not familiar with Blender, you might want to look up some basic tutorials first.
+
+## Install the Blender Addon
+
+- Download `blenvy.zip` from the [release page](https://github.com/kaosat-dev/Blenvy/releases/tag/blenvy_v0.1.0_pre_alpha)
+- Open Blender
+- Drag and drop `blenvy.zip` into Blender
+  - <details>
+    <summary>This window should show up</summary>
+
+    <img src="img/install.png" width=50%>
+
+    </summary>
+    </details>
+- Leave all settings as is and click on `OK`
+
+Leave the scene open, we will get back to it later.
+
+## Setup the Bevy side
+
+Run the following commands:
+
+```sh
+cargo new my_game
+cd my_game
+cargo add bevy
+cargo add blenvy --git https://github.com/kaosat-dev/Blenvy/ --branch blenvy
+```
+
+Now, replace the contents of `src/main.rs` with the following:
+
+<details>
+<summary>src/main.rs</summary>
+
+```rust
+use bevy::prelude::*;
+use blenvy::*;
+
+fn main() -> AppExit {
+    App::new()
+        .add_plugins((DefaultPlugins, BlenvyPlugin::default()))
+        // We need to register components to make them visible to Blenvy
+        .register_type::<Player>()
+        .add_systems(Startup, setup)
+        .run()
+}
+
+#[derive(Component, Reflect)]
+#[reflect(Component)]
+struct Player {
+    strength: f32,
+    perception: f32,
+    endurance: f32,
+    charisma: f32,
+    intelligence: f32,
+    agility: f32,
+    luck: f32,
+}
+
+fn setup(mut commands: Commands) {
+    commands.spawn((
+        BlueprintInfo::from_path("levels/World.glb"),
+        SpawnBlueprint,
+        HideUntilReady,
+        GameWorldTag,
+    ));
+}
+```
+
+</details>
+
+`Player` is the component that we will add to our entities in Blender. It can contain any fields you want, but you need to remember to call `register_type` with it.
+
+Running this won't work yet because the `levels/World.glb` we reference doesn't exist yet. We will create it in the next step.
+
+## Setup the Blender addon for your project
+
+Create a directory under `my_game` called `art`. Hop back into Blender and save the default scene as `my_game.blend` in the `art` directory we just created. Your file structure should now look like this:
+
+<details>
+<summary>File structure</summary>
+
+<img src="img/art_file_structure.png" width = 50%/>
+</details>
+
+Now, clear the default scene of any objects or collections.
+The fastest way to do this is to look for the collection named simply `Collection` all the way on the right of Blender. Right-click on it and select `Delete Hierachy`.
+
+<details>
+<summary>The default collection to delete</summary>
+
+<img src="img/default_collection.png" width = 50%/>
+</details>
+
+Rename the default scene from `Scene` to `World` by clicking on "Scene" in the upper right corner of Blender and typing a new name.
+
+<details>
+<summary>Where to rename the scene</summary>
+
+<img src="img/scene_name.png" width = 50%/>
+</details>
+
+Next, create a new scene by clicking on the icon that looks a bit like two pages, next to where you just renamed the scene, and then selecting `New`. Rename this scene to `Library`.
+
+<details>
+<summary>Where to create a new scene</summary>
+
+<img src="img/create_scene.png" width = 50%/>
+</details>
+
+If everything went alright, entering the scene selector by pressing the icon next to the scene name should look like this:
+
+<details>
+<summary>Scene selector</summary>
+
+<img src="img/scenes.png" width = 50%/>
+</details>
+
+If you switched around scenes to see if everything worked, make sure to switch back to the `Library` scene now.
+
+Press `N`. This will open a side window. In it, click on the tab `Blenvy`. This is the main window through which you will interact with Blenvy.
+
+<details>
+<summary>Blenvy menu</summary>
+<img src="img/blenvy_menu.png" width = 50%/>
+</details>
+
+You will see that two options are highlighted red because they are not yet configured.
+
+For `level scenes`, click on the selector, select `World` and hit `+`. For `library scenes`, select `Library` and again hit `+`.
+
+Your menu should now look like this:
+
+<details>
+<summary>Correctly setup Blenvy</summary>
+<img src="img/blenvy_after_setup.png" width = 50%/>
+</details>
+
+Save your Blender file by pressing `Ctrl + S` on Windows or Linux and `Cmd + S` on macOS. You should now have a new asset under `my_game/assets/levels/World.glb` and a companion file containing metadata.
+
+<details>
+<summary>The newly created level assets</summary>
+<img src="img/level_asset.png" width = 50%/>
+</details>
+Run, run your game with `cargo run`. It may crash because the scene is empty, but don't worry. The point is that now will have generated another new file, namely `assets/registry.json`. This file contains the information about all components exported by your game so that Blenvy can pso them in Blender.
+
+<details>
+<summary>The final file structure for an empty world</summary>
+<img src="img/registry.png" width = 50%/>
+</details>
+
+## Create a blueprint
+
+Now, we will create an object for the `Player` component we defined earlier. While still in the `Library` scene, right-click on the `Scene Collection` all the way on the right. Select `New Collection`. Double-click on the new collection that appeared and rename it to `Player`. Click on it to have it selected.
+
+<details>
+<summary>The player collection</summary>
+<img src="img/player_collection.png" width = 50%/>
+</details>
+
+Now, on the upper left of Blender, click on `Add` -> `Mesh` -> `Cube`. This will be our player. We will now add the `Player` component to it. Go to the Blenvy menu we opened earlier. Select the icon in its upper left corner. This is where components are managed.
+
+<details>
+<summary>The component manager</summary>
+<img src="img/component_manager.png" width = 50%/>
+</details>
+
+If your component manager says "Select an object to edit its components", make sure you have the *Cube* we just created selected by clicking on it in the 3D viewport.
+
+Click on `Components`. If it says "No results found", we need to explicitly reload the registry. In the Blenvy menu, click on the gear icon (the fourth one from the left). In the submenu, click on the second icon. Your menu should now look like this:
+
+<details>
+<summary>The registry settings</summary>
+<img src="img/registry_settings.png" width = 50%/>
+</details>
+
+Click on `reload registry` to reload it manually.
+Go back to the component manager and you should now be greeted by a whole bunch of components:
+
+<details>
+<summary>The registry settings</summary>
+<img src="img/lots_of_components.png" width = 50%/>
+</details>
+
+Type in `Player` and click on `my_game::Player`.
+
+> [!TIP]
+> If this does not show up, you have forgotten to call `register_type` with it.
+
+Now click `Add`. You can now set all the player's fields in a neat Blender UI. Note that while we are only using `f32` here, you can use any kind of field, even complicated nested enums or structs.
+
+<details>
+<summary>The player component in Blender</summary>
+<img src="img/player_component.png" width = 50%/>
+</details>
+
+Congratulations, you have just created your first blueprint.
+
+## Composing the world
+
+Let's populate our world now. Switch back to the `World` scene in Blender as described before.
+
+We will add the following kinds of objects to our world:
+
+- Some basic ground, which we will create directly in the world
+- A camera
+- A light
+- The player character, which will be a blueprint instance
+
+First, let's add a camera through `Add` -> `Camera`. Blender will make the camera face whatever direction the viewport is aimed at, which will probably be completely arbitrary. Move the camera a bit so that it faces the world origin and is rotated the right way. You can just copy our transform if you like:
+
+- Location:
+  - X: `0`
+  - Y: `-10`
+  - Z: `2`
+- Rotation
+  - X: `80`
+  - Y: `0`
+  - Z: `0`
+- Scale
+  - X: `1`
+  - Y: `1`
+  - Z: `1`
+
+  All transforms we are using assume that you are using the `XYZ Euler` mode for rotation.
+
+<details>
+<summary>The camera transform in Blender</summary>
+<img src="img/camera_transform.png" width = 50%/>
+</details>
+
+Now, let's add a ground with `Add` -> `Mesh` -> `Cube`. Again scale and move it so that it lies neatly under the camera. Our transform looks like this:
+
+- Location:
+  - X: `0`
+  - Y: `0`
+  - Z: `0`
+- Rotation
+  - X: `0`
+  - Y: `0`
+  - Z: `0`
+- Scale
+  - X: `5`
+  - Y: `5`
+  - Z: `0.1`
+
+Add a directional light with `Add` -> `Light` -> `Sun`.
+This light's position and scale do not matter, only its rotation is actually used. We are using the following:
+
+- Rotation
+  - X: `20`
+  - Y: `20`
+  - Z: `0`
+
+Finally, it is time to create an instance of our player blueprint! For this, go to `Add` -> `Collection Instance` and select `Player`. It will spawn at origin, which means directly inside the ground for us. Move it a bit up. A location of `Z: 1.1` should placed it just a tiny bit above the ground.
+
+And with that, our Blender scene is finished! The final result should look like this:
+
+<details>
+<summary>The final Blender world scene</summary>
+<img src="img/final_blender.png" width = 100%/>
+</details>
+
+Save your Blender file again. This will update the `World.glb` file in the `assets` directory and create a new file for our player blueprint under `assets/blueprints/Player.glb`, including again a metadata file.
+
+<details>
+<summary>The new blueprint files</summary>
+<img src="img/blueprint_file.png" width = 50%/>
+</details>
+
+## Run your game
+
+Congrats, you're done! Just run your game with `cargo run` and you should see your world in all its glory:
+
+<details>
+<summary>The final Bevy render</summary>
+<img src="img/final_bevy.png" width = 50%/>
+</details>
+
+Okay, maybe not that much glory. But the important part is that the player is visible in the scene and has a `Player` component on it. You can now add more components to the player, create more blueprints, and populate your world with them. They can have animations, materials, etc. Have fun!