Obstacle detection for environmental movement actions (climbing, wall jumping, etc.)

[idanarye]

Environmental movement actions (like #7, #12 and #54) are a very desired feature. These are actions (or sometimes basis) that are performed against some object in the environment - which we'll call "obstacle". Unlike ground actions (like jumping or crouching), which always know what the ground is without the user control system telling them, obstacle actions need to be told what the obstacle is.

I already have a very raw idea about how they should work:

1. Something queries the physics backend to find "opportunities" for environmental actions (ladders to climb on, walls to jump from, ledges to hang from, etc.)

2. The user control system considers these opportunities, together with the controller state and the user input, and decides on an environment action to perform.

3. The user control system generates environment action (or maybe a basis for things like climbing? But this is a different discussion) using data from the opportunity and feeds it to the controller.

   This third step has a very important key aspect - how does the action know about the obstacle it works with?

   • I don't want the action to query the physics backend (with Tnua's model - it cannot), so the system will have to pass that information to it.
   • But I also don't want to have to pass an entire big complicated geometric description of the obstacle's geometry to the action either.

   I think that in most cases it should be enough for the action to know:

   • The entity of the obstacle. This is mostly for inspection by user systems (e.g. - an animating system will want to know what the character is climbing on. Maybe it wants to sync the ladder clmibing animation with the ladder's rungs?) and maybe can be made optional.
   • A position on the surface of the obstacle.
   • A direction, which is either the normal (e.g. - for a wall) or a parallel direction (e.g. - for a vine or a ledge)

   There could be variations, of course, but I think these three pieces of data should be enough to perform the action.

This discussion is about the "Something" from the first step. How will the user control system know about the obstacles the character may interact with?

[idanarye]

Option: fully manual

The user control system will have to query the physics backend directly, without Tnua's assistance, and find the opportunities by itself. Since the data that needs to be passed to the action is relatively small and easy to get when you query the physics backend yourself - users could do it without assistance from Tnua.

With the general design I have in mind, this will be an option even if I do implement one of the other options - and I suspect there will always be users who prefer to do that detection themselves because they need that control.

This is here to discuss the particulars of this method (not that there is too much to discuss about them...) and also to consider the option of not adding a more elaborate obstacle detection assistance - at least not initially - and let users do it themselves.

[idanarye]

Option: wrappers around the physics backends' interfaces

Tnua's main crate will define a trait for ensuring a consistent interface, but each physics backend integration crate will its own SystemParam. The Rapier integration will have it wrap RapierContext and the Avian integration will wrap SpatialQuery.

User control systems will use that wrapper and query the obstacles from it.

[idanarye]

Ideally I'd like to use Rapier's intersections_with_shape and Avian's shape_intersections_callback, but these only provide the entity - not the contact data. They can't even tell me the direction I need to do a shapecast to get more information.

I'll need to check if I can somehow "cheat" - use cast_shape/shape_hits_callback with max_time_of_impact = 0.0 and a big shape that would be the same as the radar. Would this give me the proper contacts? Would the direction matter?

Or maybe I should just force the user system to choose a direction for the obstacle search...

[idanarye]

Option: spatial ("radar"?) sensors

Entity setup code will add a TnuaSpatialSensor (or maybe TnuaRadar? TnuaRadarSensor? Need to bikeshed the name) component to the character entity. Each frame, this sensor will detect all the entities inside a cylinder/sphere (need to decide which one) around the character and save them all in the sensor.

The sensor probably shouldn't store the full geometry of each entity. Instead, it should save a "projection" of it into a simple shape (rectangle?) that the user input system can work with. Need to decide exactly which shape.

[idanarye]

The general idea is to create a "ghost collider" that will register collisions without applying them to the simulation. For Rapier, this means empty SolverGroups. For Avian, this means making it a Sensor. This will generate collisions in the engine's contact graph which a Tnua system will read and use to populate the sensor's output.

[idanarye]

Pros:

• The fact an internal system is responsible for managing it (as opposed to the wrappers approach) means we are not limited by the physics backend API and even if we want to support a third backend that's very different from Rapier and Avian - we can probably get it to work there as well.
• Contacts are calculated as part of the physics backend, which should be faster (due to search optimization, parallelism, etc.) than all the ray&shape casting we'll need to find them all.
• Fits Tnua's general sensor-controller-motor architecture.

Cons:

• Need to keep a collection of the contacts (instead of just iterating on them)
• Need to do basic processing of all the contacts - can't rule some out early based on their entity, position, and the status of the character controller and the input.
• Need to do it every frame - even when the character controller does not require them.
• Need to do it in every direction - even if the character controller only needs them from a direction.
• Less flexible - can't do multiple scans with different parameters (technically I can allow multiple radars, but that'd just make everything more complicated)
• Contacts are on the globally available contact graph - may potentially confuse other systems of the game, and even worse - other plugins the user has less control over.

