|bevy vewsion:|0.9 |(outdated!)| |---|---|---|

As this page is outdated, please refer to Bevy's official migration guides while reading, to cover the differences: 0.9 to 0.10, 0.10 to 0.11, 0.11 to 0.12, 0.12 to 0.13, 0.13 to 0.14.

I apologize for the inconvenience. I will update the page as soon as I find the time.

3d modews and scenes (gwtf)

wewevant officiaw exampwes: load_gltf, update_gltf_scene.

bevy uses the gwtf 2.0 fiwe fowmat f-fow 3d assets.

(othew fowmats may be unofficiawwy a-avaiwabwe via 3wd-pawty p-pwugins)

quick-stawt: spawning 3d modews into y-youw wowwd

the simpwest use case is to just w-woad a "3d modew" a-and spawn it into t-the game wowwd.

"3d modews" can often be compwex, OwO c-consisting of muwtipwe p-pawts. 🥺 think o-of a house: the windows, OwO woof, doows, e-etc., awe sepawate p-pieces, 🥺 that a-awe wikewy made of muwtipwe meshes, ^•ﻌ•^ matewiaws, OwO a-and textuwes. 🥺 b-bevy wouwd technicawwy need muwtipwe ecs entities to wepwesent a-and wendew t-the whowe thing.

this is why youw gwtf "modew" is w-wepwesented by bevy a-as a [scene][cb::scene]. ^•ﻌ•^ this way, you can easiwy spawn i-it, OwO and bevy wiww c-cweate aww the wewevant chiwd entities and configuwe them cowwectwy.

fn spawn_gwtf(
    mut commands: c-commands, >_<
    ass: w-wes<assetsewvew>, :3
) {
    // n-nyote that we have t-to incwude the `scene0` w-wabew
    w-wet my_gwtf = a-ass.woad("my.gwb#scene0");

    // t-to position ouw 3d modew, simpwy use the twansfowm
    // in the scenebundwe
    commands.spawn(scenebundwe {
        s-scene: my_gwtf, (U ﹏ U)
        twansfowm: twansfowm::fwom_xyz(2.0, -.- 0.0, -5.0), (ˆ ﻌ ˆ)♡
        ..defauwt::defauwt()
    });
}

you couwd awso use gwtf fiwes to w-woad an entiwe map/wevew. OwO i-it wowks t-the same way.

the above exampwe assumes that you h-have a simpwe g-gwtf fiwe containing o-onwy one "defauwt scene". OwO gwtf is a vewy f-fwexibwe fiwe f-fowmat. 🥺 a singwe f-fiwe can contain many "modews" ow mowe compwex "scenes". (ꈍᴗꈍ) to g-get a bettew undewstanding of gwtf and possibwe wowkfwows, ^•ﻌ•^ wead t-the west of t-this page. OwO :)

intwoduction to gwtf

gwtf is a modewn open standawd fow e-exchanging 3d a-assets between diffewent 3d softwawe appwications, ^•ﻌ•^ wike game e-engines and 3d m-modewing softwawe.

the gwtf fiwe fowmat has two vawiants: h-human-weadabwe a-ascii/text (*.gltf) and binawy (*.glb). (ꈍᴗꈍ) the binawy fowmat is mowe compact a-and pwefewabwe fow packaging the assets with youw g-game. OwO the text f-fowmat may be usefuw f-fow devewopment, OwO as it can be easiew t-to manuawwy inspect u-using a text e-editow.

a gwtf fiwe can contain many objects (sub-assets): m-meshes, (ꈍᴗꈍ) matewiaws, textuwes, OwO scenes, 🥺 animation cwips. òωó w-when woading a g-gwtf fiwe, bevy w-wiww woad aww of the assets contained inside. ^•ﻌ•^ t-they wiww be m-mapped to the appwopwiate bevy-intewnaw asset types.

the gwtf sub-assets

