musi_lili/lib.rs
1// SPDX-FileCopyrightText: 2023 jan Wiwi <vivi-ui@tuta.io>
2// SPDX-License-Identifier: LGPL-3.0-only
3
4#![allow(clippy::needless_doctest_main)]
5
6/*!
7
8# musi lili
9
10musi lili is a retro game engine for GB styled games written in Rust. Inspired by pico8.
11
12## How to use this crate
13
14### Add musi_lili to your `Cargo.toml` file
15
16```toml
17[package]
18name = "my_game"
19version = "0.1.0"
20edition = "2021"
21
22[dependencies]
23musi_lili = { git = "https://codeberg.org/vivi-ui/lili", tag = "v0.4" }
24```
25
26### Create your game
27
28Create a struct that defines your game and implements the `musi_lili::Game` trait.
29After that you can start your game by calling `musi_lil::run` with the type of your game.
30
31```rust
32use musi_lili::{Game, Lili};
33
34struct MyGame;
35
36impl Game for MyGame {
37 fn init(_lili: &Lili) -> Self {
38 Self
39 }
40
41 fn update(&mut self, _lili: &Lili) {
42 // the code to update your game
43 }
44
45 fn draw(&mut self, lili: &Lili) {
46 // draw your game
47 lili.clear(0);
48 lili.txt("toki", 5, 5, 3);
49 }
50}
51
52fn main() {
53# return; // Don't run a window in an example
54 musi_lili::run::<MyGame>(musi_lili::load!("my-game"));
55}
56```
57
58### Upgrade Guide: v0.3 → v0.4
59
60#### Key Change
61
62Starting with **v0.4**, `musi-lili` is no longer published on [crates.io](https://crates.io). You must now reference the project directly from its Git repository.
63
64#### Steps to Upgrade
65
661. **Update your `Cargo.toml`**:
67 Replace the existing dependency with:
68
69 ```toml
70 musi_lili = { git = "https://codeberg.org/vivi-ui/lili", tag = "v0.4" }
71 ```
72
732. **Run `cargo update`**:
74 Execute the following command in your project directory to fetch the new version:
75
76 ```sh
77 cargo update -p musi_lili
78 ```
79
803. **Rebuild your project**:
81 Clean and rebuild to ensure all dependencies are correctly resolved:
82
83 ```sh
84 cargo clean && cargo build
85 ```
86
87#### Why This Change?
88
89The project is no longer published on crates.io because I no longer maintain a GitHub account, which is required for publishing there. Hosting the project directly on Codeberg aligns better with my workflow and preferences.
90If you encounter issues, check the [project’s issue tracker](https://codeberg.org/vivi-ui/lili/issues) or open a new issue.
91
92## Cargo Features
93
94* `std`: use rust std (default).
95* `gamepad`: activate gamepad support (needs `libudev` to be installed).
96* `slint-skia`: use winit with skia renderer as slint backend (default).
97* `slint-femtovg`: use winit with femtovg renderer as slint backend.
98* `slint-software`: use winit with software renderer as slint backend.
99* `experimental`: enable this feature to try out experimental features that are not yet ready for production.
100
101## Used third party libraries
102
103| Library | License | Used for |
104| ------- | ------- | -------- |
105| [Slint](https://slint.dev/) | [GNU GPlv3](https://github.com/slint-ui/slint/blob/master/LICENSES/GPL-3.0-only.txt), [Royalty-free](https://github.com/slint-ui/slint/blob/master/LICENSES/LicenseRef-Slint-Royalty-free-2.0.md) or [Paid](https://github.com/slint-ui/slint/blob/master/LICENSES/LicenseRef-Slint-Software-3.0.md) | Window, framebuffer and event handling |
106| [embedded-graphics](https://github.com/embedded-graphics/embedded-graphics) | [Apache 2.0](https://github.com/embedded-graphics/embedded-graphics/blob/master/LICENSE-APACHE) or [MIT](https://github.com/embedded-graphics/embedded-graphics/blob/master/LICENSE-MIT) | Pixel art drawing |
107| [dirs-next](https://github.com/xdg-rs/dirs) | `Apache 2.0` or `MIT` | Get user settings path |
108| [serde](https://github.com/serde-rs/serde) | [Apache 2.0](https://github.com/serde-rs/serde/blob/master/LICENSE-APACHE) or [MIT](https://github.com/serde-rs/serde/blob/master/LICENSE-MIT) | Serialize / Deserialize game data|
109| [serde-json](https://github.com/serde-rs/json) | [Apache 2.0](https://github.:com/serde-rs/json/blob/master/LICENSE-APACHE) or [MIT](https://github.com/serde-rs/json/blob/master/LICENSE-MIT) | Serialize / Deserialize game data|
110| [gilrs](https://gitlab.com/gilrs-project/gilrs) | [Apache 2.0](https://gitlab.com/gilrs-project/gilrs/-/blob/master/LICENSE-APACHE?ref_type=heads) or [MIT](https://gitlab.com/gilrs-project/gilrs/-/blob/master/LICENSE-MIT?ref_type=heads) | Support for game controllers |
111| [web-time](https://github.com/daxpedda/web-time) | [Apache 2.0](https://github.com/daxpedda/web-timeLICENSE-APACHE?ref_type=heads) or [MIT](https://github.com/daxpedda/web-time/blob/master/LICENSE-MIT?ref_type=heads) | Use Instant::now() on the web |
112| [web-sys](https://github.com/rustwasm/wasm-bindgen/tree/main/crates/web-sys) | [Apache 2.0](https://github.com/rustwasm/wasm-bindgen/blob/main/LICENSE-APACHE) or [MIT](https://github.com/rustwasm/wasm-bindgen/blob/main/LICENSE-MIT) | Used for web save game management |
113*/
114
115#![cfg_attr(not(feature = "std"), no_std)]
116
117mod api;
118
119#[doc(inline)]
120pub use api::{
121 rgb, Button, Color, Game, GameData, Key, Lili, Palette, Point, CHAR_HEIGHT, CHAR_WIDTH,
122 DISPLAY_HEIGHT, DISPLAY_WIDTH, MAP_HEIGHT, MAP_WIDTH, SPRITE_HEIGHT, SPRITE_WIDTH,
123};
124
125#[cfg(feature = "std")]
126#[doc(inline)]
127pub use tawa_lili::{
128 game_data::{data_from_path, data_from_str, save_data},
129 load,
130};
131
132#[cfg(feature = "std")]
133#[doc(inline)]
134pub use tan_lili::settings_dir;
135
136mod run;
137mod slint_ui;
138
139#[doc(inline)]
140pub use run::run;
141
142#[cfg(feature = "private_api")]
143pub use tawa_lili::editor::{DummyLanguagePlugin, LanguagePlugin, TextLine, TextModel};
144
145#[cfg(feature = "private_api")]
146pub use tawa_lili::editor::components;
147
148#[cfg(feature = "private_api")]
149pub use tan_lili::{DrawContext, FileManager, LiliRequest};