diff --git a/tools/blenvy/README-blueprints.md b/tools/blenvy/README-blueprints.md new file mode 100644 index 0000000..e4df25c --- /dev/null +++ b/tools/blenvy/README-blueprints.md @@ -0,0 +1,59 @@ +# 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 + diff --git a/tools/blenvy/README-components.md b/tools/blenvy/README-components.md new file mode 100644 index 0000000..26b0a9f --- /dev/null +++ b/tools/blenvy/README-components.md @@ -0,0 +1,165 @@ +# 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``` 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 diff --git a/tools/blenvy/README-export.md b/tools/blenvy/README-export.md new file mode 100644 index 0000000..977545b --- /dev/null +++ b/tools/blenvy/README-export.md @@ -0,0 +1,37 @@ +# 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 \ No newline at end of file diff --git a/tools/blenvy/README-levels.md b/tools/blenvy/README-levels.md new file mode 100644 index 0000000..f97e5e6 --- /dev/null +++ b/tools/blenvy/README-levels.md @@ -0,0 +1,12 @@ +# 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 \ No newline at end of file diff --git a/tools/blenvy/README-tech.md b/tools/blenvy/README-tech.md new file mode 100644 index 0000000..0a5c41f --- /dev/null +++ b/tools/blenvy/README-tech.md @@ -0,0 +1,30 @@ +### 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) diff --git a/tools/blenvy/README.md b/tools/blenvy/README.md index b54cab6..ba49da8 100644 --- a/tools/blenvy/README.md +++ b/tools/blenvy/README.md @@ -78,28 +78,32 @@ 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 +##### Root Folder (default: ../) - this is the same folder as your Bevy projects main folder: the path here is relative to the current .blend file -##### Assets Folder +##### Assets Folder (default: ./assets) - a path, relative to the *root* folder above, where you want to store your assets (delivered with your game) -##### Library Folder +##### Blueprints Folder (default: blueprints) - a path, relative to the *assets* folder above, where you want to store your *blueprints* -##### Levels Folder +##### Levels Folder (default: levels) - a path, relative to the *assets* folder above, where you want to store your *levels* -##### Materials Folder +##### Materials Folder (default: materials) - 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 +##### Level scenes + + - what are the scenes in your .blend file that are levels/worlds + +##### library scenes + - library scenes: what are the scenes in your .blend file that contain your libraries of blueprints (that you then use in your levels) @@ -121,17 +125,13 @@ 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``` -- Go to the new Components tab in the **configuration** tab - -![configuration](./docs/configuration.png) +###### registry file (default: assets/registry.json) - click on the button to select your registry.json file (in the "configuration" panel) -![configuration 2](./docs/configuration2.png) +###### reload registry -- the list of available components will appear - -![configuration 3](./docs/configuration3.png) +- click on the button to force refresh the list of components from the registry.json file ##### registry file polling @@ -139,36 +139,89 @@ 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) -### Materials +##### Auto export (default: True) -You can enable this option to automatically generate a **material library** files that combines all the materials in use in your blueprints. +- 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. -![material_library](./docs/blender_addon_materials2.png) +##### Gltf settings -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**. +- 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 -- 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 +> Important ! Do not use Blender's default gltf exporter (under file => export => gltf), as it does not impact Blenvy's settings -![material_library](./docs/blender_addon_materials.png) +##### Export scene settings (default: True) -TLDR: Use this option to make sure that each blueprint file does not contain a copy of the same materials +- 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 +##### 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, use Blender's asset library etc, we got you coverred too ! +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 ! There are only a few things to keep in mind #### Assets/library/blueprints files @@ -190,149 +243,24 @@ 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 -#### adding components +- for a detailed overview on how to add, edit, remove etc components please see [here](./README-components.md) -- 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) +### Export -![components list](./docs/components_list.png) +- for a detailed overview on auto exporting gltf files please see [here](./README-export.md) -- click on the dropdown to get the full list of available components +### Levels -![components list](./docs/components_list2.png) +- for a detailed overview of blueprints please see [here](./README-levels.md) -- 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) - - -#### 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``` 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) +### Blueprints +- for a detailed overview of blueprints please see [here](./README-blueprints.md) ## Development diff --git a/tools/blenvy/add_ons/bevy_components/components/ui.py b/tools/blenvy/add_ons/bevy_components/components/ui.py index aa9fb3d..e839137 100644 --- a/tools/blenvy/add_ons/bevy_components/components/ui.py +++ b/tools/blenvy/add_ons/bevy_components/components/ui.py @@ -257,7 +257,6 @@ 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)""" @@ -279,6 +278,9 @@ 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: diff --git a/tools/blenvy/add_ons/bevy_components/ui.py b/tools/blenvy/add_ons/bevy_components/ui.py index 44afdcd..07d6c81 100644 --- a/tools/blenvy/add_ons/bevy_components/ui.py +++ b/tools/blenvy/add_ons/bevy_components/ui.py @@ -2,10 +2,14 @@ def draw_settings_ui(layout, component_settings): row = layout.row() col = row.column() - col.enabled = False - col.prop(component_settings, "schema_path", text="Registry Schema path") + col.label(text="Registry Schema path") + col = row.column() - col.operator(operator="blenvy.components_registry_browse_schema", text="Browse for registry schema file (json)") + col.enabled = False + col.prop(component_settings, "schema_path", text="") + + col = row.column() + col.operator(operator="blenvy.components_registry_browse_schema", text="", icon="FILE_FOLDER") layout.separator() layout.operator(operator="blenvy.components_registry_reload", text="reload registry" , icon="FILE_REFRESH") diff --git a/tools/blenvy/docs/blenvy_configuration_components.png b/tools/blenvy/docs/blenvy_configuration_components.png index 5cbf304..938008c 100644 Binary files a/tools/blenvy/docs/blenvy_configuration_components.png and b/tools/blenvy/docs/blenvy_configuration_components.png differ diff --git a/tools/blenvy/docs/blueprints_always_export.png b/tools/blenvy/docs/blueprints_always_export.png new file mode 100644 index 0000000..4499fd2 Binary files /dev/null and b/tools/blenvy/docs/blueprints_always_export.png differ diff --git a/tools/blenvy/docs/blueprints_create.png b/tools/blenvy/docs/blueprints_create.png new file mode 100644 index 0000000..e7a9627 Binary files /dev/null and b/tools/blenvy/docs/blueprints_create.png differ diff --git a/tools/blenvy/docs/blueprints_create2.png b/tools/blenvy/docs/blueprints_create2.png new file mode 100644 index 0000000..055e0d3 Binary files /dev/null and b/tools/blenvy/docs/blueprints_create2.png differ diff --git a/tools/blenvy/docs/blueprints_create3.png b/tools/blenvy/docs/blueprints_create3.png new file mode 100644 index 0000000..271dba6 Binary files /dev/null and b/tools/blenvy/docs/blueprints_create3.png differ diff --git a/tools/blenvy/docs/blueprints_mark_asset.png b/tools/blenvy/docs/blueprints_mark_asset.png new file mode 100644 index 0000000..d720c15 Binary files /dev/null and b/tools/blenvy/docs/blueprints_mark_asset.png differ diff --git a/tools/blenvy/docs/blueprints_tab.png b/tools/blenvy/docs/blueprints_tab.png new file mode 100644 index 0000000..a21b5bf Binary files /dev/null and b/tools/blenvy/docs/blueprints_tab.png differ diff --git a/tools/blenvy/docs/components/invalid_components.png b/tools/blenvy/docs/components/invalid_components.png deleted file mode 100644 index e6bdae6..0000000 Binary files a/tools/blenvy/docs/components/invalid_components.png and /dev/null differ diff --git a/tools/blenvy/docs/components/missing_registry_data.png b/tools/blenvy/docs/components/missing_registry_data.png deleted file mode 100644 index 59e91aa..0000000 Binary files a/tools/blenvy/docs/components/missing_registry_data.png and /dev/null differ diff --git a/tools/blenvy/docs/components_add.png b/tools/blenvy/docs/components_add.png new file mode 100644 index 0000000..72039b9 Binary files /dev/null and b/tools/blenvy/docs/components_add.png differ diff --git a/tools/blenvy/docs/components_add2.png b/tools/blenvy/docs/components_add2.png new file mode 100644 index 0000000..198f3c0 Binary files /dev/null and b/tools/blenvy/docs/components_add2.png differ diff --git a/tools/blenvy/docs/components_blueprints.png b/tools/blenvy/docs/components_blueprints.png new file mode 100644 index 0000000..b6c7cda Binary files /dev/null and b/tools/blenvy/docs/components_blueprints.png differ diff --git a/tools/blenvy/docs/components_blueprints_blueprint.png b/tools/blenvy/docs/components_blueprints_blueprint.png new file mode 100644 index 0000000..583e82c Binary files /dev/null and b/tools/blenvy/docs/components_blueprints_blueprint.png differ diff --git a/tools/blenvy/docs/components_blueprints_instance.png b/tools/blenvy/docs/components_blueprints_instance.png new file mode 100644 index 0000000..b82434b Binary files /dev/null and b/tools/blenvy/docs/components_blueprints_instance.png differ diff --git a/tools/blenvy/docs/components_copy.png b/tools/blenvy/docs/components_copy.png new file mode 100644 index 0000000..3925e4c Binary files /dev/null and b/tools/blenvy/docs/components_copy.png differ diff --git a/tools/blenvy/docs/components_details.png b/tools/blenvy/docs/components_details.png new file mode 100644 index 0000000..b959de1 Binary files /dev/null and b/tools/blenvy/docs/components_details.png differ diff --git a/tools/blenvy/docs/components_edit.png b/tools/blenvy/docs/components_edit.png new file mode 100644 index 0000000..417581d Binary files /dev/null and b/tools/blenvy/docs/components_edit.png differ diff --git a/tools/blenvy/docs/components_invalid.png b/tools/blenvy/docs/components_invalid.png new file mode 100644 index 0000000..e65b83c Binary files /dev/null and b/tools/blenvy/docs/components_invalid.png differ diff --git a/tools/blenvy/docs/components_list.png b/tools/blenvy/docs/components_list.png new file mode 100644 index 0000000..d665299 Binary files /dev/null and b/tools/blenvy/docs/components_list.png differ diff --git a/tools/blenvy/docs/components_missing_registry_data.png b/tools/blenvy/docs/components_missing_registry_data.png new file mode 100644 index 0000000..843ef02 Binary files /dev/null and b/tools/blenvy/docs/components_missing_registry_data.png differ diff --git a/tools/blenvy/docs/components_object.png b/tools/blenvy/docs/components_object.png new file mode 100644 index 0000000..0e4beb4 Binary files /dev/null and b/tools/blenvy/docs/components_object.png differ diff --git a/tools/blenvy/docs/components_paste.png b/tools/blenvy/docs/components_paste.png new file mode 100644 index 0000000..98b199b Binary files /dev/null and b/tools/blenvy/docs/components_paste.png differ diff --git a/tools/blenvy/docs/components_rename_fix.png b/tools/blenvy/docs/components_rename_fix.png new file mode 100644 index 0000000..abf4fba Binary files /dev/null and b/tools/blenvy/docs/components_rename_fix.png differ diff --git a/tools/blenvy/docs/components_rename_fix2.png b/tools/blenvy/docs/components_rename_fix2.png new file mode 100644 index 0000000..eb38d30 Binary files /dev/null and b/tools/blenvy/docs/components_rename_fix2.png differ diff --git a/tools/blenvy/docs/components_rename_fix3.png b/tools/blenvy/docs/components_rename_fix3.png new file mode 100644 index 0000000..bc7f2ae Binary files /dev/null and b/tools/blenvy/docs/components_rename_fix3.png differ diff --git a/tools/blenvy/docs/components_rename_fix4.png b/tools/blenvy/docs/components_rename_fix4.png new file mode 100644 index 0000000..03cd983 Binary files /dev/null and b/tools/blenvy/docs/components_rename_fix4.png differ diff --git a/tools/blenvy/docs/components_search.png b/tools/blenvy/docs/components_search.png new file mode 100644 index 0000000..f9891d4 Binary files /dev/null and b/tools/blenvy/docs/components_search.png differ diff --git a/tools/blenvy/docs/components_suported_types.png b/tools/blenvy/docs/components_suported_types.png new file mode 100644 index 0000000..2261f30 Binary files /dev/null and b/tools/blenvy/docs/components_suported_types.png differ diff --git a/tools/blenvy/docs/components_unregistered_types.png b/tools/blenvy/docs/components_unregistered_types.png new file mode 100644 index 0000000..d48964a Binary files /dev/null and b/tools/blenvy/docs/components_unregistered_types.png differ diff --git a/tools/blenvy/old.md b/tools/blenvy/old.md index 0f89b2a..5a8fb9d 100644 --- a/tools/blenvy/old.md +++ b/tools/blenvy/old.md @@ -36,9 +36,6 @@ 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 @@ -53,79 +50,12 @@ 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)