🎉 Add a readme doc for each crates

README.md

@@ -1,17 +1,17 @@
 <!-- markdownlint-disable -->
 <div align="center">
-  <img src=".github/Origami.svg" height="128">
+  <img src="./docs/images/origami.svg" height="128">
 </div>
 <div align="center">
-<br />
-<!-- markdownlint-restore -->
+  <br />
+  <!-- markdownlint-restore -->
 
-<a href="https://twitter.com/dojostarknet">
-<img src="https://img.shields.io/twitter/follow/dojostarknet?style=social"/>
-</a>
-<a href="https://github.com/dojoengine/dojo">
-<img src="https://img.shields.io/github/stars/dojoengine/dojo?style=social"/>
-</a>
+  <a href="https://twitter.com/dojostarknet">
+    <img src="https://img.shields.io/twitter/follow/dojostarknet?style=social"/>
+  </a>
+  <a href="https://github.com/dojoengine/dojo">
+    <img src="https://img.shields.io/github/stars/dojoengine/dojo?style=social"/>
+  </a>
 
 [![discord](https://img.shields.io/badge/join-dojo-green?logo=discord&logoColor=white)](https://discord.gg/PwDa2mKhR4)
 ![Github Actions][gha-badge] [![Telegram Chat][tg-badge]][tg-url]
@@ -22,22 +22,30 @@
 
 </div>
 
-# Origami - Primitives for onchain Gaming
+# Origami
 
-#### "The magic of origami is in seeing a single piece of cairo evolve into a masterpiece through careful folds" - Sensei
+Origami is a collection of essential primitives designed to facilitate the development of onchain games using the Dojo engine.
+It provides a set of powerful tools and libraries that enable game developers to create complex, engaging, and efficient fully onchain games.
+
+> _The magic of origami is in seeing a single piece of cairo evolve into a masterpiece through careful folds_
+>
+> <p align="right">Sensei</p>
+
+<div align="center">
+  <img src="./docs/videos/usage.gif" height="400">
+</div>
 
 ---
 
 ### Crates
 
-- [algebra](./crates/algebra)
-- [defi](./crates/defi/)
-- [map](./crates/map)
-- [random](./crates/random)
-- [rating](./crates/rating)
-- [security](./crates/security)
-- [token](./crates/token)
-- [governance](./crates/governance)
+- [Algebra](./crates/algebra)
+- [Defi](./crates/defi/)
+- [Map](./crates/map)
+- Physics (WIP)
+- [Random](./crates/random)
+- [Rating](./crates/rating)
+- [Security](./crates/security)
 
 ### Easy integration into your project
 
@@ -47,7 +55,8 @@ Add the following to your `[dependencies]`:
 
 ```toml
 [dependencies]
-origami_token = { git = "https://github.com/dojoengine/origami" }
+origami_random = { git = "https://github.com/dojoengine/origami" }
+origami_map = { git = "https://github.com/dojoengine/origami" }
 ```
 
 Now you will be able to use origami like any other Cairo package!

crates/algebra/README.md

@@ -0,0 +1,55 @@
+# Algebra
+
+The Origami Algebra crate is a library that provides algebraic primitives for Dojo-based games. It offers efficient implementations of mathematical structures and operations commonly used in game development.
+
+## Overview
+
+The Algebra crate focuses on providing fundamental mathematical structures and operations that are essential for game development. Its primary scope includes:
+
+- Vector operations
+- Matrix operations
+- Basic algebraic computations
+
+The crate is designed to work seamlessly with the Dojo engine and other Origami crates.
+
+## Installation
+
+To add the Origami Algebra crate as a dependency in your project, you need to modify your Scarb.toml file. Add the following to your [dependencies] section:
+
+```toml
+[dependencies]
+origami_algebra = { git = "https://github.com/dojoengine/origami" }
+```
+
+Make sure you have dojo installed and configured in your project.
+
+## Features
+
+The crate currently implements a 2D vector (Vec2) with various operations:
+
+```rust
+struct Vec2<T> {
+    x: T,
+    y: T
+}
+```
+
+Key features of `Vec2` include:
+
+- Construction: new and splat methods
+- Dot product calculation
+- Swizzle operations (xx, xy, yx, yy)
+- Mask-based selection
+
+Example usage:
+
+```rust
+let vec2a = Vec2Trait::new(1, -2);
+let vec2b = Vec2Trait::new(-3, 4);
+let a_dot_b = vec2a.dot(vec2b);  // -11
+```
+
+## Conclusion
+
+The Origami Algebra crate provides a solid foundation for mathematical operations in Dojo-based games. It offers efficient implementations of 2D vectors with various utility functions. As the crate evolves, more features and mathematical structures may be added to support a wider range of game development needs.
+For the most up-to-date information and usage examples, refer to the crate's source code and any accompanying documentation in the Origami repository.

crates/defi/README.md

@@ -32,6 +32,17 @@ The process works by incrementally making more assets available for sale, splitt
 
 It's possible to compute the purchase price for any quantity of tokens gas-efficiently, using specific mathematical expressions.
 
+## Installation
+
+To add the Origami DeFi crate as a dependency in your project, you need to modify your Scarb.toml file. Add the following to your [dependencies] section:
+
+```toml
+[dependencies]
+origami_defi = { git = "https://github.com/dojoengine/origami" }
+```
+
+Make sure you have dojo installed and configured in your project.
+
 ## How to Use
 
 ### Discrete Gradual Dutch Auction
@@ -97,7 +108,7 @@ GDAs present a powerful tool for selling both fungible and non-fungible tokens i
 
 ## Overview
 
-Variable Rate GDAs ([VRGDAs](https://www.paradigm.xyz/2022/08/vrgda)) enable the selling of tokens according to a custom schedule, raising or lowering prices based on the sales pace. VRGDA is a generalization of the GDA mechanism. 
+Variable Rate GDAs ([VRGDAs](https://www.paradigm.xyz/2022/08/vrgda)) enable the selling of tokens according to a custom schedule, raising or lowering prices based on the sales pace. VRGDA is a generalization of the GDA mechanism.
 
 ## How to Use
 

crates/map/README.md

@@ -0,0 +1,132 @@
+# Map
+
+The Origami Map crate is a library that provides map generation and manipulation functionalities for Dojo-based games. It offers efficient implementations of various map-related algorithms and data structures commonly used in game development.
+
+## Overview
+
+The Map crate focuses on providing tools for creating, manipulating, and navigating 2D grid-based maps. Its primary scope includes:
+
+- Map generation algorithms (maze, cave, random walk)
+- Pathfinding
+- Object distribution on maps
+- Hexagonal grid support
+
+The crate is designed to work seamlessly with the Dojo engine and other Origami crates.
+
+## Features
+
+### Map Generation
+
+- Maze generation using [Prim's algorithm](https://en.wikipedia.org/wiki/Prim%27s_algorithm)
+- Cave generation using a [cellular automata-like](https://en.wikipedia.org/wiki/Cellular_automaton) approach
+- [Random walk](https://en.wikipedia.org/wiki/Random_walk) map generation
+
+### Pathfinding
+
+- [A\* algorithm](https://en.wikipedia.org/wiki/A*_search_algorithm) for finding the shortest path between two points
+
+### Map Manipulation
+
+- Adding corridors to existing maps
+- Integrating mazes into existing maps
+
+### Object Distribution
+
+- Spreading objects uniformly across walkable areas of the map
+
+### Hexagonal Grid Support
+
+- Basic operations for hexagonal grids
+
+## Installation
+
+To add the Origami Map crate as a dependency in your project, you need to modify your Scarb.toml file. Add the following to your [dependencies] section:
+
+```toml
+[dependencies]
+origami_map = { git = "https://github.com/dojoengine/origami" }
+```
+
+Make sure you have dojo installed and configured in your project.
+
+## How to use it?
+
+Here are some examples of how to use the Map crate:
+
+### Generating a maze
+
+```rust
+use origami_map::map::MapTrait;
+
+let width = 18;
+let height = 14;
+let order = 0;
+let seed = 'SEED';
+let maze_map = MapTrait::new_maze(width, height, order, seed);
+```
+
+### Generating a cave
+
+```rust
+use origami_map::map::MapTrait;
+
+let width = 18;
+let height = 14;
+let order = 3;
+let seed = 'SEED';
+let cave_map = MapTrait::new_cave(width, height, order, seed);
+```
+
+### Generating a random walk
+
+```rust
+use origami_map::map::MapTrait;
+
+let width = 18;
+let height = 14;
+let steps = 500;
+let seed = 'SEED';
+let random_walk_map = MapTrait::new_random_walk(width, height, steps, seed);
+```
+
+### Opening an existing map with a corridor
+
+```rust
+use origami_map::map::MapTrait;
+
+let mut map = MapTrait::new_maze(width, height, order, seed);
+let position = 1;
+let order = 0;
+map.open_with_corridor(position, order);
+```
+
+### Opening an existing map with a maze
+
+```rust
+use origami_map::map::MapTrait;
+
+let mut map = MapTrait::new_maze(width, height, order, seed);
+let position = 1;
+let order = 0;
+map.open_with_maze(position, order);
+```
+
+### Finding a path using A\* algorithm
+
+```rust
+use origami_map::map::MapTrait;
+
+let map = MapTrait::new_maze(width, height, order, seed);
+let path = map.search_path(start_position, end_position);
+```
+
+### Distributing objects on the map
+
+```rust
+use origami_map::map::MapTrait;
+
+let map = MapTrait::new_maze(width, height, order, seed);
+let distribution = map.compute_distribution(10, seed);
+```
+
+Remember to import the necessary traits and types when using the Map crate in your project.

crates/random/README.md

@@ -0,0 +1,103 @@
+# Random
+
+The Origami Random crate is a library that provides pseudo-random generation functionality for Dojo-based games. It offers efficient implementations of random number generation and randomization techniques commonly used in game development.
+
+## Overview
+
+The Random crate focuses on providing random generation primitives that are essential for game development. Its primary scope includes:
+
+- Dice rolling
+- Card deck management and shuffling
+
+The crate is designed to work seamlessly with the Dojo engine and other Origami crates.
+
+## Features
+
+### Dice Rolling
+
+- Create dice with customizable face counts
+- Generate random rolls based on a seed
+
+### Card Deck Management
+
+- Create decks with a specified number of cards
+- Draw cards randomly from the deck
+- Discard and withdraw cards from the deck
+- Create decks from bitmaps for custom initial states
+
+## Installation
+
+To add the Origami Random crate as a dependency in your project, you need to modify your Scarb.toml file. Add the following to your [dependencies] section:
+
+```toml
+[dependencies]
+origami_random = { git = "https://github.com/dojoengine/origami" }
+```
+
+Make sure you have dojo installed and configured in your project.
+
+## How to use it?
+
+Here are some examples of how to use the Random crate:
+
+### Dice Rolling
+
+To use the dice rolling feature:
+
+```rust
+use origami_random::dice::{Dice, DiceTrait};
+
+// Create a new 6-sided dice with a seed
+let mut dice = DiceTrait::new(6, 'SEED');
+
+// Roll the dice
+let result = dice.roll();
+```
+
+### Card Deck Management
+
+To use the card deck management feature:
+
+```rust
+use origami_random::deck::{Deck, DeckTrait};
+
+// Create a new deck with 52 cards and a seed
+let mut deck = DeckTrait::new('SEED', 52);
+
+// Draw a card from the deck
+let card = deck.draw();
+
+// Discard a card back into the deck
+deck.discard(card);
+
+// Withdraw a specific card from the deck
+deck.withdraw(10);
+```
+
+### Advanced usage
+
+Dice and Deck can be used to create more complex randomization mechanics in your game. For example, you can use Dice to determine the outcome of a skill check, or use a Deck to randomly sequence game events.
+
+In the following example, we use the Dice to define the number of mobs to spawn and use the Deck to associate a specifc order to each mob.
+
+```rust
+use origami_random::dice::{Dice, DiceTrait};
+use origami_random::deck::{Deck, DeckTrait};
+
+// Spawn 1 to 6 mobs
+let mut dice = DiceTrait::new(6, 'SEED');
+let mut count = dice.roll();
+
+// Create a deck with the same number of cards as the number of mobs
+let mut deck = DeckTrait::new('SEED', count.into());
+
+// Draw each mob from the deck and create an array of mob ids
+let mut mob_ids: Array<u8> = array![];
+while count > 0 {
+    let mob_id = deck.draw();
+    mob_ids.append(mob_id);
+    count -= 1;
+}
+```
+
+Remember to import the necessary traits and types when using the Random crate in your project.