Ryot Ray Casting

What is Ryot Ray Casting?

Ryot Ray Casting leverages the concept of ray casting to provide a robust ray casting system for Bevy. It is designed to work seamlessly with Bevy's ECS, enabling developers to implement advanced trajectory-based mechanics in their games and simulations that require precise straight-line trajectory calculations, with support for obstacles, line of sight, and other complex interactions. Even though it's optimized for 2D grid-based environments, it can be easily extended to fit specific game requirements and open-world scenarios. It's part of Ryot framework, having Ryot Core and Ryot Utils as dependencies.

Ray Casting and Trajectories

Ray Casting is a fundamental concept in game development, enabling complex game mechanics such as projectile motion, line of sight, fog of war, collision detection, and more. Ray casting is a technique used to simulate trajectories by tracing rays through a 2D or 3D environment, detecting collisions and interactions along the way. It's widely used in games to implement realistic physics, lighting effects, and AI behaviors, providing a versatile tool for creating engaging gameplay experiences.

In the context of Ryot Ray Casting offers a comprehensive solution for implementing ray casting systems in Bevy projects, providing a flexible and extensible framework for handling ray casting logic. By leveraging the ECS architecture and seamless Bevy integration, developers can create dynamic ray casting systems that adapt to changing game conditions and player interactions.

Ryot RayCasting uses Bevy RayCast3d as the underlying ray casting library, for both 2D and 3D environments.

Capabilities

• Seamless Bevy Integration: Built to work hand-in-hand with Bevy's ECS, offering smooth integration and ensuring compatibility with Bevy's event systems.
• Ray Casting Support: Utilizes ray casting to simulate trajectories, enabling precise collision detection and interaction with obstacles.
• 2D Optimization: Specially tailored for 2D grid-based navigation, providing robust tools for tile-based and open-world game environments.
• Extensible Architecture: Designed to be flexible, allowing developers to extend and customize ray casting logic to fit specific game requirements.

Basic Setup

Before setting up the ray casting framework, lets understand the core concepts: Point, RayCastingPoint, Navigable, RadialArea<P> and Perspective<P>.

Point

The Point trait represents a position in the world. It's a core concept of the Ryot ecosystem, that allows you to integrate your own world representation with Ryot and its spatial algorithms.

RayCastingPoint

An extension of the Point trait, the RayCastingPoint trait represents a position in the world that can be used to evaluate ray casting. It's used to generate the bounding box of a given point in space, used to check the point against the ray cast. This crate uses primarily the aabb3d (axis-aligned bounding box) to represent the bounding box of a point in space and the ray cast aabb intersection to check if a point is inside a ray or not.

Navigable

The Navigable trait belongs to ryot_core and is used to determine if a point is navigable or not. It's used to determine if an actor can go through a particular point in the world, for instance if this point is walkable or not.

Currently, Navigable has two flags: is_walkable and is_flyable. The first one is used to determine if an actor can walk through a point, and the second one is used to determine if an actor can fly through a point.

RadialArea

The RadialArea struct is a descriptive representation of an area in the game world. It contains only primitive and copyable types, implements Hash and its main purpose is to be used as a descriptive representation of Perspectives, allowing to cache complex calculations of perspectives and reuse them in the future.

Perspective

The Perspective struct is a representation of a perspective from a given spectator point. It contains an array of traversals, which are tuples of RayCast3d and the area traversed by the ray. It's used to represent all the rays that can be cast from a spectator perspective in a determined scenario/condition.

Bevy

To integrate ryot_ray_casting you need to add a ray casting to your Bevy app. This is done by calling the add_ray_casting<T, P, N>, where T is a marker type that represents the ray casting context, P a RayCastingPoint type and N is the Navigable type. This method is a builder method on your Bevy app builder.

Here is a basic example:

use bevy::prelude::*;
use ryot_core::prelude::*;
use ryot_ray_casting::prelude::*;

fn setup<P: RayCastingPoint + Component>(mut commands: Commands) {
    // here we use () as a marker, but in a real scenario you should use a marker type
    // that properly represents the context of the ray casting.
    commands.spawn(RayCasting::<(), P>::default());
}

fn build_app<P: RayCastingPoint + Component>(app: &mut App) -> &mut App {
    app
        .add_plugins(DefaultPlugins)
        .add_ray_casting::<(), P, Flags>()
}

