Billiards simulation — Phase 1 (physics core + visualization)
git clone https://github.com/Hamza7p/billiards_simulation.git
git checkout -b {branch_name}
git push -u origin {branch_name}يهدف هذا المشروع إلى بناء نواة محاكاة فيزيائية (physical simulation) لطاولة بلياردو في المستوي الأفقي (horizontal/X–Y plane) مع التكامل المرحلي نحو نموذج ثلاثي الأبعاد (3D) لاحقاً. لا يتم استخدام وكلاء تعلّم آلية؛ الحركة مبنية على معادلات تكامل زمني (time-step integration) وفصل واضح بين:
- النواة الرياضية/الفيزيائية (simulation/math core) — من دون اعتماد على مكتبات الرسم.
- العرض (rendering) عبر Three.js الذي يكتفي بقراءة حالة المحاكاة (الموقع، الزخم الزاوي…).
المكدس التقني: React 19, Vite, three.js.
npm install
npm run dev # بيئة تطوير + HMR
npm run build # إنتاج dist/
npm run preview # معاينة الإنتاج
npm run lint # ESLint| المسار | الدور والمسؤولية |
|---|---|
index.html |
نقطة دخول الوثيقة؛ تحميل src/main.jsx. |
vite.config.js |
إعداد Vite و plugin React. |
src/main.jsx |
ربط جذر React إلى #root وتهيئة الأنماط العامة. |
src/index.css |
خطوط Cairo، متغيّرات ألوان/تخطيط (:root), فئات تخطيط التطبيق. |
src/App.jsx |
تنسيق الواجهة، حلقة المحاكاة (physics loop)، ربط SimulationPanel بـ BilliardsScene. |
src/config/ |
constants.js: ثوابت العالم (جاذبية، أنصاف أبعاد الطاولة، μ defaults، خوارزمية التوقف، نسبة اشتقاق rolling resistance)، إلخ. |
src/math/ |
Vector2.js, Vector3.js: متجهات خفيفة مستقلة عن Three لتبقى النواة pure. |
src/simulation/ |
Ball.js: جسم متصل بكتلة، نصف قطر، موقع، سرعة، ω؛ النبضة الخطية عبر applyCueImpulse. Table2D.js: حدود مستطيلة. friction.js: قوى/عزوم الاحتكاك. stepBallOnTable.js: خطوة تكامل + ارتداد من الجدران + تشبع التوقف العددي. |
src/ui/ |
SimulationPanel.jsx, SimulationPanel.module.css: لوحة المعاملات والنتائج. |
src/view/ |
BilliardsScene.jsx: مشهد Orthographic ثلاثي الأبعاد للقراءة فقط من مرجع الكرة. |
public/ |
موارد ثابتة عند الحاجة (لم تُفعّل حالياً لنسيج الكرة الافتراضي). |
ملاحظة معمارية: أي توسعة لاحقة (اصطدام كرتين، وسائد، عرض 3D كامل للكيوب يُفضّل أن تبقي المعادلات في
simulation/والعرض على Three فقط.)
-
علاقة النبضة والسرعة (impulse–momentum theorem):
$$\Delta \mathbf{v} = \frac{\mathbf{J}}{m}$$ حيث J (وحدة SI: N·s) نبضة أفقية، m كتلة، Δv تغير السرعة الخطية.
- تحديث الموقع: position += velocity × Δt بعد تطبيع التسارع الناتج عن القوى.
- عطالة الكرة المنيعة الموحدة:
$$I = \frac{2}{5} m r^2$$
-
المتجه الموازي لسطح الطاولة:
$$\mathbf{v}{\mathrm{slip},,xy} = \mathbf{v}{xy} + (\boldsymbol{\omega} \times \mathbf{r}c){xy}$$
حيث r_c متجه من مركز الكرة إلى نقطة الاتصال (نموذجياً عمود على السطح باتجاه −z لتكوين عزوم من احتكاك أفقي).
-
تفاعل عمود على القماش: تُقرف رد الفعل المعياري تقريباً بـ N ≈ m g.
-
إذا كان |v_slip| أعظم من حد عددي ε (slip threshold):
$$|\mathbf{F}| = \mu_k, m, g$$ الاتجاه عكس v_slip؛ العزم τ = r_c × F يُحدّث ω.
عندما ينزل |v_slip| تحت الحدّ:
- مقاومة خطية شبيهة بـ rolling resistance: تخميد يتناسب مع μ_r g ومقاييس أخرى مضبوطة للقماش؛
- محاذاة لطيفة نحو pure rolling (تطابق تقريبي بين ω الأفقي وسرعة الانزلاق) مع spin damping.
μ_r في الواجهة يُشتق من μ_k وفقاً لثابت ROLLING_FROM_KINETIC_RATIO في الإعدادات (موثّق بالكود) للحفاظ على معنيين فيزيائيين مع واجحة أقل ازدحاماً.
حدود مستطيلة مع coefficient of restitution جزئية للمحور المتصادم.
عند ضعف الطاقة الحركية الخطية وضعف الدوران دون معالم، تُصفّ السرعات إلى صفر لتجنّب الزحف العددي.
| عنصر الواجهة | المعنى الفيزيائي |
|---|---|
| J (N·s) | مقدار النبضة المتجه افتراضياً على محور خط التصويب. |
| الاتجاه (deg) | زاوية الضربة في المستوى الأفقي. |
| μ_k | معامل احتكاك حركي بلا بعد (dimensionless) في انزلاق نقطة اللمس. |
| m (kg) | كتلة الكرة. |
| الأزرار ضربة / إعادة | تنفيذ ضرب تمركزي ثم تصفير الحالة الموضعية أو إيقاف وتصفير الحركة. |
عُرض لاحقًا: قراءات |v|، |v_slip|، الموضع، الزمن المتكامل، المسافة المقطوعة، ω، الطاقة الحركية الخطية تقريباً.
| مصطلح عربي | English | فكرة مختصرة |
|---|---|---|
| نبضة | Impulse J | تغير في الزخم؛ لها نفس أبعاد N·s. |
| انزلاق التماس | Contact slip velocity | نقطة تماس تجرب سرعة مختلفة عن بقية الطاولة → احتكاك حركي. |
| تدحرج مثالي | Pure rolling | الشرط حيث لا انزلاق نسبي؛ هنا تحقيق تقريبي بعد إدخال μ_r. |
| عطالة | Moment of inertia I | مقاومة الجسم لتسارّع زاوي لعزم محدّد. |
| المصطلح | المعنى في هذا المشروع |
|---|---|
Stateful UI (useState) |
معاملات اللوحة ولوحة الإحصاء تُحدّث الواجهة. |
Refs (useRef) |
حالة المحاكاة mutable الكرة؛ لا تعيد تصيير كامل كل إطار. |
useEffect + RAF |
حلقة requestAnimationFrame للتقدم الزمني المستمر وفصلها عن تصيير React. |
forwardRef / useImperativeHandle |
في BilliardsScene: الواجهة الأب تنادي sync(ball) دون اعتماد react-three/fiber. |
| المفهوم | الاستخدام هنا |
|---|---|
OrthographicCamera |
أسقاط شبيه بلعبة لوحية؛ تقليل تشويه المنظور المناسب لتصور المسطح. |
WebGLRenderer + مستويات (PlaneGeometry, SphereGeometry) |
مستوى لبساط الطاولة وكرة بسيطة؛ الأبعاد تُمزامَن تقريبيًا مع نصف القطر الفيزيائي. |
| فصل العرض عن الفيزياء | المواضع تأتي من ball.position; أي توسعة لاحقة (أنسجة، ظلالات) لا تلمس المعادلات. |
- تصادم كرة–كرة (ball–ball collision)، مخطط وسائد دقيق (cushion geometry)، نقل كامل ثلاثي الأبعاد للكيو (cue ball English/side-spin) عبر نقاط تأثير فعلية خارج المركز (off-center impulses أو Jacobian contact solver مخفّف).
- اختبارات وحدة (unit tests) على
math/Vector2ودوال احتكاك معتدلة المعالم. - اختصار حقيبة Three بتقسيم ديناميكي إذا وسع التطبيق.
تم بناء مرحلة أولى قوية للصيانة والتعليم: فيزياء كولومب نموذجية بنقطة تماس، تكامل خطوة بعد خطوة، واجهة عربية بمعايير SI، وطبقة رسوم Three.js معزولة لتسهل إضافة ميزات بصارية دون خلط المعادلات. استخدم هذا الملف كـ لبّ التوثيق (canonical doc baseline) وقت إضافة مراحل لاحقة.
آخر تحديث وثيق بالمخطط الحالي لمستودع src/.