Crate bevy_adventure

Bevy_adventure

A framework for building 3d adventure games in Bevy.

https://user-images.githubusercontent.com/29737477/212168485-6497dfdf-cfa6-406a-814b-8a6598e20152.mp4

Features

• Interactive trait is the backbone of the framework, allowing you to create powerful, dynamic objects in your world that can be interacted with and can affect other objects or global state.
• AdventureScene trait exposes a Plugin-like interface for managing GLTF scenes and assigning components to entities (based on bevy_scene_hook)
• WorldState resource, a stringly-typed storage for tracking progression
• Inventory resource allows you to track held items and create recipes for combining them
• Automatic camera animation and state management, Component-based interface
• Support for multiple scenes (built on top of States)
• Support for triggering animations and audio clips

Examples

There is an elaborate example available at examples/main.rs. Three scenes are included, with multiple objects that can be interacted with or picked up.

Notes

Save States

bevy_adventure intentionally omits implementing save state functionality, as different games will have different requirements.

If you want to implement this, here is what you need to keep track of:

• CurrentSpot resource, which determines your current camera spot in the scene. When saving, save the name of the CameraSpot from this resource. When loading, create a new NextSpot instance from the loaded name, and insert it with Commands.
• State<S> resource, which determines what scene is currently loaded
• Inventory resource, which tracks what items the player is holding
• WorldState resource, the global game state storage

You will also have to enable the serde feature to allow serialization and deserialization of these resources.

Using WorldState

When you are building interactives, you have the ability to store information in the component itself or the WorldState.

The component should only hold temporary state information - like which drawer is open on a dresser or if an entity has been spawned.

If you want to store any other kind of information, it should be done in the WorldState resource. This is so other interactives in your scene can access this state (for example, you’d flip a switch and the lights would go out) and so you are storing state information in a single place.

Creating scenes

When implementing the Scene trait, the scene method should return a path to a file that can be loaded with the AssetServer to create a Bevy Scene. In practice this is a GLTF scene file, but any other format can be used as long as it creates a Bevy Scene when loaded.

When imported with bevy_adventure, Cameras are automatically converted to CameraSpots, and PointLights are configured to cast shadows.

The Scene trait’s spawn method is called for every Entity in the scene - you can use this to assign components and initialize behavior for objects in your scene. The best way to do this is to match entity Names (from their names in the Scene), see the examples for an idea of how you should do this.

The only real requirement for your scene is that you create a special Camera with the name Camera_Main. This is where your Camera will be positioned upon entering the Scene. The app will panic if a scene is loaded without the Main Camera.

If you have issues matching objects by name, you might be matching the parent instead of the actual object you want to match. Adding a print statement inside of your Scene’s spawn method might help you figure out if the object is actually being found.

Note that when you are loading Scenes into Bevy, the ‘Transform Scale’ of each object is also loaded in. This could cause colliders to be the wrong size - you should ‘apply Scale’ before exporting.

Object origin is also used loaded in - this could cause misaligned colliders if your object’s origin doesn’t match the center of your object.

Blender is a good choice to create GLTF scenes, but you must make sure you configure the export settings correctly:

• Under Include, check Custom Properties, Cameras, and Punctual Lights.
• Under Transform, uncheck Y+ Up

TODO

• Save state example

License

bevy_adventure is dual-licensed under MIT and Apache-2.0.

Compatibility

NOTE: We do not track Bevy main.

Bevy Version	Crate Version
0.12	0.6
0.10	0.5
0.9	0.1, 0.2, 0.3, 0.4

Modules

• prelude
  Prelude: convenient import for all the user-facing APIs provided by the crate

Structs

• AdventurePlugin
  The main plugin that must be added to your app with App::add_plugin.
• AnimationServer
  SystemParam for registering named Animations.
• AudioServer
  SystemParam for registering AudioSource clips by path.
• BackToSpot
  A component for a CameraSpot that defines what spot you will go back when at that spot.
• BackToState
  A component for a CameraSpot that defines what state you will go back when at that spot.
• CameraSpot
  A CameraSpot - a location the Camera might be at in the scene.
• CameraSpots
  SystemParam for retrieving CameraSpots for entities or from names.
• CommandsExt
  SystemParam that acts as an extension to Commands for working with named entities.
• CurrentSpot
  Resource that specifies what CameraSpot the player is at.
• Cursor
  A resource that stores the current position of the Cursor.
• Description
  A preset Interactive that displays a message when interacted with.
• DraggingItem
  A resource that stores which items are being dragged, if any.
• Hovering
  The entity that the cursor is currently hovering over, if any.
• Ignores
  A component for a CameraSpot that defines what objects are ignored when at that spot.
• Inventory
  A resource that stores the player’s current inventory.
• Item
  An item.
• ItemRef
  A reference to an item, passed into an Interactive.
• MoveTo
  A preset Interactive that moves to a CameraSpot when interacted with.
• NewMessage
  An event that triggers whenever an Action::Message is executed.
• NextSpot
  Insert this resource to determine what CameraSpot the Camera will move to next.
• Portal
  A preset Interactive that changes the current state when interacted with.
• Prop
  A preset Interactive that does nothing when interacted with.
• Recipes
  A resource that stores all registered item combinations.
• Simple
  An Interactive that just runs the given actions when interacted with.
• SkipAnimation
  Insert this resource at the same time as NextSpot to skip animation.
• Trigger
  A preset Interactive that does nothing when interacted with.
• WorldState
  Stringly-typed key value store for tracking game progression.

Enums

• Action
  An enum of possible actions an Interactive might take after being interacted with in some way.
• Message
  A struct that represents a message that should be displayed.

Constants

• MAIN_CAMERA
  The main camera spot in a scene is always named Camera_Main.

Traits

• AdventureScene
  Trait that provides a Plugin-like interface for defining game scenes.
• AppSceneStateExt
  Extension trait that adds Scene-related methods to Bevy’s App.
• CommandsActionsExt
  Extension trait that adds Action-related methods to Bevy’s EntityCommands.
• Interactive
  Trait that allows you to define behavior for an object in a Scene.

Functions

• invalid_item_used
  Helper function that returns an action with an InvalidItemUsed message.