diff --git a/README.md b/README.md index e8591b2..1118388 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@
-![banner](.github/images/logos/omath_logo_macro.png) +![banner](docs/images/logos/omath_logo_macro.png) ![Static Badge](https://img.shields.io/badge/license-libomath-orange) ![GitHub contributors](https://img.shields.io/github/contributors/orange-cpp/omath) @@ -61,7 +61,7 @@ It provides the latest features, is highly customizable, has all for cheat devel
-[![Youtube Video](.github/images/yt_previews/img.png)](https://youtu.be/lM_NJ1yCunw?si=-Qf5yzDcWbaxAXGQ) +[![Youtube Video](docs/images/yt_previews/img.png)](https://youtu.be/lM_NJ1yCunw?si=-Qf5yzDcWbaxAXGQ)
@@ -88,10 +88,10 @@ It provides the latest features, is highly customizable, has all for cheat devel - [All contributors](https://github.com/orange-cpp/omath/graphs/contributors) -[APEX Preview]: .github/images/showcase/apex.png -[BO2 Preview]: .github/images/showcase/cod_bo2.png -[CS2 Preview]: .github/images/showcase/cs2.jpeg -[TF2 Preview]: .github/images/showcase/tf2.jpg +[APEX Preview]: docs/images/showcase/apex.png +[BO2 Preview]: docs/images/showcase/cod_bo2.png +[CS2 Preview]: docs/images/showcase/cs2.jpeg +[TF2 Preview]: docs/images/showcase/tf2.jpg [INSTALL]: INSTALL.md [DOCUMENTATION]: http://libomath.org diff --git a/.github/images/banner.png b/docs/images/banner.png similarity index 100% rename from .github/images/banner.png rename to docs/images/banner.png diff --git a/.github/images/logos/omath_logo_macro.png b/docs/images/logos/omath_logo_macro.png similarity index 100% rename from .github/images/logos/omath_logo_macro.png rename to docs/images/logos/omath_logo_macro.png diff --git a/.github/images/logos/omath_logo_mega.png b/docs/images/logos/omath_logo_mega.png similarity index 100% rename from .github/images/logos/omath_logo_mega.png rename to docs/images/logos/omath_logo_mega.png diff --git a/.github/images/logos/omath_logo_micro.png b/docs/images/logos/omath_logo_micro.png similarity index 100% rename from .github/images/logos/omath_logo_micro.png rename to docs/images/logos/omath_logo_micro.png diff --git a/.github/images/logos/omath_logo_nano.png b/docs/images/logos/omath_logo_nano.png similarity index 100% rename from .github/images/logos/omath_logo_nano.png rename to docs/images/logos/omath_logo_nano.png diff --git a/.github/images/showcase/apex.png b/docs/images/showcase/apex.png similarity index 100% rename from .github/images/showcase/apex.png rename to docs/images/showcase/apex.png diff --git a/.github/images/showcase/cod_bo2.png b/docs/images/showcase/cod_bo2.png similarity index 100% rename from .github/images/showcase/cod_bo2.png rename to docs/images/showcase/cod_bo2.png diff --git a/.github/images/showcase/cs2.jpeg b/docs/images/showcase/cs2.jpeg similarity index 100% rename from .github/images/showcase/cs2.jpeg rename to docs/images/showcase/cs2.jpeg diff --git a/.github/images/showcase/tf2.jpg b/docs/images/showcase/tf2.jpg similarity index 100% rename from .github/images/showcase/tf2.jpg rename to docs/images/showcase/tf2.jpg diff --git a/.github/images/yt_previews/img.png b/docs/images/yt_previews/img.png similarity index 100% rename from .github/images/yt_previews/img.png rename to docs/images/yt_previews/img.png diff --git a/docs/index.md b/docs/index.md index 70faad5..61872d1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,68 +1,75 @@ -# Installation +
+ +

+ omath banner +

-## Using vcpkg -**Note**: Support vcpkg for package management -1. Install [vcpkg](https://github.com/microsoft/vcpkg) -2. Run the following command to install the orange-math package: -``` -vcpkg install orange-math -``` -CMakeLists.txt -```cmake -find_package(omath CONFIG REQUIRED) -target_link_libraries(main PRIVATE omath::omath) -``` -For detailed commands on installing different versions and more information, please refer to Microsoft's [official instructions](https://learn.microsoft.com/en-us/vcpkg/get_started/overview). + +

+ license: libomath + GitHub contributors + Top language + + CodeFactor + + GitHub Actions Workflow Status + + Vcpkg package + + GitHub forks + + Join us on Discord + + + Telegram + +

+
+OMath is a 100% independent, constexpr template blazingly fast math library that doesn't have legacy C++ code. -## Using xrepo -**Note**: Support xrepo for package management -1. Install [xmake](https://xmake.io/) -2. Run the following command to install the omath package: -``` -xrepo install omath -``` -xmake.lua -```xmake -add_requires("omath") -target("...") - add_packages("omath") -``` +It provides the latest features, is highly customizable, has all for cheat development, DirectX/OpenGL/Vulkan support, premade support for different game engines, much more constexpr stuff than in other libraries and more... -## Build from source using CMake -1. **Preparation** - Install needed tools: cmake, clang, git, msvc (windows only). +# Features +- **Efficiency**: Optimized for performance, ensuring quick computations using AVX2. +- **Versatility**: Includes a wide array of mathematical functions and algorithms. +- **Ease of Use**: Simplified interface for convenient integration into various projects. +- **Projectile Prediction**: Projectile prediction engine with O(N) algo complexity, that can power you projectile aim-bot. +- **3D Projection**: No need to find view-projection matrix anymore you can make your own projection pipeline. +- **Collision Detection**: Production ready code to handle collision detection by using simple interfaces. +- **No Additional Dependencies**: No additional dependencies need to use OMath except unit test execution +- **Ready for meta-programming**: Omath use templates for common types like Vectors, Matrixes etc, to handle all types! +- **Engine support**: Supports coordinate systems of **Source, Unity, Unreal, Frostbite, IWEngine and canonical OpenGL**. +- **Cross platform**: Supports Windows, MacOS and Linux. +- **Algorithms**: Has ability to scan for byte pattern with wildcards in PE files/modules, binary slices, works even with Wine apps. - 1. **Linux:** - ```bash - sudo pacman -Sy cmake ninja clang git - ``` - 2. **MacOS:** - ```bash - brew install llvm git cmake ninja - ``` - 3. **Windows:** +# Gallery - Install Visual Studio from [here](https://visualstudio.microsoft.com/downloads/) and Git from [here](https://git-scm.com/downloads). +
- Use x64 Native Tools shell to execute needed commands down below. -2. **Clone the repository:** - ```bash - git clone https://github.com/orange-cpp/omath.git - ``` -3. **Navigate to the project directory:** - ```bash - cd omath - ``` -4. **Build the project using CMake:** - ```bash - cmake --preset windows-release -S . - cmake --build cmake-build/build/windows-release --target omath -j 6 - ``` - Use **\-\** preset to build suitable version for yourself. Like **windows-release** or **linux-release**. +[![Youtube Video](images/yt_previews/img.png)](https://youtu.be/lM_NJ1yCunw?si=-Qf5yzDcWbaxAXGQ) - | Platform Name | Build Config | - |---------------|---------------| - | windows | release/debug | - | linux | release/debug | - | darwin | release/debug | +
+ +![APEX Preview] + +
+ +![BO2 Preview] + +
+ +![CS2 Preview] + +
+ +![TF2 Preview] + +
+
+ + +[APEX Preview]: images/showcase/apex.png +[BO2 Preview]: images/showcase/cod_bo2.png +[CS2 Preview]: images/showcase/cs2.jpeg +[TF2 Preview]: images/showcase/tf2.jpg \ No newline at end of file diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..4a3cd31 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,68 @@ +# Installation + +## Using vcpkg +**Note**: Support vcpkg for package management +1. Install [vcpkg](https://github.com/microsoft/vcpkg) +2. Run the following command to install the orange-math package: +``` +vcpkg install orange-math +``` +CMakeLists.txt +```cmake +find_package(omath CONFIG REQUIRED) +target_link_libraries(main PRIVATE omath::omath) +``` +For detailed commands on installing different versions and more information, please refer to Microsoft's [official instructions](https://learn.microsoft.com/en-us/vcpkg/get_started/overview). + +## Using xrepo +**Note**: Support xrepo for package management +1. Install [xmake](https://xmake.io/) +2. Run the following command to install the omath package: +``` +xrepo install omath +``` +xmake.lua +```xmake +add_requires("omath") +target("...") + add_packages("omath") +``` + +## Build from source using CMake +1. **Preparation** + + Install needed tools: cmake, clang, git, msvc (windows only). + + 1. **Linux:** + ```bash + sudo pacman -Sy cmake ninja clang git + ``` + 2. **MacOS:** + ```bash + brew install llvm git cmake ninja + ``` + 3. **Windows:** + + Install Visual Studio from [here](https://visualstudio.microsoft.com/downloads/) and Git from [here](https://git-scm.com/downloads). + + Use x64 Native Tools shell to execute needed commands down below. +2. **Clone the repository:** + ```bash + git clone https://github.com/orange-cpp/omath.git + ``` +3. **Navigate to the project directory:** + ```bash + cd omath + ``` +4. **Build the project using CMake:** + ```bash + cmake --preset windows-release -S . + cmake --build cmake-build/build/windows-release --target omath -j 6 + ``` + Use **\-\** preset to build suitable version for yourself. Like **windows-release** or **linux-release**. + + | Platform Name | Build Config | + |---------------|---------------| + | windows | release/debug | + | linux | release/debug | + | darwin | release/debug | diff --git a/docs/styles/center.css b/docs/styles/center.css new file mode 100644 index 0000000..c1b0e2a --- /dev/null +++ b/docs/styles/center.css @@ -0,0 +1,4 @@ +/* docs/css/custom.css */ +.center-text { + text-align: center; +} \ No newline at end of file diff --git a/docs/utility/pattern_scan.md b/docs/utility/pattern_scan.md index c1bc883..182c5b5 100644 --- a/docs/utility/pattern_scan.md +++ b/docs/utility/pattern_scan.md @@ -45,7 +45,7 @@ The pattern string is parsed into a sequence of byte **tokens**: * **Wildcard byte**: `?` or `??` matches **any single byte**. * **Separators**: any ASCII whitespace (space, tab, newline) is **ignored** and may be used to group tokens. -> ✔️ Valid: `"48 8B ?? 05 00"`, `"90 90 90"`, `"??"`, `"00??FF"` (no spaces) +> ✔️ Valid: `"48 8B ?? 05 00"`, `"90 90 90"`, `"??"` > ❌ Invalid: odd number of hex digits in a token, non-hex characters (besides `?` and whitespace) If the string cannot be parsed into a clean sequence of tokens, `parse_pattern()` returns `std::unexpected(PatternScanError::INVALID_PATTERN_STRING)`, and the public scan function returns **end**. diff --git a/docs/utility/pe_pattern_scan.md b/docs/utility/pe_pattern_scan.md new file mode 100644 index 0000000..026afa7 --- /dev/null +++ b/docs/utility/pe_pattern_scan.md @@ -0,0 +1,155 @@ +# `omath::PePatternScanner` — Scan PE images for byte patterns + +> Header: your project’s `pe_pattern_scanner.hpp` +> Namespace: `omath` +> Platform: **Windows / PE (Portable Executable) images** +> Depends on: ``, ``, `` +> Companion: works well with `omath::PatternScanner` (same pattern grammar) + +`PePatternScanner` searches **Portable Executable (PE)** binaries for a hex pattern (with wildcards). You can scan: + +* a **loaded module** in the current process, or +* a **PE file on disk** (by section name; defaults to **`.text`**). + +--- + +## Pattern string grammar (same as `PatternScanner`) + +* **Hex byte**: two hex digits → one byte (`90`, `4F`, `00`, `ff`). +* **Wildcard byte**: `?` or `??` matches **any byte**. +* **Whitespace**: ignored (use to group tokens). + +✔️ `"48 8B ?? ?? 89"`, `"55 8B EC"`, `"??"` +❌ odd digit counts, non-hex characters (besides `?` and whitespace) + +--- + +## API + +```cpp +namespace omath { + +struct PeSectionScanResult { + std::uint64_t virtual_base_addr; // RVA base of the scanned section (ImageBase + SectionRVA) + std::uint64_t raw_base_addr; // file offset (start of section in the file) + std::ptrdiff_t target_offset; // offset from section base to the first matched byte +}; + +class PePatternScanner final { +public: + // Scan a module already loaded in *this* process. + // module_base_address: HMODULE / ImageBase (e.g., from GetModuleHandle) + // Returns absolute address (process VA) of the first match, or nullopt. + static std::optional + scan_for_pattern_in_loaded_module(const void* module_base_address, + const std::string_view& pattern); + + // Scan a PE file on disk, by section name (default ".text"). + // Returns section bases (virtual + raw) and match offset within the section, or nullopt. + static std::optional + scan_for_pattern_in_file(const std::filesystem::path& path_to_file, + const std::string_view& pattern, + const std::string_view& target_section_name = ".text"); +}; + +} // namespace omath +``` + +--- + +## Return values + +* **Loaded module**: `std::optional` + + * `value()` = **process virtual address** (ImageBase + SectionRVA + match offset). + * `nullopt` = no match or parse/PE error. + +* **File scan**: `std::optional` + + * `virtual_base_addr` = **ImageBase + SectionRVA** of the scanned section (as if mapped). + * `raw_base_addr` = **file offset** of section start. + * `target_offset` = offset from the section base to the **first matched byte**. + * To get addresses: + + * **Virtual (RVA)** of hit = `virtual_base_addr + target_offset` + * **Raw file offset** of hit = `raw_base_addr + target_offset` + +--- + +## Usage examples + +### Scan a loaded module (current process) + +```cpp +#include +#include "pe_pattern_scanner.hpp" + +using omath::PePatternScanner; + +auto hMod = ::GetModuleHandleW(L"kernel32.dll"); +if (hMod) { + auto addr = PePatternScanner::scan_for_pattern_in_loaded_module( + hMod, "48 8B ?? ?? 89" // hex + wildcards + ); + if (addr) { + // Use the absolute process VA: + std::uintptr_t hit_va = *addr; + // ... + } +} +``` + +### Scan a PE file on disk (default section “.text”) + +```cpp +#include "pe_pattern_scanner.hpp" +using omath::PePatternScanner; + +auto res = PePatternScanner::scan_for_pattern_in_file( + R"(C:\Windows\System32\kernel32.dll)", "55 8B EC" +); +if (res) { + auto rva_hit = res->virtual_base_addr + res->target_offset; + auto raw_hit = res->raw_base_addr + res->target_offset; + // rva_hit: where it would be in memory; raw_hit: file offset +} +``` + +### Scan another section (e.g., “.rdata”) + +```cpp +auto res = PePatternScanner::scan_for_pattern_in_file( + "foo.dll", "48 8D 0D ?? ?? ?? ??", ".rdata" +); +``` + +--- + +## Notes & edge cases + +* **PE only**: these functions assume a valid **PE/COFF** layout. Non-PE files or corrupted headers yield `nullopt`. +* **Section name**: `scan_for_pattern_in_file` defaults to **`.text`**; pass a different name to target other sections. +* **Alignment & RVAs**: `virtual_base_addr` is computed from section headers (RVA aligned per section alignment). The returned “virtual” base is suitable for RVA math; the **process VA** returned by the “loaded module” API already includes the image base. +* **Architecture**: works for 32-bit and 64-bit PEs; `std::uintptr_t` size matches the build architecture. +* **Performance**: Pattern matching is **O(N × M)** (sliding window with wildcards). For large images, prefer scanning only necessary sections. +* **Wildcards**: Each `?` matches **one byte** (no nibble masks). If you need `A?`-style nibble wildcards, extend the parser (see `PatternScanner`). +* **Safety**: For loaded modules, you must have access to the memory; scanning read-only sections is fine, but never write. For file scans, ensure the file path is accessible. + +--- + +## Troubleshooting + +* **`nullopt`**: Verify the pattern (valid tokens), correct **section**, and that you’re scanning the intended module/file (check bitness and version). +* **“Loaded module” address math**: If you need an **offset from the module base**, compute `offset = hit_va - reinterpret_cast(module_base_address)`. +* **Multiple matches**: Only the **first** match is returned. If you need all matches, extend the implementation to continue scanning from `target_offset + 1`. + +--- + +## See also + +* `omath::PatternScanner` — raw buffer/iterator scanning with the same pattern grammar. +* `omath::Triangle`, `omath::Vector3` — math types used elsewhere in the library. + +--- + +*Last updated: 31 Oct 2025* diff --git a/mkdocs.yml b/mkdocs.yml index 08deb72..2534924 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,3 +1,5 @@ site_name: OMATH Docs theme: - name: darkly \ No newline at end of file + name: darkly +extra_css: + - styles/center.css \ No newline at end of file