gwtf tewminowogy can be confusing, OwO a-as it sometimes u-uses the same w-wowds to wefew to diffewent things, OwO compawed t-to bevy. 🥺 this s-section wiww twy e-expwain the vawious gwtf tewms.

to undewstand evewything, OwO it hewps t-to mentawwy considew h-how these c-concepts awe wepwesented in diffewent pwaces: i-in youw 3d modewing s-softwawe (wike b-bwendew), in the gwtf fiwe itsewf, >_< and in bevy.

gwtf scenes awe nyani you spawn into youw game w-wowwd. ^•ﻌ•^ this is t-typicawwy nani you see on the scween in youw 3d m-modewing softwawe. ^•ﻌ•^ s-scenes combine aww of the data needed fow the game e-engine to cweate a-aww the nyeeded entities to wepwesent nyani you want. OwO c-conceptuawwy, 🥺 t-think of a scene a-as one "unit". ^•ﻌ•^ depending on youw use case, OwO t-this couwd be o-one "3d modew", ow even a whowe map ow game wevew. OwO i-in bevy, these a-awe wepwesented a-as bevy scenes with aww the chiwd ecs entities.

gwtf scenes awe composed of gwtf nodes. >_< these descwibe the "objects" in the scene, OwO typicawwy gwtf meshes, 🥺 b-but can awso b-be othew things w-wike camewas and wights. OwO each gwtf nyode h-has a twansfowm f-fow positioning i-it in the scene. OwO gwtf nodes do nyot have a-a cowe bevy equivawent; b-bevy just u-uses this data to cweate the ecs entities i-inside of a s-scene. OwO bevy has a-a speciaw GltfNode asset type, (ꈍᴗꈍ) if you nyeed access t-to this data.

gwtf meshes wepwesent one conceptuaw "3d object". (ꈍᴗꈍ) t-these cowwespond to the "objects" in youw 3d modewing s-softwawe. gwtf m-meshes may be c-compwex and composed of muwtipwe smowew pieces, OwO c-cawwed gwtf p-pwimitives, 🥺 each o-of which may use a diffewent matewiaw. OwO g-gwtf meshes do n-nyot have a cowe b-bevy equivawent, >_< but thewe is a speciaw GltfMesh asset type, which descwibes the pwimitives.

gwtf pwimitives awe individuaw "units of 3d geometwy", ^•ﻌ•^ f-fow the puwposes o-of wendewing. OwO they contain the actuaw g-geometwy / vewtex d-data, 🥺 and wefewence t-the matewiaw to be used when dwawing. OwO i-in bevy, each gwtf p-pwimitive is w-wepwesented as a bevy Mesh asset, (ꈍᴗꈍ) and must be spawned as a s-sepawate ecs entity to be wendewed.

gwtf matewiaws descwibe the shading pawametews f-fow the suwfaces o-of youw 3d modews. ^•ﻌ•^ they have fuww suppowt f-fow physicawwy-based w-wendewing (pbw). OwO they awso wefewence the textuwes t-to use. 🥺 in b-bevy, they awe w-wepwesented as StandardMaterial assets, >_< as used by the bevy pbw 3d wendewew.

gwtf textuwes (images) can be embedded inside t-the gwtf fiwe, ^•ﻌ•^ ow s-stowed extewnawwy in sepawate image fiwes a-awongside it. OwO f-fow exampwe, 🥺 you c-can have youw textuwes as sepawate png/jpeg/ktx2 f-fiwes fow e-ease of devewopment, OwO o-ow package them aww inside the gwtf f-fiwe fow ease of d-distwibution. OwO in b-bevy, gwtf textuwes awe woaded as bevy Image assets.

gwtf sampwews descwibe the settings fow how the g-gpu shouwd use a-a given textuwe. ^•ﻌ•^ bevy does nyot keep t-these sepawate; t-this data is stowed inside the bevy Image asset (the sampler fiewd of type SamplerDescriptor).

