Merge pull request #32 from bytestring-net/dev

Pull updates

.github/workflows/deploy.yml

@@ -0,0 +1,38 @@
+name: Deploy
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # To push a branch 
+      pages: write  # To push to a GitHub Pages site
+      id-token: write # To update the deployment status
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install latest mdbook
+        run: |
+          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
+          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
+          mkdir mdbook
+          curl -sSL $url | tar -xz --directory=./mdbook
+          echo `pwd`/mdbook >> $GITHUB_PATH
+      - name: Build Book
+        run: |
+          cd docs
+          mdbook build
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload entire repository
+          path: 'book'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

Cargo.toml

@@ -10,6 +10,7 @@
   exclude = [
     "promo/*",
     "examples/*",
+    "docs/*",
     ".gitignore",
     ".vscode",
   ]
@@ -18,8 +19,8 @@
   opt-level = 1
 
 [workspace.package]
-  authors     = ["Dominik Kaspar"]
-  version     = "0.1.0-alpha"
+  authors     = ["IDEDARY"]
+  version     = "0.1.0-alpha.2"
   edition     = "2021"
   license     = "MIT OR Apache-2.0"
   repository  = "https://github.com/bytestring-net/bevy-lunex"
@@ -28,16 +29,14 @@
 
 [workspace.dependencies]
 
