bevy_cursor_kit 0.6.0

A Bevy plugin for working with cursors.
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
133
134
135
136
137
138
139
140
141
142

# `bevy_cursor_kit`

[![Crates.io](https://img.shields.io/crates/v/bevy_cursor_kit.svg)](https://crates.io/crates/bevy_cursor_kit)
[![Docs.rs](https://docs.rs/bevy_cursor_kit/badge.svg)](https://docs.rs/bevy_cursor_kit)
[![CI](https://github.com/mgi388/bevy-cursor-kit/workflows/CI/badge.svg)](https://github.com/mgi388/bevy-cursor-kit/actions)

## Summary

`bevy_cursor_kit` is a crate for Bevy apps that lets you load cursor assets in various formats and use them as custom `CursorIcon`s.

## Features

### `.CUR` and `.ANI` binary formats

Load the classic Microsoft Windows `.CUR` and `.ANI` cursor file formats.

- `.CUR` files can be used for static cursor icons like a grabbing hand.
- `.ANI` files can be used for animated cursor icons like an hourglass.

### `.cur.json`, `.cur.ron`, `.cur.toml`, `.ani.json`, `.ani.ron`, `.ani.toml` text formats

Text-based versions of the classic `.CUR` static cursor and `.ANI` animated cursor file formats.

Write your cursors in JSON, RON, or TOML and `bevy_cursor_kit` can load them for you.

#### Static cursor

```ron
(
    image: (
        path: "path/to/sprite-sheet.png",
    ),
    texture_atlas_layout: (
        tile_size: (32, 32),
        columns: 20,
        rows: 10,
    ),
    hotspots: (
        default: (0, 0),
        overrides: {
            11: (32, 32),
            95: (32, 8),
        },
    ),
)
```

Check out the [cur_ron_asset.rs example](example/cur_ron_asset.rs) for more details.

#### Animated cursor

```ron
(
    image: (
        path: "path/to/sprite-sheet.png",
    ),
    texture_atlas_layout: (
        tile_size: (32, 32),
        columns: 2,
        rows: 2,
    ),
    hotspots: (
        default: (0, 0),
    ),
    animation: (
        repeat: Loop,
        clips: [
            (
                atlas_indices: [3, 0, 1, 2],
                duration: PerFrame(75),
            ),
            (
                atlas_indices: [2],
                duration: PerFrame(5000),
            ),
        ],
    )
)
```

## Quick start

Add the asset plugin for asset loader support:

```rust
use bevy_cursor_kit::prelude::*;

app.add_plugins(CursorAssetPlugin);
```

Load a static cursor or an animated cursor:

```rust
let handle = asset_server.load("example.CUR");
```

When the asset is ready, use its `image` when creating a custom `CursorIcon` component on your `Window`s:

```rust
let Some(cursor) = static_cursors.get(&handle) else {
  // ...
};

commands
  .entity(window)
  .insert(CursorIcon::Custom(
    CustomCursorImageBuilder::from_static_cursor(cursor, None).build(),
  ));
```

If you want to use the text-based formats, enable the `serde_json_asset`, `serde_ron_asset`, or `serde_toml_asset` feature in your `Cargo.toml` and load away:

```rust
let handle = asset_server.load("example.cur.ron");
```

Check out the [examples](examples) for more details.

## Version compatibility

| bevy | bevy_cursor_kit |
| ---- | --------------- |
| 0.17 | 0.6             |
| 0.16 | 0.4 - 0.5       |
| 0.15 | 0.3             |

## License

Licensed under either of

- Apache License, Version 2.0
  ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license
  ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

## Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.