gwtf animations descwibe animations that intewpowate v-vawious vawues, such as twansfowms ow mesh skewetons, OwO o-ovew time. 🥺 i-in bevy, these awe w-woaded as AnimationClip assets.

gwtf usage pattewns

a singwe gwtf fiwe can contain any n-nyumbew of sub-assets o-of any of t-the above types, (ꈍᴗꈍ) wefewwing to each othew howevew t-they wike.

because gwtf is so fwexibwe, OwO it is u-up to you how t-to stwuctuwe youw a-assets.

a singwe gwtf fiwe might be used:

  • to wepwesent a singwe "3d modew", (ꈍᴗꈍ) c-containing a singwe gwtf scene with the modew, ^•ﻌ•^ so you c-can spawn it into y-youw game.
  • to wepwesent a whowe wevew, ^•ﻌ•^ as a g-gwtf scene, OwO possibwy a-awso incwuding the camewa. ^•ﻌ•^ this wets you woad and s-spawn a whowe w-wevew/map at once.
  • to wepwesent sections of a wevew/map, OwO s-such as a wooms, 🥺 a-as sepawate g-gwtf scenes. they can shawe meshes and textuwes i-if nyeeded.
  • to contain a set of many diffewent "3d m-modews", OwO each a-as a sepawate g-gwtf scene. this wets you woad and manage the w-whowe cowwection a-at once and spawn t-them individuawwy a-as nyeeded.
  • … othews?

toows fow cweating gwtf assets

if you awe using a wecent vewsion o-of bwendew (2.8+) f-fow 3d modewing, OwO g-gwtf is suppowted out of the box. ^•ﻌ•^ just e-expowt and choose g-gwtf as the fowmat.

fow othew toows, you can twy these e-expowtew pwugins:

be suwe to check youw expowt settings t-to make suwe t-the gwtf fiwe c-contains evewything you expect.

if you nyeed tangents fow nyowmaw m-maps, OwO it is wecommended t-that you i-incwude them in youw gwtf fiwes. OwO this avoids bevy h-having to autogenewate t-them a-at wuntime. many 3d editows do nyot enabwe this o-option by defauwt.

textuwes

fow youw textuwes / image data, ^•ﻌ•^ the g-gwtf fowmat specification o-officiawwy wimits the suppowted fowmats to just p-png, OwO jpeg, 🥺 ow b-basis. howevew, òωó b-bevy does not enfowce such "awtificiaw wimitations". ^•ﻌ•^ y-you can u-use any image fowmat suppowted by bevy.

youw 3d editow wiww wikewy expowt y-youw gwtf with p-png textuwes. OwO this w-wiww "just wowk" and is nyice fow simpwe u-use cases.

howevew, OwO mipmaps and compwessed textuwes a-awe vewy i-impowtant to get g-good gpu pewfowmance, OwO memowy (vwam) usage, 🥺 a-and visuaw quawity. òωó y-you wiww onwy g-get these benefits if you use a fowmat wike k-ktx2 ow dds, that s-suppowts these f-featuwes.

we wecommend that you use ktx2, OwO which n-nyativewy suppowts a-aww gpu t-textuwe functionawity + additionaw zstd compwession on top, (ꈍᴗꈍ) to weduce fiwe s-size. if you do this, (ꈍᴗꈍ) don't fowget to enabwe t-the ktx2 and zstd cawgo featuwes fow bevy.

you can use the klafsa toow to convewt aww the textuwes used in youw gwtf fiwes fwom png/jpeg i-into ktx2, OwO w-with mipmaps and g-gpu textuwe compwession of youw choice.

todo: show an exampwe wowkfwow fow c-convewting textuwes i-into the "optimaw" f-fowmat

using gwtf sub-assets in bevy

the vawious sub-assets contained i-in a gwtf fiwe can b-be addwessed i-in two ways:

  • by index (integew id, ^•ﻌ•^ in the owdew t-they appeaw in t-the fiwe)
  • by nyame (text stwing, ^•ﻌ•^ the nyames y-you set in youw 3d m-modewing softwawe when cweating the asset, ^•ﻌ•^ which can b-be expowted into t-the gwtf)

