diff --git a/README.md b/README.md index 435552c..4048f35 100644 --- a/README.md +++ b/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! diff --git a/crates/algebra/README.md b/crates/algebra/README.md new file mode 100644 index 0000000..cea79b0 --- /dev/null +++ b/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. diff --git a/crates/defi/README.md b/crates/defi/README.md index 301b7a0..2d84275 100644 --- a/crates/defi/README.md +++ b/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 diff --git a/crates/map/README.md b/crates/map/README.md new file mode 100644 index 0000000..e09f458 --- /dev/null +++ b/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. diff --git a/crates/random/README.md b/crates/random/README.md new file mode 100644 index 0000000..435db49 --- /dev/null +++ b/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. diff --git a/crates/rating/README.md b/crates/rating/README.md new file mode 100644 index 0000000..f913285 --- /dev/null +++ b/crates/rating/README.md @@ -0,0 +1,61 @@ +# Rating + +The Origami Rating crate is a library that provides rating-related algorithms for Dojo-based games. It offers efficient implementations of rating systems commonly used in game development and competitive matchmaking. + +## Overview + +The Rating crate focuses on providing rating algorithms that are essential for game development, particularly for competitive games. Its primary scope includes: + +- Elo rating system implementation + +The crate is designed to work seamlessly with the Dojo engine and other Origami crates. + +## Features + +### Elo Rating System + +- Calculate rating changes based on game outcomes +- Support for different K-factors +- Handling of wins, losses, and draws + +## Installation + +To add the Origami Rating 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_rating = { 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 Rating crate: + +### Elo rating system + +This example demonstrates how to calculate and apply a rating change using the Elo system. The rating_change function takes the current ratings of both players, the game outcome, and the K-factor as inputs. It returns the magnitude of the rating change and a boolean indicating whether the change is negative. + +```rust +use origami_rating::elo::EloTrait; + +// Calculate rating change for player A +let (change, is_negative) = EloTrait::rating_change( + 1200_u64, // Player A's current rating + 1400_u64, // Player B's current rating + 100_u16, // Outcome (100 = win, 50 = draw, 0 = loss) + 20_u8 // K-factor +); + +// Apply the rating change +let new_rating_a = if is_negative { + 1200 - change +} else { + 1200 + change +}; + +println!("Player A's new rating: {}", new_rating_a); +``` + +Remember to import the necessary traits and types when using the Rating crate in your project. diff --git a/crates/security/README.md b/crates/security/README.md new file mode 100644 index 0000000..83ce68c --- /dev/null +++ b/crates/security/README.md @@ -0,0 +1,60 @@ +# Security + +The Origami Security crate is a library that provides security-related primitives for Dojo-based games. It offers implementations of common security patterns and utilities to enhance the safety and integrity of game development on the Dojo framework. + +## Overview + +The Security crate focuses on providing fundamental security mechanisms that are essential for game development. Its primary scope includes: + +- Commitment schemes + +The crate is designed to work seamlessly with the Dojo engine and other Origami crates. + +## Features + +### Commitment schemes + +A Commitment is a cryptographic primitive that allows you to commit to a chosen value while keeping it hidden, with the ability to reveal it later. This is useful in scenarios where you want to make a binding commitment to a value, meaning that once a commitment is made, it cannot be changed or altered. + +Features of the Commitment implementation include: + +- Creation of new commitments +- Committing to a hash value +- Revealing and verifying committed values + +## Installation + +To add the Origami Security 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_security = { 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 Security crate: + +### Commit/Reveal + +```rust +use origami_security::commitment::{Commitment, CommitmentTrait}; + +// Create a new commitment +let mut commitment = CommitmentTrait::new(); + +// Commit to a value (in this case, a string) +let value = 'secret'; +let mut serialized = array![]; +value.serialize(ref serialized); +let hash = poseidon_hash_span(serialized.span()); +commitment.commit(hash); + +// Later, reveal and verify the commitment +let is_valid = commitment.reveal('secret'); +assert(is_valid, 'Invalid reveal for commitment'); +``` + +Remember to import the necessary traits and types when using the Security crate in your project. diff --git a/.github/Origami.svg b/docs/images/origami.svg similarity index 100% rename from .github/Origami.svg rename to docs/images/origami.svg diff --git a/docs/videos/usage.gif b/docs/videos/usage.gif new file mode 100644 index 0000000..fc07d50 Binary files /dev/null and b/docs/videos/usage.gif differ