سایر۳۲ تست Vitestموتور قوانین مجزاهوش مصنوعی هیوریستیک۵ تم ترمینال

تخته نرد در ترمینال (Backgammon TUI)

بازی تخته نرد مدرن، تعاملی و ارگونومیک در محیط ترمینال با TypeScript، React و Ink

نقش من

طراح و توسعه‌دهنده

بازه زمانی

۱۴۰۴ – ۱۴۰۵

دسته‌بندی

سایر

پروژه‌ها و کارهای من

9 فناوری استفاده‌شده

بسته NPM مشاهده سورس‌کد در گیت‌هاب

پیش‌نمایش و دمو

گیم‌پلی تعاملی در محیط ترمینال، هوش مصنوعی و داشبورد زنده

تجربه کامل تخته نرد در محیط ترمینال: پیمایش خانه‌ها با کلیدهای جهت‌نما یا ویم، ریختن تاس، اعتبارسنجی دقیق خوردن مهره و ورود از بار، رقابت با هوش مصنوعی، برگرداندن حرکت و تغییر تم به‌صورت زنده.

demo.local/backgammon-tui

دمو

پیش‌نمایش زنده در محیط خط فرمان: بازی تک‌نفره با هوش مصنوعی، پرتاب تاس، جابجایی مهره‌ها و داشبورد شمارش پیپ.

HD 720p • 30fps

راهنمای تست و بررسی

1نصب و اجرای آنی در ترمینال با دستور npx backgammon-tui یا کلون کردن مخزن گیت‌هاب.
2انتخاب حالت تک‌نفره برای مسابقه با هوش مصنوعی یا بازی دو نفره لوکال.
3فشردن کلید Space برای ریختن تاس‌ها و نمایش حرکات مجاز بر روی تخته.
4پیمایش روی خانه‌ها با کلیدهای جهت‌نما یا کلیدهای ویم (HJKL) و زدن Enter برای جابجایی.
5فشردن کلید U برای بازگرداندن حرکت در طول نوبت، یا Q برای ذخیره و خروج.

قابلیت‌های بررسی‌شده:۳۲ تست خودکار و مبتنی بر مشخصه (Vitest + fast-check)موتور منطقی ۱۰۰٪ مستقل و بدون وابستگی به فریم‌ورک‌های UIرعایت توالی حداکثری حرکات تاس (قوانین رسمی مسابقات)۵ تم رنگی چشم‌نواز (Obsidian, Classic, Nordic, ...)ذخیره‌سازی وضعیت و تنظیمات کاربر با اعتبارسنجی Zod

به صورت رسمی در npm منتشر شده و در هر ترمینالی با دستور npx backgammon-tui قابل اجراست.

درباره این پروژه

یک بازی تخته نرد مدرن و سرگرم‌کننده در محیط ترمینال که با Node.js، تایپ‌اسکریپت، React و Ink ساخته شده است. این پروژه دارای موتور قوانین مستقل و خالص با رعایت ۱۰۰٪ قوانین مسابقه‌ای تخته نرد، حریف هوش مصنوعی با وزن‌دهی هیوریستیک، ۵ تم رنگی، پشتیبانی از نمادهای یونیکد و اسکی، قابلیت بازگرداندن حرکت (Undo)، داشبورد آماری زنده (HUD) و ذخیره‌سازی خودکار با اعتبارسنجی Zod است.

ویژگی‌ها و امکانات

موتور قوانین استاندارد و تفکیک‌شده

هسته دامنه بدون هیچ وابستگی به لایه نمایش، قوانین کامل شماره‌گذاری ۱ تا ۲۴، ورود از بار، زدن مهره، خروج از بازی و برد‌های معمولی، مارس (Gammon) و مارس سیاه (Backgammon) را پیاده کرده است.

هوش مصنوعی خودکار با الگوریتم هیوریستیک

حالت تک‌نفره با حریف کامپیوتری که درخت حرکات مجاز را ارزیابی کرده و با وزن‌دهی هوشمند، امنیت مهره‌ها، زدن مهره حریف و برن‌آف را اولویت‌بندی می‌کند.

کنترل راحت و ارگونومیک در ترمینال

پیمایش روان کیبورد با پشتیبانی همزمان از کلیدهای جهت‌نما و کلیدهای ویم (HJKL)، پرش سریع به بار (B) و سینی خروج (O)، و بازگردانی فوری حرکت‌ها (U).

۵ تم رنگی و پشتیبانی از یونیکد و ASCII

پالت‌های رنگی متنوع شامل ابزیدین، کلاسیک، نوردیک، مونوکروم و کنتراست بالا همراه با تغییر خودکار نمادها از کاراکترهای یونیکد به سمبل‌های ساده ASCII.

ذخیره‌سازی مطمئن با اعتبارسنجی Zod

ذخیره خودکار پیشرفت بازی، تنظیمات و وضعیت مهره‌ها روی دیسک با اعتبارسنجی در زمان اجرا توسط Zod برای جلوگیری از خرابی داده‌ها.

تست‌های مبتنی بر مشخصه (Property-Based) با Vitest