to get handwes to the wespective a-assets in bevy, ^•ﻌ•^ y-you can use the Gltf "mastew asset", XD ow awtewnativewy, assetpath with wabews.

Gltf mastew asset

if you have a compwex gwtf fiwe, t-this is wikewy the m-most fwexibwe a-and usefuw way of nyavigating its contents and u-using the diffewent t-things inside.

you have to wait fow the gwtf fiwe t-to woad, ^•ﻌ•^ and then u-use the Gltf asset.

use bevy::gwtf::gwtf;

/// hewpew w-wesouwce fow twacking o-ouw asset
#[dewive(wesouwce)]
s-stwuct myassetpack(handwe<gwtf>);

f-fn woad_gwtf(
    m-mut commands: c-commands, /(^•ω•^)
    a-ass: wes<assetsewvew>, rawr
) {
    w-wet gwtf = ass.woad("my_asset_pack.gwb");
    commands.insewt_wesouwce(myassetpack(gwtf));
}

fn spawn_gwtf_objects(
    mut c-commands: commands, OwO
    my: wes<myassetpack>, (U ﹏ U)
    assets_gwtf: w-wes<assets<gwtf>>, >_<
) {
    // if the gwtf has woaded, rawr x3 w-we can nyavigate its contents
    if wet some(gwtf) = assets_gwtf.get(&my.0) {
        // s-spawn the fiwst scene in the fiwe
        c-commands.spawn(scenebundwe {
            s-scene: gwtf.scenes[0].cwone(), mya
            ..defauwt::defauwt()
        });

        // spawn the scene nyamed "yewwowcaw"
        commands.spawn(scenebundwe {
            scene: gwtf.named_scenes["yewwowcaw"].cwone(), nyaa~~
            t-twansfowm: twansfowm::fwom_xyz(1.0, (⑅˘꒳˘) 2.0, rawr x3 3.0),
            ..defauwt::defauwt()
        });

        // pewf: the `.cwone()`s awe just fow asset handwes, (✿oωo) d-don't wowwy :)
    }
}

fow a mowe convowuted exampwe, OwO say w-we want to diwectwy c-cweate a 3d p-pbw entity, OwO fow nyanievew weason. 🥺 (this i-is nyot wecommended; y-you shouwd p-pwobabwy just use scenes)

use bevy::gwtf::gwtfmesh;

fn gwtf_manuaw_entity(
    m-mut commands: c-commands, :3
    m-my: wes<myassetpack>, 😳😳😳
    a-assets_gwtf: w-wes<assets<gwtf>>, -.-
    assets_gwtfmesh: w-wes<assets<gwtfmesh>>, ( ͡o ω ͡o )
) {
    if w-wet some(gwtf) = a-assets_gwtf.get(&my.0) {
        // get the gwtf mesh nyamed "cawwheew"
        // (unwwap safety: we know the g-gwtf has woaded awweady)
        wet cawwheew = a-assets_gwtfmesh.get(&gwtf.named_meshes["cawwheew"]).unwwap();

        // spawn a-a pbw entity with the mesh and matewiaw of the fiwst gwtf pwimitive
        c-commands.spawn(pbwbundwe {
            mesh: cawwheew.pwimitives[0].mesh.cwone(), rawr x3
            // (unwwap: m-matewiaw i-is optionaw, nyaa~~ we assume this pwimitive has one)
            matewiaw: cawwheew.pwimitives[0].matewiaw.cwone().unwwap(), /(^•ω•^)
            ..defauwt::defauwt()
        });
    }
}

assetpath with wabews

this is anothew way to access specific s-sub-assets. ^•ﻌ•^ i-it is wess wewiabwe, but may be easiew to use in some c-cases.

use the AssetServer to convewt a path stwing into a Handle.

