nightshade-api 0.44.0

Procedural high level API for the nightshade game engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

//! One call interaction: what is under the cursor, what did the user click.

use crate::input::{mouse_clicked, mouse_position};
use crate::scene::is_reserved;
use nightshade::ecs::gpu_picking::GpuPickResult;
use nightshade::prelude::*;
use std::collections::HashSet;

/// The closest entity under the cursor, if any. The api's own scaffolding
/// (draw pools, cameras, lights) is never returned.
pub fn entity_under_cursor(world: &World) -> Option<Entity> {
    pick_entities(world, mouse_position(world), PickingOptions::default())
        .into_iter()
        .map(|result| result.entity)
        .find(|&entity| !is_reserved(world, entity))
}

/// The entity the user clicked this frame with the left mouse button, if any.
pub fn clicked_entity(world: &World) -> Option<Entity> {
    if !mouse_clicked(world, MouseButton::Left) {
        return None;
    }
    entity_under_cursor(world)
}

/// Where the cursor's ray meets the ground plane at y zero, if it does.
pub fn cursor_on_ground(world: &World) -> Option<Vec3> {
    get_ground_position_from_screen(world, mouse_position(world), 0.0)
}

/// The closest entity under `screen_pos` that is not in `exclude` and is not
/// api scaffolding. Lets a tool ray-cast past a translucent placement ghost
/// that would otherwise pick itself.
pub fn pick_excluding(
    world: &World,
    screen_pos: Vec2,
    exclude: &HashSet<Entity>,
) -> Option<Entity> {
    pick_entities(world, screen_pos, PickingOptions::default())
        .into_iter()
        .map(|result| result.entity)
        .find(|entity| !is_reserved(world, *entity) && !exclude.contains(entity))
}

/// Requests a precise GPU pick at `screen_pos`, sampling the depth and entity-id
/// buffers. The result is not ready this frame; read it next frame with
/// [`take_surface_pick`].
pub fn request_surface_pick(world: &mut World, screen_pos: Vec2) {
    world
        .resources
        .gpu_picking
        .request_pick(screen_pos.x.max(0.0) as u32, screen_pos.y.max(0.0) as u32);
}

/// Takes the result of a [`request_surface_pick`], if the renderer has produced
/// one. Carries the exact world position, surface normal, and the picked
/// entity's id.
pub fn take_surface_pick(world: &mut World) -> Option<GpuPickResult> {
    world.resources.gpu_picking.take_result()
}