shipyard 0.11.2

Entity Component System
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
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

# Systems


Systems are a great way to organize code.  
A function with views as arguments is all you need.

Here's an example:

```rust, noplaypen
fn create_ints(mut entities: EntitiesViewMut, mut u32s: ViewMut<u32>) {
    // -- snip --
}
```

We have a system, let's run it!

```rust, noplaypen
let world = World::new();

world.run(create_ints).unwrap();
```

It also works with closures.

### Passing Data to Systems


The first argument doesn't have to be a view, you can pass any data, even references.

```rust, noplaypen
fn in_acid(season: Season, positions: View<Position>, mut healths: ViewMut<Health>) {
    // -- snip --
}

let world = World::new();

world.run_with_data(in_acid, Season::Spring).unwrap();
```

We call [`run_with_data`](https://docs.rs/shipyard/0.5.0/shipyard/struct.World.html#method.run_with_data) instead of [`run`](https://docs.rs/shipyard/0.5.0/shipyard/struct.World.html#method.run) when we want to pass data to a system.

If you want to pass multiple variables, you can use a tuple.

```rust, noplaypen
fn in_acid(
    (season, precipitation): (Season, Precipitation),
    positions: View<Position>,
    mut healths: ViewMut<Health>,
) {
    // -- snip --
}

let world = World::new();

world
    .run_with_data(in_acid, (Season::Spring, Precipitation(0.1)))
    .unwrap();
```

### Workloads


A workload is a named group of systems.

```rust, noplaypen
fn create_ints(mut entities: EntitiesViewMut, mut u32s: ViewMut<u32>) {
    // -- snip --
}

fn delete_ints(mut u32s: ViewMut<u32>) {
    // -- snip --
}

let world = World::new();

Workload::builder("Int cycle")
    .with_system(&create_ints)
    .with_system(&delete_ints)
    .add_to_world(&world)
    .unwrap();

world.run_workload("Int cycle").unwrap();
```

Workloads are stored in the [`World`](https://docs.rs/shipyard/0.5.0/shipyard/struct.World.html), ready to be run again and again.  
They don't take up much memory so even if you make a few with similar systems it's not a problem.

Workloads will run their systems first to last or at the same time when possible. We call this _outer-parallelism_, you can learn more about it in [this chapter](../going-further/parallelism.md).

#### Workload Nesting


You can also add a workload to another and build your execution logic brick by brick.

```rust, noplaypen
struct Dead<T>(core::marker::PhantomData<T>);

fn increment(mut u32s: ViewMut<u32>) {
    for mut i in (&mut u32s).iter() {
        *i += 1;
    }
}

fn flag_deleted_u32s(u32s: View<u32>, mut deads: ViewMut<Dead<u32>>) {
    for (id, i) in u32s.iter().with_id() {
        if *i > 100 {
            deads.add_component_unchecked(id, Dead(core::marker::PhantomData));
        }
    }
}

fn clear_deleted_u32s(mut all_storages: AllStoragesViewMut) {
    all_storages.delete_any::<SparseSet<Dead<u32>>>();
}

let world = World::new();

Workload::builder("Filter u32")
    .with_system(&flag_deleted_u32s)
    .with_system(&clear_deleted_u32s)
    .add_to_world(&world)
    .unwrap();

Workload::builder("Loop")
    .with_system(&increment)
    .with_workload("Filter u32")
    .add_to_world(&world)
    .unwrap();

world.run_workload("Loop").unwrap();
```

---

Congratulations, you made it to the end of the fundamentals!  
The next section will take you under the hood to learn how to get the most out of Shipyard.