diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 25b6b8766a67f..5b51e1322acc1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -162,7 +162,7 @@ jobs: markdownlint: runs-on: ubuntu-latest - needs: check-missing-examples-in-docs + needs: check-examples-readme-update-needed if: always() steps: - uses: actions/checkout@v3 @@ -261,14 +261,19 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - - name: Check that examples are present in both README and Cargo - uses: Weibye/action-internal-link-consistency@1.0.0 - with: - source: './examples/' - targets: '[ "./Cargo.toml", "./examples/README.md" ]' - file-types: '[".rs"]' - exclude-folders: '["./examples/ios"]' - exclude-files: '[]' + - run: cargo run -p build-example-pages -- check-missing + + check-examples-readme-update-needed: + needs: check-missing-examples-in-docs + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - run: cargo run -p build-example-pages -- update + - name: Check for modified files + run: | + echo "if this step fails, run the following command and commit the changed file on your PR." + echo " > cargo run -p build-example-pages -- update" + git diff --quiet HEAD -- check-unused-dependencies: runs-on: ubuntu-latest diff --git a/Cargo.toml b/Cargo.toml index d69f0c234a785..2306477cc4012 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -13,7 +13,7 @@ repository = "https://github.com/bevyengine/bevy" [workspace] exclude = ["benches", "crates/bevy_ecs_compile_fail_tests"] -members = ["crates/*", "examples/ios", "tools/ci", "tools/spancmp", "tools/build-wasm-example", "errors"] +members = ["crates/*", "examples/ios", "tools/ci", "tools/spancmp", "tools/build-example-pages", "tools/build-wasm-example", "errors"] [features] default = [ @@ -126,543 +126,1333 @@ crossbeam-channel = "0.5.0" name = "hello_world" path = "examples/hello_world.rs" +[package.metadata.example.hello_world] +hidden = true + # 2D Rendering [[example]] name = "move_sprite" path = "examples/2d/move_sprite.rs" +[package.metadata.example.move_sprite] +name = "Move Sprite" +description = "Changes the transform of a sprite" +category = "2D Rendering" +wasm = true + [[example]] name = "rotation" path = "examples/2d/rotation.rs" +[package.metadata.example.rotation] +name = "2D Rotation" +description = "Demonstrates rotating entities in 2D with quaternions" +category = "2D Rendering" +wasm = true + [[example]] name = "mesh2d" path = "examples/2d/mesh2d.rs" +[package.metadata.example.mesh2d] +name = "Mesh 2D" +description = "Renders a 2d mesh" +category = "2D Rendering" +wasm = true + [[example]] name = "mesh2d_manual" path = "examples/2d/mesh2d_manual.rs" +[package.metadata.example.mesh2d_manual] +name = "Manual Mesh 2D" +description = "Renders a custom mesh \"manually\" with \"mid-level\" renderer apis" +category = "2D Rendering" +wasm = true + [[example]] name = "mesh2d_vertex_color_texture" path = "examples/2d/mesh2d_vertex_color_texture.rs" +[package.metadata.example.mesh2d_vertex_color_texture] +name = "Mesh 2D With Vertex Colors" +description = "Renders a 2d mesh with vertex color attributes" +category = "2D Rendering" +wasm = true + [[example]] name = "shapes" path = "examples/2d/shapes.rs" +[package.metadata.example.shapes] +name = "Shapes" +description = "Renders a rectangle, circle, and hexagon" +category = "2D Rendering" +wasm = true + [[example]] name = "sprite" path = "examples/2d/sprite.rs" +[package.metadata.example.sprite] +name = "Sprite" +description = "Renders a sprite" +category = "2D Rendering" +wasm = true + [[example]] name = "sprite_flipping" path = "examples/2d/sprite_flipping.rs" +[package.metadata.example.sprite_flipping] +name = "Sprite Flipping" +description = "Renders a sprite flipped along an axis" +category = "2D Rendering" +wasm = true + [[example]] name = "sprite_sheet" path = "examples/2d/sprite_sheet.rs" +[package.metadata.example.sprite_sheet] +name = "Sprite Sheet" +description = "Renders an animated sprite" +category = "2D Rendering" +wasm = true + [[example]] name = "text2d" path = "examples/2d/text2d.rs" +[package.metadata.example.text2d] +name = "Text 2D" +description = "Generates text in 2D" +category = "2D Rendering" +wasm = true + [[example]] name = "texture_atlas" path = "examples/2d/texture_atlas.rs" +[package.metadata.example.texture_atlas] +name = "Texture Atlas" +description = "Generates a texture atlas (sprite sheet) from individual sprites" +category = "2D Rendering" +wasm = true + [[example]] name = "transparency_2d" path = "examples/2d/transparency_2d.rs" +[package.metadata.example.transparency_2d] +name = "Transparency in 2D" +description = "Demonstrates transparency in 2d" +category = "2D Rendering" +wasm = true + # 3D Rendering [[example]] name = "3d_scene" path = "examples/3d/3d_scene.rs" +[package.metadata.example.3d_scene] +name = "3D Scene" +description = "Simple 3D scene with basic shapes and lighting" +category = "3D Rendering" +wasm = true + [[example]] name = "3d_shapes" path = "examples/3d/shapes.rs" +[package.metadata.example.3d_shapes] +name = "3D Shapes" +description = "A scene showcasing the built-in 3D shapes" +category = "3D Rendering" +wasm = true + [[example]] name = "lighting" path = "examples/3d/lighting.rs" +[package.metadata.example.lighting] +name = "Lighting" +description = "Illustrates various lighting options in a simple scene" +category = "3D Rendering" +wasm = true + [[example]] name = "load_gltf" path = "examples/3d/load_gltf.rs" +[package.metadata.example.load_gltf] +name = "Load glTF" +description = "Loads and renders a glTF file as a scene" +category = "3D Rendering" +wasm = true + [[example]] name = "msaa" path = "examples/3d/msaa.rs" +[package.metadata.example.msaa] +name = "MSAA" +description = "Configures MSAA (Multi-Sample Anti-Aliasing) for smoother edges" +category = "3D Rendering" +wasm = true + [[example]] name = "orthographic" path = "examples/3d/orthographic.rs" +[package.metadata.example.orthographic] +name = "Orthographic View" +description = "Shows how to create a 3D orthographic view (for isometric-look in games or CAD applications)" +category = "3D Rendering" +wasm = true + [[example]] name = "parenting" path = "examples/3d/parenting.rs" +[package.metadata.example.parenting] +name = "Parenting" +description = "Demonstrates parent->child relationships and relative transformations" +category = "3D Rendering" +wasm = true + [[example]] name = "pbr" path = "examples/3d/pbr.rs" +[package.metadata.example.pbr] +name = "Physically Based Rendering" +description = "Demonstrates use of Physically Based Rendering (PBR) properties" +category = "3D Rendering" +wasm = true + [[example]] name = "render_to_texture" path = "examples/3d/render_to_texture.rs" +[package.metadata.example.render_to_texture] +name = "Render to Texture" +description = "Shows how to render to a texture, useful for mirrors, UI, or exporting images" +category = "3D Rendering" +wasm = true + [[example]] name = "shadow_biases" path = "examples/3d/shadow_biases.rs" +[package.metadata.example.shadow_biases] +name = "Shadow Biases" +description = "Demonstrates how shadow biases affect shadows in a 3d scene" +category = "3D Rendering" +wasm = true + [[example]] name = "shadow_caster_receiver" path = "examples/3d/shadow_caster_receiver.rs" +[package.metadata.example.shadow_caster_receiver] +name = "Shadow Caster and Receiver" +description = "Demonstrates how to prevent meshes from casting/receiving shadows in a 3d scene" +category = "3D Rendering" +wasm = true + [[example]] name = "spherical_area_lights" path = "examples/3d/spherical_area_lights.rs" +[package.metadata.example.spherical_area_lights] +name = "Spherical Area Lights" +description = "Demonstrates how point light radius values affect light behavior" +category = "3D Rendering" +wasm = true + [[example]] name = "split_screen" path = "examples/3d/split_screen.rs" +[package.metadata.example.split_screen] +name = "Split Screen" +description = "Demonstrates how to render two cameras to the same window to accomplish \"split screen\"" +category = "3D Rendering" +wasm = true + [[example]] name = "texture" path = "examples/3d/texture.rs" +[package.metadata.example.texture] +name = "Texture" +description = "Shows configuration of texture materials" +category = "3D Rendering" +wasm = true + [[example]] name = "transparency_3d" path = "examples/3d/transparency_3d.rs" +[package.metadata.example.transparency_3d] +name = "Transparency in 3D" +description = "Demonstrates transparency in 3d" +category = "3D Rendering" +wasm = true + [[example]] name = "two_passes" path = "examples/3d/two_passes.rs" +[package.metadata.example.two_passes] +name = "Two Passes" +description = "Renders two 3d passes to the same window from different perspectives" +category = "3D Rendering" +wasm = true + [[example]] name = "update_gltf_scene" path = "examples/3d/update_gltf_scene.rs" +[package.metadata.example.update_gltf_scene] +name = "Update glTF Scene" +description = "Update a scene from a glTF file, either by spawning the scene as a child of another entity, or by accessing the entities of the scene" +category = "3D Rendering" +wasm = true + [[example]] name = "vertex_colors" path = "examples/3d/vertex_colors.rs" +[package.metadata.example.vertex_colors] +name = "Vertex Colors" +description = "Shows the use of vertex colors" +category = "3D Rendering" +wasm = true + [[example]] name = "wireframe" path = "examples/3d/wireframe.rs" +[package.metadata.example.wireframe] +name = "Wireframe" +description = "Showcases wireframe rendering" +category = "3D Rendering" +wasm = true + # Animation [[example]] name = "animated_fox" path = "examples/animation/animated_fox.rs" +[package.metadata.example.animated_fox] +name = "Animated Fox" +description = "Plays an animation from a skinned glTF" +category = "Animation" +wasm = true + [[example]] name = "animated_transform" path = "examples/animation/animated_transform.rs" +[package.metadata.example.animated_transform] +name = "Animated Transform" +description = "Create and play an animation defined by code that operates on the `Transform` component" +category = "Animation" +wasm = true + [[example]] name = "custom_skinned_mesh" path = "examples/animation/custom_skinned_mesh.rs" +[package.metadata.example.custom_skinned_mesh] +name = "Custom Skinned Mesh" +description = "Skinned mesh example with mesh and joints data defined in code" +category = "Animation" +wasm = true + [[example]] name = "gltf_skinned_mesh" path = "examples/animation/gltf_skinned_mesh.rs" +[package.metadata.example.gltf_skinned_mesh] +name = "glTF Skinned Mesh" +description = "Skinned mesh example with mesh and joints data loaded from a glTF file" +category = "Animation" +wasm = true + # Application [[example]] name = "custom_loop" path = "examples/app/custom_loop.rs" +[package.metadata.example.custom_loop] +name = "Custom Loop" +description = "Demonstrates how to create a custom runner (to update an app manually)" +category = "Application" +wasm = false + [[example]] name = "drag_and_drop" path = "examples/app/drag_and_drop.rs" +[package.metadata.example.drag_and_drop] +name = "Drag and Drop" +description = "An example that shows how to handle drag and drop in an app" +category = "Application" +wasm = false + [[example]] name = "empty" path = "examples/app/empty.rs" +[package.metadata.example.empty] +name = "Empty" +description = "An empty application (does nothing)" +category = "Application" +wasm = false + [[example]] name = "empty_defaults" path = "examples/app/empty_defaults.rs" +[package.metadata.example.empty_defaults] +name = "Empty with Defaults" +description = "An empty application with default plugins" +category = "Application" +wasm = true + [[example]] name = "headless" path = "examples/app/headless.rs" +[package.metadata.example.headless] +name = "Headless" +description = "An application that runs without default plugins" +category = "Application" +wasm = false + [[example]] name = "logs" path = "examples/app/logs.rs" +[package.metadata.example.logs] +name = "Logs" +description = "Illustrate how to use generate log output" +category = "Application" +wasm = true + [[example]] name = "plugin" path = "examples/app/plugin.rs" +[package.metadata.example.plugin] +name = "Plugin" +description = "Demonstrates the creation and registration of a custom plugin" +category = "Application" +wasm = true + [[example]] name = "plugin_group" path = "examples/app/plugin_group.rs" +[package.metadata.example.plugin_group] +name = "Plugin Group" +description = "Demonstrates the creation and registration of a custom plugin group" +category = "Application" +wasm = true + [[example]] name = "return_after_run" path = "examples/app/return_after_run.rs" +[package.metadata.example.return_after_run] +name = "Return after Run" +description = "Show how to return to main after the Bevy app has exited" +category = "Application" +wasm = false + [[example]] name = "thread_pool_resources" path = "examples/app/thread_pool_resources.rs" +[package.metadata.example.thread_pool_resources] +name = "Thread Pool Resources" +description = "Creates and customizes the internal thread pool" +category = "Application" +wasm = false + [[example]] name = "headless_defaults" path = "examples/app/headless_defaults.rs" +[package.metadata.example.headless_defaults] +name = "Headless with Defaults" +description = "An application that runs with default plugins, but without an actual renderer" +category = "Application" +wasm = false + [[example]] name = "without_winit" path = "examples/app/without_winit.rs" +[package.metadata.example.without_winit] +name = "Without Winit" +description = "Create an application without winit (runs single time, no event loop)" +category = "Application" +wasm = false + # Assets [[example]] name = "asset_loading" path = "examples/asset/asset_loading.rs" +[package.metadata.example.asset_loading] +name = "Asset Loading" +description = "Demonstrates various methods to load assets" +category = "Assets" +wasm = true + [[example]] name = "custom_asset" path = "examples/asset/custom_asset.rs" +[package.metadata.example.custom_asset] +name = "Custom Asset" +description = "Implements a custom asset loader" +category = "Assets" +wasm = true + [[example]] name = "custom_asset_io" path = "examples/asset/custom_asset_io.rs" +[package.metadata.example.custom_asset_io] +name = "Custom Asset IO" +description = "Implements a custom asset io loader" +category = "Assets" +wasm = true + [[example]] name = "hot_asset_reloading" path = "examples/asset/hot_asset_reloading.rs" +[package.metadata.example.hot_asset_reloading] +name = "Hot Reloading of Assets" +description = "Demonstrates automatic reloading of assets when modified on disk" +category = "Assets" +wasm = true + # Async Tasks [[example]] name = "async_compute" path = "examples/async_tasks/async_compute.rs" +[package.metadata.example.async_compute] +name = "Async Compute" +description = "How to use `AsyncComputeTaskPool` to complete longer running tasks" +category = "Async Tasks" +wasm = false + [[example]] name = "external_source_external_thread" path = "examples/async_tasks/external_source_external_thread.rs" +[package.metadata.example.external_source_external_thread] +name = "External Source of Data on an External Thread" +description = "How to use an external thread to run an infinite task and communicate with a channel" +category = "Async Tasks" +wasm = false + # Audio [[example]] name = "audio" path = "examples/audio/audio.rs" +[package.metadata.example.audio] +name = "Audio" +description = "Shows how to load and play an audio file" +category = "Audio" +wasm = true + [[example]] name = "audio_control" path = "examples/audio/audio_control.rs" +[package.metadata.example.audio_control] +name = "Audio Control" +description = "Shows how to load and play an audio file, and control how it's played" +category = "Audio" +wasm = true + # Diagnostics [[example]] name = "log_diagnostics" path = "examples/diagnostics/log_diagnostics.rs" +[package.metadata.example.log_diagnostics] +name = "Log Diagnostics" +description = "Add a plugin that logs diagnostics, like frames per second (FPS), to the console" +category = "Diagnostics" +wasm = true + [[example]] name = "custom_diagnostic" path = "examples/diagnostics/custom_diagnostic.rs" +[package.metadata.example.custom_diagnostic] +name = "Custom Diagnostic" +description = "Shows how to create a custom diagnostic" +category = "Diagnostics" +wasm = true + # ECS (Entity Component System) [[example]] name = "ecs_guide" path = "examples/ecs/ecs_guide.rs" +[package.metadata.example.ecs_guide] +name = "ECS Guide" +description = "Full guide to Bevy's ECS" +category = "ECS (Entity Component System)" +wasm = false + [[example]] name = "component_change_detection" path = "examples/ecs/component_change_detection.rs" +[package.metadata.example.component_change_detection] +name = "Component Change Detection" +description = "Change detection on components" +category = "ECS (Entity Component System)" +wasm = false + [[example]] name = "custom_query_param" path = "examples/ecs/custom_query_param.rs" +[package.metadata.example.custom_query_param] +name = "Custom Query Parameters" +description = "Groups commonly used compound queries and query filters into a single type" +category = "ECS (Entity Component System)" +wasm = false + [[example]] name = "event" path = "examples/ecs/event.rs" +[package.metadata.example.event] +name = "Event" +description = "Illustrates event creation, activation, and reception" +category = "ECS (Entity Component System)" +wasm = false + [[example]] name = "fixed_timestep" path = "examples/ecs/fixed_timestep.rs" +[package.metadata.example.fixed_timestep] +name = "Fixed Timestep" +description = "Shows how to create systems that run every fixed timestep, rather than every tick" +category = "ECS (Entity Component System)" +wasm = false + [[example]] name = "generic_system" path = "examples/ecs/generic_system.rs" +[package.metadata.example.generic_system] +name = "Generic System" +description = "Shows how to create systems that can be reused with different types" +category = "ECS (Entity Component System)" +wasm = false + [[example]] name = "hierarchy" path = "examples/ecs/hierarchy.rs" +[package.metadata.example.hierarchy] +name = "Hierarchy" +description = "Creates a hierarchy of parents and children entities" +category = "ECS (Entity Component System)" +wasm = false + [[example]] name = "iter_combinations" path = "examples/ecs/iter_combinations.rs" +[package.metadata.example.iter_combinations] +name = "Iter Combinations" +description = "Shows how to iterate over combinations of query results" +category = "ECS (Entity Component System)" +wasm = true + [[example]] name = "parallel_query" path = "examples/ecs/parallel_query.rs" +[package.metadata.example.parallel_query] +name = "Parallel Query" +description = "Illustrates parallel queries with `ParallelIterator`" +category = "ECS (Entity Component System)" +wasm = false + [[example]] name = "removal_detection" path = "examples/ecs/removal_detection.rs" +[package.metadata.example.removal_detection] +name = "Removal Detection" +description = "Query for entities that had a specific component removed in a previous stage during the current frame" +category = "ECS (Entity Component System)" +wasm = false + [[example]] name = "startup_system" path = "examples/ecs/startup_system.rs" +[package.metadata.example.startup_system] +name = "Startup System" +description = "Demonstrates a startup system (one that runs once when the app starts up)" +category = "ECS (Entity Component System)" +wasm = false + [[example]] name = "state" path = "examples/ecs/state.rs" +[package.metadata.example.state] +name = "State" +description = "Illustrates how to use States to control transitioning from a Menu state to an InGame state" +category = "ECS (Entity Component System)" +wasm = false + [[example]] name = "system_chaining" path = "examples/ecs/system_chaining.rs" +[package.metadata.example.system_chaining] +name = "System Chaining" +description = "Chain two systems together, specifying a return type in a system (such as `Result`)" +category = "ECS (Entity Component System)" +wasm = false + [[example]] name = "system_closure" path = "examples/ecs/system_closure.rs" +[package.metadata.example.system_closure] +name = "System Closure" +description = "Show how to use closures as systems, and how to configure `Local` variables by capturing external state" +category = "ECS (Entity Component System)" +wasm = false + [[example]] name = "system_param" path = "examples/ecs/system_param.rs" +[package.metadata.example.system_param] +name = "System Parameter" +description = "Illustrates creating custom system parameters with `SystemParam`" +category = "ECS (Entity Component System)" +wasm = false + [[example]] name = "system_sets" path = "examples/ecs/system_sets.rs" +[package.metadata.example.system_sets] +name = "System Sets" +description = "Shows `SystemSet` use along with run criterion" +category = "ECS (Entity Component System)" +wasm = false + [[example]] name = "timers" path = "examples/ecs/timers.rs" +[package.metadata.example.timers] +name = "Timers" +description = "Illustrates ticking `Timer` resources inside systems and handling their state" +category = "ECS (Entity Component System)" +wasm = false + # Games [[example]] name = "alien_cake_addict" path = "examples/games/alien_cake_addict.rs" +[package.metadata.example.alien_cake_addict] +name = "Alien Cake Addict" +description = "Eat the cakes. Eat them all. An example 3D game" +category = "Games" +wasm = true + [[example]] name = "breakout" path = "examples/games/breakout.rs" +[package.metadata.example.breakout] +name = "Breakout" +description = "An implementation of the classic game \"Breakout\"" +category = "Games" +wasm = true + [[example]] name = "contributors" path = "examples/games/contributors.rs" +[package.metadata.example.contributors] +name = "Contributors" +description = "Displays each contributor as a bouncy bevy-ball!" +category = "Games" +wasm = true + [[example]] name = "game_menu" path = "examples/games/game_menu.rs" +[package.metadata.example.game_menu] +name = "Game Menu" +description = "A simple game menu" +category = "Games" +wasm = true + # Input [[example]] name = "char_input_events" path = "examples/input/char_input_events.rs" +[package.metadata.example.char_input_events] +name = "Char Input Events" +description = "Prints out all chars as they are inputted" +category = "Input" +wasm = false + [[example]] name = "gamepad_input" path = "examples/input/gamepad_input.rs" +[package.metadata.example.gamepad_input] +name = "Gamepad Input" +description = "Shows handling of gamepad input, connections, and disconnections" +category = "Input" +wasm = false + [[example]] name = "gamepad_input_events" path = "examples/input/gamepad_input_events.rs" +[package.metadata.example.gamepad_input_events] +name = "Gamepad Input Events" +description = "Iterates and prints gamepad input and connection events" +category = "Input" +wasm = false + [[example]] name = "keyboard_input" path = "examples/input/keyboard_input.rs" +[package.metadata.example.keyboard_input] +name = "Keyboard Input" +description = "Demonstrates handling a key press/release" +category = "Input" +wasm = false + [[example]] name = "keyboard_modifiers" path = "examples/input/keyboard_modifiers.rs" +[package.metadata.example.keyboard_modifiers] +name = "Keyboard Modifiers" +description = "Demonstrates using key modifiers (ctrl, shift)" +category = "Input" +wasm = false + [[example]] name = "keyboard_input_events" path = "examples/input/keyboard_input_events.rs" +[package.metadata.example.keyboard_input_events] +name = "Keyboard Input Events" +description = "Prints out all keyboard events" +category = "Input" +wasm = false + [[example]] name = "mouse_input" path = "examples/input/mouse_input.rs" +[package.metadata.example.mouse_input] +name = "Mouse Input" +description = "Demonstrates handling a mouse button press/release" +category = "Input" +wasm = false + [[example]] name = "mouse_input_events" path = "examples/input/mouse_input_events.rs" +[package.metadata.example.mouse_input_events] +name = "Mouse Input Events" +description = "Prints out all mouse events (buttons, movement, etc.)" +category = "Input" +wasm = false + [[example]] name = "mouse_grab" path = "examples/input/mouse_grab.rs" +[package.metadata.example.mouse_grab] +name = "Mouse Grab" +description = "Demonstrates how to grab the mouse, locking the cursor to the app's screen" +category = "Input" +wasm = false + [[example]] name = "touch_input" path = "examples/input/touch_input.rs" +[package.metadata.example.touch_input] +name = "Touch Input" +description = "Displays touch presses, releases, and cancels" +category = "Input" +wasm = false + [[example]] name = "touch_input_events" path = "examples/input/touch_input_events.rs" +[package.metadata.example.touch_input_events] +name = "Touch Input Events" +description = "Prints out all touch inputs" +category = "Input" +wasm = false + # Reflection [[example]] name = "reflection" path = "examples/reflection/reflection.rs" +[package.metadata.example.reflection] +name = "Reflection" +description = "Demonstrates how reflection in Bevy provides a way to dynamically interact with Rust types" +category = "Reflection" +wasm = false + [[example]] name = "generic_reflection" path = "examples/reflection/generic_reflection.rs" +[package.metadata.example.generic_reflection] +name = "Generic Reflection" +description = "Registers concrete instances of generic types that may be used with reflection" +category = "Reflection" +wasm = false + [[example]] name = "reflection_types" path = "examples/reflection/reflection_types.rs" +[package.metadata.example.reflection_types] +name = "Reflection Types" +description = "Illustrates the various reflection types available" +category = "Reflection" +wasm = false + [[example]] name = "trait_reflection" path = "examples/reflection/trait_reflection.rs" +[package.metadata.example.trait_reflection] +name = "Trait Reflection" +description = "Allows reflection with trait objects" +category = "Reflection" +wasm = false + # Scene [[example]] name = "scene" path = "examples/scene/scene.rs" +[package.metadata.example.scene] +name = "Scene" +description = "Demonstrates loading from and saving scenes to files" +category = "Scene" +wasm = false + # Shaders +[[package.metadata.category]] +name = "Shaders" +description = """ +These examples demonstrate how to implement different shaders in user code. + +A shader in its most common usage is a small program that is run by the GPU per-vertex in a mesh (a vertex shader) or per-affected-screen-fragment (a fragment shader.) The GPU executes these programs in a highly parallel way. + +There are also compute shaders which are used for more general processing leveraging the GPU's parallelism. +""" + [[example]] name = "custom_vertex_attribute" path = "examples/shader/custom_vertex_attribute.rs" +[package.metadata.example.custom_vertex_attribute] +name = "Custom Vertex Attribute" +description = "A shader that reads a mesh's custom vertex attribute" +category = "Shaders" +wasm = true + [[example]] name = "post_processing" path = "examples/shader/post_processing.rs" +[package.metadata.example.post_processing] +name = "Post Processing" +description = "A custom post processing effect, using two cameras, with one reusing the render texture of the first one" +category = "Shaders" +wasm = true + [[example]] name = "shader_defs" path = "examples/shader/shader_defs.rs" +[package.metadata.example.shader_defs] +name = "Shader Defs" +description = "A shader that uses \"shaders defs\" (a bevy tool to selectively toggle parts of a shader)" +category = "Shaders" +wasm = true + [[example]] name = "shader_material" path = "examples/shader/shader_material.rs" +[package.metadata.example.shader_material] +name = "Material" +description = "A shader and a material that uses it" +category = "Shaders" +wasm = true + [[example]] name = "shader_material_screenspace_texture" path = "examples/shader/shader_material_screenspace_texture.rs" +[package.metadata.example.shader_material_screenspace_texture] +name = "Material - Screenspace Texture" +description = "A shader that samples a texture with view-independent UV coordinates" +category = "Shaders" +wasm = true + [[example]] name = "shader_material_glsl" path = "examples/shader/shader_material_glsl.rs" +[package.metadata.example.shader_material_glsl] +name = "Material - GLSL" +description = "A shader that uses the GLSL shading language" +category = "Shaders" +wasm = true + [[example]] name = "shader_instancing" path = "examples/shader/shader_instancing.rs" +[package.metadata.example.shader_instancing] +name = "Instancing" +description = "A shader that renders a mesh multiple times in one draw call" +category = "Shaders" +wasm = true + [[example]] name = "animate_shader" path = "examples/shader/animate_shader.rs" +[package.metadata.example.animate_shader] +name = "Animated" +description = "A shader that uses dynamic data like the time since startup" +category = "Shaders" +wasm = true + [[example]] name = "compute_shader_game_of_life" path = "examples/shader/compute_shader_game_of_life.rs" +[package.metadata.example.compute_shader_game_of_life] +name = "Compute - Game of Life" +description = "A compute shader that simulates Conway's Game of Life" +category = "Shaders" +wasm = false + # Stress tests +[[package.metadata.category]] +name = "Stress Tests" +description = """ +These examples are used to test the performance and stability of various parts of the engine in an isolated way. + +Due to the focus on performance it's recommended to run the stress tests in release mode: + +```sh +cargo run --release --example +``` +""" [[example]] name = "bevymark" path = "examples/stress_tests/bevymark.rs" +[package.metadata.example.bevymark] +name = "Bevymark" +description = "A heavy sprite rendering workload to benchmark your system with Bevy" +category = "Stress Tests" +wasm = true + [[example]] name = "many_cubes" path = "examples/stress_tests/many_cubes.rs" +[package.metadata.example.many_cubes] +name = "Many Cubes" +description = "Simple benchmark to test per-entity draw overhead. Run with the `sphere` argument to test frustum culling" +category = "Stress Tests" +wasm = true + [[example]] name = "many_foxes" path = "examples/stress_tests/many_foxes.rs" +[package.metadata.example.many_foxes] +name = "Many Foxes" +description = "Loads an animated fox model and spawns lots of them. Good for testing skinned mesh performance. Takes an unsigned integer argument for the number of foxes to spawn. Defaults to 1000" +category = "Stress Tests" +wasm = true + [[example]] name = "many_lights" path = "examples/stress_tests/many_lights.rs" +[package.metadata.example.many_lights] +name = "Many Lights" +description = "Simple benchmark to test rendering many point lights. Run with `WGPU_SETTINGS_PRIO=webgl2` to restrict to uniform buffers and max 256 lights" +category = "Stress Tests" +wasm = true + [[example]] name = "many_sprites" path = "examples/stress_tests/many_sprites.rs" +[package.metadata.example.many_sprites] +name = "Many Sprites" +description = "Displays many sprites in a grid arragement! Used for performance testing" +category = "Stress Tests" +wasm = true + [[example]] name = "transform_hierarchy" path = "examples/stress_tests/transform_hierarchy.rs" -# Tools +[package.metadata.example.transform_hierarchy] +name = "Transform Hierarchy" +description = "Various test cases for hierarchy and transform propagation performance" +category = "Stress Tests" +wasm = true +# Tools [[example]] name = "scene_viewer" path = "examples/tools/scene_viewer.rs" +[package.metadata.example.scene_viewer] +name = "Scene Viewer" +description = "A simple way to view glTF models with Bevy. Just run `cargo run --release --example scene_viewer /path/to/model.gltf#Scene0`, replacing the path as appropriate. With no arguments it will load the FieldHelmet glTF model from the repository assets subdirectory" +category = "Tools" +wasm = true + # Transforms [[example]] name = "global_vs_local_translation" path = "examples/transforms/global_vs_local_translation.rs" +[package.metadata.example.global_vs_local_translation] +name = "Global / Local Translation" +description = "Illustrates the difference between direction of a translation in respect to local object or global object Transform" +category = "Transforms" +wasm = true + [[example]] name = "3d_rotation" path = "examples/transforms/3d_rotation.rs" +[package.metadata.example.3d_rotation] +name = "3D Rotation" +description = "Illustrates how to (constantly) rotate an object around an axis" +category = "Transforms" +wasm = true + [[example]] name = "scale" path = "examples/transforms/scale.rs" +[package.metadata.example.scale] +name = "Scale" +description = "Illustrates how to scale an object in each direction" +category = "Transforms" +wasm = true + [[example]] name = "transform" path = "examples/transforms/transform.rs" +[package.metadata.example.transform] +name = "Transform" +description = "Shows multiple transformations of objects" +category = "Transforms" +wasm = true + [[example]] name = "translation" path = "examples/transforms/translation.rs" +[package.metadata.example.translation] +name = "Translation" +description = "Illustrates how to move an object along an axis" +category = "Transforms" +wasm = true + # UI (User Interface) [[example]] name = "button" path = "examples/ui/button.rs" +[package.metadata.example.button] +name = "Button" +description = "Illustrates creating and updating a button" +category = "UI (User Interface)" +wasm = true + [[example]] name = "font_atlas_debug" path = "examples/ui/font_atlas_debug.rs" +[package.metadata.example.font_atlas_debug] +name = "Font Atlas Debug" +description = "Illustrates how FontAtlases are populated (used to optimize text rendering internally)" +category = "UI (User Interface)" +wasm = true + [[example]] name = "text" path = "examples/ui/text.rs" +[package.metadata.example.text] +name = "Text" +description = "Illustrates creating and updating text" +category = "UI (User Interface)" +wasm = true + [[example]] name = "text_debug" path = "examples/ui/text_debug.rs" +[package.metadata.example.text_debug] +name = "Text Debug" +description = "An example for debugging text layout" +category = "UI (User Interface)" +wasm = true + [[example]] name = "transparency_ui" path = "examples/ui/transparency_ui.rs" +[package.metadata.example.transparency_ui] +name = "Transparency UI" +description = "Demonstrates transparency for UI" +category = "UI (User Interface)" +wasm = true + [[example]] name = "ui" path = "examples/ui/ui.rs" +[package.metadata.example.ui] +name = "UI" +description = "Illustrates various features of Bevy UI" +category = "UI (User Interface)" +wasm = true + # Window [[example]] name = "clear_color" path = "examples/window/clear_color.rs" +[package.metadata.example.clear_color] +name = "Clear Color" +description = "Creates a solid color window" +category = "Window" +wasm = true + [[example]] name = "low_power" path = "examples/window/low_power.rs" +[package.metadata.example.low_power] +name = "Low Power" +description = "Demonstrates settings to reduce power use for bevy applications" +category = "Window" +wasm = true + [[example]] name = "multiple_windows" path = "examples/window/multiple_windows.rs" +[package.metadata.example.multiple_windows] +name = "Multiple Windows" +description = "Demonstrates creating multiple windows, and rendering to them" +category = "Window" +wasm = false + [[example]] name = "scale_factor_override" path = "examples/window/scale_factor_override.rs" +[package.metadata.example.scale_factor_override] +name = "Scale Factor Iverride" +description = "Illustrates how to customize the default window settings" +category = "Window" +wasm = true + [[example]] name = "transparent_window" path = "examples/window/transparent_window.rs" +[package.metadata.example.transparent_window] +name = "Transparent Window" +description = "Illustrates making the window transparent and hiding the window decoration" +category = "Window" +wasm = false + [[example]] name = "window_settings" path = "examples/window/window_settings.rs" +[package.metadata.example.window_settings] +name = "Window Settings" +description = "Demonstrates customizing default window settings" +category = "Window" +wasm = true + [[example]] name = "resizing" path = "tests/window/resizing.rs" +[package.metadata.example.resizing] +hidden = true + [[example]] name = "minimising" path = "tests/window/minimising.rs" +[package.metadata.example.minimising] +hidden = true # Android [[example]] @@ -670,6 +1460,9 @@ crate-type = ["cdylib"] name = "android" path = "examples/android/android.rs" +[package.metadata.example.android] +hidden = true + [package.metadata.android] apk_label = "Bevy Example" assets = "assets" diff --git a/examples/README.md b/examples/README.md index 221f2eceb6ed5..9791e63499649 100644 --- a/examples/README.md +++ b/examples/README.md @@ -52,11 +52,12 @@ git checkout v0.4.0 - [Scene](#scene) - [Shaders](#shaders) - [Stress Tests](#stress-tests) - - [Tests](#tests) - [Tools](#tools) - [Transforms](#transforms) - [UI (User Interface)](#ui-user-interface) - [Window](#window) + +- [Tests](#tests) - [Platform-Specific Examples](#platform-specific-examples) - [Android](#android) - [Setup](#setup) @@ -76,191 +77,190 @@ git checkout v0.4.0 ## Hello, World! -Example | File | Description ---- | --- | --- -`hello_world` | [`hello_world.rs`](./hello_world.rs) | Runs a minimal example that outputs "hello world" +Example | Description +--- | --- +[`hello_world.rs`](./hello_world.rs) | Runs a minimal example that outputs "hello world" # Cross-Platform Examples ## 2D Rendering -Example | File | Description ---- | --- | --- -`move_sprite` | [`2d/move_sprite.rs`](./2d/move_sprite.rs) | Changes the transform of a sprite. -`mesh2d` | [`2d/mesh2d.rs`](./2d/mesh2d.rs) | Renders a 2d mesh -`mesh2d_manual` | [`2d/mesh2d_manual.rs`](./2d/mesh2d_manual.rs) | Renders a custom mesh "manually" with "mid-level" renderer apis. -`mesh2d_vertex_color_texture` | [`2d/mesh2d_vertex_color_texture.rs`](./2d/mesh2d_vertex_color_texture.rs) | Renders a 2d mesh with vertex color attributes. -`shapes` | [`2d/shapes.rs`](./2d/shapes.rs) | Renders a rectangle, circle, and hexagon -`sprite` | [`2d/sprite.rs`](./2d/sprite.rs) | Renders a sprite -`sprite_sheet` | [`2d/sprite_sheet.rs`](./2d/sprite_sheet.rs) | Renders an animated sprite -`text2d` | [`2d/text2d.rs`](./2d/text2d.rs) | Generates text in 2d -`sprite_flipping` | [`2d/sprite_flipping.rs`](./2d/sprite_flipping.rs) | Renders a sprite flipped along an axis -`texture_atlas` | [`2d/texture_atlas.rs`](./2d/texture_atlas.rs) | Generates a texture atlas (sprite sheet) from individual sprites -`rotation` | [`2d/rotation.rs`](./2d/rotation.rs) | Demonstrates rotating entities in 2D with quaternions -`transparency_2d` | [`2d/transparency_2d.rs`](./2d/transparency_2d.rs) | Demonstrates transparency in 2d +Example | Description +--- | --- +[2D Rotation](../examples/2d/rotation.rs) | Demonstrates rotating entities in 2D with quaternions +[Manual Mesh 2D](../examples/2d/mesh2d_manual.rs) | Renders a custom mesh "manually" with "mid-level" renderer apis +[Mesh 2D](../examples/2d/mesh2d.rs) | Renders a 2d mesh +[Mesh 2D With Vertex Colors](../examples/2d/mesh2d_vertex_color_texture.rs) | Renders a 2d mesh with vertex color attributes +[Move Sprite](../examples/2d/move_sprite.rs) | Changes the transform of a sprite +[Shapes](../examples/2d/shapes.rs) | Renders a rectangle, circle, and hexagon +[Sprite](../examples/2d/sprite.rs) | Renders a sprite +[Sprite Flipping](../examples/2d/sprite_flipping.rs) | Renders a sprite flipped along an axis +[Sprite Sheet](../examples/2d/sprite_sheet.rs) | Renders an animated sprite +[Text 2D](../examples/2d/text2d.rs) | Generates text in 2D +[Texture Atlas](../examples/2d/texture_atlas.rs) | Generates a texture atlas (sprite sheet) from individual sprites +[Transparency in 2D](../examples/2d/transparency_2d.rs) | Demonstrates transparency in 2d ## 3D Rendering -Example | File | Description ---- | --- | --- -`3d_scene` | [`3d/3d_scene.rs`](./3d/3d_scene.rs) | Simple 3D scene with basic shapes and lighting -`3d_shapes` | [`3d/shapes.rs`](./3d/shapes.rs) | A scene showcasing the built-in 3D shapes -`lighting` | [`3d/lighting.rs`](./3d/lighting.rs) | Illustrates various lighting options in a simple scene -`load_gltf` | [`3d/load_gltf.rs`](./3d/load_gltf.rs) | Loads and renders a gltf file as a scene -`msaa` | [`3d/msaa.rs`](./3d/msaa.rs) | Configures MSAA (Multi-Sample Anti-Aliasing) for smoother edges -`orthographic` | [`3d/orthographic.rs`](./3d/orthographic.rs) | Shows how to create a 3D orthographic view (for isometric-look games or CAD applications) -`parenting` | [`3d/parenting.rs`](./3d/parenting.rs) | Demonstrates parent->child relationships and relative transformations -`pbr` | [`3d/pbr.rs`](./3d/pbr.rs) | Demonstrates use of Physically Based Rendering (PBR) properties -`render_to_texture` | [`3d/render_to_texture.rs`](./3d/render_to_texture.rs) | Shows how to render to a texture, useful for mirrors, UI, or exporting images -`shadow_caster_receiver` | [`3d/shadow_caster_receiver.rs`](./3d/shadow_caster_receiver.rs) | Demonstrates how to prevent meshes from casting/receiving shadows in a 3d scene -`shadow_biases` | [`3d/shadow_biases.rs`](./3d/shadow_biases.rs) | Demonstrates how shadow biases affect shadows in a 3d scene -`spherical_area_lights` | [`3d/spherical_area_lights.rs`](./3d/spherical_area_lights.rs) | Demonstrates how point light radius values affect light behavior. -`split_screen` | [`3d/split_screen.rs`](./3d/split_screen.rs) | Demonstrates how to render two cameras to the same window to accomplish "split screen". -`texture` | [`3d/texture.rs`](./3d/texture.rs) | Shows configuration of texture materials -`transparency_3d` | [`3d/transparency_3d.rs`](./3d/transparency_3d.rs) | Demonstrates transparency in 3d -`two_passes` | [`3d/two_passes.rs`](./3d/two_passes.rs) | Renders two 3d passes to the same window from different perspectives. -`update_gltf_scene` | [`3d/update_gltf_scene.rs`](./3d/update_gltf_scene.rs) | Update a scene from a gltf file, either by spawning the scene as a child of another entity, or by accessing the entities of the scene -`vertex_colors` | [`3d/vertex_colors.rs`](./3d/vertex_colors.rs) | Shows the use of vertex colors -`wireframe` | [`3d/wireframe.rs`](./3d/wireframe.rs) | Showcases wireframe rendering +Example | Description +--- | --- +[3D Scene](../examples/3d/3d_scene.rs) | Simple 3D scene with basic shapes and lighting +[3D Shapes](../examples/3d/shapes.rs) | A scene showcasing the built-in 3D shapes +[Lighting](../examples/3d/lighting.rs) | Illustrates various lighting options in a simple scene +[Load glTF](../examples/3d/load_gltf.rs) | Loads and renders a glTF file as a scene +[MSAA](../examples/3d/msaa.rs) | Configures MSAA (Multi-Sample Anti-Aliasing) for smoother edges +[Orthographic View](../examples/3d/orthographic.rs) | Shows how to create a 3D orthographic view (for isometric-look in games or CAD applications) +[Parenting](../examples/3d/parenting.rs) | Demonstrates parent->child relationships and relative transformations +[Physically Based Rendering](../examples/3d/pbr.rs) | Demonstrates use of Physically Based Rendering (PBR) properties +[Render to Texture](../examples/3d/render_to_texture.rs) | Shows how to render to a texture, useful for mirrors, UI, or exporting images +[Shadow Biases](../examples/3d/shadow_biases.rs) | Demonstrates how shadow biases affect shadows in a 3d scene +[Shadow Caster and Receiver](../examples/3d/shadow_caster_receiver.rs) | Demonstrates how to prevent meshes from casting/receiving shadows in a 3d scene +[Spherical Area Lights](../examples/3d/spherical_area_lights.rs) | Demonstrates how point light radius values affect light behavior +[Split Screen](../examples/3d/split_screen.rs) | Demonstrates how to render two cameras to the same window to accomplish "split screen" +[Texture](../examples/3d/texture.rs) | Shows configuration of texture materials +[Transparency in 3D](../examples/3d/transparency_3d.rs) | Demonstrates transparency in 3d +[Two Passes](../examples/3d/two_passes.rs) | Renders two 3d passes to the same window from different perspectives +[Update glTF Scene](../examples/3d/update_gltf_scene.rs) | Update a scene from a glTF file, either by spawning the scene as a child of another entity, or by accessing the entities of the scene +[Vertex Colors](../examples/3d/vertex_colors.rs) | Shows the use of vertex colors +[Wireframe](../examples/3d/wireframe.rs) | Showcases wireframe rendering ## Animation -Example | File | Description ---- | --- | --- -`animated_fox` | [`animation/animated_fox.rs`](./animation/animated_fox.rs) | Plays an animation from a skinned glTF. -`animated_transform` | [`animation/animated_transform.rs`](./animation/animated_transform.rs) | Create and play an animation defined by code that operates on the `Transform` component. -`custom_skinned_mesh` | [`animation/custom_skinned_mesh.rs`](./animation/custom_skinned_mesh.rs) | Skinned mesh example with mesh and joints data defined in code. -`gltf_skinned_mesh` | [`animation/gltf_skinned_mesh.rs`](./animation/gltf_skinned_mesh.rs) | Skinned mesh example with mesh and joints data loaded from a glTF file. +Example | Description +--- | --- +[Animated Fox](../examples/animation/animated_fox.rs) | Plays an animation from a skinned glTF +[Animated Transform](../examples/animation/animated_transform.rs) | Create and play an animation defined by code that operates on the `Transform` component +[Custom Skinned Mesh](../examples/animation/custom_skinned_mesh.rs) | Skinned mesh example with mesh and joints data defined in code +[glTF Skinned Mesh](../examples/animation/gltf_skinned_mesh.rs) | Skinned mesh example with mesh and joints data loaded from a glTF file ## Application -Example | File | Description ---- | --- | --- -`custom_loop` | [`app/custom_loop.rs`](./app/custom_loop.rs) | Demonstrates how to create a custom runner (to update an app manually). -`drag_and_drop` | [`app/drag_and_drop.rs`](./app/drag_and_drop.rs) | An example that shows how to handle drag and drop in an app. -`empty` | [`app/empty.rs`](./app/empty.rs) | An empty application (does nothing) -`empty_defaults` | [`app/empty_defaults.rs`](./app/empty_defaults.rs) | An empty application with default plugins -`headless` | [`app/headless.rs`](./app/headless.rs) | An application that runs without default plugins -`headless_defaults` | [`app/headless_defaults.rs`](./app/headless_defaults.rs) | An application that runs with default plugins, but without an actual renderer -`logs` | [`app/logs.rs`](./app/logs.rs) | Illustrate how to use generate log output -`plugin` | [`app/plugin.rs`](./app/plugin.rs) | Demonstrates the creation and registration of a custom plugin -`plugin_group` | [`app/plugin_group.rs`](./app/plugin_group.rs) | Demonstrates the creation and registration of a custom plugin group -`return_after_run` | [`app/return_after_run.rs`](./app/return_after_run.rs) | Show how to return to main after the Bevy app has exited -`thread_pool_resources` | [`app/thread_pool_resources.rs`](./app/thread_pool_resources.rs) | Creates and customizes the internal thread pool -`without_winit` | [`app/without_winit.rs`](./app/without_winit.rs) | Create an application without winit (runs single time, no event loop) +Example | Description +--- | --- +[Custom Loop](../examples/app/custom_loop.rs) | Demonstrates how to create a custom runner (to update an app manually) +[Drag and Drop](../examples/app/drag_and_drop.rs) | An example that shows how to handle drag and drop in an app +[Empty](../examples/app/empty.rs) | An empty application (does nothing) +[Empty with Defaults](../examples/app/empty_defaults.rs) | An empty application with default plugins +[Headless](../examples/app/headless.rs) | An application that runs without default plugins +[Headless with Defaults](../examples/app/headless_defaults.rs) | An application that runs with default plugins, but without an actual renderer +[Logs](../examples/app/logs.rs) | Illustrate how to use generate log output +[Plugin](../examples/app/plugin.rs) | Demonstrates the creation and registration of a custom plugin +[Plugin Group](../examples/app/plugin_group.rs) | Demonstrates the creation and registration of a custom plugin group +[Return after Run](../examples/app/return_after_run.rs) | Show how to return to main after the Bevy app has exited +[Thread Pool Resources](../examples/app/thread_pool_resources.rs) | Creates and customizes the internal thread pool +[Without Winit](../examples/app/without_winit.rs) | Create an application without winit (runs single time, no event loop) ## Assets -Example | File | Description ---- | --- | --- -`asset_loading` | [`asset/asset_loading.rs`](./asset/asset_loading.rs) | Demonstrates various methods to load assets -`custom_asset` | [`asset/custom_asset.rs`](./asset/custom_asset.rs) | Implements a custom asset loader -`custom_asset_io` | [`asset/custom_asset_io.rs`](./asset/custom_asset_io.rs) | Implements a custom asset io loader -`hot_asset_reloading` | [`asset/hot_asset_reloading.rs`](./asset/hot_asset_reloading.rs) | Demonstrates automatic reloading of assets when modified on disk +Example | Description +--- | --- +[Asset Loading](../examples/asset/asset_loading.rs) | Demonstrates various methods to load assets +[Custom Asset](../examples/asset/custom_asset.rs) | Implements a custom asset loader +[Custom Asset IO](../examples/asset/custom_asset_io.rs) | Implements a custom asset io loader +[Hot Reloading of Assets](../examples/asset/hot_asset_reloading.rs) | Demonstrates automatic reloading of assets when modified on disk ## Async Tasks -Example | File | Description ---- | --- | --- -`async_compute` | [`async_tasks/async_compute.rs`](async_tasks/async_compute.rs) | How to use `AsyncComputeTaskPool` to complete longer running tasks -`external_source_external_thread` | [`async_tasks/external_source_external_thread.rs`](async_tasks/external_source_external_thread.rs) | How to use an external thread to run an infinite task and communicate with a channel +Example | Description +--- | --- +[Async Compute](../examples/async_tasks/async_compute.rs) | How to use `AsyncComputeTaskPool` to complete longer running tasks +[External Source of Data on an External Thread](../examples/async_tasks/external_source_external_thread.rs) | How to use an external thread to run an infinite task and communicate with a channel ## Audio -Example | File | Description ---- | --- | --- -`audio` | [`audio/audio.rs`](./audio/audio.rs) | Shows how to load and play an audio file -`audio_control` | [`audio/audio_control.rs`](./audio/audio_control.rs) | Shows how to load and play an audio file, and control how it's played +Example | Description +--- | --- +[Audio](../examples/audio/audio.rs) | Shows how to load and play an audio file +[Audio Control](../examples/audio/audio_control.rs) | Shows how to load and play an audio file, and control how it's played ## Diagnostics -Example | File | Description ---- | --- | --- -`custom_diagnostic` | [`diagnostics/custom_diagnostic.rs`](./diagnostics/custom_diagnostic.rs) | Shows how to create a custom diagnostic -`log_diagnostics` | [`diagnostics/log_diagnostics.rs`](./diagnostics/log_diagnostics.rs) | Add a plugin that logs diagnostics, like frames per second (FPS), to the console +Example | Description +--- | --- +[Custom Diagnostic](../examples/diagnostics/custom_diagnostic.rs) | Shows how to create a custom diagnostic +[Log Diagnostics](../examples/diagnostics/log_diagnostics.rs) | Add a plugin that logs diagnostics, like frames per second (FPS), to the console ## ECS (Entity Component System) -Example | File | Description ---- | --- | --- -`ecs_guide` | [`ecs/ecs_guide.rs`](./ecs/ecs_guide.rs) | Full guide to Bevy's ECS -`component_change_detection` | [`ecs/component_change_detection.rs`](./ecs/component_change_detection.rs) | Change detection on components -`custom_query_param` | [`ecs/custom_query_param.rs`](./ecs/custom_query_param.rs) | Groups commonly used compound queries and query filters into a single type -`event` | [`ecs/event.rs`](./ecs/event.rs) | Illustrates event creation, activation, and reception -`fixed_timestep` | [`ecs/fixed_timestep.rs`](./ecs/fixed_timestep.rs) | Shows how to create systems that run every fixed timestep, rather than every tick -`generic_system` | [`ecs/generic_system.rs`](./ecs/generic_system.rs) | Shows how to create systems that can be reused with different types -`hierarchy` | [`ecs/hierarchy.rs`](./ecs/hierarchy.rs) | Creates a hierarchy of parents and children entities -`iter_combinations` | [`ecs/iter_combinations.rs`](./ecs/iter_combinations.rs) | Shows how to iterate over combinations of query results. -`parallel_query` | [`ecs/parallel_query.rs`](./ecs/parallel_query.rs) | Illustrates parallel queries with `ParallelIterator` -`removal_detection` | [`ecs/removal_detection.rs`](./ecs/removal_detection.rs) | Query for entities that had a specific component removed in a previous stage during the current frame. -`startup_system` | [`ecs/startup_system.rs`](./ecs/startup_system.rs) | Demonstrates a startup system (one that runs once when the app starts up) -`state` | [`ecs/state.rs`](./ecs/state.rs) | Illustrates how to use States to control transitioning from a Menu state to an InGame state -`system_chaining` | [`ecs/system_chaining.rs`](./ecs/system_chaining.rs) | Chain two systems together, specifying a return type in a system (such as `Result`) -`system_closure` | [`ecs/system_closure.rs`](./ecs/system_closure.rs) | Show how to use closures as systems, and how to configure `Local` variables by capturing external state -`system_param` | [`ecs/system_param.rs`](./ecs/system_param.rs) | Illustrates creating custom system parameters with `SystemParam` -`system_sets` | [`ecs/system_sets.rs`](./ecs/system_sets.rs) | Shows `SystemSet` use along with run criterion -`timers` | [`ecs/timers.rs`](./ecs/timers.rs) | Illustrates ticking `Timer` resources inside systems and handling their state +Example | Description +--- | --- +[Component Change Detection](../examples/ecs/component_change_detection.rs) | Change detection on components +[Custom Query Parameters](../examples/ecs/custom_query_param.rs) | Groups commonly used compound queries and query filters into a single type +[ECS Guide](../examples/ecs/ecs_guide.rs) | Full guide to Bevy's ECS +[Event](../examples/ecs/event.rs) | Illustrates event creation, activation, and reception +[Fixed Timestep](../examples/ecs/fixed_timestep.rs) | Shows how to create systems that run every fixed timestep, rather than every tick +[Generic System](../examples/ecs/generic_system.rs) | Shows how to create systems that can be reused with different types +[Hierarchy](../examples/ecs/hierarchy.rs) | Creates a hierarchy of parents and children entities +[Iter Combinations](../examples/ecs/iter_combinations.rs) | Shows how to iterate over combinations of query results +[Parallel Query](../examples/ecs/parallel_query.rs) | Illustrates parallel queries with `ParallelIterator` +[Removal Detection](../examples/ecs/removal_detection.rs) | Query for entities that had a specific component removed in a previous stage during the current frame +[Startup System](../examples/ecs/startup_system.rs) | Demonstrates a startup system (one that runs once when the app starts up) +[State](../examples/ecs/state.rs) | Illustrates how to use States to control transitioning from a Menu state to an InGame state +[System Chaining](../examples/ecs/system_chaining.rs) | Chain two systems together, specifying a return type in a system (such as `Result`) +[System Closure](../examples/ecs/system_closure.rs) | Show how to use closures as systems, and how to configure `Local` variables by capturing external state +[System Parameter](../examples/ecs/system_param.rs) | Illustrates creating custom system parameters with `SystemParam` +[System Sets](../examples/ecs/system_sets.rs) | Shows `SystemSet` use along with run criterion +[Timers](../examples/ecs/timers.rs) | Illustrates ticking `Timer` resources inside systems and handling their state ## Games -Example | File | Description ---- | --- | --- -`alien_cake_addict` | [`games/alien_cake_addict.rs`](./games/alien_cake_addict.rs) | Eat the cakes. Eat them all. An example 3D game -`breakout` | [`games/breakout.rs`](./games/breakout.rs) | An implementation of the classic game "Breakout" -`contributors` | [`games/contributors.rs`](./games/contributors.rs) | Displays each contributor as a bouncy bevy-ball! -`game_menu` | [`games/game_menu.rs`](./games/game_menu.rs) | A simple game menu +Example | Description +--- | --- +[Alien Cake Addict](../examples/games/alien_cake_addict.rs) | Eat the cakes. Eat them all. An example 3D game +[Breakout](../examples/games/breakout.rs) | An implementation of the classic game "Breakout" +[Contributors](../examples/games/contributors.rs) | Displays each contributor as a bouncy bevy-ball! +[Game Menu](../examples/games/game_menu.rs) | A simple game menu ## Input -Example | File | Description ---- | --- | --- -`char_input_events` | [`input/char_input_events.rs`](./input/char_input_events.rs) | Prints out all chars as they are inputted. -`gamepad_input` | [`input/gamepad_input.rs`](./input/gamepad_input.rs) | Shows handling of gamepad input, connections, and disconnections -`gamepad_input_events` | [`input/gamepad_input_events.rs`](./input/gamepad_input_events.rs) | Iterates and prints gamepad input and connection events -`keyboard_input` | [`input/keyboard_input.rs`](./input/keyboard_input.rs) | Demonstrates handling a key press/release -`keyboard_input_events` | [`input/keyboard_input_events.rs`](./input/keyboard_input_events.rs) | Prints out all keyboard events -`keyboard_modifiers` | [`input/keyboard_modifiers.rs`](./input/keyboard_modifiers.rs) | Demonstrates using key modifiers (ctrl, shift) -`mouse_input` | [`input/mouse_input.rs`](./input/mouse_input.rs) | Demonstrates handling a mouse button press/release -`mouse_input_events` | [`input/mouse_input_events.rs`](./input/mouse_input_events.rs) | Prints out all mouse events (buttons, movement, etc.) -`mouse_grab` | [`input/mouse_grab.rs`](./input/mouse_grab.rs) | Demonstrates how to grab the mouse, locking the cursor to the app's screen -`touch_input` | [`input/touch_input.rs`](./input/touch_input.rs) | Displays touch presses, releases, and cancels -`touch_input_events` | [`input/touch_input_events.rs`](./input/touch_input_events.rs) | Prints out all touch inputs +Example | Description +--- | --- +[Char Input Events](../examples/input/char_input_events.rs) | Prints out all chars as they are inputted +[Gamepad Input](../examples/input/gamepad_input.rs) | Shows handling of gamepad input, connections, and disconnections +[Gamepad Input Events](../examples/input/gamepad_input_events.rs) | Iterates and prints gamepad input and connection events +[Keyboard Input](../examples/input/keyboard_input.rs) | Demonstrates handling a key press/release +[Keyboard Input Events](../examples/input/keyboard_input_events.rs) | Prints out all keyboard events +[Keyboard Modifiers](../examples/input/keyboard_modifiers.rs) | Demonstrates using key modifiers (ctrl, shift) +[Mouse Grab](../examples/input/mouse_grab.rs) | Demonstrates how to grab the mouse, locking the cursor to the app's screen +[Mouse Input](../examples/input/mouse_input.rs) | Demonstrates handling a mouse button press/release +[Mouse Input Events](../examples/input/mouse_input_events.rs) | Prints out all mouse events (buttons, movement, etc.) +[Touch Input](../examples/input/touch_input.rs) | Displays touch presses, releases, and cancels +[Touch Input Events](../examples/input/touch_input_events.rs) | Prints out all touch inputs ## Reflection -Example | File | Description ---- | --- | --- -`reflection` | [`reflection/reflection.rs`](./reflection/reflection.rs) | Demonstrates how reflection in Bevy provides a way to dynamically interact with Rust types -`generic_reflection` | [`reflection/generic_reflection.rs`](./reflection/generic_reflection.rs) | Registers concrete instances of generic types that may be used with reflection -`reflection_types` | [`reflection/reflection_types.rs`](./reflection/reflection_types.rs) | Illustrates the various reflection types available -`trait_reflection` | [`reflection/trait_reflection.rs`](./reflection/trait_reflection.rs) | Allows reflection with trait objects +Example | Description +--- | --- +[Generic Reflection](../examples/reflection/generic_reflection.rs) | Registers concrete instances of generic types that may be used with reflection +[Reflection](../examples/reflection/reflection.rs) | Demonstrates how reflection in Bevy provides a way to dynamically interact with Rust types +[Reflection Types](../examples/reflection/reflection_types.rs) | Illustrates the various reflection types available +[Trait Reflection](../examples/reflection/trait_reflection.rs) | Allows reflection with trait objects ## Scene -Example | File | Description ---- | --- | --- -`scene` | [`scene/scene.rs`](./scene/scene.rs) | Demonstrates loading from and saving scenes to files +Example | Description +--- | --- +[Scene](../examples/scene/scene.rs) | Demonstrates loading from and saving scenes to files ## Shaders These examples demonstrate how to implement different shaders in user code. -A shader in its most common usage is a small program that is run by the GPU per-vertex in a mesh (a vertex shader) -or per-affected-screen-fragment (a fragment shader.) The GPU executes these programs in a highly parallel way. +A shader in its most common usage is a small program that is run by the GPU per-vertex in a mesh (a vertex shader) or per-affected-screen-fragment (a fragment shader.) The GPU executes these programs in a highly parallel way. -There are also compute shaders which are used for more general processing leveraging the GPU’s parallelism. +There are also compute shaders which are used for more general processing leveraging the GPU's parallelism. -Example | File | Description ---- | --- | --- -`animate_shader` | [`shader/animate_shader.rs`](./shader/animate_shader.rs) | A shader that uses dynamic data like the time since startup. -`compute_shader_game_of_life` | [`shader/compute_shader_game_of_life.rs`](./shader/compute_shader_game_of_life.rs) | A compute shader that simulates Conway's Game of Life. -`custom_vertex_attribute` | [`shader/custom_vertex_attribute.rs`](./shader/custom_vertex_attribute.rs) | A shader that reads a mesh's custom vertex attribute. -`post_processing` | [`shader/post_processing.rs`](./shader/post_processing.rs) | A custom post processing effect, using two cameras, with one reusing the render texture of the first one. -`shader_defs` | [`shader/shader_defs.rs`](./shader/shader_defs.rs) | A shader that uses "shaders defs" (a bevy tool to selectively toggle parts of a shader). -`shader_instancing` | [`shader/shader_instancing.rs`](./shader/shader_instancing.rs) | A shader that renders a mesh multiple times in one draw call. -`shader_material` | [`shader/shader_material.rs`](./shader/shader_material.rs) | A shader and a material that uses it. -`shader_material_glsl` | [`shader/shader_material_glsl.rs`](./shader/shader_material_glsl.rs) | A shader that uses the GLSL shading language. -`shader_material_screenspace_texture` | [`shader/shader_material_screenspace_texture.rs`](./shader/shader_material_screenspace_texture.rs) | A shader that samples a texture with view-independent UV coordinates. +Example | Description +--- | --- +[Animated](../examples/shader/animate_shader.rs) | A shader that uses dynamic data like the time since startup +[Compute - Game of Life](../examples/shader/compute_shader_game_of_life.rs) | A compute shader that simulates Conway's Game of Life +[Custom Vertex Attribute](../examples/shader/custom_vertex_attribute.rs) | A shader that reads a mesh's custom vertex attribute +[Instancing](../examples/shader/shader_instancing.rs) | A shader that renders a mesh multiple times in one draw call +[Material](../examples/shader/shader_material.rs) | A shader and a material that uses it +[Material - GLSL](../examples/shader/shader_material_glsl.rs) | A shader that uses the GLSL shading language +[Material - Screenspace Texture](../examples/shader/shader_material_screenspace_texture.rs) | A shader that samples a texture with view-independent UV coordinates +[Post Processing](../examples/shader/post_processing.rs) | A custom post processing effect, using two cameras, with one reusing the render texture of the first one +[Shader Defs](../examples/shader/shader_defs.rs) | A shader that uses "shaders defs" (a bevy tool to selectively toggle parts of a shader) ## Stress Tests @@ -272,58 +272,58 @@ Due to the focus on performance it's recommended to run the stress tests in rele cargo run --release --example ``` -Example | File | Description ---- | --- | --- -`bevymark` | [`stress_tests/bevymark.rs`](./stress_tests/bevymark.rs) | A heavy sprite rendering workload to benchmark your system with Bevy -`many_cubes` | [`stress_tests/many_cubes.rs`](./stress_tests/many_cubes.rs) | Simple benchmark to test per-entity draw overhead. Run with the `sphere` argument to test frustum culling. -`many_foxes` | [`stress_tests/many_foxes.rs`](./stress_tests/many_foxes.rs) | Loads an animated fox model and spawns lots of them. Good for testing skinned mesh performance. Takes an unsigned integer argument for the number of foxes to spawn. Defaults to 1000. -`many_lights` | [`stress_tests/many_lights.rs`](./stress_tests/many_lights.rs) | Simple benchmark to test rendering many point lights. Run with `WGPU_SETTINGS_PRIO=webgl2` to restrict to uniform buffers and max 256 lights. -`many_sprites` | [`stress_tests/many_sprites.rs`](./stress_tests/many_sprites.rs) | Displays many sprites in a grid arragement! Used for performance testing. -`transform_hierarchy.rs` | [`stress_tests/transform_hierarchy.rs`](./stress_tests/transform_hierarchy.rs) | Various test cases for hierarchy and transform propagation performance - -## Tests - -Example | File | Description ---- | --- | --- -`how_to_test_systems` | [`../tests/how_to_test_systems.rs`](../tests/how_to_test_systems.rs) | How to test systems with commands, queries or resources +Example | Description +--- | --- +[Bevymark](../examples/stress_tests/bevymark.rs) | A heavy sprite rendering workload to benchmark your system with Bevy +[Many Cubes](../examples/stress_tests/many_cubes.rs) | Simple benchmark to test per-entity draw overhead. Run with the `sphere` argument to test frustum culling +[Many Foxes](../examples/stress_tests/many_foxes.rs) | Loads an animated fox model and spawns lots of them. Good for testing skinned mesh performance. Takes an unsigned integer argument for the number of foxes to spawn. Defaults to 1000 +[Many Lights](../examples/stress_tests/many_lights.rs) | Simple benchmark to test rendering many point lights. Run with `WGPU_SETTINGS_PRIO=webgl2` to restrict to uniform buffers and max 256 lights +[Many Sprites](../examples/stress_tests/many_sprites.rs) | Displays many sprites in a grid arragement! Used for performance testing +[Transform Hierarchy](../examples/stress_tests/transform_hierarchy.rs) | Various test cases for hierarchy and transform propagation performance ## Tools -Example | File | Description ---- | --- | --- -`scene_viewer` | [`tools/scene_viewer.rs`](./tools/scene_viewer.rs) | A simple way to view glTF models with Bevy. Just run `cargo run --release --example scene_viewer /path/to/model.gltf#Scene0`, replacing the path as appropriate. With no arguments it will load the FieldHelmet glTF model from the repository assets subdirectory. +Example | Description +--- | --- +[Scene Viewer](../examples/tools/scene_viewer.rs) | A simple way to view glTF models with Bevy. Just run `cargo run --release --example scene_viewer /path/to/model.gltf#Scene0`, replacing the path as appropriate. With no arguments it will load the FieldHelmet glTF model from the repository assets subdirectory ## Transforms -Example | File | Description ---- | --- | --- -`3d_rotation` | [`transforms/3d_rotation.rs`](./transforms/3d_rotation.rs) | Illustrates how to (constantly) rotate an object around an axis -`global_vs_local_translation` | [`transforms/global_vs_local_translation.rs`](./transforms/global_vs_local_translation.rs) | Illustrates the difference between direction of a translation in respect to local object or global object Transform. -`scale` | [`transforms/scale.rs`](./transforms/scale.rs) | Illustrates how to scale an object in each direction -`transform` | [`transforms/transfrom.rs`](./transforms/transform.rs) | Shows multiple transformations of objects -`translation` | [`transforms/translation.rs`](./transforms/translation.rs) | Illustrates how to move an object along an axis +Example | Description +--- | --- +[3D Rotation](../examples/transforms/3d_rotation.rs) | Illustrates how to (constantly) rotate an object around an axis +[Global / Local Translation](../examples/transforms/global_vs_local_translation.rs) | Illustrates the difference between direction of a translation in respect to local object or global object Transform +[Scale](../examples/transforms/scale.rs) | Illustrates how to scale an object in each direction +[Transform](../examples/transforms/transform.rs) | Shows multiple transformations of objects +[Translation](../examples/transforms/translation.rs) | Illustrates how to move an object along an axis ## UI (User Interface) -Example | File | Description ---- | --- | --- -`button` | [`ui/button.rs`](./ui/button.rs) | Illustrates creating and updating a button -`font_atlas_debug` | [`ui/font_atlas_debug.rs`](./ui/font_atlas_debug.rs) | Illustrates how FontAtlases are populated (used to optimize text rendering internally) -`text` | [`ui/text.rs`](./ui/text.rs) | Illustrates creating and updating text -`text_debug` | [`ui/text_debug.rs`](./ui/text_debug.rs) | An example for debugging text layout -`transparency_ui` | [`ui/transparency_ui.rs`](./ui/transparency_ui.rs) | Demonstrates transparency for UI -`ui` | [`ui/ui.rs`](./ui/ui.rs) | Illustrates various features of Bevy UI +Example | Description +--- | --- +[Button](../examples/ui/button.rs) | Illustrates creating and updating a button +[Font Atlas Debug](../examples/ui/font_atlas_debug.rs) | Illustrates how FontAtlases are populated (used to optimize text rendering internally) +[Text](../examples/ui/text.rs) | Illustrates creating and updating text +[Text Debug](../examples/ui/text_debug.rs) | An example for debugging text layout +[Transparency UI](../examples/ui/transparency_ui.rs) | Demonstrates transparency for UI +[UI](../examples/ui/ui.rs) | Illustrates various features of Bevy UI ## Window -Example | File | Description ---- | --- | --- -`clear_color` | [`window/clear_color.rs`](./window/clear_color.rs) | Creates a solid color window -`low_power` | [`window/low_power.rs`](./window/low_power.rs) | Demonstrates settings to reduce power use for bevy applications -`multiple_windows` | [`window/multiple_windows.rs`](./window/multiple_windows.rs) | Demonstrates creating multiple windows, and rendering to them -`scale_factor_override` | [`window/scale_factor_override.rs`](./window/scale_factor_override.rs) | Illustrates how to customize the default window settings -`transparent_window` | [`window/transparent_window.rs`](./window/transparent_window.rs) | Illustrates making the window transparent and hiding the window decoration -`window_settings` | [`window/window_settings.rs`](./window/window_settings.rs) | Demonstrates customizing default window settings +Example | Description +--- | --- +[Clear Color](../examples/window/clear_color.rs) | Creates a solid color window +[Low Power](../examples/window/low_power.rs) | Demonstrates settings to reduce power use for bevy applications +[Multiple Windows](../examples/window/multiple_windows.rs) | Demonstrates creating multiple windows, and rendering to them +[Scale Factor Iverride](../examples/window/scale_factor_override.rs) | Illustrates how to customize the default window settings +[Transparent Window](../examples/window/transparent_window.rs) | Illustrates making the window transparent and hiding the window decoration +[Window Settings](../examples/window/window_settings.rs) | Demonstrates customizing default window settings + +# Tests + +Example | Description +--- | --- +[How to Test Systems](../tests/how_to_test_systems.rs) | How to test systems with commands, queries or resources # Platform-Specific Examples @@ -435,13 +435,7 @@ cargo install wasm-bindgen-cli ### Build & Run Following is an example for `lighting`. For other examples, change the `lighting` in the -following command. - -```sh -cargo run -p build-wasm-example -- lighting -``` - -This is the same as running +following commands. ```sh cargo build --release --example lighting --target wasm32-unknown-unknown diff --git a/examples/README.md.tpl b/examples/README.md.tpl new file mode 100644 index 0000000000000..bdc54eb868e89 --- /dev/null +++ b/examples/README.md.tpl @@ -0,0 +1,220 @@ + + + +# Examples + +These examples demonstrate the main features of Bevy and how to use them. +To run an example, use the command `cargo run --example `, and add the option `--features x11` or `--features wayland` to force the example to run on a specific window compositor, e.g. + +```sh +cargo run --features wayland --example hello_world +``` + +**⚠️ Note: for users of releases on crates.io!** + +There are often large differences and incompatible API changes between the latest [crates.io](https://crates.io/crates/bevy) release and the development version of Bevy in the git main branch! + +If you are using a released version of bevy, you need to make sure you are viewing the correct version of the examples! + +- Latest release: [https://github.com/bevyengine/bevy/tree/latest/examples](https://github.com/bevyengine/bevy/tree/latest/examples) +- Specific version, such as `0.4`: [https://github.com/bevyengine/bevy/tree/v0.4.0/examples](https://github.com/bevyengine/bevy/tree/v0.4.0/examples) + +When you clone the repo locally to run the examples, use `git checkout` to get the correct version: + +```bash +# `latest` always points to the newest release +git checkout latest +# or use a specific version +git checkout v0.4.0 +``` + +--- + +## Table of Contents + +- [Examples](#examples) + - [Table of Contents](#table-of-contents) +- [The Bare Minimum](#the-bare-minimum) + - [Hello, World!](#hello-world) +- [Cross-Platform Examples](#cross-platform-examples) +{% for category, _ in all_examples %} - [{{ category }}](#{{ category | slugify }}) +{% endfor %} +- [Tests](#tests) +- [Platform-Specific Examples](#platform-specific-examples) + - [Android](#android) + - [Setup](#setup) + - [Build & Run](#build--run) + - [Old phones](#old-phones) + - [iOS](#ios) + - [Setup](#setup-1) + - [Build & Run](#build--run-1) + - [WASM](#wasm) + - [Setup](#setup-2) + - [Build & Run](#build--run-2) + - [Loading Assets](#loading-assets) + +# The Bare Minimum + + + +## Hello, World! + +Example | Description +--- | --- +[`hello_world.rs`](./hello_world.rs) | Runs a minimal example that outputs "hello world" + +# Cross-Platform Examples +{% for category, details in all_examples %} +## {{ category }} + +{% if details.description is string %}{{ details.description }} +{% endif %}Example | Description +--- | --- +{% for example in details.examples %}[{{ example.name }}](../{{ example.path }}) | {{ example.description }} +{% endfor %}{% endfor %} +# Tests + +Example | Description +--- | --- +[How to Test Systems](../tests/how_to_test_systems.rs) | How to test systems with commands, queries or resources + +# Platform-Specific Examples + +## Android + +### Setup + +```sh +rustup target add aarch64-linux-android armv7-linux-androideabi +cargo install cargo-apk +``` + +The Android SDK must be installed, and the environment variable `ANDROID_SDK_ROOT` set to the root Android `sdk` folder. + +When using `NDK (Side by side)`, the environment variable `ANDROID_NDK_ROOT` must also be set to one of the NDKs in `sdk\ndk\[NDK number]`. + +### Build & Run + +To run on a device setup for Android development, run: + +```sh +cargo apk run --example android +``` + +:warning: At this time Bevy does not work in Android Emulator. + +When using Bevy as a library, the following fields must be added to `Cargo.toml`: + +```toml +[package.metadata.android] +build_targets = ["aarch64-linux-android", "armv7-linux-androideabi"] +target_sdk_version = 29 +min_sdk_version = 16 +``` + +Please reference `cargo-apk` [README](https://crates.io/crates/cargo-apk) for other Android Manifest fields. + +### Old phones + +Bevy by default targets Android API level 29 in its examples which is the +[Play Store's minimum API to upload or update apps](https://developer.android.com/distribute/best-practices/develop/target-sdk). +Users of older phones may want to use an older API when testing. + +To use a different API, the following fields must be updated in Cargo.toml: + +```toml +[package.metadata.android] +target_sdk_version = >>API<< +min_sdk_version = >>API or less<< +``` + +Example | File | Description +--- | --- | --- +`android` | [`android/android.rs`](./android/android.rs) | The `3d/3d_scene.rs` example for Android + +## iOS + +### Setup + +You need to install the correct rust targets: + +- `aarch64-apple-ios`: iOS devices +- `x86_64-apple-ios`: iOS simulator on x86 processors +- `aarch64-apple-ios-sim`: iOS simulator on Apple processors + +```sh +rustup target add aarch64-apple-ios x86_64-apple-ios aarch64-apple-ios-sim +``` + +### Build & Run + +Using bash: + +```sh +cd examples/ios +make run +``` + +In an ideal world, this will boot up, install and run the app for the first +iOS simulator in your `xcrun simctl devices list`. If this fails, you can +specify the simulator device UUID via: + +```sh +DEVICE_ID=${YOUR_DEVICE_ID} make run +``` + +If you'd like to see xcode do stuff, you can run + +```sh +open bevy_ios_example.xcodeproj/ +``` + +which will open xcode. You then must push the zoom zoom play button and wait +for the magic. + +Example | File | Description +--- | --- | --- +`ios` | [`ios/src/lib.rs`](./ios/src/lib.rs) | The `3d/3d_scene.rs` example for iOS + +## WASM + +### Setup + +```sh +rustup target add wasm32-unknown-unknown +cargo install wasm-bindgen-cli +``` + +### Build & Run + +Following is an example for `lighting`. For other examples, change the `lighting` in the +following commands. + +```sh +cargo build --release --example lighting --target wasm32-unknown-unknown +wasm-bindgen --out-name wasm_example --out-dir examples/wasm/target --target web target/wasm32-unknown-unknown/release/examples/lighting.wasm +``` + +The first command will build the example for the wasm target, creating a binary. Then, +[wasm-bindgen-cli](https://rustwasm.github.io/wasm-bindgen/reference/cli.html) is used to create +javascript bindings to this wasm file, which can be loaded using this +[example HTML file](./wasm/index.html). + +Then serve `examples/wasm` directory to browser. i.e. + +```sh +# cargo install basic-http-server +basic-http-server examples/wasm + +# with python +python3 -m http.server --directory examples/wasm + +# with ruby +ruby -run -ehttpd examples/wasm +``` + +### Loading Assets + +To load assets, they need to be available in the folder examples/wasm/assets. Cloning this +repository will set it up as a symlink on Linux and macOS, but you will need to manually move +the assets on Windows. diff --git a/tools/build-example-pages/Cargo.toml b/tools/build-example-pages/Cargo.toml new file mode 100644 index 0000000000000..d14bff97f9981 --- /dev/null +++ b/tools/build-example-pages/Cargo.toml @@ -0,0 +1,13 @@ +[package] +name = "build-example-pages" +version = "0.1.0" +edition = "2021" +description = "handle examples in Bevy" +publish = false +license = "MIT OR Apache-2.0" + +[dependencies] +toml = "0.5" +tera = "1.15" +serde = { version = "1.0", features = [ "derive" ] } +bitflags = "1.3" diff --git a/tools/build-example-pages/src/main.rs b/tools/build-example-pages/src/main.rs new file mode 100644 index 0000000000000..b64530a97bc9c --- /dev/null +++ b/tools/build-example-pages/src/main.rs @@ -0,0 +1,153 @@ +use std::{cmp::Ordering, collections::HashMap, fs::File}; + +use bitflags::bitflags; +use serde::Serialize; +use tera::{Context, Tera}; +use toml::Value; + +bitflags! { + struct Command: u32 { + const CHECK_MISSING = 0b00000001; + const UPDATE = 0b00000010; + } +} + +fn main() { + let what_to_run = match std::env::args().nth(1).as_deref() { + Some("check-missing") => Command::CHECK_MISSING, + Some("update") => Command::UPDATE, + _ => Command::all(), + }; + + let examples = parse_examples(what_to_run.contains(Command::CHECK_MISSING)); + + if what_to_run.contains(Command::UPDATE) { + let categories = parse_categories(); + let examples_by_category: HashMap = examples + .into_iter() + .fold(HashMap::>::new(), |mut v, ex| { + v.entry(ex.category.clone()).or_default().push(ex); + v + }) + .into_iter() + .map(|(key, mut examples)| { + examples.sort(); + let description = categories.get(&key).cloned(); + ( + key, + Category { + description, + examples, + }, + ) + }) + .collect(); + + let mut context = Context::new(); + context.insert("all_examples", &examples_by_category); + Tera::new("examples/*.md.tpl") + .expect("error parsing template") + .render_to( + "README.md.tpl", + &context, + File::create("examples/README.md").expect("error creating file"), + ) + .expect("error rendering template"); + } +} + +#[derive(Debug, Serialize, PartialEq, Eq)] +struct Category { + description: Option, + examples: Vec, +} + +#[derive(Debug, Serialize, PartialEq, Eq)] +struct Example { + technical_name: String, + path: String, + name: String, + description: String, + category: String, + wasm: bool, +} + +impl Ord for Example { + fn cmp(&self, other: &Self) -> Ordering { + match self.category.cmp(&other.category) { + Ordering::Equal => self.name.cmp(&other.name), + ordering => ordering, + } + } +} + +impl PartialOrd for Example { + fn partial_cmp(&self, other: &Self) -> Option { + Some(self.cmp(other)) + } +} + +fn parse_examples(panic_on_missing: bool) -> Vec { + let manifest_file = std::fs::read_to_string("Cargo.toml").unwrap(); + let manifest: HashMap = toml::from_str(&manifest_file).unwrap(); + let metadatas = manifest + .get("package") + .unwrap() + .get("metadata") + .as_ref() + .unwrap()["example"] + .clone(); + + manifest["example"] + .as_array() + .unwrap() + .iter() + .flat_map(|val| { + let technical_name = val["name"].as_str().unwrap().to_string(); + if panic_on_missing && metadatas.get(&technical_name).is_none() { + panic!("Missing metadata for example {}", technical_name); + } + + if metadatas + .get(&technical_name) + .and_then(|metadata| metadata.get("hidden")) + .and_then(|hidden| hidden.as_bool()) + .and_then(|hidden| hidden.then(|| ())) + .is_some() + { + return None; + } + + metadatas.get(&technical_name).map(|metadata| Example { + technical_name, + path: val["path"].as_str().unwrap().to_string(), + name: metadata["name"].as_str().unwrap().to_string(), + description: metadata["description"].as_str().unwrap().to_string(), + category: metadata["category"].as_str().unwrap().to_string(), + wasm: metadata["wasm"].as_bool().unwrap(), + }) + }) + .collect() +} + +fn parse_categories() -> HashMap { + let manifest_file = std::fs::read_to_string("Cargo.toml").unwrap(); + let manifest: HashMap = toml::from_str(&manifest_file).unwrap(); + manifest + .get("package") + .unwrap() + .get("metadata") + .as_ref() + .unwrap()["category"] + .clone() + .as_array() + .unwrap() + .iter() + .map(|v| { + ( + v.get("name").unwrap().as_str().unwrap().to_string(), + v.get("description").unwrap().as_str().unwrap().to_string(), + ) + }) + .collect() +}