npc_engine_core/
lib.rs

1/*
2 *  SPDX-License-Identifier: Apache-2.0 OR MIT
3 *  © 2020-2022 ETH Zurich and other contributors, see AUTHORS.txt for details
4 */
5
6//! This is the core of the NPC engine, containing the [MCTS] algorithm implementation and related abstractions.
7//!
8//! We provide several [examples](https://github.com/ethz-gtc/npc-engine/tree/main/npc-engine-core/examples)
9//! as introductions on how to use the planner.
10//! A good place to start is [tic-tac-toe](https://github.com/ethz-gtc/npc-engine/tree/main/npc-engine-core/examples/tic-tac-toe).
11//!
12//! The core of the planner is the [MCTS] struct, which holds the state of the planner.
13//! It has two constructors, a simplified one, [new](MCTS::new), and a complete one, [new_with_tasks](MCTS::new_with_tasks).
14//! Once constructed, the [run](MCTS::run) method performs the search and returns the best task.
15//! After a search, the resulting tree can be inspected, starting from the [root node](MCTS::root_node).
16//!
17//! The [MCTS] struct is generic over a [Domain], which you have to implement to describe your own planning domain.
18//! You need to implement at least these three methods:
19//! * [list_behaviors](Domain::list_behaviors) returns the possible actions employing a hierarchical [Behavior] abstraction.
20//! * [get_current_value](Domain::get_current_value) returns the instantaneous (not discounted) value of an agent in a given state.
21//! * [update_visible_agents](Domain::update_visible_agents) lists all agents visible from a given agent in a given state.
22//!
23//! The `graphviz` feature enables to output the search tree in the Graphviz's dot format using the [plot_mcts_tree](graphviz::plot_mcts_tree) function.
24//!
25//! Additional features and utilites such as execution loops are available in the [`npc-engine-utils`](https://crates.io/crates/npc-engine-utils/) crate.
26//! You might want to use them in your project as they make the planner significantly simpler to use.
27//! Most [examples](https://github.com/ethz-gtc/npc-engine/tree/main/npc-engine-core/examples) use them.
28
29mod active_task;
30mod behavior;
31mod config;
32mod domain;
33mod edge;
34mod mcts;
35mod node;
36mod state_diff;
37mod task;
38mod util;
39
40pub use active_task::*;
41pub use behavior::*;
42pub use config::*;
43pub use domain::*;
44pub use edge::*;
45pub use mcts::*;
46pub use node::*;
47pub use state_diff::*;
48pub use task::*;
49use util::*;
50
51/// The identifier of an agent, essentially a u32.
52#[derive(
53    Copy, Clone, Debug, Hash, PartialEq, Eq, PartialOrd, Ord, serde::Serialize, serde::Deserialize,
54)]
55#[serde(rename_all = "kebab-case")]
56pub struct AgentId(
57    /// The internal identifier
58    pub u32,
59);
60impl std::fmt::Display for AgentId {
61    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
62        write!(f, "A{}", self.0)
63    }
64}
npc_engine_core/lib.rs

npc_engine_core/
lib.rs
