Merge remote-tracking branch 'upstream/release-0.14.0' into main

.cargo/config_fast_builds.toml

@@ -1,40 +1,151 @@
-# Add the contents of this file to `config.toml` to enable "fast build" configuration. Please read the notes below.
-
-# NOTE: For maximum performance, build using a nightly compiler
-# If you are using rust stable, remove the "-Zshare-generics=y" below.
+# Copy this file to `config.toml` to speed up your builds.
+#
+# # Faster linker
+#
+# One of the slowest aspects of compiling large Rust programs is the linking time. This file configures an
+# alternate linker that may improve build times. When choosing a new linker, you have two options:
+#
+# ## LLD
+#
+# LLD is a linker from the LLVM project that supports Linux, Windows, MacOS, and WASM. It has the greatest
+# platform support and the easiest installation process. It is enabled by default in this file for Linux
+# and Windows. On MacOS, the default linker yields higher performance than LLD and is used instead.
+#
+# To install, please scroll to the corresponding table for your target (eg. `[target.x86_64-pc-windows-msvc]`
+# for Windows) and follow the steps under `LLD linker`.
+#
+# For more information, please see LLD's website at <https://lld.llvm.org>.
+#
+# ## Mold
+#
+# Mold is a newer linker written by one of the authors of LLD. It boasts even greater performance, specifically
+# through its high parallelism, though it only supports Linux.
+#
+# Mold is  disabled by default in this file. If you wish to enable it, follow the installation instructions for
+# your corresponding target, disable LLD by commenting out its `-Clink-arg=...` line, and enable Mold by
+# *uncommenting* its `-Clink-arg=...` line.
+#
+# There is a fork of Mold named Sold that supports MacOS, but it is unmaintained and is about the same speed as
+# the default ld64 linker. For this reason, it is not included in this file.
+#
+# For more information, please see Mold's repository at <https://github.com/rui314/mold>.
+#
+# # Nightly configuration
+#
+# Be warned that the following features require nightly Rust, which is expiremental and may contain bugs. If you
+# are having issues, skip this section and use stable Rust instead.
+#
+# There are a few unstable features that can improve performance. To use them, first install nightly Rust
+# through Rustup:
+#
+# ```
+# rustup toolchain install nightly
+# ```
+#
+# Finally, uncomment the lines under the `Nightly` heading for your corresponding target table (eg.
+# `[target.x86_64-unknown-linux-gnu]` for Linux) to enable the following features:
+#
+# ## `share-generics`
+#
+# Usually rustc builds each crate separately, then combines them all together at the end. `share-generics` forces
+# crates to share monomorphized generic code, so they do not duplicate work.
+#
+# In other words, instead of crate 1 generating `Foo<String>` and crate 2 generating `Foo<String>` separately,
+# only one crate generates `Foo<String>` and the other adds on to the pre-exiting work.
+#
+# Note that you may have some issues with this flag on Windows. If compiling fails due to the 65k symbol limit,
+# you may have to disable this setting. For more information and possible solutions to this error, see
+# <https://github.com/bevyengine/bevy/issues/1110>.
+#
+# ## `threads`
+#
+# This option enables rustc's parallel frontend, which improves performance when parsing, type checking, borrow
+# checking, and more. We currently set `threads=0`, which defaults to the amount of cores in your CPU.
+#
+# For more information, see the blog post at <https://blog.rust-lang.org/2023/11/09/parallel-rustc.html>.
 
 [target.x86_64-unknown-linux-gnu]
 linker = "clang"
 rustflags = [
-  "-Clink-arg=-fuse-ld=lld", # Use LLD Linker
-  "-Zshare-generics=y",      # (Nightly) Make the current crate share its generic instantiations
-  "-Zthreads=0",             # (Nightly) Use improved multithreading with the recommended amount of threads.
+  # LLD linker
+  #
+  # You may need to install it:
+  #
+  # - Ubuntu: `sudo apt-get install lld clang`
+  # - Fedora: `sudo dnf install lld clang`
+  # - Arch: `sudo pacman -S lld clang`
+  "-Clink-arg=-fuse-ld=lld",
+
+  # Mold linker
+  #
+  # You may need to install it:
+  #
+  # - Ubuntu: `sudo apt-get install mold clang`
+  # - Fedora: `sudo dnf install mold clang`
+  # - Arch: `sudo pacman -S mold clang`
+  # "-Clink-arg=-fuse-ld=/usr/bin/mold",
+
+  # Nightly
+  # "-Zshare-generics=y",
+  # "-Zthreads=0",
 ]
 