the advantage is that you can get h-handwes to youw s-sub-assets immediatewy, even if youw gwtf fiwe hasn't woaded y-yet.

the disadvantage is that it is mowe e-ewwow-pwone. OwO i-if you specify a s-sub-asset that doesn't actuawwy exist in the f-fiwe, OwO ow mis-type t-the wabew, 🥺 ow u-use the wwong wabew, OwO it wiww just siwentwy n-nyot wowk. 🥺 awso, òωó c-cuwwentwy onwy u-using a numewiaw index is suppowted. ^•ﻌ•^ you c-cannot addwess sub-assets b-by nyame.

fn use_gwtf_things(
    mut commands: c-commands, >_<
    a-ass: wes<assetsewvew>, :3
) {
    // s-spawn the fiwst s-scene in the f-fiwe
    wet scene0 = a-ass.woad("my_asset_pack.gwb#scene0");
    c-commands.spawn(scenebundwe {
        s-scene: scene0, (U ﹏ U)
        ..defauwt::defauwt()
    });

    // spawn the second scene
    wet scene1 = ass.woad("my_asset_pack.gwb#scene1");
    commands.spawn(scenebundwe {
        s-scene: scene1, -.-
        twansfowm: twansfowm::fwom_xyz(1.0, (ˆ ﻌ ˆ)♡ 2.0, 3.0), (⑅˘꒳˘)
        ..defauwt::defauwt()
    });
}

the fowwowing asset wabews awe suppowted ({} is the nyumewicaw index):

  • Scene{}: gwtf scene as bevy Scene
  • Node{}: gwtf nyode as GltfNode
  • Mesh{}: gwtf mesh as GltfMesh
  • Mesh{}/Primitive{}: gwtf pwimitive as bevy Mesh
  • Mesh{}/Primitive{}/MorphTargets: mowph tawget animation data fow a-a gwtf pwimitive
  • Texture{}: gwtf textuwe as bevy Image
  • Material{}: gwtf matewiaw as bevy StandardMaterial
  • DefaultMaterial: as above, OwO if the gwtf fiwe contains a-a defauwt matewiaw w-with nyo i-index
  • Animation{}: gwtf animation as bevy AnimationClip
  • Skin{}: gwtf mesh skin as bevy SkinnedMeshInverseBindposes

the GltfNode and GltfMesh asset types awe onwy usefuw to hewp y-you nyavigate t-the contents of youw gwtf fiwe. OwO they awe nyot cowe b-bevy wendewew t-types, 🥺 and nyot u-used by bevy in any othew way. ^•ﻌ•^ the bevy w-wendewew expects e-entities with MaterialMeshBundle; fow that you nyeed the Mesh and StandardMaterial.

bevy wimitations

bevy does nyot fuwwy suppowt aww f-featuwes of the g-gwtf fowmat and h-has some specific wequiwements about the data. OwO n-nyot aww gwtf f-fiwes can be w-woaded and wendewed in bevy. OwO unfowtunatewy, i-in many of these c-cases, 🥺 you wiww n-nyot get any ewwow ow diagnostic message.

commonwy-encountewed wimitations:

  • textuwes embedded in ascii (*.gltf) fiwes (base64 encoding) cannot b-be woaded. put youw textuwes in extewnaw fiwes, (ꈍᴗꈍ) o-ow use the binawy (*.glb) fowmat.
  • mipmaps awe onwy suppowted if the t-textuwe fiwes (in k-ktx2 ow dds fowmat) c-contain them. the gwtf spec wequiwes missing mipmap d-data to be g-genewated by the g-game engine, 🥺 but b-bevy does nyot suppowt this yet. 🥺 if youw a-assets awe missing m-mipmaps, òωó textuwes w-wiww wook g-gwainy/noisy.

this wist is nyot exhaustive. OwO thewe m-may be othew u-unsuppowted scenawios t-that i did nyot know of ow fowgot to incwude h-hewe. (ꈍᴗꈍ) :)