Crash Game

პროექტის გაშვება

npm install
npm run dev

npm run dev გამოიყენება მხოლოდ პროექტზე მუშაობისას. რთავს Vite-ის development რეჟიმს, HMR-ს და development-ისთვის საჭირო დამატებით პროცესებს.

Production build-ის გასაშვებად:

npm run build
npm run preview

Benchmark და Lighthouse

Performance benchmark-ისთვის გამოიყენეთ მხოლოდ production build:

npm run build
npm run preview

Benchmark არ უნდა გაეშვას npm run dev-ზე, რადგან development რეჟიმში კოდი და asset-ები production-ის მსგავსად ოპტიმიზებული არ არის. HMR-მა და development-ის დამატებითმა პროცესებმა შეიძლება შედეგი ხელოვნურად გააუარესოს და რეალური production performance არ აჩვენოს.

კოდის ყოველი ცვლილების შემდეგ საჭიროა npm run build-ის თავიდან გაშვება და შემდეგ preview სერვერის გადატვირთვა. შედეგების შედარებისას გამოიყენეთ ერთი და იგივე URL, viewport და Lighthouse-ის პარამეტრები.

კოდის შესამოწმებლად:

npm run lint

პროექტის ძირითადი სტრუქტურა

├── public/ # public ფაილი
├── src/
│ ├── app/
│ │ ├── audio/ # ხმების მართვა
│ │ ├── components/
│ │ │ ├── betting/ # ფსონისა და Auto Bet-ის კომპონენტები
│ │ │ ├── game/ # თამაშის React UI
│ │ │ ├── header/ # მენიუ და საინფორმაციო დიალოგები
│ │ │ ├── multipliers/
│ │ │ ├── stats/
│ │ │ └── ui/ # საერთო Button, Dialog, NumberStepper და Switch
│ │ ├── hooks/ # React-ის custom hook-ები
│ │ └── Layout/ # გვერდის ძირითადი განლაგება
│ ├── assets/ # სურათები, SVG და sound asset-ები
│ ├── game/ # Phaser, Spine და canvas rendering
│ ├── locales/ # ქართული, ინგლისური და რუსული თარგმანები
│ ├── store/ # საერთო settings და URL state
│ ├── styles/ # საერთო სტილები და design token-ები
│ ├── dummyData/ # mock მონაცემები და betting state
│ │ ├── bets.ts
│ │ ├── crashEngine.ts
│ │ ├── crashEngine.types.ts
│ │ ├── freeBets.ts
│ │ └── multipliers.ts
│ └── main.tsx # აპლიკაციის საწყისი წერტილი
├── vite.config.ts # build და development კონფიგურაცია
└── package.json # scripts და dependencies

React-ის ინტერფეისი src/app-შია, ხოლო Phaser/Spine-ის rendering — src/game-ში. დაჯგუფების საქაღალდეები lowercase-ით, კონკრეტული კომპონენტების საქაღალდეები კი PascalCase-ითაა დასახელებული.

3rd party პაკეტები

• phaser, @esotericsoftware/spine-phaser-v4, @esotericsoftware/spine-core — თამაშის სცენა და Spine ანიმაციები. spine-core პირდაპირ dependency-ადაც არის აღწერილი, რადგან SpineGameView მას პირდაპირ import-ს უკეთებს.
• i18next, react-i18next — მრავალენოვანი ინტერფეისი.
• @rolldown/plugin-babel, babel-plugin-react-compiler — React Compiler-ის build პროცესში ჩასართავად.
• vite-plugin-compression2 — ფაილების (JS/CSS) ავტომატური შეკუმშვა (Gzip/Brotli), რაც ამცირებს ბანდლის ზომას და ზოგავს სერვერის რესურსს (რეკომენდებულია Krash SDK-ის დოკუმენტაციაში).

მნიშვნელოვანი გადაწყვეტილებები

• დიზაინი დავყავი პატარა კომპონენტებად; Button, Dialog, NumberStepper და Switch საერთო UI კომპონენტებია.
• სტილებისთვის გამოვიყენე CSS Modules და საერთო design token-ები.
• ერთი საერთო Dialog კომპონენტი desktop-ზე modal-ად, ხოლო mobile-ზე bottom drawer-ად მუშაობს.
• ენა და ვალუტა URL-ის query პარამეტრებით იმართება.
• production build-ში React, Phaser, Spine და სხვა third-party dependency-ები ცალკე chunk-ებადაა გამოყოფილი.

არქიტექტურული პასუხისმგებლობები