Components

This crate has two main ECS components:

RayCasting<T, P>

This struct is a representation of a ray casting in the game world. It's a component that can be attached to entities in the ECS, and it's used to represent the ray casting request of an entity given a context T.

This component is attached to entities that require a ray casting computation. It specifies the parameters for the ray casting evaluation:

• area: the radial area that represents the plan over which the rays will be casted.
• shared_with: the entities that the propagation of the rays will be shared with.
• conditions: the conditions that the plane points P must satisfy, based on a navigable type, to avoid colliding with the rays cast.
• params: a set of parameters that can be used to customize the ray casting calculation.
  • max_collisions: the maximum number of collisions that a ray cast can have before stopping propagating.
  • reversed: if the ray should be analysed in reverse order (from the end to the start).
  • execution_type: the type of execution that the ray casting should have: once or time based.
• last_executed_at: the last time that the ray casting was executed, a flag to determine if it should be executed again or not.

It's part of the public API and should be used by the user to trigger ray casting computations.

This component is automatically removed when it no longer meets the execution requirements related to its ExecutionType.

RayPropagation<T, P>

This component is attached to entities that have completed a ray casting computation. It holds the result of the ray casting evaluation, how the ray propagated over the given plane, represented by:

• collisions: the collisions between the ray and the requested plane, meaning that the those points are not navigable.
  • position: the position where the collision happened.
  • distance: the distance from the ray's origin to the collision point.
  • previous_position: the previous position that the ray touched before the collision occurred.
  • pierced: if the collision was pierced or not, meaning that the ray propagation continued after the collision.
• area_of_interest: the area of interest of the ray casting, all points through which the rays cast propagated, meaning that the ray influences the world in these points.

This component is attached to entities that have completed a ray casting computation. It's part of the public API and should be used by the user to check the ray propagation.

Systems

The ray casting framework is composed of three main systems:

1. update_intersection_cache<T, P>: this system updates the cache of intersections represented by a radial area present in the RayCasting<T, P> component. This cache is used to speed up the ray casting computation, avoiding re-calculating already calculated ray cast aabb intersections.
2. process_ray_casting<T, P, N>: the main system of the ray casting framework, it executes the ray casting requests present in the ECS, calculating the ray propagation and attaching the results to the entities.
3. share_results<T, P>: this system shares the ray propagation results of an entity with the entities that the ray casting can be shared with.

There are also two systems that are part of the clean-up process:

1. remove_stale_results<T, P>: this system removes the RayPropagation<T, P> from entities that no longer have a RayCasting<T, P> component.
2. remove_stale_requests<T, P>: this system removes the RayCasting<T, P> requests that are no longer valid.

Examples

Choose an example to run based on your needs, such as handling multiple entities or dealing with obstacles:

cargo run --example example_name --features stubs

Replace example_name with the name of the example you wish to run.

Understanding the Examples

Each example included in the library showcases different aspects of the ray casting system:

• Basic: Demonstrates a basic complete ray casting use case, with obstacles and different radial areas.
• Stress Test: Evaluates the ray casting's performance under high load conditions.

Building Your Own Scenarios

Leverage the ExampleBuilder to customize and create tailored ray casting example/test scenarios:

fn main() {
    // ExampleBuilder::<T /* Contextual Marker */, P /* RayCastingPoint */, N /* Navigable */>::new()
    // .with_ray_castings(/* array of (ray casting, count) tuples, containing the ray casting to be instantiated and how many */)
    //  .with_obstacles(/* number of obstacles to be instantiated */)
    //      .app() // basic app with visual capabilities
    //      /* add your custom systems, plugins and resources here */
    //      .run();
}

Benchmarks

Performance benchmarks are included to provide insights into the crate's efficiency. The benchmark can be run to evaluate performance under various conditions:

cargo bench --features stubs

Results

There are three main benchmarks for the ray casting system: creating the perspectives, executing the ray casting, and checking navigable points against the ray propagation. The benchmarks cover different scenarios, such as linear, sectorial and circular areas, with different ranges values.

The following tables provide an overview of the benchmark results for the ray casting system:

Creation

Execution

Navigable Collision

This README format clearly sections out the features, example usage, and benchmarks, providing a comprehensive guide for anyone looking to integrate the ryot_ray_casting crate into their projects.