پوشش گسترده با ۳۲ تست خودکار در Vitest با ترکیب تست‌های واحد و آزمون‌های فازینگ fast-check برای تضمین حفظ پایدار قوانین و شرایط نامتغیر بازی.

پشت‌صحنه فنی و معماری

معماری پروژه در چهار لایه شفاف پیاده‌سازی شده است: هسته دامنه (Domain Core)، موتور فرمان و رویداد (Engine & Command Layer)، مدیریت متمرکز ورودی (Input Manager) و رابط کاربری ترمینال با Ink React. مدل دامنه تخته را به عنوان وضعیت‌های تغییرناپذیر و تبدیلات ریاضیاتی محض نگهداری می‌کند. پترن Command Processor باعث جدایی کامل تعاملات کاربر از تغییر وضعیت شده و قابلیت برگشت حرکت را از طریق اسنپ‌شات نوبت فراهم می‌سازد.

نکات برجسته فنی

معماری لایه‌ای تمیز با تفکیک ۱۰۰٪ منطق بازی از ران‌تایم React و Ink
الگوی پردازش فرمان با قابلیت بازگرداندن آنی حرکت‌ها (Undo) از طریق Snapshot
محاسبه توالی حداکثری حرکات طبق قوانین بین‌المللی مسابقات تخته نرد
موتور ارزیابی و تصمیم‌گیری هیوریستیک برای بازی تک‌نفره با کامپیوتر
اعتبارسنجی در لحظه ساختار ذخیره‌سازی با Zod جهت محافظت در برابر داده‌های ناقص
مجموعه تست کامل شامل ۳۲ تست با Vitest و آزمون‌های مشخصه (Property Tests) با fast-check

هسته و موتور بازی

Node.jsTypeScriptInk 5React 18Zod

تست و اعتبارسنجی

Vitestfast-checkTypeCheck (tsc)

رابط کاربری ترمینال

ANSI Stylingکلیدهای Vimنمادهای Unicodeپشتیبانی از ASCII

توزیع و پکیجینگ

پکیج رسمی NPMدستور اجرایی NPXSemantic Versioning

چالش‌ها و راه‌حل‌های مهندسی

چالش مهندسی

مدل‌سازی دقیق قوانین رسمی مسابقات تخته نرد، به ویژه قانون اجباری بودن استفاده از بیشترین تعداد تاس ممکن و ترجیح تاس بزرگتر هنگام تک‌حرکتی بودن.

راه‌حل و تصمیم معماری

پیاده‌سازی الگوریتم بازگشتی findMaximalTurnSequences که تمام جایگشت‌های حرکات معتبر را کشف کرده و تنها مسیرهایی را که از حداکثر تاس ممکن استفاده می‌کنند مجاز می‌شمارد.

چالش مهندسی

رندر کردن تخته نرد با تمام خانه‌های بالا، پایین، بار وسط و سینی خروج در فضای متنی ترمینال بدون پرش صفحه (Flicker) و به هم ریختگی چیدمان.

راه‌حل و تصمیم معماری

طراحی لایه واسط BoardViewModel برای نگاشت ۲۴ نقطه به دو ردیف بالا و پایین، بهره‌گیری از چیدمان Flexbox در Ink با ابعاد ثابت سلول‌ها و کش کردن استایل‌های ANSI.

چالش مهندسی

فراهم آوردن امکان بازگرداندن حرکت (Undo) بدون ایجاد نشتی در وضعیت‌های تغییرپذیر یا بهم خوردن ترتیب تاس‌ها.

راه‌حل و تصمیم معماری

به‌کارگیری پترن Snapshot در GameEngine که وضعیت تخته و تاس‌های باقیمانده را در شروع نوبت ذخیره کرده و بازگشت حرکت را به شکل بازنشانی امن اسنپ‌شات قبلی انجام می‌دهد.

Deep Dive

معماری تمیز در اپلیکیشن ترمینالی

تخته نرد تحت ترمینال به گونه‌ای مهندسی شده که هسته محاسباتی آن هیچ گونه وابستگی به React یا Ink ندارد:

src/
├── domain/       # بدون وابستگی خارجی؛ هندسه تخته و قوانین ریاضی بازی
├── engine/       # الگوی فرمان (Command Pattern)، چرخه نوبت، هوش مصنوعی
├── input/        # ترجمه کلیدهای ترمینال (کلیدهای جهت‌نما، Vim، میانبرها)
└── ui/           # کامپوننت‌های Ink React و استایل‌های ANSI

قانون انتخاب حداکثری تاس‌ها

در قوانین بین‌المللی تخته نرد، اگر بازیکنی دو تاس ریخته باشد (مثلاً ۶ و ۲) و بتواند هر یک از آن‌ها را به تنهایی بازی کند اما امکان بازی همزمان هر دو وجود نداشته باشد، قانوناً موظف است تاس بزرگتر (۶) را بازی کند. موتور بازی این شرط را با جستجوی بازگشتی درخت حرکات بررسی کرده و انتخاب‌های غیرمجاز را رد می‌کند.