[idanarye]

A moving sensor, at least in Avian, kills the performance. But maybe an intersection query followed by a point projection (or several?) would be faster? Maybe it'll suffice?

[idanarye]

Point projections seem fast enough (at least in Avian - haven't checked in Rapier yet). So this is my current plan (still considered part of this option):

1. Do a shape intersection test with a cylinder (which won't be inserted into the actual simulation's contact graph) to find all the colliders around the character. This will only give use the Entity identifiers, not the actual manifolds.
2. Do two point projections on each such collider - one from the top of the radar cylinder and one from its bottom.
3. Use the two points to determine the position and the "height" of the intractable part of the obstacle.

The height is important for ledge grabbing - if the top is too far away, we can't ledge-grab (we also need to know where the top is in order to do the ledge-grab.

[idanarye]

Another option is to do a point projection from the character's center first to determine the "position" of the obstacle, and then do two the two cylinder-top and cylinder-bottom projections from projections of that projection on the cylinder. This should give more accurate results if there is a slope.

Maye also no a raycast in order to get the normal?

[idanarye]

Option: Combine a radar component with user-controls-system triggered extra queries

This is a combination of the two other ideas:

• Use a radar to collect and maintain a list of all the colliders the character can interact with.
• Use wrappers around the physics backends' interfaces to get the actual spatial data from them.

The reason I want to use the fill the radar in a system is that the shape intersections method in both Rapier and Avian is accepting a predicate, which means I won't be able to work with an Iterator of entities unless I store them in some collection beforehand. Which is possible - it'll be more memory efficient to persist that collection inside a component.

And even if they were Iterators - it's harder to be generic over iterators (impl Trait for trait methods helps, but it still has its limitations and probably breaks object safety and I want to utilize object safety in the demos)

Once we get an entity, the other queries will (probably) all have a simple non-generic interface.

[idanarye]

I originally thought about doing a point projection as part of the radar, but on second thought there is no reason not to make it part of the wrapper.

[idanarye]

I'm thinking the API can look roughly like this:

fn user_control_system(
    mut query: Query<(&mut TnuaController, &TnuaRadar)>>,
    spatial: TnuaSpatialLens<TnuaSpatialExtAvian3d>,
) {
    for (mut controller, radar) in query.iter_mut() {
        let radar = spatial.for_radar(radar);
        for obstacle in radar.obstacles() {
            // Can be used for checking which components the obstacle has, and also
            // because the obstacle action will probably require an entity.
            let obstacle_entity = obstacle.entity();

            let general_direction = obstacle.general_direction().reject_from(Vector::Y);
            if general_direction.dot(controls_movement_direction.normalize_or_zero()) < 0.7 {
                // Player does not try to move toward the obstacle (0.7 is an arbitrary threshold)
                continue;
            }

            // more checks to see if the obstacle is suitable for the action
        }
    }
}

The purpose of TnuaSpatialLens is that a TnuaSpatialExt trait (which things like TnuaSpatialExtAvian3d will implement) can be defined in the physics integration layer crate with a small API, and TnuaSpatialLens will be defined in the main crate and provide a wrapper with a more elaborate API.