-  bevy_lunex   = { path = "crates/bevy_lunex", version = "0.1.0-alpha" }
-  lunex_engine = { path = "crates/lunex_engine", version = "0.1.0-alpha" }
+  bevy_lunex   = { path = "crates/bevy_lunex", version = "0.1.0-alpha.2" }
+  lunex_engine = { path = "crates/lunex_engine", version = "0.1.0-alpha.2" }
 
   colored            = { version = "^2.1" }
   indexmap           = { version = "^2.1" }
   thiserror          = { version = "^1.0" }
 
   bevy = { version = "0.13.2", default_features = false, features = [
-    #"bevy_asset",
-    #"bevy_gilrs",
     "bevy_pbr",
     "bevy_sprite",
     "bevy_text",

README.md

@@ -1,4 +1,4 @@
-![image](crates/bevy_lunex/promo/bevy_lunex.png)
+![image](promo/bevy_lunex.png)
 
 <div align="center">
   <a href="https://crates.io/crates/bevy_lunex"><img src="https://img.shields.io/crates/v/bevy_lunex?label=version&color=d69039"></a>
@@ -22,7 +22,7 @@ Currently, it is most suited for game-like user interfaces. Use for regular appl
 
 ##
 
-![image](crates/bevy_lunex/promo/image.png)
+![image](promo/image.png)
 
 *^ A recreation of ***Cyberpunk*** UI in ***Bevy***. [(Source code here)](https://github.com/IDEDARY/Bevypunk).*
 

crates/lunex_engine/src/layout/layout.rs

@@ -435,7 +435,7 @@ impl NiceDisplay for Boundary {
 /// ```
 #[derive(Debug, Default, Clone, Copy, PartialEq)]
 pub struct Window {
-    /// Position of the top-left corner.
+    /// Position of the node.
     pub pos : UiValue<Vec2>,
     /// Decides where position should be applied at.
     pub anchor: Anchor,

docs/.gitignore

@@ -0,0 +1 @@
+book

docs/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["IDEDARY"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Bevy Lunex Documentation"

docs/src/README.md

@@ -0,0 +1 @@
+# Readme

docs/src/SUMMARY.md

@@ -0,0 +1,30 @@
+# Summary
+
+[Introduction](overview.md)
+
+---
+
+# Getting started
+
+- [Installation](installation.md)
+- [Quick start](quick_start.md)
+- [Debug](debug.md)
+
+---
+
+# Advanced
+- [Layouts](advanced/layouts.md)
+- [Units](advanced/units.md)
+- [Cursor](advanced/cursor.md)
+- [Routes](advanced/routes.md)
+- [Components](advanced/components.md)
+- [Interactivity](advanced/interactivity.md)
+- [Animation](advanced/animation.md)
+- [2D & 3D](advanced/2d_and_3d.md)
+- [Worldspace UI](advanced/worldspace_ui.md)
+- [Custom rendering](advanced/rendering.md)
+
+-----------
+
+[Contributors](contributors.md)
+[Help](help.md)

docs/src/advanced/2d_and_3d.md

@@ -0,0 +1 @@
+# 2D & 3D combined

docs/src/advanced/animation.md

@@ -0,0 +1 @@
+# Animation

docs/src/advanced/components.md

@@ -0,0 +1 @@
+# Components

docs/src/advanced/cursor.md

@@ -0,0 +1,61 @@
+# Cursor
+
+Lunex provides a custom API for styling a cursor within your Bevy application.
+
+This feature works by spawning a cursor atlas image alongside a special `Cursor2d` component as a child of a 2D camera.
+
+To use the custom cursor styling, we need to expand our `Camera2d` entity as follows:
+
+```rust
+# fn setup(mut commands: Commands, assets: Res<AssetServer>, mut atlas_layout: ResMut<Assets<TextureAtlasLayout>>){
+commands.spawn((
+    MainUi,
+    Camera2dBundle { transform: Transform::from_xyz(0.0, 0.0, 1000.0), ..default() }
+)).with_children(|camera| {
+
+    // Spawn cursor entity
+    camera.spawn ((
+
+        // Here we can map different native cursor icons to texture atlas indexes and sprite offsets
+        Cursor2d::new().native_cursor(false)
+            .register_cursor(CursorIcon::Default, 0, (14.0, 14.0))
+            .register_cursor(CursorIcon::Pointer, 1, (10.0, 12.0))
+            .register_cursor(CursorIcon::Grab, 2, (40.0, 40.0)),
+
+        // Add a SpriteSheetBundle to the cursor
+        SpriteSheetBundle {
+            texture: assets.load("cursor.png"),
+
+            // Define the texture atlas layout
+            atlas: TextureAtlas {
+                layout: atlas_layout.add(TextureAtlasLayout::from_grid(Vec2::splat(80.0), 3, 1, None, None)),
+                index: 0,
+            },
+
+            // Modify the scale of the cursor
+            transform: Transform { scale: Vec3::new(0.45, 0.45, 1.0), ..default() },
+
+            // Set the anchor to top-left
+            sprite: Sprite {
+                anchor: bevy::sprite::Anchor::TopLeft,
+                ..default()
+            },
+            ..default()
+        },
+
+        // Make the raycaster ignore this entity to prevent the cursor from blocking clicks
+        Pickable::IGNORE,
+    ));
+});
+# }
+```
+
+When creating a `Cursor2d` component, you can use the `native_cursor()` method to specify whether the cursor should exist as an entity within the game world or be injected into the `Winit` crate as a custom cursor sprite. (Note: This feature is currently a work in progress, and enabling it only hides the sprite for now.)
+
+![Cursor](../images/cursor.png)
+
+By default, spawning the cursor entity will hide the native system cursor unless `native_cursor(true)` is set.
+
+Additionally, you must register each cursor icon with its respective texture atlas indices and sprite offsets to define the appearance and positioning of different cursor states.
+
+Finally, to prevent the cursor from interfering with clicking events, we add the `Pickable::IGNORE` component. This ensures that the cursor sprite does not block any button interactions or other clickable elements in the UI.

docs/src/advanced/interactivity.md

@@ -0,0 +1 @@
+# Interactivity

docs/src/advanced/layouts.md

@@ -0,0 +1,55 @@
+# Layouts
+
+There are multiple layouts that you can utilize to achieve the structure you are aiming for.
+
+### Boundary
+Defined by **point1** and **point2**, it is not influenced by UI flow and is absolutely positioned.
+- **pos1** - Position of the top-left corner
+- **pos2** - Position of the bottom-right corner
+
+This will make a node start at `20%` and end at `80%` on both axis from the parent node.
+
+```rust
+UiLayout::boundary()
+    .pos1(Rl(20.0))
+    .pos2(Rl(80.0))
+    .pack()
+```
+
+### Window
+Defined by **position** and **size**, it is not influenced by UI flow and is absolutely positioned.
+- **pos** - Position of the node
+- **anchor** - The origin point relative to the rest of the node
+- **size** - Size of the node
+
+This will make a node centered at `x: 53%`, `y: 15%` and with size `width: 60%` and `height: 65%`.
+
+```rust
+UiLayout::window()
+    .pos(Rl((53.0, 15.0)))
+    .anchor(Anchor::Center)
+    .size(Rl((60.0, 65.0)))
+    .pack()
+```
+
+### Solid
+Defined by **size** only, it will scale to fit the parenting node. It is not influenced by UI flow.
+- **size** - Aspect ratio, it doesn't matter if it is `(10, 10)` or `(100, 100)`
+- **align_x** - Horizontal alignment, `-1.0 to 1.0` with `0.0` as default
+- **align_y** - Vertical alignment, `-1.0 to 1.0` with `0.0` as default
+- **scaling** - If the container should `fit` inside parent or `fill` the parent
+
+This layout is ideal for images, because it preserves aspect ratio under all costs.
+Here we will set aspect ratio to the size of our imaginary texture `(881.0, 1600.0)` in pixels.
+Then we can align it horizontally.
+
+```rust
+UiLayout::solid()
+    .size((881.0, 1600.0))
+    .align_x(-0.74)
+    .pack(),
+```
+
+### Div
+
+*Coming soon...*

docs/src/advanced/rendering.md

@@ -0,0 +1 @@
+# Custom rendering

docs/src/advanced/routes.md

@@ -0,0 +1 @@
+# Routes

docs/src/advanced/units.md

@@ -0,0 +1 @@
+# Units

docs/src/advanced/worldspace_ui.md

@@ -0,0 +1 @@
+# Worldspace UI

docs/src/alternatives.md

@@ -0,0 +1 @@
+# Alternatives

docs/src/contributors.md

@@ -0,0 +1,4 @@
+# Contributors
+
+This documentation is maintained by
+- [`IDEDARY`](https://github.com/IDEDARY)

docs/src/debug.md

@@ -0,0 +1,41 @@
+# Debug
+
+Lunex offers great debugging functionality. To enable these features, add the following plugin:
+
+```rust
+App::new()
+    .add_plugins(UiDebugPlugin::<MainUi>::new())
+    .run();
+```
+
+This will draw gizmo outlines around all your nodes, allowing you to see their positions and sizes.
+
+![Debug overlay](images/debug-overlay.png)
+
+Additionally, it will print the `UiTree` to the console whenever a change is detected. This can be extremely useful for debugging your UI.
+
+```rust
+> MainMenu == Window [pos: (x: 0, y: 0) size: (x: 100%, y: 100%) anchor: TopLeft]
+  |-> Background == Solid [size: (x: 2968, y: 1656) align_x: 0 align_y: 0]
+  |-> Solid == Solid [size: (x: 881, y: 1600) align_x: -0.74 align_y: 0]
+  |    |-> Board == Window [pos: (x: 50%, y: 0) size: (x: 105%, y: 105%) anchor: TopCenter]
+  |    |    |-> CONTINUE == Window [pos: (x: 0, y: 0) size: (x: 100%, y: 14%) anchor: TopLeft]
+  |    |    |-> NEW GAME == Window [pos: (x: 0, y: 17%) size: (x: 100%, y: 14%) anchor: TopLeft]
+  |    |    |-> LOAD GAME == Window [pos: (x: 0, y: 34%) size: (x: 100%, y: 14%) anchor: TopLeft]
+  |    |    |-> SETTINGS == Window [pos: (x: 0, y: 51%) size: (x: 100%, y: 14%) anchor: TopLeft]
+  |    |    |-> ADDITIONAL CONTENT == Window [pos: (x: 0, y: 68%) size: (x: 100%, y: 14%) anchor: TopLeft]
+  |    |    |-> CREDITS == Window [pos: (x: 0, y: 85%) size: (x: 100%, y: 14%) anchor: TopLeft]
+  |    |    |-> QUIT GAME == Window [pos: (x: 0, y: 102%) size: (x: 100%, y: 14%) anchor: TopLeft]
+```
+
+### More detail
+
+For even more detailed debugging, such as tracking what each system is doing and when, enable the `debug` feature. This will output detailed information to the console, which can be useful if you are integrating custom logic into the system.
+
+```rust
+INFO bevy_lunex::systems: -> UiTree - Fetched Transform data from Camera
+INFO bevy_lunex::systems: <> UiTree - Recomputed
+INFO bevy_lunex::systems: <- Foo/Bar - Linked ENTITY fetched Dimension data from node
+INFO bevy_lunex::systems: <- Foo/Bar - Linked ELEMENT fetched Transform data
+INFO bevy_lunex::systems: -- ELEMENT - Piped Dimension into sprite size
+```

docs/src/help.md

@@ -0,0 +1,7 @@
+# Help
+
+For issues related to the library, please create a ticket on [`GitHub`](https://github.com/bytestring-net/bevy_lunex/issues).
+
+You can also reach out on the [`Bevy Discord`](https://discord.gg/bevy), where I am likely to see your message.
+
+For questions or additional help, feel free to send me a direct message on Discord: `@idedary`.