• src/app არის React-ის UI subtree: მართავს მარკაპს, მომხმარებლის ინტერაქციებსა და ლოკალურ UI state-ს. თამაშის რენდერინგის დეტალები React კომპონენტებში არ არის შერეული.
• src/game არის Phaser/Spine subtree: ის მართავს canvas rendering-ს, scene-ებს, animation-ებსა და მათ lifecycle-ს და React კომპონენტებს არ შეიცავს.
• ეს subtree-ები ცალკეა, რადგან React-ის render lifecycle და Phaser-ის მუდმივი game loop სხვადასხვა პასუხისმგებლობაა. მათ შორის საზღვარი PhaserGame-ია: React ქმნის და ზომავს container-ს, ხოლო GameEngine მასში Phaser instance-ს მართავს.
• src/dummyData/crashEngine.ts არის დავალების mock მონაცემთა წყარო. React მას useSyncExternalStore-ით უკავშირდება, ამიტომ engine-ის snapshot-ები React state-ში არ დუბლირდება და თითოეული betting slot მხოლოდ მისთვის საჭირო ცვლილებებზე რეაგირებს.
• PhaserGame ჯერ ელოდება კონტეინერის რეალურ ზომას და მხოლოდ შემდეგ ტვირთავს GameEngine-ს. კომპონენტის unmount-ისას წყდება ResizeObserver და ნადგურდება Phaser instance.
• GameScene ფლობს Phaser/Spine ობიექტების lifecycle-სა და subscription-ებს. scene shutdown-ისას listener-ები, tween-ები და Spine animation listener-ები იწმინდება.
• dialog-ები mount-controlled არის: აქტიური dialog-ის კონტენტი პირობითად render-დება, ხოლო საერთო native <dialog> კომპონენტი მართავს focus-ს, backdrop-ს, Escape-ს, scroll lock-სა და დახურვის ანიმაციას.
• Dialog-ის submit action-ებიც საერთო close lifecycle-ს იყენებს. transitionend არის დახურვის ნორმალური გზა, ხოლო transitioncancel შეწყვეტილ transition-ს ასრულებს, რათა dialog უხილავად ღია არ დარჩეს.

Responsive სტრატეგია

• ძირითადი layout breakpoint-ებია 768px და 1024px; დამატებითი breakpoint მხოლოდ კონკრეტული კომპონენტის რეალური სივრცითი საჭიროებისთვის გამოიყენება.
• 1024px-ზე ზემოთ გამოიყენება ორსვეტიანი desktop layout და ორი betting panel ერთ რიგში.
• 1024px-სა და ქვემოთ game და stats სექციები ვერტიკალურად ნაწილდება, რათა კონტენტი მხოლოდ desktop ვერსიის დაპატარავება არ იყოს.
• ამავე breakpoint-ზე fixed stats summary-ის სიმაღლე shared token-ით წინასწარ არის დაცული game area-ში, ამიტომ summary betting controls-ს არ ფარავს.
• ამავე დიაპაზონში game canvas-ის სიმაღლე მაქსიმუმ 500px-ია, რათა მაღალ tablet viewport-ზე game area ზედმეტად არ გაიზარდოს.
• 768px-ზე ქვემოთ betting panel-ები ვერტიკალურად ლაგდება და dialog-ები bottom drawer-ად იხსნება.
• 700px ან ნაკლები სიმაღლის mobile viewport-ზე stats summary normal flow-ში ბრუნდება და game area usable მინიმალურ სიმაღლეს ინარჩუნებს, რათა game canvas თხელ ზოლად არ შეიკუმშოს.
• 480px, 400px და 360px გამოიყენება მხოლოდ იმ კომპონენტების მცირე ეკრანის კორექციებისთვის, რომლებსაც ამ ზომებზე დამატებითი სივრცის მართვა სჭირდებათ.

გამოყენებულია React Compiler

React Compiler კომპონენტებსა და hook-ებს build-ის დროს ავტომატურად ოპტიმიზირებს. ეს ამცირებს არასაჭირო re-render-ებს ყველა კომპონენტში ხელით useMemo, useCallback ან memo დამატების გარეშე.

Compiler პროექტში ჩართულია reactCompilerPreset-ით და @rolldown/plugin-babel-ით. ეს არის build-ის ოპტიმიზაცია და პროექტის კომპონენტურ არქიტექტურას არ ცვლის.

Vite კონფიგურაცია

• @ alias პირდაპირ src საქაღალდეზე მიუთითებს და import-ებს უფრო მოკლესა და გასაგებს ხდის.
• React Compiler reactCompilerPreset-ისა და @rolldown/plugin-babel-ის საშუალებითაა ჩართული.
• Phaser-ის ESM ფაილი optimizeDeps-შია მითითებული, რათა development რეჟიმში dependency სწორად დამუშავდეს.
• production build ცალკე react-vendor, phaser-vendor, spine-vendor და საერთო vendor chunk-ებს ქმნის. ეს dependency-ებს ერთმანეთისგან გამოყოფს და browser cache-ის გამოყენებას ამარტივებს.
• build-ის კომენტარები იშლება, ხოლო vite-plugin-compression2 1 KB-ზე დიდი ფაილებისთვის Gzip და Brotli ვერსიებს ქმნის.
• chunkSizeWarningLimit გაზრდილია Phaser-ის მოსალოდნელი დიდი vendor chunk-ის გამო. ეს მხოლოდ warning-ის ზღვარია და თავისით performance ოპტიმიზაციას არ წარმოადგენს.