|
| 1 | +# Gemini CLI - Contextual Instructions |
| 2 | + |
| 3 | +This file provides foundational context for Gemini CLI when interacting with the **Gear Optimizer** project. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | +**Gear Optimizer** is a high-performance React-based web application designed to optimize equipment loadouts for the game *NGU Idle*. It is a modernized fork of the original optimizer, featuring a sleek Material UI (MUI) interface, real-time "Live Sync" via a game mod, and advanced projections for NGU and Hack growth. |
| 7 | + |
| 8 | +### Core Technologies |
| 9 | +- **Frontend**: React 18, Vite, Material UI (MUI) v5, Recharts. |
| 10 | +- **State Management**: Redux Toolkit, Redux-Saga. |
| 11 | +- **Performance**: Heavy mathematical computations (optimization algorithms) are offloaded to **Web Workers** (`src/sagas/optimize.worker.js`). |
| 12 | +- **Integration**: |
| 13 | + - **C# (BepInEx)**: A mod (`build_mod/`) that enables real-time data syncing from the game to the web app. |
| 14 | + - **Python/Bash**: Scripts in `data/` for decoding game saves and gathering item data. |
| 15 | + |
| 16 | +## Project Structure |
| 17 | +- `src/`: Main application source. |
| 18 | + - `actions/` & `reducers/`: Redux logic (using `@reduxjs/toolkit`). |
| 19 | + - `sagas/`: Orchestrates Web Workers and async side effects. |
| 20 | + - `components/` & `containers/`: UI architecture. |
| 21 | + - `utils/`: Core scoring logic (`scoring.js`) and game-specific formatting. |
| 22 | + - `assets/`: Item databases (`Items.js`) and images. |
| 23 | +- `data/`: Utility scripts for processing game data and saves. |
| 24 | +- `build_mod/`: Source code for the `NGULiveSync` C# mod. |
| 25 | +- `public/`: Static assets, including the pre-compiled `NGULiveSync.dll`. |
| 26 | + |
| 27 | +## Building and Running |
| 28 | + |
| 29 | +### Development |
| 30 | +```bash |
| 31 | +npm install |
| 32 | +npm start # Starts the Vite development server |
| 33 | +``` |
| 34 | + |
| 35 | +### Production & Testing |
| 36 | +```bash |
| 37 | +npm run build # Generates a production build in /dist (or /build) |
| 38 | +npm run preview # Previews the production build locally |
| 39 | +npm test # Runs Vitest tests |
| 40 | +``` |
| 41 | + |
| 42 | +### Deployment |
| 43 | +```bash |
| 44 | +npm run deploy # Deploys the application to GitHub Pages |
| 45 | +``` |
| 46 | + |
| 47 | +## Development Conventions |
| 48 | + |
| 49 | +### State & Logic |
| 50 | +- **Slices**: Use Redux Toolkit's `createSlice` for state mutations (found in `src/reducers/optimizerSlice.js`). |
| 51 | +- **Immutability**: While RTK uses Immer, ensure complex state transitions (like adding/removing slots) are handled safely. |
| 52 | +- **Workers**: Do not perform heavy loops or optimization logic on the main thread; use the Saga/Worker pattern established in `src/sagas/`. |
| 53 | + |
| 54 | +### UI & Styling |
| 55 | +- **MUI**: Adhere to the Material UI v5 components and system. |
| 56 | +- **Theming**: Use the custom theme definitions in `src/theme.js` and `src/themeColors.js`. |
| 57 | +- **Responsive Design**: The application uses a glassmorphism aesthetic; maintain consistency with existing `App.css` styles. |
| 58 | + |
| 59 | +### Domain Logic |
| 60 | +- **Scoring**: Gear scores are calculated in `src/utils/scoring.js`. Any changes to stat weights or hardcaps must be verified against game mechanics. |
| 61 | +- **Formatting**: Use `src/utils/formatting.js` for game-style number abbreviations (K, M, B, T, etc.). |
| 62 | + |
| 63 | +## Integration Notes |
| 64 | +- **Live Sync**: The web app listens for data via a socket or local server provided by the C# mod. Changes to the data structure in `optimizerSlice` may require corresponding updates in `NGULiveSync.cs`. |
| 65 | +- **Data Gathering**: If the game adds new items, use the scripts in `data/` to regenerate `src/assets/Items.js`. |
0 commit comments