From 576cec21bf117518d5a0d17acac672638daba012 Mon Sep 17 00:00:00 2001
From: Youcef <154016962+mazerissa@users.noreply.github.com>
Date: Tue, 4 Aug 2026 21:20:23 +0200
Subject: [PATCH] Enhance README with project details and instructions

Expanded README with detailed project description, features, installation instructions, and usage examples.
---
 README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index a7a8ac8..8b5af84 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,68 @@
-# Physics Engine written in `C`
+# phy
 
-will be public asap.
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Language](https://img.shields.io/badge/Language-C-00599C.svg)](https://en.wikipedia.org/wiki/C_(programming_language))
+
+**A Physics Engine written in C**
+
+`phy` is a lightweight physics engine developed in pure C. Built with performance and simplicity in mind, it provides the fundamental building blocks for simulating physical systems, collision detection, and rigid body dynamics.
+
+*Note: The engine is currently in development and the full source code will be made public soon.*
+
+## Features
+
+* **Pure C Implementation**: Lightweight, fast, and easy to integrate into existing C/C++ projects or game engines.
+* **Optimized Math Backend**: Powered by [`cglm`](https://github.com/recp/cglm) for highly optimized 3D math operations (vectors, matrices, quaternions).
+* **Rigid Body Dynamics** *(In Progress)*: Core structures for handling mass, velocity, acceleration, and forces.
+* **Collision Detection** *(Planned)*: Primitives for AABB, spheres, and complex mesh intersections.
+
+## Dependencies
+
+* [`cglm`](https://github.com/recp/cglm) - Required for mathematical operations.
+
+## Installation
+
+### Using Git Submodules
+
+The easiest way to integrate `phy` into your project is by adding it as a git submodule. This will also fetch necessary dependencies like `cglm`.
+
+```bash
+git submodule add https://github.com/recp/phy.git
+git submodule update --init --recursive
+```
+
+### Linking to Your Project
+
+Add the `include/` directory to your project's include path and compile the source files along with your project.
+
+## Usage
+
+```c
+#include <phy/phy.h>
+
+int main(void) {
+    // API is under active development.
+    // Example conceptual usage:
+    // 
+    // phy_world_t* world = phy_world_create();
+    // 
+    // // Simulation loop
+    // while (running) {
+    //     phy_world_step(world, delta_time);
+    // }
+    // 
+    // phy_world_destroy(world);
+    
+    return 0;
+}
+
+```
+
+## Contributing
+
+Contributions, issues, and feature requests are welcome!
+Feel free to check the [issues page](https://www.google.com/search?q=https://github.com/recp/phy/issues) if you want to contribute once the full codebase is public.
+
+## License
+
+`phy` is distributed under the [Apache License 2.0](https://www.google.com/search?q=https://github.com/recp/phy/blob/master/LICENSE). See `LICENSE` for more information.