Merge ee14ec69bd into 9b50d77790

tools/blenvy/README-blueprints.md

@@ -1,59 +0,0 @@
-# Blueprints
-
-## What are blueprints 
-
-- blueprints are just Blender collections , and reuseable "prefabs":
-  - as long as they have been defined in one of the library scenes
-  - have at least one instance
-  - or have been marked as assets
-
-## How to create a blueprint
-
-Since blueprints are just Blender collections with a tiny bit of extra configuration, you can use your normal Blender workflow.
-
-But here is Blueprint creation in more detail:
-
-- create a library scene if you do not have one
-- make sure to tag the scene as a library scene in the Blenvy settings
-- create a collection
-
-![blueprints create](./docs/blueprints_create.png)
-
-- add anything you want inside your blueprint
-
-![blueprints create](./docs/blueprints_create2.png)
-
-- add any component you want to your blueprint (see [here](./README-components.md#adding-components) for more details)
-
-![blueprints create](./docs/blueprints_create3.png)
-
-
-## How to use blueprints
-
-- Once you have create a blueprint as outlined above, go to one of your [level](./README-levels.md) scenes and add a collection instance
-- or 
-    - if you do not want to create an instance as part of a level (for blueprint instances that need to be spawned dynamically while your game is running)
-    - if your project is a pure library project (no levels, just blueprints for reuse) , right click on the collection & click on "mark as asset"
-
-![blueprints mark asset](./docs/blueprints_mark_asset.png)
-
-
-## Viewing all of your project's blueprints
-
-If you want to view all of your blueprints, navigate to the Blueprints tab
-
-![blueprints tab](./docs/blueprints_tab.png)
-
-- you will be able to see both the local blueprints (defined in the current .blend file) and the ones from external asset files (defined in other .blend files)
-- you can click on the selection tool (arrow icon) to automatically go to the scene where the blueprint is defined & automatically select it
-
-## Exporting blueprints
-
-- blueprint export is automatic if you have toggle the ["auto export"](./README.md#auto-export-default-true) setting in the configuration 
-- you can also force per blueprint systematic export (regardless of change detection), by checking the "always export" checkbox in the Blueprints tab
-
-![blueprints always export](./docs/blueprints_always_export.png)
-
-* those blueprints will be exported on every save
-* this option is disabled for external blueprints
-    

tools/blenvy/README-components.md

@@ -1,165 +0,0 @@
-# Components
-
-## Supported components
-
-- normally (minus any bugs, please report those!) all components using **registered** types should be useable and editable
-- this includes (non exhaustive list):
-  * enums (even complex ones !)  
-  * complex structs, with various types of fields (including nested ones)
-  * lists/ vecs
-  * hashmaps
-  * etc !
-
-![suported types](./docs/components_suported_types.png)
-
-## Supported items for components
-
-you can add components to 
-  - objects 
-  - collections/ blueprints
-  - meshes
-  - materials
-
-These will be all applied correctly to the resulting entities on the Bevy side
-
-### Blueprints & components:
-
-- to add components to a blueprint, select your blueprint's collection and add the desired component
-
-![blueprint components](./docs/components_blueprints.png)
-
-- when you select a blueprint/collection **instance** you can view both the **blueprint** level components (for all instances) ...
-
-![blueprint components](./docs/components_blueprints_blueprint.png)
-
-
-- and the components specific to that **instance**
-
-![blueprint components](./docs/components_blueprints_instance.png)
-
-
-> if the instance and blueprint have the same component, the component value of the **instance** takes precedence & overwrites that of the blueprint ! In the case above, the component will have the value ```Metal``` for that instance.
-
-## adding components
-
-- to add a component, select any object, collection, mesh or material and then select the component from the components list: (the full type information will be displayed as tooltip)
-
-- click on the dropdown to get the full list of available components
-
-![components list](./docs/components_list.png)
-
-- the list of components is searchable !
-
-![filter components](./docs/components_search.png)
-
-- add a component by clicking on the "add component" button once you have selected your desired component
-
-![add component](./docs/components_add.png)
-
-  it will appear in the component list for that object
-
-![add component](./docs/components_add2.png)
-
-
-## editing components
-
-- to edit a component's value just use the UI: 
-
-![edit component](./docs/components_edit.png)
-
-
-## copy & pasting 
-
-- you can also copy & paste components between objects/collections/meshes/materials
-
-- click on the "copy component button" of the component you want to copy
-
-![copy component](./docs/components_copy.png)
-
-- then select the item you want to copy the component (& its value) to, and click on the paste button.
-
-It will add the component to the select item
-
-![paste component](./docs/components_paste.png)
-
-> if the target item already has the same component, its values will be overwritten
-
-
-## Toggling component details
-
-- for large/ complex components you can toggle the details of that component:
-
-![toggle details](./docs/components_details.png)
-
-
-## Error handling & unregistered types
-
-- if you have a component made up of unregistered structs/enums etc, you will get visual feedback & the component will be deactivated
-
-    ![invalid component](./docs/components_invalid.png)
-
-  > see [here](#renamingupgradingfixing-components) for ways to convert invalid / unregistered components to other types.
-
-
-- if you are encountering this type of view: don't panic your component data is not gone ! It just means you need to reload the registry data by clicking on the relevant button
-
-    ![missing registry data](./docs/components_missing_registry_data.png)
-
-- non registered types can be viewed in this panel : (can be practical to see if you have any missing registrations too!)
-
-    ![unregistered types](./docs/components_unregistered_types.png)
-
-
-## Renaming/upgrading/fixing components
-
-![rename and fix](./docs/components_rename_fix.png)
-
-### Single item actions
-
-this panel shows you the list of components that either 
- * are not in the registry anymore
- * are invalid (there is some error in the component that makes it unavailable in Blenvy)
- * need upgrading (ie they where stored as a custom property instead of Blenvy metadata for example)
-
-> The last case is also for components that where created before Blenvy , using the legacy **bevy_components** Blender add-on
-
-> The objects & components in this panel are not related to your current selection
-
-- select the target component for a given source item/component:
-
-![rename and fix](./docs/components_rename_fix2.png)
-
-- click on the apply button
-
-![rename and fix](./docs/components_rename_fix3.png)
-
-- you will get a notification depending on how the process went, and if all went well, the entry will be deleted from the list of items that need fixing/upgrades
-
-![rename and fix](./docs/components_rename_fix4.png)
-
-
-### Bulk actions:
-
-- you can rename/convert/upgrade or delete a given type of component to another for ALL of your objects, collections, meshes and materials in one go
-by choosing an original and a target component & clicking on apply or delete
-
-
-## Known issues & limitations:
-
-* **Range** data (ie ```Range<f32>``` etc) are not handled at this time
-* **Entity** structs are always set to 0 (setting entity values on the Blender side at this time does not make much sense anyway) 
-
-
-
-## Technical details
-
-- Blenvy's component system uses the data from the exported **type registry** in the registry.json file to add **metadata** to objects/collection/meshes/etc containing information about what components it uses + some extra information
-- uses Blender's **PropertyGroups** to generate custom UIs & connects those groups with the custom properties so that no matter the complexity
-of your Bevy components you get a nicely packed custom_property
-- in order to avoid name clashes, it uses the full paths of components & stores the data in the ```bevy_components``` custom property
-- changing the values of a component in the UI  will automatically update the value of the underlying entry in the ```bevy_components``` custom property
-- different item types in Blender result in different types of GltfExtra components in Bevy (this all happens under the hood):
-  - objects : GltfExtras
-  - collections/ blueprints: SceneGltfExtras (as the Blueprints get exported as seperate scenes)
-  - meshes: MeshGltfExtras
-  - materials: MaterialGltfExtras

tools/blenvy/README-export.md

@@ -1,37 +0,0 @@
-# Export
-
-## Materials
-
-You can enable this option to automatically generate a **material library** files that combines all the materials in use in your blueprints.
-
-![material_library](./docs/blender_addon_materials2.png)
-
-Since each blueprint is normally a completely independant gltf file, without this option, if you have a material with a large texture for example, 
-**ALL** of your blueprints using that material will embed that large texture, leading to **significant bloat & memory use**.
-
-- When this option is enabled, you get a single material library per Blender project, and a **MaterialInfo** component is inserted into each object using a material.
-- The correct material will then be inserted on the Bevy side (that loads any number of material libraries that you need) into the correct mesh
-- Only one material per object is supported at this stage, ie the last material slot's material is the one that is going to be used
-
-![material_library](./docs/blender_addon_materials.png)
-
-TLDR: Use this option to make sure that each blueprint file does not contain a copy of the same materials 
-
-
-## Technical details
-
-### Internal process (simplified)
-
-This is the internal logic of the export process with blueprints (simplified)
-
-![process](./docs/process.svg)
-
-ie this is an example scene...
-
-![](./docs/workflow_original.jpg)
-
-and what actually gets exported for the level scene/world/level
-
-![](./docs/workflow_empties.jpg)
-
-all collections instances replaced with empties, and all those collections exported to gltf files as seen above

tools/blenvy/README-levels.md

@@ -1,12 +0,0 @@
-# Levels
-
-## What are levels ?
-
-- any Blender scene that has been tagged as a level in the Blenvy settings
-
-## How to create levels ?
-
-- create a Blender scene
-- tag it as a level in the Blenvy settings
-- place blueprint/collection instances or any normal Blender mesh/object in the scene
-- just save your file

tools/blenvy/README-tech.md

@@ -1,30 +0,0 @@
-### Blueprints
-
-You can enable this option to automatically replace all the **collection instances** inside your level scene with blueprints
-- whenever you change your level scene (or your library scene , if that option is enabled), all your collection instances 
-    * will be replaced with empties (this will not be visible to you)
-    * those empties will have additional custom properties / components : ```BlueprintInfo``` & ```SpawnBlueprint```
-    * your level scene/ level will be exported to a much more trimmed down gltf file (see next point)
-    * all the original collections (that you used to create the instances) will be exported as **seperate gltf files** into the "library" folder
-
-- this means you will have 
-    * one small main gltf file (your level/world)
-    * as many gltf files as you have used collections in the level scene , in the library path you specified :
-    for the included [basic](../../examples/bevy_gltf_blueprints/basic/) example's [assets](../../examples/bevy_gltf_blueprints/basic/assets/), it looks something like this: 
-
-    ![library](./docs/exported_library_files.png)
-    
-    the .blend file that they are generated from can be found [here](../../examples/bevy_gltf_blueprints/basic/assets/advanced.blend)
-
-- the above only applies to collections that have **instances** in your level scene!
-    if you want a specific collection in your library to always get exported regardless of its use, you need to add 
-    a **COLLECTION** (boolean) custom property called ```AutoExport``` set to true
-    > not at the object level ! the collection level !
-
-    ![force-export](./docs/force_export.jpg)
-
-    It will get automatically exported like any of the "in-use" collections.
-
-- you can also get an overview of all the exported collections in the export menu
-
-    ![exported collections](./docs/exported_collections.png)

tools/blenvy/README.md

@@ -78,32 +78,28 @@ Blenvy is opinionated !
   - keep you art/sources (usually not delivered with your game) seperate from your game assets
   - keep your blueprints/levels/materials gltf files seperate
 
-##### Root Folder (default: ../)
+##### Root Folder
 
 - this is the same folder as your Bevy projects main folder: the path here is relative to the current .blend file
 
-##### Assets Folder (default: ./assets)
+##### Assets Folder
 
 - a path, relative to the *root* folder above, where you want to store your assets (delivered with your game)
 
-##### Blueprints Folder (default: blueprints)
+##### Library Folder
 
 - a path, relative to the *assets* folder above, where you want to store your *blueprints*
 
-##### Levels Folder (default: levels)
+##### Levels Folder
 
 - a path, relative to the *assets* folder above, where you want to store your *levels*
 
-##### Materials Folder (default: materials)
+##### Materials Folder
 
 - a path, relative to the *assets* folder above, where you want to store your *materials*
 
-##### Level scenes
-
-  -  what are the scenes in your .blend file that are levels/worlds
-
-##### library scenes
-
+#####
+  - level scenes: what are the scenes in your .blend file that are levels/worlds
   - library scenes: what are the scenes in your .blend file that contain your libraries of blueprints (that you then use in your levels)
 
 
@@ -125,13 +121,17 @@ The second tab contains the component settings:
 
 > you normally do not need to do anything, as the defaults are already pre-set to match those on the Bevy side for the location of the ```registry.json``` file, unless you want to store it somewhere other than ```assets/registry.json```
 
-###### registry file (default: assets/registry.json)
+- Go to the new Components tab in the **configuration** tab
+
+![configuration](./docs/configuration.png)
 
 - click on the button to select your registry.json file (in the "configuration" panel)
 
-###### reload registry
+![configuration 2](./docs/configuration2.png)
 
-- click on the button to force refresh the list of components from the registry.json file
+- the list of available components will appear
+
+![configuration 3](./docs/configuration3.png)
 
 
 ##### registry file polling
@@ -139,89 +139,36 @@ The second tab contains the component settings:
 * by default, the add-on will check for changes in your registry file every second, and refresh the UI accordingly
 * you can set the polling frequency or turn it off if you do not want auto-refresh
 
+![registry file polling](./docs/registry_polling.png)
+
 #### Export
 
 Last but not least, the export/ auto-export settings tab
 
 ![blenvy export settings](./docs/blenvy_configuration_export.png)
 
-##### Auto export (default: True)
+### Materials
 
-- toggle this to turn the whole auto-export system on or off : 
- when enabled, **every time you save your blend file** Blenvy will automatically export a set of gltf files , for levels, blueprints, materials etc depending on your settings, see below.
+You can enable this option to automatically generate a **material library** files that combines all the materials in use in your blueprints.
 
-##### Gltf settings
+![material_library](./docs/blender_addon_materials2.png)
 
-- click on this button to open Blender's standard gltf exporter settings **specific to Blenvy** : ie you have access to all of the normal gltf settings, but there is additional boilerplate
-to gather these settings for Blenvy only, so it does not impact your normal export settings
-- you *must* keep the "remember export settings" checkbox checked in order for the settings to be useable by Blenvy
+Since each blueprint is normally a completely independant gltf file, without this option, if you have a material with a large texture for example, 
+**ALL** of your blueprints using that material will embed that large texture, leading to **significant bloat & memory use**.
 
-> Important ! Do not use Blender's default gltf exporter (under file => export => gltf), as it does not impact Blenvy's settings
+- When this option is enabled, you get a single material library per Blender project, and a **MaterialInfo** component is inserted into each object using a material.
+- The correct material will then be inserted on the Bevy side (that loads any number of material libraries that you need) into the correct mesh (see the configuration
+options in **bevy_gltf_blueprints** for more information on that)
+- Only one material per object is supported at this stage, ie the last material slot's material is the one that is going to be used
 
-##### Export scene settings (default: True)
+![material_library](./docs/blender_addon_materials.png)
 
-- toggle this to export additional settings like ambient color, bloom, ao, etc from Blender to Bevy: this automatically generates additional components at the scene level that get processed by the Blenvy crate
+TLDR: Use this option to make sure that each blueprint file does not contain a copy of the same materials 
 
-##### Use change detection (default: True)
-
-- toggle this to enable change detection: ie, to make sure that only the blueprints , levels or materials that have actually **changed since your last save** get exported to gltf files, a sort of "incremental export".
-
-> Under the hood, Blenvy serializes your whole Blender project to a simplified representation, to be able to tell the differents between successive changes
-
-##### Detailed materials scan (default: True)
-
-- this options enables more detailed materials scanning & thus detecting smaller changes, even **changes in material nodes** . This comes at a potential additional processing cost, so if you notice performance issues in projects with complex materials
-you can turn this off
-
-##### Detailed modifiers scan (default: True)
-
-- similar to the one above but for modifiers, this options enables more finer grained change detection in modifiers, even **changes in geometry nodes** . This comes at a potential additional processing cost, so if you notice performance issues in projects with complex modifiers
-you can turn this off
-
-##### Export blueprints (default: True)
-
-- check this if you want to automatically export blueprints 
-
-##### Collection instances (default: split)
-
-select which option you want to use to deal with collection instances (aka combine mode) (both inside blueprint collections & main collections)
-
-  * split (default, highly recomended) : the addon will 'split out' any nested collections/ blueprints & export them
-  * embed: choose this option if you want to keep everything inside a gltf file (less efficient, not recomended)
-  * embedExternal: this will embed ONLY collection instances whose collections have not been found inside the current blend file
-
-  These options can also be **overridden** on a per collection instance basis: (if you want to split out most collection instances, but keep a few specific ones embeded
-  inside your gltf file)
-      
-  ![combine override](./docs/combine_override.png) 
-
-  - simply add a custom property called **_combine** to the collection instance, and set it to one of the options above
-
-##### Export dynamic and static objects seperatly (default: False)
- 
-
-For levels scenes only, toggle this to generate 2 files per level: 
-
-  - one with all dynamic data: collections or instances marked as dynamic (aka saveable)
-  - one with all static data: anything else that is NOT marked as dynamic, the file name will have the suffix **_dynamic**
-
-  Ie if you add a **Dynamic** custom/ component to either your collection instances or your blueprint, you get a clean seperation between 
-
-  - your static level data (anything that will never change during the lifetime of your Bevy app)
-  - your dynamic objects (anything that will change during the lifetime of your Bevy app, that can be saved & reloaded in save files for example)
-
-##### export materials library (default: True)
-
-check this if you want to automatically export material libraries 
-please read the dedicated [section](./README-export.md#materials) below for more information
-
-#### Additional export settings
-
-- you can also force per level or per blueprint systematic export (regardless of change detection), see the relevant sections in the levels & blueprint documentation
 
 ### Multiple blend file workflow
 
-If you want to use multiple blend files (recomended if your project starts to grow even a bit), use Blender's asset library etc, we got you coverred too !
+If you want to use multiple blend files, use Blender's asset library etc, we got you coverred too !
 There are only a few things to keep in mind 
 
 #### Assets/library/blueprints files
@@ -243,24 +190,149 @@ There are only a few things to keep in mind
 Take a look at the [relevant](../../examples/demo/) example for more [details](../../examples/demo/art/) 
 
 
+
+
 ## Useage
 
 ### Components
 
-- for a detailed overview on how to add, edit, remove etc components please see [here](./README-components.md)
+#### adding components
 
-### Export
+- to add a component, select an object, collection, mesh or material and then select the component from the components list: (the full type information will be displayed as tooltip)
 
-- for a detailed overview on auto exporting gltf files please see [here](./README-export.md)
+![components list](./docs/components_list.png)
 
-### Levels
+- click on the dropdown to get the full list of available components
 
-- for a detailed overview of blueprints please see [here](./README-levels.md)
+![components list](./docs/components_list2.png)
+
+- you can also filter components by name for convenience
+
+![filter components](./docs/filter_components.png)
+
+- add a component by clicking on the "add component" button once you have selected your desired component
+  
+  it will appear in the component list for that object
+
+![add component](./docs/add_component.png)
 
 
-### Blueprints
+#### editing components
+
+- to edit a component's value just use the UI: 
+
+![edit component](./docs/edit_component.png)
+
+#### copy & pasting 
+
+- you can also copy & paste components between objects
+
+- click on the "copy component button" of the component you want to copy
+
+![copy component](./docs/copy_component.png)
+
+- then select the object you want to copy the component (& its value) to, and click on the paste button.
+
+It will add the component to the select object
+
+![paste component](./docs/paste_component.png)
+
+> if the target object already has the same component, its values will be overwritten
+
+
+#### Additional components UI features
+
+
+##### Toggling component details
+
+- for large/ complex components you can toggle the details of that component:
+
+![toggle details](./docs/toggle_details.png)
+
+
+##### Supported components
+
+- normally (minus any bugs, please report those!) all components using **registered** types should be useable and editable
+- this includes (non exhaustive list):
+  * enums (even complex ones !)
+
+    ![enums](./docs/enums.png)
+
+    ![enums](./docs/enums2.png)
+
+  
+  * complex structs, with various types of fields (including nested ones)
+
+    ![complex](./docs/complex_components2.png)
+
+  * lists/ vecs (here a vec of tuples)
+
+    ![lists](./docs/vecs_lists.png)
+
+  * etc !
+
+##### Unregistered types & error handling
+
+- non registered types can be viewed in this panel : (can be practical to see if you have any missing registrations too!)
+
+    ![unregistered types](./docs/unregistered_types.png)
+
+- if you have a component made up of unregistered structs/enums etc, you will get visual feedback & the component will be deactivated
+
+    ![invalid component](./docs/invalid_components.png)
+
+  > see [here](#invalidunregistered-type-renaming--conversion) for ways to convert invalid / unregistered components to other types.
+
+
+- if you are encountering this type of view: don't panic your component data is not gone ! It just means you need to reload the registry data by clicking on the relevant button
+
+    ![missing registry data](./docs/missing_registry_data.png)
+
+## Levels
+
+## Blueprints
+
+
+## Technical details
+
+- adds **metadata** to objects containing information about what components it uses + some extra information
+- uses Blender's **PropertyGroups** to generate custom UIs & connects those groups with the custom properties so that no matter the complexity
+of your Bevy components you get a nicely packed custom_property to use with ...
+- supports any number of main/level scenes 
+    - Blender scenes where you define your levels, and all collection instances are replaced with "pointers" to other gltf files (all automatic)
+- supports any number of library scenes
+    - Blender scenes where you define the assets that you use in your levels, in the form of collections
+- automatic export of **changed** objects & collections only ! a sort of "incremental export", where only the changed collections (if in use)
+        get exported when you save your blend file
+
+### Components
+
+changing the values of a component in the UI  will automatically update the value of the underlying entry in the ```bevy_components``` custom property
+
+![edit component](./docs/edit_component2.png)
+
+### Internal process (simplified)
+
+This is the internal logic of the export process with blueprints (simplified)
+
+![process](./docs/process.svg)
+
+ie this is an example scene...
+
+![](./docs/workflow_original.jpg)
+
+and what actually gets exported for the level scene/world/level
+
+![](./docs/workflow_empties.jpg)
+
+all collections instances replaced with empties, and all those collections exported to gltf files as seen above
+
+
+## Known issues & limitations:
+
+* **Range** data (ie ```Range<f32>``` etc) are not handled at this time (issue seems to be on the Bevy side)
+* **Entity** structs are always set to 0 (setting entity values on the Blender side at this time does not make much sense anyway) 
 
-- for a detailed overview of blueprints please see [here](./README-blueprints.md)
 
 ## Development 
 

tools/blenvy/add_ons/bevy_components/components/ui.py

@@ -257,6 +257,7 @@ def draw_component_ui(layout, object_or_collection, registry, selected_component
         # we fetch the matching ui property group
         root_propertyGroup_name = registry.get_propertyGroupName_from_longName(component_name)
         """print("root_propertyGroup_name", root_propertyGroup_name)"""
+
         if root_propertyGroup_name:
             propertyGroup = getattr(component_meta, root_propertyGroup_name, None)
             """print("propertyGroup", propertyGroup)"""
@@ -278,9 +279,6 @@ def draw_component_ui(layout, object_or_collection, registry, selected_component
             else:
                 error_message = invalid_details if component_invalid else "Missing component UI data, please reload registry !"
                 row.label(text=error_message)
-        else:
-            error_message = invalid_details if component_invalid else "Missing component UI data, please reload registry !"
-            row.label(text=error_message)
 
         # "footer" with additional controls
         if component_invalid:

tools/blenvy/add_ons/bevy_components/ui.py

@@ -1,15 +1,11 @@
 def draw_settings_ui(layout, component_settings):
 
     row = layout.row()
-    col = row.column()
-    col.label(text="Registry Schema path")
-
     col = row.column()
     col.enabled = False
-    col.prop(component_settings, "schema_path", text="")
-
+    col.prop(component_settings, "schema_path", text="Registry Schema path")
     col = row.column()
-    col.operator(operator="blenvy.components_registry_browse_schema", text="", icon="FILE_FOLDER")
+    col.operator(operator="blenvy.components_registry_browse_schema", text="Browse for registry schema file (json)")
 
     layout.separator()
     layout.operator(operator="blenvy.components_registry_reload", text="reload registry" , icon="FILE_REFRESH")

tools/blenvy/old.md

@@ -36,6 +36,9 @@ This issue has been resolved in v0.9.
 
 
     - export folder: root folder to export models too
+    - export scene settings: exports "global"/scene settings like ambient color, bloom, ao, etc 
+        
+        This automatically generates additional components at the scene level 
 
     - pick your main (level) scenes and/or library scenes (see the chapter about [Blueprints](#blueprints) and [multiple Blend filles workflow](#multiple-blend-file-workflow) below)   
         - click in the scene picker & select your scene
@@ -50,12 +53,79 @@ This issue has been resolved in v0.9.
         
         ![select scene3](./docs/blender_addon_add_scene3.png) 
 
+    - export blueprints: check this if you want to automatically export blueprints (default: True)
     - blueprints path: the path to export blueprints to , relative to the main **export folder** (default: library)
+    - collection instances: select which option you want to use to deal with collection instances (aka combine mode) (both inside blueprint collections & main collections)
 
+        * split (default, highly recomended) : the addon will 'split out' any nested collections/ blueprints & export them
+        * embed: choose this option if you want to keep everything inside a gltf file (less efficient, not recomended)
+        * embedExternal: this will embed ONLY collection instances whose collections have not been found inside the current blend file
+
+        These options can also be **overridden** on a per collection instance basis: (if you want to split out most collection instances, but keep a few specific ones embeded
+        inside your gltf file)
+            
+        ![combine override](./docs/combine_override.png) 
+
+        - simply add a custom property called **_combine** to the collection instance, and set it to one of the options above
 
         please read the dedicated [section](#collection-instances--nested-blueprints) below for more information
 
 
+    - Export dynamic and static objects seperatly : For MAIN scenes only (aka levels), toggle this to generate 2 files per level: 
+
+        - one with all dynamic data: collection or instances marked as dynamic (aka saveable)
+        - one with all static data: anything else that is NOT marked as dynamic, the file name will have the suffix **_dynamic**
+
+        Ie if you add a "Dynamic" custom property/ component to either your collection instances or your blueprint, you get a clean seperation between 
+
+        - your static level data (anything that will never change during the lifetime of your Bevy app)
+        - your dynamic objects (anything that will change during the lifetime of your Bevy app, that can be saved & reloaded in save files for example)
+
+    - export materials library: check this if you want to automatically export material libraries (default: False)
+    please read the dedicated [section](#materials) below for more information
+
+        > This only works together with blueprints !
+
+    - materials path: where to export materials to
+
+* and your standard gltf export parameters in the **gltf** panel
+
+    ![blender addon use2](./docs/blender_addon_use2.png)
+
+
+* click on "apply settings"
+* now next time you save your blend file you will get an automatically exported gltf file (or more than one, depending on your settings, see below)
+
+### Blueprints
+
+You can enable this option to automatically replace all the **collection instances** inside your level scene with blueprints
+- whenever you change your level scene (or your library scene , if that option is enabled), all your collection instances 
+    * will be replaced with empties (this will not be visible to you)
+    * those empties will have additional custom properties / components : ```BlueprintInfo``` & ```SpawnBlueprint```
+    * your level scene/ level will be exported to a much more trimmed down gltf file (see next point)
+    * all the original collections (that you used to create the instances) will be exported as **seperate gltf files** into the "library" folder
+
+- this means you will have 
+    * one small main gltf file (your level/world)
+    * as many gltf files as you have used collections in the level scene , in the library path you specified :
+    for the included [basic](../../examples/bevy_gltf_blueprints/basic/) example's [assets](../../examples/bevy_gltf_blueprints/basic/assets/), it looks something like this: 
+
+    ![library](./docs/exported_library_files.png)
+    
+    the .blend file that they are generated from can be found [here](../../examples/bevy_gltf_blueprints/basic/assets/advanced.blend)
+
+- the above only applies to collections that have **instances** in your level scene!
+    if you want a specific collection in your library to always get exported regardless of its use, you need to add 
+    a **COLLECTION** (boolean) custom property called ```AutoExport``` set to true
+    > not at the object level ! the collection level !
+
+    ![force-export](./docs/force_export.jpg)
+
+    It will get automatically exported like any of the "in-use" collections.
+
+- you can also get an overview of all the exported collections in the export menu
+
+    ![exported collections](./docs/exported_collections.png)
 
 - there are some workflow specificities for multi blend file [workflows](#multiple-blend-file-workflow)