-# NOTE: you must install [Mach-O LLD Port](https://lld.llvm.org/MachO/index.html) on mac. you can easily do this by installing llvm which includes lld with the "brew" package manager:
-# `brew install llvm`
 [target.x86_64-apple-darwin]
 rustflags = [
-  "-Clink-arg=-fuse-ld=/usr/local/opt/llvm/bin/ld64.lld", # Use LLD Linker
-  "-Zshare-generics=y",                                   # (Nightly) Make the current crate share its generic instantiations
-  "-Zthreads=0",                                          # (Nightly) Use improved multithreading with the recommended amount of threads.
+  # LLD linker
+  #
+  # The default ld64 linker is faster, you should continue using it instead.
+  #
+  # You may need to install it:
+  #
+  # Brew: `brew install llvm`
+  # Manually: <https://lld.llvm.org/MachO/index.html>
+  # "-Clink-arg=-fuse-ld=/usr/local/opt/llvm/bin/ld64.lld",
+
+  # Nightly
+  # "-Zshare-generics=y",
+  # "-Zthreads=0",
 ]
 
 [target.aarch64-apple-darwin]
 rustflags = [
-  "-Clink-arg=-fuse-ld=/opt/homebrew/opt/llvm/bin/ld64.lld", # Use LLD Linker
-  "-Zshare-generics=y",                                      # (Nightly) Make the current crate share its generic instantiations
-  "-Zthreads=0",                                             # (Nightly) Use improved multithreading with the recommended amount of threads.
+  # LLD linker
+  #
+  # The default ld64 linker is faster, you should continue using it instead.
+  #
+  # You may need to install it:
+  #
+  # Brew: `brew install llvm`
+  # Manually: <https://lld.llvm.org/MachO/index.html>
+  # "-Clink-arg=-fuse-ld=/opt/homebrew/opt/llvm/bin/ld64.lld",
+
+  # Nightly
+  # "-Zshare-generics=y",
+  # "-Zthreads=0",
 ]
 
 [target.x86_64-pc-windows-msvc]
-linker = "rust-lld.exe" # Use LLD Linker
+# LLD linker
+#
+# You may need to install it:
+#
+# ```
+# cargo install -f cargo-binutils
+# rustup component add llvm-tools
+# ```
+linker = "rust-lld.exe"
 rustflags = [
-  "-Zshare-generics=n",
-  "-Zthreads=0",        # (Nightly) Use improved multithreading with the recommended amount of threads.
+  # Nightly
+  # "-Zshare-generics=y",
+  # "-Zthreads=0",
 ]
 
 # Optional: Uncommenting the following improves compile times, but reduces the amount of debug info to 'line number tables only'
 # In most cases the gains are negligible, but if you are on macos and have slow compile times you should see significant gains.
-#[profile.dev]
-#debug = 1
+# [profile.dev]
+# debug = 1
+
+# This is enables you to run the CI tool using `cargo ci`.
+# This is not enabled by default, you need to copy this file to `config.toml`.
+[alias]
+ci = "run --package ci --"

.github/FUNDING.yml

@@ -1,3 +1 @@
-# These are supported funding model platforms
-
-custom: https://bevyengine.org/community/donate/
+custom: https://bevyengine.org/donate/

.github/actions/install-linux-deps/action.yml

@@ -0,0 +1,49 @@
+# This action installs a few dependencies necessary to build Bevy on Linux. By default it installs
+# alsa and udev, but can be configured depending on which libraries are needed:
+#
+# ```
+# - uses: ./.github/actions/install-linux-deps
+#   with:
+#     alsa: false
+#     wayland: true
+# ```
+#
+# See the `inputs` section for all options and their defaults. Note that you must checkout the
+# repository before you can use this action.
+#
+# This action will only install dependencies when the current operating system is Linux. It will do
+# nothing on any other OS (MacOS, Windows).
+
+name: Install Linux dependencies
+description: Installs the dependencies necessary to build Bevy on Linux.
+inputs:
+  alsa:
+    description: Install alsa (libasound2-dev)
+    required: false
+    default: true
+  udev:
+    description: Install udev (libudev-dev)
+    required: false
+    default: true
+  wayland:
+    description: Install Wayland (libwayland-dev)
+    required: false
+    default: false
+  xkb:
+    description: Install xkb (libxkbcommon-dev)
+    required: false
+    default: false
+runs:
+  using: composite
+  steps:
+    - name: Install Linux dependencies
+      shell: bash
+      if: ${{ runner.os == 'linux' }}
+      run: >
+        sudo apt-get update
+
+        sudo apt-get install --no-install-recommends
+        ${{ fromJSON(inputs.alsa) && 'libasound2-dev' || '' }}
+        ${{ fromJSON(inputs.udev) && 'libudev-dev' || '' }}
+        ${{ fromJSON(inputs.wayland) && 'libwayland-dev' || '' }}
+        ${{ fromJSON(inputs.xkb) && 'libxkbcommon-dev' || '' }}

.github/contributing/engine_style_guide.md

@@ -14,6 +14,7 @@ For more advice on contributing to the engine, see the [relevant section](../../
    4. Use \`variable_name\` code blocks in comments to signify that you're referring to specific types and variables.
    5. Start comments with capital letters. End them with a period if they are sentence-like.
 3. Use comments to organize long and complex stretches of code that can't sensibly be refactored into separate functions.
+4. When using [Bevy error codes](https://bevyengine.org/learn/errors/) include a link to the relevant error on the Bevy website in the returned error message `... See: https://bevyengine.org/learn/errors/#b0003`.
 
 ## Rust API guidelines
 

.github/example-run/alien_cake_addict.ron

@@ -1,3 +1,5 @@
 (
-    exit_after: Some(300)
+    events: [
+        (300, AppExit),
+    ]
 )

.github/example-run/breakout.ron

@@ -1,5 +1,9 @@
 (
-    exit_after: Some(900),
-    frame_time: Some(0.03),
-    screenshot_frames: [200],
+    setup: (
+        fixed_frame_time: Some(0.03),
+    ),
+    events: [
+        (200, Screenshot),
+        (900, AppExit),
+    ]
 )

.github/example-run/contributors.ron

@@ -1,3 +1,5 @@
 (
-    exit_after: Some(900)
+    events: [
+        (900, AppExit),
+    ]
 )

.github/example-run/load_gltf.ron

@@ -1,5 +1,9 @@
 (
-    exit_after: Some(300),
-    frame_time: Some(0.03),
-    screenshot_frames: [100],
+    setup: (
+        frame_time: Some(0.03),
+    ),
+    events: [
+        (100, Screenshot),
+        (300, AppExit),
+    ]
 )

.github/example-run/no_renderer.ron

@@ -1,3 +1,5 @@
 (
-    exit_after: Some(100)
+    events: [
+        (100, AppExit),
+    ]
 )

.github/example-run/scene.ron

@@ -1,3 +1,5 @@
 (
-    exit_after: Some(100)
+    events: [
+        (100, AppExit),
+    ]
 )

.github/pull_request_template.md

@@ -7,6 +7,13 @@
 
 - Describe the solution used to achieve the objective above.
 
+## Testing
+
+- Did you test these changes? If so, how?
+- Are there any parts that need more testing?
+- How can other people (reviewers) test your changes? Is there anything specific they need to know?
+- If relevant, what platforms did you test these changes on, and are there any important ones you can't test?
+
 ---
 
 ## Changelog